Filament/ADL Integration

[gabizon103]

Exploring how we can use Filament as a way to integrate designs generated from tools like HLS and XLS. This is a running, exploratory-type thing so I figured it'd be better to put in a discussion rather than issues.

[gabizon103]

I used MachSuite to generate some HLS designs - for now, just gemm and aes. The aes design has variable latency for some reason, but gemm is statically scheduled. However, the interface that gets exposed is not very nice to use. The aes interface looks like this:

module aes256_encrypt_ecb (
      ap_clk,
      ap_rst,
      ap_start,
      ap_done,
      ap_idle,
      ap_ready,
      ctx_address0,
      ctx_ce0,
      ctx_we0,
      ctx_d0,
      ctx_q0,
      ctx_address1,
      ctx_ce1,
      ctx_we1,
      ctx_d1,
      ctx_q1,
      k_address0,
      k_ce0,
      k_q0,
      buf_r_address0,
      buf_r_ce0,
      buf_r_we0,
      buf_r_d0,
      buf_r_q0,
      buf_r_address1,
      buf_r_ce1,
      buf_r_we1,
      buf_r_d1,
      buf_r_q1
);

It might be more trouble than it is worth to figure out what source-level constructs each of these ports map to, but not impossible. The gemm interface is a bit more straightforward:

module gemm (
        ap_clk,
        ap_rst,
        ap_start,
        ap_done,
        ap_idle,
        ap_ready,
        m1_address0,
        m1_ce0,
        m1_q0,
        m1_address1,
        m1_ce1,
        m1_q1,
        m2_address0,
        m2_ce0,
        m2_q0,
        m2_address1,
        m2_ce1,
        m2_q1,
        prod_address0,
        prod_ce0,
        prod_we0,
        prod_d0
);

My thinking is that if we want to make integrating with HLS designs easier on an RTL level, we might be limited by the annoying-to-use interfaces exposed by the compiler. It also might not scale well for designs that have more complicated data structures as inputs. gemm seems reasonable because the inputs are just matrices, but by looking at aes it seems like this might blow up pretty quickly if you start using even things like simple structs to keep track of data passed into/out of the design. I'll spend some time experimenting with this, but right now it is looking like XLS might be the better option since it is hopefully less opaque and easier to use than the HLS compiler.

[rachitnigam]

Awesome, thanks for digging into this and documenting the interfaces out. I think you're right that the default interfaces exposed here leave a lot to be desired. We can try pinging some other people who've played with HLS tools a bit more but moving onto XLS is probably the right move for now.

[sampsyo]

Awesome! Just to start walking through what is evident from the code itself, we start with:

        ap_clk,
        ap_rst,
        ap_start,
        ap_done,

…which are actually pretty reminiscent of Calyx interface ports (where start = go and done = done).

It looks to me like the rest of the ports here are all for external memories? For example, check out the C signature for aes:
https://github.com/breagen/MachSuite/blob/6236e593012cb86b0d2f08d9fb9ba0411ff989b4/aes/aes/aes.c#L176

It takes 3 arrays as arguments: ctx, k, and buf. Note that the remaining ports there are all named after those arrays. Of course, it's anyone's guess exactly what ce, we, d, and q mean in the context of each external-memory interface (although we is almost certainly "write enable"). But one way or another, this is how Vitis is setting up accesses to arrays.

[rachitnigam]

Yeah, ce is clock enable probably. One recommendation from @andrewb1999 was that for purely statically scheduled modules, we ignore the done signal completely and start reading off the data as soon as the expected number of cycles elapses.

The document also looks promising: Interfaces of HLS designs and might shed light on how to use the designs.

[gabizon103]

XLS Demo

I think we were right; XLS seems easier to work with.
I made a branch called adl for messing around with this kind of stuff, so the examples are there in apps/xls. I wrote a simple DSLX program:

pub fn mul(
    a: u32,
    b: u32
) -> u32 {
    a * b
}

I thought multiplication would be a good and simple example because I wanted to parameterize this over pipeline stages (latency). I wasn't sure how the XLS compiler would implement multiplication, and thought that it might split up the computation over a few pipeline stages. The Verilog that gets emitted ends up being a little silly:

