.. _language-task-ids: Task Identifiers ================ The term "task identifier" or "task ID" is used to refer to a numerical value that can be associated with a task. A task ID is a number from 0 to 63, excluding 31. Within this range there are two properties that further distinguish a task ID: routable and activatable. Routable Identifiers (Colors) ----------------------------- The IDs 0 to 23 are recognized by the hardware as virtual communication channels for passing wavelets between PEs. These IDs are sometimes referred to as the routable "colors" and are the only ones that can be used with the ``@set_color_config`` and ``@set_local_color_config`` builtins. Both routing and color swap configuration is performed using the ``@set_color_config`` or ``@set_local_color_config`` builtins. See `their documentation `_ for more on this topic. Note that it is only safe to enable multiple input directions for a given color if it is known that wavelets will never arrive from multiple directions on this color at once. If wavelets arrive from two enabled directions on the same color at once, the behavior of the hardware router is undefined. .. _language-task-ids-color-swapping: Color Swapping ^^^^^^^^^^^^^^ The hardware supports color "swapping," a feature allowing incoming data on one color to be sent out on another color. Two colors are swappable if they differ only in the low bit (i.e. ``x ^ y == 1``). Color swapping is set per-color East-West (horizontal) or North-South (vertical). So, e.g. if East-West color swapping is enabled for color 3, wavelets arriving from either the East or West on color *2* will be sent out on color 3. This transmission is still subject to which directions are enabled in the receive and transmit fields for this color. If *both* East-West color swap and North-South color swap are enabled for a given color, color swap is also enabled for wavelets arriving from the CE (onramp). Compute Element (CE) Injection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CE inject mode is a per-color setting that can be enabled at compile-time. A CE inject configured color is hard wired to the tile's output queue corresponding to the color number divided by 4. E.g. color 4 in this mode is connected to output queue 1. This is an integer floor division, so e.g. if color 5 is in this mode it is also connected to output queue 1. Note that this means in practice only one of every four colors can be used in CE inject mode at once. Either low priority or high priority can be selected when configuring this mode. When either the fabric buffers are empty or the relevant output queue is empty, these modes behave identically. When both are non-empty, low priority mode will preference the fabric buffers, whereas high priority mode will preference the relevant output queue. To explain this more concretely, in low priority mode, the switch for this color flips to position 1 when the fabric buffers are empty and begins transmitting from the relevant output queue. It switches back to position 0 if the fabric buffers ever become non-empty. In high priority mode, the switch will flip to position 1 whenever the relevant output queue is non-empty and will only flip back to position 0 when the output queue becomes empty. In either mode, control wavelets on this color have no effect; the switch position is controlled entirely by buffer and queue occupancy. Activatable Identifiers ----------------------- The IDs 0 to 30 are activatable, meaning they can be used in local activation calls. See documentation of the |builtins.activate|_ builtin for more on this topic. .. |builtins.activate| replace:: ``@activate`` .. _builtins.activate: _language-builtins-rst-activate IDs 29 and 30 should generally be avoided in programs as they are used for system tasks. ID 29 is bound to a teardown task that runs when the tile is in teardown mode and ID 30 is bound to a timer task. Sentinel Identifiers -------------------- The IDs 32 to 63 are neither routable nor activatable. However they can be used as sentinel values. By binding a task to one of these IDs, that task can be triggered when the value of this ID arrives in the data field of a control wavelet on any color.