Data Structure Descriptors¶

Data Structure Descriptors (DSDs) are a compact representation of a (possibly non-contiguous) chunk of memory or a sequence of incoming or outgoing wavelets. Combined with DSD operations, DSDs enable various repeated operations to be expressed using just one hardware instruction.

Basic Syntax¶

DSDs are defined in CSL using the following syntax:

@get_dsd(dsd_type, properties);

Where:

dsd_type is one of mem1d_dsd, mem4d_dsd, fabin_dsd, or fabout_dsd.
properties is a struct that specifies auxiliary properties of the particular DSD type.

Different DSD types require different properties.

One-Dimensional Memory Vectors¶

The mem1d_dsd type is used to encode a memory vector using a single induction variable. Memory vectors are configured using the following fields:

tensor_access
wavelet_index_offset

`tensor_access`¶

The memory access pattern is defined by the tensor_access field, which is expected to contain an affine map, like so:

const array = @zeros([10]u16);
const tenWords = @get_dsd(mem1d_dsd, .{
  .tensor_access = |i|{10} -> array[i]
});

In the above snippet, tenWords is a mem1d_dsd specifying accesses to array at indices 0 through 9.

The affine map described by the tensor_access field has the following syntax:

|<induction-variable>| {<length>} -> <array-variable>[<expr>]

Where:

induction-variable is the loop iteration variable
length specifies the number of times to iterate
array-variable is a pointer to a variable of array type
expr is an affine expression of the loop iteration variable and comptime-known values

The tensor_access expression can be used to refer to odd elements of an array:

const array = @zeros([10]u16);
const oddElements = @get_dsd(mem1d_dsd, .{
  .tensor_access = |i|{5} -> array[2 * i + 1]
});

The tensor_access expression can be used to refer to a single element of the array as well:

const array = @zeros([10]u16);
const firstElement = @get_dsd(mem1d_dsd, .{
  .tensor_access = |i|{10} -> array[0]
});

Such a pattern is often useful in reduction operations.

Although mem1d_dsd allows only one induction variable, the underlying array can still be a multidimensional array. For instance, the following mem1d DSD refers to the diagonal elements of a 2D (20x20) array.

const array = @zeros([20,20]u16);
const diagonal = @get_dsd(mem1d_dsd, .{
  .tensor_access = |i|{20} -> array[i,i]
});

`wavelet_index_offset`¶

The wavelet_index_offset field expects a comptime-known boolean value that indicates whether the wavelet_index_offset mode is enabled.

If the wavelet_index_offset mode is enabled, the address of the underlying memory buffer is incremented by the index specified in the DSD operation as explained in Explicit Index Offset.

If a DSD with wavelet_index_offset enabled is used in a DSD operation, the DSD operation must provide an index field. Otherwise, the behavior of the respective DSD operation is undefined.

const array = @zeros([size]u16);
const memDSD = @get_dsd(mem1d_dsd, .{
  .tensor_access = |i|{10} -> array[i],
  .wavelet_index_offset = true
});

task my_task() void {
  // The addition will start at an offset specified
  // by 'my_index'.
  @add16(memDSD, memDSD, data, .{.index = my_index});

  // The behavior of this builtin is undefined.
  @add16(memDSD, memDSD, data);
}

Two-, Three-, or Four-Dimensional Memory Vectors¶

The mem4d_dsd is a DSD type that is used to refer to multi-dimensional memory vectors, up to a maximum of four dimensions. Multi-dimensional memory vectors are configured using the following fields:

tensor_access
wavelet_index_offset

`tensor_access`¶

Like one-dimensional memory vectors, the specific memory locations for mem4d_dsd are also specified using the affine map in the tensor_access field, although the programmer can specify up to four induction variables and length values.

The following example shows a DSD that points to a 2x2 subset of a 2D array.

const array = @zeros([4,3]u16);
const subset = @get_dsd(mem4d_dsd, .{
  .tensor_access = |i,j|{2,2} -> array[i, j]
});

The following, more complicated, example shows a DSD that uses all four dimensions with non-zero offsets.

const array = @zeros([1,2,3,4]u16);
const subset = @get_dsd(mem4d_dsd, .{
  .tensor_access = |i,j,k,l|{1,2,1,4} -> array[i, j, 1+k, l]
});

mem4d DSDs can be used with single-dimensional vectors as well, like in the following, somewhat contrived, example:

const subset = @get_dsd(mem4d_dsd, .{
  .tensor_access = |i,j,k,l|{1,1,1,1} -> array[i + j + k + l]
});

`wavelet_index_offset`¶

