> ## Documentation Index > Fetch the complete documentation index at: https://sdk.cerebras.ai/llms.txt > Use this file to discover all available pages before exploring further. # Libraries > Explore the CSL standard library modules available for import, including math, complex numbers, data utilities, memory allocation, and collective operations. Libraries are imported by enclosing the name of the library with angled brackets. ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} // Filename: main.csl const math = @import_module(""); fn distance(x0 : f16, y0 : f16, x1 : f16, x1 : f16) f16 { return math.sqrt((x0-x1)*(x0-x1) + (x0-x1)*(x0-x1)); } ``` ## `` The `complex` library provides structs containing `real` and `imag` components and basic complex functions. `complex` is a generic struct parameterized by its field type. The `complex_32` and `complex_64` non-generic names are also provided; these define a complex number using two `f16` values and a complex number using two `f32` values, respectively. `get_complex` is a generic constructor that returns a complex struct based on the type of its inputs. The non-generic `get_complex_32` and `get_complex_64` constructor functions are provided as well: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} // Returns struct {real: T, imag: T} where T can be f16 or f32 fn complex(comptime T: type) type const complex_32 = complex(f16); // struct {real: f16, imag: f16} const complex_64 = complex(f32); // struct {real: f32, imag: f32} // Can operate on f16 or f32 fn get_complex(r: anytype, i: @type_of(r)) complex(@type_of(r)) fn get_complex_32(r : f16, i : f16) complex_32 fn get_complex_64(r : f32, i : f32) complex_64 ``` The following functions are provided for operating on complex numbers. They are written as generic functions to facilitate use in other libraries or abstractions. In addition, non-generic `complex_32` and `complex_64` functions are provided. These functions have names suffixed with `_32` and `_64`, respectively. ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} // x, y can be complex_32 or complex_64 fn add_complex(x: anytype, y: @type_of(x)) @type_of(x) fn subtract_complex(x: anytype, y: @type_of(x)) @type_of(x) fn multiply_complex(x: anytype, y: @type_of(x)) @type_of(x) ``` ## `` The `control` library provides utilities for constructing control wavelets. The following functions and enums are provided by the library: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} // Max commands that can be encoded in a control wavelet const MAX_CMDS = 8; // Struct for representing switching opcodes const opcode = enum(u32) { NOP = 0, SWITCH_ADV = 1, SWITCH_RST = 2, TEARDOWN = 3 }; // Encode payload that activates a control task with no argument fn encode_control_task_payload(entrypoint: control_task_id) u32; // Encode payload with one switch command, plus control task entrypoint. fn encode_single_payload(cmd: opcode, ce_ignore: bool, comptime entrypoint: control_task_id, data: u16) u32; // Encode general control wavelet payload fn encode_payload(comptime N: u16, comptime cmds: [N]opcode, comptime ce_ignore: [N]bool, ce_ignore_remaining: bool, comptime entrypoint: anytype) u32; ``` All functions construct a payload returned as a 32-bit unsigned integer which can be sent in a control wavelet. `encode_control_task_payload` returns a control wavelet payload which activates a control task on all receiving PEs. It has one argument: * `entrypoint`: a `control_task_id` which is bound to the control task activated on a CE by the receipt of this wavelet. `encode_single_payload` returns a control wavelet payload containing one switch command, along with an optional control task entrypoint with 16-bit data argument. The function has the following arguments: * `cmd`: a switching opcode to be consumed by the receiving PE router. This command will instruct the router to modify the configuration of the color on which the control wavelet is sent. This command can advance the switch position, reset the switch position, teardown the color, or do nothing. If the router of the PE on which the control wavelet is sent pops this command, then no additional receiving PEs will receive a switching opcode. * `ce_ignore`: a boolean which determines whether this control wavelet is to be ignored by the CE of PEs which receive it. If `true`, the control wavelet will not be forwarded to the CE. If `false`, and the receiving color is configured to transmit down the `RAMP`, the control wavelet will be forwarded to the CE. `ce_ignore` must be `false` for an `entrypoint` to be activated by a receiving PE. * `entrypoint`: a `control_task_id` will be activated on a CE by the receipt of this wavelet. Passing `{}` indicates that no control task activation on receiving PEs is desired. The control task will only be activated on a CE if `ce_ignore` is `false`, and the receiving color is configured to transmit down the `RAMP`. * `data`: The control task activated by `entrypoint` may take a single 16-bit argument. If the control task takes no argument, then this value will be ignored. `encode_payload` can encode a general control wavelet payload with up to eight switching commands. The function has the following arguments: * `N`: number of commands to encode in the control wavelet. Maximum number of commands is eight. * `cmd`: an array of switching opcodes to be consumed by PE routers. Each command will instruct the router to modify the configuration of the color on which the control wavelet is sent. Each command can advance the switch position, reset the switch position, teardown the color, or do nothing. If the router of the PE on which a command is executed pops the command, then the *next* command will be executed by the next receiving router. * `ce_ignore`: an array of booleans which determines whether this control wavelet is to be ignored by the CE of PEs which receive it. Each `ce_ignore` value is processed along with the associated `cmd`, i.e., the same rules for popping commands apply. If the processed value is `true`, the control wavelet will not be forwarded to the CE. If `false`, and the receiving color is configured to transmit down the `RAMP`, the control wavelet will be forwarded to the CE. `ce_ignore` must be `false` for an `entrypoint` to be activated by a receiving PE. * `ce_ignore_remaining`: a boolean which determines whether all other commands contained in this control wavelet are to be ignored by the CE of PEs receiving it. When `ce_ignore_remaining` is set to `false`, each unspecified command will travel down the `RAMP` and reach the CE (as a `NOP` command). * `entrypoint`: a `control_task_id` which is bound to the control task activated on a CE by the receipt of this wavelet. Passing `{}` indicates that no control task activation on receiving PEs is desired. The control task will only be activated on a CE if `ce_ignore` is `false`, and the receiving color is configured to transmit down the `RAMP`. Because this function can encode up to eight switching commands, no data payload can be provided for this control task. Unlike `encode_single_payload`, `encode_payload` does not take a `data` argument. If a control payload only contains a single switching command, then a 16-bit data argument can be supplied as an argument to the control task activated on receipt of the wavelet. `data` is not meaningful if there is more than one switching command in the control wavelet, because the bits that would encode `data` encode the additional switching commands instead. A control task that declares no arguments will ignore `data`, and furthermore, `data` is ignored if the wavelet is not forwarded to the CE (the current command’s `ce_ignore` value is `true`). ### Example The task `main_task` sends out a control wavelet along the color `comm`, which encodes a control task ID: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} const ctrl = @import_module(""); const comm = @get_color(0); const comm_out_queue = @get_output_queue(2); const ctrl_entrypt_id = @get_control_task_id(40); task main_task() void { const comm_out_dsd = @get_dsd(fabout_dsd, .{ .extent = 1, .fabric_color = comm, .control = true, .output_queue = comm_out_queue, }); @mov32(comm_out_dsd, ctrl.encode_control_task_payload(ctrl_entrypt_id)); } ``` PEs which receive this wavelet along the color `comm` will activate a control task bound to this control task ID. For instance, if the receiving PE has the following code, then upon receipt of the control wavelet, it will activate a task which increments the value `my_global`: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} const my_ctrl_id = @get_control_task_id(40); var my_global: u32 = 0; task my_ctrl_task() void { my_global += 1; } comptime { @bind_control_task(my_ctrl_task, my_ctrl_id); } ``` ## `` The `data_utils` library provides low-level data manipulation and bit extraction functions. The following functions return the lower or higher 16 bits of a 32-bit variable. The `lo16` function can also be called on a 16-bit data type. Similarly, variants for 64-bit data types are also available. ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} inline fn lo16(src0: anytype) u16; inline fn hi16(src0: anytype) u16; inline fn lo32(src0: anytype) u32; inline fn hi32(src0: anytype) u32; ``` ## `` The `debug` library provides a tracing mechanism to record tagged values. ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} // Record values of the specified type fn trace_bool(x : bool) void fn trace_u8(x : u8) void fn trace_i8(x : i8) void fn trace_u16(x : u16) void fn trace_i16(x : i16) void fn trace_f16(x : @fp16()) void fn trace_u32(x : u32) void fn trace_i32(x : i32) void fn trace_f32(x : f32) void // Record a compile-time string fn trace_string(comptime str : comptime_string) void // Generic version fn trace(x : anytype) void // Record timestamp using the
On WSE-2, all colors support switch configuration. On WSE-3, only a subset of colors support switch configuration: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 13, 16, 17, 20, and 21. `switch_config` APIs should only be used with these colors on WSE-3. These functions can be used as follows: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} param red: color; var blue: color; const tile_config = @import_module(""); const switch_config = tile_config.switch_config; const switch_status_addr = switch_config.get_switch_config_addr(red, switch_config.switch_status); task teardown() void { // Color `blue` is a `var` and therefore not known until runtime. const addr = switch_config.get_switch_config_addr(blue, switch_config.pop_mode); // We can manipulate the switch configuration using a // comptime-known color, a runtime color or an address to // a color configuration register. switch_config.clear_current_position(red); switch_config.clear_current_position(blue); switch_config.clear_current_position(switch_status_addr); // Reset the pop mode to a new setting. switch_config.set_pop_mode(red, switch_config.pop_mode.ALWAYS_POP); } ``` ### task\_priority This submodule of `tile_config` contains APIs for configuring task priority: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} // Enum for task priorities: either HIGH or LOW. const level = enum(u16) { LOW = 0, HIGH = 1 }; // Updates the task priority associated with `task_id` to `priority`. fn update_task_priority(task_id: anytype, priority: level) void // Sets the task priority associated with `task_id` to high. fn set_task_priority(task_id: anytype) void // Sets the task priority associated with `task_id` to low. fn clear_task_priority(task_id: anytype) void ``` The provided `task_id` can be a `data_task_id` or `local_task_id` to set the priority of the associated task. In addition, the priority of tasks activated by wavelets, including tasks bound to a `control_task_id`, can be specified using the `color` on WSE-2, or the `input_queue` on WSE-3, that carries the wavelets. Note that updates to task priority made at runtime may take a few clock cycles to take effect. These functions may be used at comptime or at runtime. These functions can be used like: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} const config = @import_module(""); const task_priority = config.task_priority; const task_priority_level = task_priority.level; param high_id: data_task_id; param low_id: local_task_id; comptime { // Equivalent to: // task_priority.update_task_priority( // high_id, // task_priority_level.HIGH); task_priority.set_task_priority(high_id); } task main() void { // Equivalent to: // task_priority.update_task_priority( // low_id, // task_priority_level.LOW); task_priority.clear_task_priority(low_id); } ``` ### teardown This submodule of `tile_config` contains teardown APIs: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} // Returns the task ID that is reserved for the teardown handler. fn get_task_id() local_task_id // Return the values of the "teardown-pending" registers combined into // one value. Only the first invocation of this function per-task is // guaranteed to return the correct value. Any additional calls per-task // will have undefined results. fn get_pending() double_reg_type // Given a value that represents the "teardown-pending" state, which has 1 // bit per routable color indicating the ones that are currently in // teardown state, return `true` iff the input color `c` is in teardown // state. fn is_pending(value: double_reg_type, c: color) bool // Exit the teardown state for a given color `c`. fn exit(c: color) void ``` These functions can be used like: ```csl theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}} const config = @import_module(""); // Check if teardown is pending on color 8 or 9 var pendings = config.teardown.get_pending(); bool pending_8_or_9 = config.teardown.is_pending(pendings, @get_color(8)) or config.teardown.is_pending(pendings, @get_color(9)); ``` ## `