4. Parameters

The previous tutorial wrote a complete program that copies data to and from the device, but both the host and device still need to define the dimensions M and N. This tutorial introduces compile time parameters to set M and N while compiling the code, and shows how your host code can read these values from the compile output.

Learning Objectives

After completing this tutorial, you should know how to:

Define compile time parameters for your device code
Set the value of compile time parameters when compiling
Read the value of compile time parameters from compile output in your host code

Example Overview

Your program will run on a single processing element (PE). Like the previous tutorials, this tutorial demonstrates the program with a simulated fabric consisting of an 8 x 3 block of PEs. The problem steps are identical to the previous tutorial. The device code needs to be modified to replace the constants M and N with parameters, and the compile command needs to be modified to set these parameter values. The host code must be modified to read these values from compile output.

Modify the CSL

How must the layout code be modified to support compile time parameters for M and N?

Define top-level parameters for M and N that will be set by the compile command
Pass these parameters along to the PE program

Take a look at the modified layout.csl:

param M: i16;
param N: i16;

const memcpy = @import_module("<memcpy/get_params>", .{ .width = 1, .height = 1 });

layout {
  @set_rectangle(1, 1);
  @set_tile_code(0, 0, "pe_program.csl", .{
    .memcpy_params = memcpy.get_params(0),
    .M = M,
    .N = N
  });

  // export symbol names
  @export_name("A", [*]f32, true);
  @export_name("x", [*]f32, true);
  @export_name("b", [*]f32, true);
  @export_name("y", [*]f32, false);
  @export_name("init_and_compute", fn()void);
}

Notice that two parameters are defined at the top of the file:

param M: i16;
param N: i16;

These parameters are also passed along to the PE program inside of the @set_tile_code call:

@set_tile_code(0, 0, "pe_program.csl", .{
  .memcpy_params = memcpy.get_params(0),
  .M = M,
  .N = N
});

Now take a look at the modified pe_program.csl:

param memcpy_params;

// Matrix dimensions
param M: i16;
param N: i16;

// memcpy module provides infrastructure for copying data
// and launching functions from the host
const sys_mod = @import_module("<memcpy/memcpy>", memcpy_params);

// 48 kB of global memory contain A, x, b, y
var A: [M*N]f32; // A is stored row major
var x: [N]f32;
var b: [M]f32;
var y = @zeros([M]f32); // Initialize y to zero

// DSDs for accessing A, b, y
// A_dsd accesses column of A
var A_dsd = @get_dsd(mem1d_dsd, .{ .tensor_access = |i|{M} -> A[i*N] });
var b_dsd = @get_dsd(mem1d_dsd, .{ .base_address = &b, .extent = M });
var y_dsd = @get_dsd(mem1d_dsd, .{ .base_address = &y, .extent = M });

// ptrs to A, x, b, y will be advertised as symbols to host
var A_ptr: [*]f32 = &A;
var x_ptr: [*]f32 = &x;
var b_ptr: [*]f32 = &b;
const y_ptr: [*]f32 = &y;

// Compute gemv
fn gemv() void {
  // Loop over all columns of A
  for (@range(i16, N)) |i| {
    // Calculate contribution to A*x from ith column of A, ith elem of x
    @fmacs(y_dsd, y_dsd, A_dsd, x[i]);
    // Move A_dsd to next column of A
    A_dsd = @increment_dsd_offset(A_dsd, 1, f32);
  }
  // Add b to A*x
  @fadds(y_dsd, y_dsd, b_dsd);
}

// Call initialize and gemv functions
fn init_and_compute() void {
  gemv();
  sys_mod.unblock_cmd_stream();
}

comptime {
  @export_symbol(A_ptr, "A");
  @export_symbol(x_ptr, "x");
  @export_symbol(b_ptr, "b");
  @export_symbol(y_ptr, "y");
  @export_symbol(init_and_compute);
}

pe_program.csl must also contain parameter declarations for M and N. When this file is compiled, it uses the values passed to it by layout.csl’s @set_tile_code call to bind them. M and N are no longer hard-coded in this file.

Compile and Run the Program

The device and host code now use the compile time parameters, but how are they set? The compile command now includes a --params flag, which specifies the values:

$ cslc layout.csl --fabric-dims=8,3 --fabric-offsets=4,1 --params=M:4,N:6 --memcpy --channels=1 -o out
$ cs_python run.py --name out

The run command stays the same. You should see a SUCCESS! message at the end of execution.

Exercises

A is stored row-major in the above code. How would you rewrite A_dsd and the gemv function if A were stored column major instead?

This series has now gone over some basics for writing a complete program using a single PE. The next tutorial moves on to using multiple PEs.

Start Here

Tutorials

Development Guides

Debugging

CSL Language Reference

Host API Reference

Learning Objectives

Example Overview

Modify the CSL

Compile and Run the Program

Exercises

Next

​Learning Objectives

​Example Overview

​Modify the CSL

​Compile and Run the Program

​Exercises

​Next

Learning Objectives

Example Overview

Modify the CSL

Compile and Run the Program

Exercises

Next