See wavelet_index_offset.

Pointers To Scalars As Destinations¶

Some DSD operations support pointers to scalars as destination arguments. These operations essentially behave as if the destination were a memory DSD with zero stride, whose destination is a one-element array whose data is stored at the pointer. For example:

const src_array = [8]f16{ 0, 1, 2, 3, 4, 5, 6, 7 };
// src_dsd will access src_array at indices, 0, 2, 4, and 6.
const src_dsd = @get_dsd(mem1d_dsd, .{
  .tensor_access = |i|{4} -> src_array[2*i]
});

const dst_array = @zeros([1]f16);
// Because dst_dsd has zero stride (`i` is never mentioned to the right of
// the arrow in the tensor access expression), the @fmovh below will first
// move 0, then 2, then 4, then 6 into dst_array[0]. Thus afterwards,
// dst_array[0] will have a value of 6.
const dst_dsd = @get_dsd(mem1d_dsd, .{
  .tensor_access = |i|{4} -> dst_array[0]
});
@fmovh(dst_array, src_dsd);
@assert(dst_array[0] == 6);

// An @fmovh operation with a pointer to scalar as its destination behaves
// similarly, so the value of dst_scalar after the following @fmovh will
// also be 6.
const dst_scalar: f16 = 0;
@fmovh(&dst_scalar, src_dsd);
@assert(dst_scalar == 6);

Fabric Input Vectors¶

The fabin_dsd DSD type is used to refer to wavelets arriving at the PE from the fabric. Fabric input vectors are configured using the following two fields.

fabric_color, which specifies the color of the wavelets to associate with this vector
extent, which specifies the number of wavelets that this vector refers to

For instance, the following DSD refers to 5 wavelets expected to arrive on color trigger.

const inDsd = @get_dsd(fabin_dsd, .{ .extent = 5, .fabric_color = trigger });

Fabric Output Vectors¶

Fabric output vectors, specified using the fabout_dsd type, are configured similarly to fabric input (fabin_dsd) vectors, with the exception that fabric output vectors may contain the following additional fields:

control
wavelet_index_offset

`control`¶

The control field expects a comptime-known boolean expression, which is used to signify control wavelets.

For instance, the following DSD refers to 1024 non-control wavelets to be sent along the color tx.

const outDsd = @get_dsd(fabout_dsd, .{ .extent = 1024, .fabric_color = tx });

Whereas the following DSD refers to a single control wavelet to be sent along the color out.

const dsd = @get_dsd(fabout_dsd, .{
  .extent = 1,
  .control = true,
  .fabric_color = out,
});

`wavelet_index_offset`¶

The wavelet_index_offset field expects a comptime-known boolean expression, which is used to enable the wavelet_index_offset mode. When this mode is enabled, the outgoing wavelets will carry a fixed index field specified by the user per-operation as explained in Explicit Index Offset. Similar to the semantics of memory DSDs, if the operations that use fabric output DSDs with wavelet_index_offset enabled do not specify an index value, then the behavior is undefined.

const outDSD = @get_dsd(fabout_dsd, .{
  .extent = 1,
  .fabric_color = out,
  .wavelet_index_offset = true,
});

task my_task() void {
  // The outgoing wavelets will have 'my_index' stored in
  // their high 16-bits.
  @add16(outDSD, memDSD, 42, .{.index = my_index});

  // The behavior of this builtin is undefined.
  @add16(outDSD, memDSD, 42);
}

FIFOs¶

A FIFO DSD is a kind of DSD that uses a memory region to create a First-In First-Out buffer.

To create a FIFO DSD, the @allocate_fifo builtin is used:

var fifo_buffer = @zeros([32]i16);
const fifo = @allocate_fifo(fifo_buffer);

The @allocate_fifo builtin must be associated with a const variable in the global scope. The argument to @allocate_fifo must be a global array or pointer to a global array. This array must be marked as var and must have elements of type i16, u16, f16, i32, u32 or f32.

If the fifo buffer (i.e., the argument to @allocate_fifo) was declared without an explicit alignment requirement (by using the align) directive (see Variables) then the compiler will force its alignment to be the minimum alignment that is required for fifos on the target architecture.

On the other hand, if the fifo buffer has been declared with an explicit alignment requirement that is less than the minimum alignment required for fifo buffers on the target architecture, an error will be raised.

Note that if the fifo buffer is declared as extern (see Variables) without an explicit align directive then a warning will be emitted indicating that proper alignment must be specified for the respective buffer definition. This warning can be suppressed by specifying an explicit alignment requirement to the extern fifo buffer declaration.

