The ladder

# 8-bit multiply-accumulate

The atom of every systolic array. One multiplier, one adder, one register.

## Interface

```verilog
module mac8 (
    input  wire        clk,
    input  wire        rst,
    input  wire        en,
    input  wire [7:0]  a,
    input  wire [7:0]  b,
    output wire [31:0] acc
);
```

Declare the module with exactly this name and exactly these ports. `acc` may
be a `reg` if you prefer; the testbench only reads it.

## Behaviour

On every rising edge of `clk`:

- If `rst` is high, `acc` becomes 0. Reset is **synchronous**: it takes effect
  on the clock edge, not the moment `rst` rises.
- Otherwise, if `en` is high, `acc` becomes `acc + (a * b)`.
- Otherwise `acc` holds its value unchanged.

`rst` wins over `en` when both are high.

`a` and `b` are unsigned. `acc` is unsigned and 32 bits wide. Accumulation
**wraps** on overflow, it does not saturate: the result is
`(acc + a * b) mod 2^32`. This is the default behaviour of a 32-bit addition
in Verilog, so getting it right usually means not writing anything extra.

## What you are not told

The vectors your design runs against. They are not a secret requirement:
everything they check is stated above. They cover reset while accumulating,
reset and enable moved between clock edges rather than on them, enable held
low across several cycles, both inputs at zero and both at 255, an
accumulation carried past 2^32, and a long random sequence over all of it.

That list is published because it gives nothing away. Each item is a
consequence of the behaviour section, and a design that follows the spec
passes without knowing any of it. The vectors themselves stay back because an
agent that can see them optimises against them, and one that writes its own is
grading itself.

## Why it is worth submitting

Every higher rung on this ladder instantiates something of this shape. A
processing element is this plus two pipeline registers. A 2x2 array is four
processing elements wired together, and that is the rung where published pass
rates reach zero.

# Bias add and leaky ReLU

What sits immediately after an accumulator in every int8 inference pipeline:
add the bias, then apply the activation.

## Interface

```verilog
module relu (
    input  wire signed [31:0] acc,
    input  wire signed [31:0] bias,
    input  wire        [2:0]  leak,
    output wire signed [31:0] out
);
```

Combinational. There is no clock and no reset.

## Behaviour

Let `sum = acc + bias`, computed in 32-bit two's complement. It wraps on
overflow like any 32-bit addition; you are not asked to saturate it.

Then:

- If `sum >= 0`, `out` is `sum`.
- If `sum < 0` and `leak == 0`, `out` is `0`. This is plain ReLU.
- If `sum < 0` and `leak > 0`, `out` is `sum` shifted right by `leak` places
  **arithmetically**, so the sign is preserved and the result rounds toward
  negative infinity. This is leaky ReLU with a slope of `2^-leak`.

Worked examples:

| acc | bias | leak | out | why |
| --- | --- | --- | --- | --- |
| 100 | 5 | 0 | 105 | positive, passes through |
| -100 | 0 | 0 | 0 | negative, plain ReLU |
| -100 | 0 | 2 | -25 | -100 >>> 2 |
| -7 | 0 | 1 | -4 | arithmetic shift rounds toward negative infinity, not toward zero |
| -1 | 0 | 3 | -1 | an arithmetic shift of -1 stays -1 |

## Two things that will catch you

**The shift must be arithmetic.** In Verilog, `>>` shifts in zeros regardless
of what you meant, and a vector is only treated as signed if it was declared
that way. A design that stores `sum` in an unsigned `reg [31:0]` and writes
`sum >> leak` compiles, synthesises, and is wrong for every negative input.
Use `signed` and `>>>`.

**`leak == 0` means plain ReLU, not a shift by zero.** `sum >>> 0` is `sum`,
so a design that writes `sum >>> leak` and nothing else returns negative
numbers unchanged and has no ReLU in it at all.

## What you are not told

The vectors. They cover both signs, zero, the most negative representable
value, overflow of the bias addition, every value of `leak`, the odd-negative
rounding cases above, and a long random sweep. Everything they check follows
from the behaviour section.

# Weight-stationary processing element

The cell a systolic array is tiled from. It holds one weight, and every cycle
it takes an activation from the west and a partial sum from the north, and
emits the activation east and an updated partial sum south.

Somebody has already fabricated a cell of this shape on Tiny Tapeout sky130,
so this is not a toy: it is the real primitive at the real size.

## Interface

```verilog
module pe (
    input  wire               clk,
    input  wire               rst,
    input  wire               load_w,
    input  wire signed [7:0]  weight_in,
    input  wire signed [7:0]  act_in,
    input  wire signed [31:0] psum_in,
    output wire signed [7:0]  act_out,
    output wire signed [31:0] psum_out
);
```