module Mul(
  input wire clk,
  input wire [31:0] a,
  input wire [31:0] b,
  output wire [31:0] out
);
  // lint_off MULTIPLY
  function automatic [31:0] umul32b_32b_x_32b (input reg [31:0] lhs, input reg [31:0] rhs);
    begin
      umul32b_32b_x_32b = lhs * rhs;
    end
  endfunction
  // lint_on MULTIPLY

  // ===== Pipe stage 0:

  // Registers for pipe stage 0:
  reg [31:0] p0_a;
  reg [31:0] p0_b;
  always_ff @ (posedge clk) begin
    p0_a <= a;
    p0_b <= b;
  end

  // ===== Pipe stage 1:

  // Registers for pipe stage 1:
  reg [31:0] p1_a;
  reg [31:0] p1_b;
  always_ff @ (posedge clk) begin
    p1_a <= p0_a;
    p1_b <= p0_b;
  end

  // ===== Pipe stage 2:

  // Registers for pipe stage 2:
  reg [31:0] p2_a;
  reg [31:0] p2_b;
  always_ff @ (posedge clk) begin
    p2_a <= p1_a;
    p2_b <= p1_b;
  end

  // ===== Pipe stage 3:
  wire [31:0] p3_umul_18_comb;
  assign p3_umul_18_comb = umul32b_32b_x_32b(p2_a, p2_b);

  // Registers for pipe stage 3:
  reg [31:0] p3_umul_18;
  always_ff @ (posedge clk) begin
    p3_umul_18 <= p3_umul_18_comb;
  end
  assign out = p3_umul_18;
endmodule

The multiplication is implemented combinationally and no computations happen until the last stage. I was having issues compiling XLS's float32::mul, which I thought might be a better example, so I just continued with this because it would still illustrate the point pretty well.

Steps

I think working through this example by hand reveals some important steps in going from ADL -> Filament that we would need to generalize in order to implement #364. I'll list them here with code snippets, though a working example is in the repo.

1. We write our program (here, in DSLX) and then compile it to Verilog. Then, we put that implementation in some file in our Filament design (I'll call it impl.v). Then, we give it a Filament signature. At this point, we have a latency specific to this implementation that we encode into the signature. Here's an example for a multiplier with 4 pipeline stages:

extern "impl.v" {
    comp Mul<'G:1>(
        clk: 1,
        a: ['G, 'G+1] 32,
        b: ['G, 'G+1] 32
    ) -> (
        out: ['G+4, 'G+5] 32
    );
}

2. Next, we create a wrapper around that specific multiplier to give it an existential parameter:

comp MulWrapper<'G:1>(
    clk: 1,
    a: ['G, 'G+1] 32,
    b: ['G, 'G+1] 32
) -> (
    out: ['G+L, 'G+L+1] 32
) with {
    some L where L > 0;
} {
    m := new Mul<'G>(a, b);
    out = m.out;

    L := 4;
}

3. Create an abstract multiplier in Filament. We need something that will instantiate the wrapper around our multiplier, where the abstract multiplier's latency is the wrapper's latency. Because of existential parameters, this will obviously work with any multiplier implementation that has a wrapper around it for its existential parameters. The abstract multiplier looks like this:

comp MulAbstract<'G:1>(
    a: ['G, 'G+1] 32,
    b: ['G, 'G+1] 32
) -> (
    out: ['G+L, 'G+L+1] 32
) with {
    some L where L > 0;
} {
    M := new MulWrapper;
    m := M<'G>(a, b);
    out = m.out;

    L := M::L;
}

4. Now, one of two things can happen. The Aetherling example has another level called Wrapper that wraps the abstract module. Rachit can clarify if I'm wrong, but it looks like this happens because we at some point need to specify how many inputs we want to perform the convolution on (in the example, it is 16) and then serialize the data to reuse the Conv2dAbstract instance as necessary. For the multiplier (and modules with similar interfaces), however, there is no need to transform our inputs or outputs so we can just call MulAbstract in main or whatever other context we want to use it in, and it should be fine:

comp main<'G:1>(
    go: interface['G],
    a: ['G, 'G+1] 32,
    b: ['G, 'G+1] 32,
) -> (
    out: ['G+L, 'G+L+1] 32
) with {
    some L where L > 0;
} {
    M := new MulAbstract;
    m := M<'G>(a, b);
    out = m.out;
    L := M::L;
}

In general, I think nothing too crazy happens at any of these stages. One thing that might require some thinking is step 4, where we need to do something to transform the inputs and outputs. I guess the tool could stop at the Abstract module and leave it up to the user to transform the inputs and outputs correctly for actual use. This seems like a good idea because it would let the user control things like reuse of the Abstract modules, like any other module, for example. The only thing gen/opt is responsible for emitting is a module that wraps some implementation with existential parameters.