Allocating a FIFO consumes hardware resources for the duration of the program, as such they should be used sparingly.

The following restrictions apply when using a FIFO DSD in a DSD operation:

The FIFO DSD operand must be comptime-known.
A FIFO cannot be used as an operand to the @map builtin.
If a DSD operation uses more than one source operand:
- at most one operand may be a FIFO DSD, and
- the FIFO DSD operand must not be the first (left-most) source operand.

An asynchronous DSD operation that reads from an empty FIFO will be suspended until the FIFO receives an element.

An asynchronous DSD operation that writes to a full FIFO will be suspended until the FIFO is not full.

A non-asynchronous DSD operation that reads from an empty FIFO will terminate and return false. The length of the FIFO will be updated to the remaining length after the FIFO became empty. If the destination operand is a pointer to a scalar, any data popped from the FIFO during the operation will be discarded, and the value stored at the pointer will remain unchanged.

A non-asynchronous DSD operation that writes to a full FIFO will terminate and return false. The length of the FIFO will be updated to the remaining length after the FIFO became full.

FIFOs are typically used with a pair of DSD operations: one operation writing elements to the FIFO and one operation reading elements from the FIFO. For example:

@mov16(fifo, ...); // Write to the FIFO
@mov16(..., fifo); // Read from the FIFO

Task Activation on Pop and Push¶

The @allocate_fifo builtin takes an optional configuration struct with two fields, both optional. The .activate_pop field specifies a local_task_id or comptime-known task name to be activated on pop from the FIFO. The .activate_push field specifies a local_task_id or comptime-known task name to be activated on push to the FIFO. The associated task must be bound as a local task.

Note that the specified .activate_pop task is only activated on pop if the FIFO has previously hit a FIFO full event, and if the pop causes the FIFO to transition from having insufficient free space to having sufficient free space, where “sufficient free space” means sufficient space for the push operation that originally triggered the FIFO full event to proceed. The amount of space required depends on the operand size and SIMD width of the push operation that previously triggered the FIFO full event.

Similar rules apply in the other direction: the .activate_push task is only activated on push if the FIFO has previously hit a FIFO empty event, and if the push causes the FIFO to transition from having insufficient data to having sufficient data, where “sufficient data” means sufficient data in the queue for the pop operation that originally triggered the FIFO empty event to proceed.

task on_push() void { ... }
task on_pop() void { ... }

var fifo_buffer = @zeros([32]i16);
const fifo = @allocate_fifo(
  fifo_buffer,
  .{ .activate_pop = on_pop, .activate_push = on_push }
);

Changing FIFO Properties¶

The following builtins can be used to change the properties of a FIFO at runtime. Changing FIFO properties at comptime will be enabled in the future through the FIFO initialization builtin (i.e., @allocate_fifo). As was mentioned earlier, FIFOs acquire hardware resources for the duration of the program and therefore updating the properties of FIFOs happens in-place by directly accessing these hardware resources without creating new DSD values as is the case for the rest of the DSD kinds.

@set_fifo_read_length and @set_fifo_write_length¶

Update the length field of a FIFO that is associated with a read or write operation respectively.

Syntax¶

@set_fifo_read_length(fifo, length);
@set_fifo_write_length(fifo, length);

Where:

fifo is a comptime-known FIFO DSD expression.
length is a 16-bit unsigned integer expression that specifies the length to be applied in number of FIFO elements.

Example¶

var fifo_buffer = @zeros([32]i16);
// FIFOs are always initialized with read/write length zero.
const fifo = @allocate_fifo(fifo_buffer);
const fifo_length = 42;

// Sets the FIFO write length before a write operation.
@set_fifo_write_length(fifo, fifo_length);
@mov16(fifo, ...);

// Sets the FIFO read length before a read operation.
@set_fifo_read_length(fifo, fifo_length);
@move(..., fifo);

Semantics¶

The builtin will update the read or write length of the input FIFO in-place by modifying the underlying hardware resource directly.

Changing DSD Properties¶

The following builtins can be used to change DSD properties at runtime or comptime. All of these builtins will always result in a new DSD value while the input value remains unchanged.

@set_dsd_base_addr¶

Create a new memory DSD value based on the input memory DSD value and base address.

Syntax¶

@set_dsd_base_addr(input_dsd, base_addr);

Where:

input_dsd is a memory DSD expression, i.e., a DSD expression with a type that is either mem1d_dsd or mem4d_dsd.
base_addr is a tensor identifier or a pointer expression whose base-type is a tensor.

Example¶