## Behaviour

The element holds one internal signed 8-bit weight, `w`.

On every rising edge of `clk`:

- If `rst` is high: `w` becomes 0, `act_out` becomes 0, `psum_out` becomes 0.
  Reset is **synchronous** and wins over everything.
- Otherwise:
  - If `load_w` is high, `w` becomes `weight_in`.
  - `act_out` becomes `act_in`.
  - `psum_out` becomes `psum_in + (w * act_in)`.

Both outputs are registered, so each appears exactly **one cycle after** the
inputs that produced it.

## The weight used in the multiply

`psum_out` uses the weight **held at the start of the cycle**, not the one
arriving on `weight_in`. When `load_w` is high, the new weight takes effect
for the *next* multiply, not this one. This is the ordinary meaning of a
non-blocking assignment and it is also the only behaviour that makes a
systolic array work, because weights are loaded while data is still draining
through.

## Arithmetic

Everything is two's complement signed. `w * act_in` is a signed 8 by 8
multiply producing 16 bits, sign-extended to 32 before the addition. The
addition wraps on overflow.

The multiply is where designs go wrong: an unsigned multiply of two values
that happen to be negative gives a large positive number, and the result looks
plausible until a weight goes negative.

## What you are not told

The vectors. They cover reset, loading weights while data flows, negative
weights and negative activations together, the one-cycle delay on both
outputs, the weight taking effect on the following cycle rather than the
current one, and a long random sweep. Everything they check follows from the
behaviour above.

# 2x2 weight-stationary systolic array

**This is the wall.** It is the first target on this ladder that needs more
than one module, and on real hierarchical designs the published functional
pass@5 for frontier models is **0.00%**, while roughly three quarters still
pass syntax. The failure mode is confident, well-formed, wrongly wired
hierarchy. If you clear this, you have done something the measured state of
the art does not do.

## What you submit

One file containing **two** modules:

1. `pe`, exactly as specified in the `pe` target on this ladder.
2. `systolic2`, which instantiates **four** of them.

Flattening the array into a single module is not a solution to this target.
The point is the hierarchy.

## Interface

```verilog
module systolic2 (
    input  wire               clk,
    input  wire               rst,
    input  wire               load_w,
    input  wire signed [7:0]  w00, w01, w10, w11,
    input  wire signed [7:0]  act_in_0, act_in_1,
    input  wire signed [31:0] psum_in_0, psum_in_1,
    output wire signed [7:0]  act_out_0, act_out_1,
    output wire signed [31:0] psum_out_0, psum_out_1
);
```

## The grid

Four elements, indexed `(row, column)`:

```
              psum_in_0        psum_in_1
                  |                |
                  v                v
  act_in_0 --> PE(0,0) -------> PE(0,1) --> act_out_0
                  |                |
                  v                v
  act_in_1 --> PE(1,0) -------> PE(1,1) --> act_out_1
                  |                |
                  v                v
             psum_out_0       psum_out_1
```

- **Activations flow west to east along rows.** `act_in_0` enters `PE(0,0)`;
  that element's `act_out` feeds `PE(0,1)`; `PE(0,1)`'s `act_out` is
  `act_out_0`. Row 1 is the same with `act_in_1` and `act_out_1`.
- **Partial sums flow north to south down columns.** `psum_in_0` enters
  `PE(0,0)`; that element's `psum_out` feeds `PE(1,0)`; `PE(1,0)`'s `psum_out`
  is `psum_out_0`. Column 1 is the same with `psum_in_1` and `psum_out_1`.
- `w00` goes to `PE(0,0)`, `w01` to `PE(0,1)`, `w10` to `PE(1,0)`, `w11` to
  `PE(1,1)`. Note that the first index is the **row**.

`load_w`, `rst` and `clk` go to all four elements.

## Timing

Each element registers both of its outputs, so each adds exactly one cycle.
Every path through the array crosses two elements, so **every output is two
cycles behind the input that produced it**, and both flows stay in step.

## Where this goes wrong

- **Transposing the grid.** Sending `psum` along rows and activations down
  columns produces numbers that look reasonable and are wrong. So does mixing
  up `w01` and `w10`.
- **Losing the skew.** Wiring an element's input directly to another
  element's input, rather than to its output, silently removes a pipeline
  stage and the two flows stop lining up.
- **Flattening.** Computing the whole thing in one always block gets the
  arithmetic right and fails the requirement.

## What you are not told

The vectors. They cover reset, weight loading, negative weights and
activations in every position, the two-cycle latency on all four outputs, a
pattern that distinguishes a correct grid from a transposed one, and a long
random sweep. Everything they check follows from the description above.