var A = @zeros([10]i16);
// Create a new DSD that is a clone of 'input_dsd' but has
// 'A' as its base-address.
var dsd1 = @set_dsd_base_addr(input_dsd, A);
// Use a pointer expression as the new base-address parameter.
var dsd2 = @set_dsd_base_addr(input_dsd, &A);

Semantics¶

The builtin returns a new memory DSD value that is a clone of the input DSD value but with the provided base_addr parameter as the new base address. The new base address will replace both the base address and offset (if any) of the input DSD value.

@increment_dsd_offset¶

Create a new memory DSD value based on the input memory DSD value, offset and tensor element type.

Syntax¶

@increment_dsd_offset(input_dsd, offset, elem_type);

Where:

input_dsd is a memory DSD expression, i.e., a DSD expression with a type that is either mem1d_dsd or mem4d_dsd.
offset is a 16-bit signed integer that specifies the offset to be applied as number of elements of elem_type.
elem_type is a type expression that is used to convert offset into number of words. It must be a 16-bit or 32-bit numeric type (u16, i16, i16, i32, f16, or f32).

Example¶

const A = @zeros([10, 10]f32);

// dsdA is defined as a 2x2 square that is at a diagonal
// offset within A.
const dsdA = @get_dsd(mem4d_dsd, .{
  .tensor_access = |i, j|{2, 2} -> A[i + 1, j + 1]});

// Create a new DSD that is a clone of the 'dsdA' but its
// base address is moved backwards by 10 f32 elements. In
// practice, new_dsd will have moved the 2x2 square upwards
// by one row.
var new_dsd = @increment_dsd_offset(dsdA, -10, f32);

Semantics¶

The builtin returns a new memory DSD value that is a clone of the input DSD value but with a new base address that is the result of adding the offset parameter to the base address of the input DSD. The offset parameter specifies the number of tensor elements to be added to the input DSD’s base address. The builtin performs no runtime or comptime checks for out-of-bounds accesses so the user needs to be aware of such risk.

@set_dsd_length¶

Create a new DSD value based on the input DSD and length.

Syntax¶

@set_dsd_length(input_dsd, length);

Where:

input_dsd is a DSD expression with any DSD type except mem4d_dsd.
length is a 16-bit unsigned integer that specifies the length to be applied in number of tensor elements or wavelets.

Semantics¶

The builtin returns a new DSD value that is a clone of the input DSD value but with the new length applied.

@set_dsd_stride¶

Create a new 1D memory DSD value based on the input 1D memory DSD and stride.

Syntax¶

@set_dsd_stride(input_dsd, stride);

Where:

input_dsd is a DSD expression that must be of type mem1d_dsd.
stride is an 8-bit signed integer that specifies the stride to be applied in number of tensor elements.

Semantics¶

The builtin returns a new DSD value that is a clone of the input DSD value but with the new stride applied.

Queue Identifiers	Input Queue Length (words)	Output Queue Length (words)
0, 1	6	2
2, 3	4	6
4, 5	2	2
6, 7	2	N/A

SDK Documentation (1.1.0)

Data Structure Descriptors

Contents

Data Structure Descriptors¶

Basic Syntax¶

One-Dimensional Memory Vectors¶

tensor_access¶

wavelet_index_offset¶

Two-, Three-, or Four-Dimensional Memory Vectors¶

tensor_access¶

wavelet_index_offset¶

Pointers To Scalars As Destinations¶

Fabric Input Vectors¶

Fabric Output Vectors¶

control¶

wavelet_index_offset¶

FIFOs¶

Task Activation on Pop and Push¶

Changing FIFO Properties¶

@set_fifo_read_length and @set_fifo_write_length¶

Syntax¶

Example¶

Semantics¶

Changing DSD Properties¶

@set_dsd_base_addr¶

Syntax¶

Example¶

Semantics¶

@increment_dsd_offset¶

Syntax¶

Example¶

Semantics¶

@set_dsd_length¶

Syntax¶

Semantics¶

@set_dsd_stride¶

Syntax¶

Semantics¶

Asynchronous DSD Operations¶

Completion of Asynchronous DSD Operations¶

Dynamic Completion Based on Control Wavelets¶

Hardware Resources and Asynchronous DSD Operations¶

Fabric Queues¶

Microthreads¶

Microthread Priority¶

Explicit Index Offset¶

Advanced DSD Features¶

SIMD Mode¶

Reset a Source Operand¶

Advancing Switch Positions¶

Control Wavelet Transform¶

`tensor_access`¶

`wavelet_index_offset`¶

`tensor_access`¶

`wavelet_index_offset`¶

`control`¶

`wavelet_index_offset`¶