More › fpga

More

FPGA components

Extension — not covered by the 1.0 stability promise (fpga; the core)

A component with a clock is hardware. You write it as any other component: ports, variables, functions in the action language, a state machine, test cases. archec reads the same model three ways. The simulator runs it cycle by cycle. archec gen --target vhdl writes it as synthesisable VHDL. archec test --target vhdl runs its test cases on that VHDL, in GHDL. archec synth synthesises it, places and routes it for a device, and says what it takes and how fast it runs.

This page builds a PWM generator: a register block a processor writes, an over-current input that trips the output, and a heartbeat LED. The finished model is examples/fpga-pwm/main.arche. A second one, examples/fpga-uart/main.arche, has two clocks: a UART receiver on its own clock sets the duty cycle of a PWM on another.

What you need#

Writing, checking, simulating and generating need nothing more than archec. Running the VHDL needs GHDL, a free VHDL simulator. Synthesis needs Yosys and nextpnr (where they come from). arche-lang downloads neither.

  • In VS Code, install the build of the extension for your machine (arche-lang-darwin-arm64.vsix, -darwin-x64, -linux-x64 or -win32-x64). It carries GHDL.
  • Without the extension, install GHDL (brew install ghdl, apt install ghdl, or a release unpacked in ~/.arche/fpga). archec also takes ARCHE_GHDL=/path/to/ghdl.

Where GHDL comes from has the versions and the platforms.

1. A component with a clock#

component Pwm "PWM generator" {
  clock clk 100MHz
  reset rst_n active low async
  step tick

  in over_current: bool "Over-current"
  out pwm:         bool "PWM"

  var counter: uint8 = 0
  var periods: uint16 = 0

  fn tick "Every clock cycle"
}
Diagram: PWM generator
What archec draws from this code: PWM generator
You write Meaning
clock clk 100MHz The component is an FPGA component. clk is the clock's name, 100MHz its frequency. Every rising edge is one cycle.
reset rst_n active low async Its reset: a name, active high or active low, sync or async. With no reset line it is rst, active high, synchronous.
step tick The function called on every cycle, as a thread's step is called every period.
in over_current: bool A signal: a port whose type is a data type.
var counter: uint8 = 0 A register. Its first value is its value at reset.

clock 10ms, with one value, keeps its old meaning: the period of a component that is not hardware.

Signals and widths#

A port typed with data is a signal of that width. In a body it is a name, as a variable is: an in signal is read, an out signal is assigned.

Type Width
bool 1 bit (std_logic on the entity)
uint8, uint16, uint32, uint64 8 to 64 bits, unsigned
int8 … int64 8 to 64 bits, signed
an enum the bits its literals need
type Adc12 = uint16 { bits 12 } 12 bits: bits on a type gives any width up to 64
type Adc12 = uint16 { bits 12 }

component Filter "Filter" {
  clock clk 50MHz
  in sample: Adc12
  out level: Adc12
}
Diagram: Filter
What archec draws from this code: Filter

An array has a size (var taps: uint8[4]). Floats and strings have no bits: the checker says so.

Arithmetic means what it means in the simulator. An expression is computed in full: the sum of two uint8 has 9 bits, and a uint8 less a uint8 may be negative. It is cut to its width where it is assigned, so a counter wraps. A shift left stays in the width of what it shifts. A value of a type with bits 12 wraps at 12 bits, on the simulator too.

Messages#

A port that sends or receives messages stays what it is. Between two FPGA parts a message is a handshake: valid from the sender with the message's fields as a record (data), and ready from the receiver.

message PERIOD_DONE "Period done" { periods: uint16 }

component Heartbeat "Heartbeat" {
  clock clk 100MHz
  reset rst_n active low async
  in beat:   data receives PERIOD_DONE { handler PERIOD_DONE -> on_period }
  out led:   bool "LED"
  var count: uint8 = 0

  fn on_period(periods: uint16) ```arche
    if count == 1 {
      count = 0
      led = not led
    } else {
      count += 1
    }
  ```
}
Diagram: Heartbeat
What archec draws from this code: Heartbeat

A sender holds valid until ready. A receiver is ready when it can take the message: When the receiver is not ready says when that is. A message port linked to nothing inside is a port of the top entity. In a test, sent(MSG) counts the messages a link carries.

Registers on a bus#

A memory block with an address is a register the processor beside the FPGA reaches over the bus. archec writes the AXI4-Lite bank (regmap.md) and wires it to the component.

component Regs "Registers" {
  clock clk 100MHz
  memory CTRL @ 0x4000_0000 : uint32 rw { enable: uint8 bits "0:0" }
  memory DUTY @ 0x4000_0004 : uint32 rw
  memory STATUS @ 0x4000_0008 : uint32 r
}
Diagram: Registers
What archec draws from this code: Registers

In a body CTRL and DUTY are read: the bus writes them (rw, w). STATUS is assigned: the logic drives it and the bus reads it (r).

2. What it does#

The bodies are the action language, as everywhere. This is the PWM's tick and its state machine:

const PERIOD = 100
const ENABLE = 1

component Pwm "PWM generator" {
  clock clk 100MHz
  reset rst_n active low async
  step tick
  memory CTRL @ 0x4000_0000 : uint32 rw
  memory DUTY @ 0x4000_0004 : uint32 rw
  in over_current: bool
  out pwm:         bool
  var counter:     uint8 = 0

  fn tick ```arche
    if over_current and state != Tripped { goto Tripped }
    if state == Running {
      pwm = counter < DUTY
      if counter == PERIOD - 1 { counter = 0 } else { counter += 1 }
    } else {
      pwm = false
      counter = 0
    }
  ```

  states {
    initial Idle
    state Idle
    state Running
    state Tripped
    Idle -> Running [CTRL & ENABLE == ENABLE]
    Running -> Idle [CTRL & ENABLE == 0]
    Tripped -> Tripped [over_current]
    Tripped -> Idle on "after 1us"
  }
}
Diagram: PWM generator
What archec draws from this code: PWM generator

What a cycle does#

On each rising edge, in this order:

  1. fn main, when the component has one: its statements up to its next wait.
  2. Each message taken on this edge: the transition it triggers, the port's on-receive, its handlers.
  3. The transitions on "after …" whose time has come.
  4. The transitions with a guard and no trigger. They are tried on every cycle.
  5. The step function.

A body reads what it has just written, as in any other component. Outputs are registered: what a cycle computes is seen outside from the next cycle.

Time is counted in cycles#

on "after 1us" is 100 cycles of a 100 MHz clock. A duration that is not a whole number of cycles is rounded up. Durations go down to the picosecond: 800ps, 6.4ns. fn main runs on its own, and its wait is counted the same way:

component Blink "Blink" {
  clock clk 100MHz
  out led: bool
  fn main ```arche
    while true {
      led = not led
      wait 500ns
    }
  ```
}
Diagram: Blink
What archec draws from this code: Blink

Keep the waits at the top of fn main or of its while true loop. A wait anywhere else is not synthesised.

States inside states#

A state may hold states, as in any other component. The hardware keeps one register: the innermost state it is in. The states around it are known from it, so state == On is true in every state inside On.

states {
  initial Off
  state Off
  state On {
    state Pick { pseudo choice }
    state Heating {
      state Low
      state High
      Low -> High [ticks >= 12]
    }
    state Soak
    Pick -> High [level > 100]
    Pick -> Low [level > 0]
    Pick -> Soak
    Heating -> Soak on "after 100ns"
  }
  Off -> Pick on GO / level = power
  On -> Off on STOP
}
You write What the hardware does
On -> Off on STOP Taken in any state inside On. Each on-exit runs from the inside out, then the action, then each on-enter from the outside in.
A transition into Heating It enters its first state (Low), or the one marked pseudo initial.
Heating -> Soak on "after 100ns" Counted from when Heating was entered. A change of state inside it does not start the count again.
state Pick { pseudo choice } Left in the cycle it is entered, by its first transition whose guard holds. Give it a last transition with no guard.
A transition of the state it is in, and one of a state around it The one of the innermost state is tried first.
goto Off in a body The same exits and entries as a transition from where it is.

The simulator and the VHDL run these the same way. A region (region left), a history state, a fork and a join are not synthesised: archec check says so. Two regions are two machines: make each a component.

When the receiver is not ready#

A message is a handshake. The sender holds valid and the fields until the receiver's ready is high on a clock edge.

When a receiver is ready.

The in port It takes a message
has an on-receive or a handler for it on every cycle
has neither, and transitions are triggered by it in the states those transitions leave (and the states inside them)
has depth N while it keeps fewer than N. It hands them one a cycle to the rule above.
component Worker "Worker" {
  clock clk 100MHz
  in items: data receives ITEM
  states {
    initial Idle
    state Idle
    state Busy
    Idle -> Busy on ITEM / take(n)
    Busy -> Idle on "after 40ns"
  }
}

Worker takes an ITEM in Idle. In Busy its ready is low and the item waits at its sender. With in items: data receives ITEM { depth 3 } three items wait in the port itself.

What a sender does when its port is full. An out port keeps one message until it is taken, or depth N of them.

Where the send is With no room on the port
At the top of fn main, or of its while true loop It waits. main goes on when there is room.
Anywhere else: the step function, a handler, an action, inside an if The message is dropped. The cycle goes on.

A dropped message is never silent. The test run says it, on the simulator and in GHDL:

PASS  TP/TC-DROP  A step that sends every cycle
        note: 2 TICK dropped (the first at 30ns): the port they were sent on was full — give it a `depth`, or send from the top of fn main, which waits for room

In a case, dropped(MSG) is how many were dropped: at 1us expect dropped(TICK) == 0. A message a test sends from outside the FPGA (do send host.port MSG { … }) waits the same way, one behind the other.

3. What cannot be synthesised#

archec check reads every body of an FPGA component as hardware and says what cannot be made, where it is written:

main.arche:26:12 error f: a floating-point type has no bits to synthesise: use an integer, or a fixed-point value in an integer (millivolts in a uint16) [fpga-synthesis]
main.arche:27:5 error a while loop has no known number of turns, and in hardware a loop runs within one cycle: write `for i in 0..N { … }` with a constant N, or spread the work over cycles with a state [fpga-synthesis]
main.arche:25:15 warning counter is uint8: this value has 12 bits, its top 4 are lost — widen counter, or keep the bits you want (`& 0xFF`) [fpga-width]
Refused Write instead
float32, float64, a number like 1.5 An integer, or fixed-point in an integer.
A string, a duration as a value An enum or a number; wait and after count the cycles.
An array with no size var buf: uint8[8], or a constant for the size.
while c { … } for i in 0..N { … } with constant bounds, or a state.
A function that calls itself The loop it stands for.
port.op(…), a call to another part A message, or a signal.
A Python or TypeScript body The action language.

An assignment that loses bits is a warning (fpga-width): a uint16 value into a uint8, the literal 300 into a uint8. counter += 1 is not one: a counter wraps at its own width, here as in the simulator. A division by anything but a constant power of two is a warning too (fpga-divide): it is synthesised, as a large and slow circuit.

In VS Code these appear in the editor as you type.

4. The system#

component Fpga "FPGA" { kind fpga; chip "LFE5U-25F-6BG381" }

system PwmBoard "PWM board" {
  part fpga:  Fpga
  part pwm:   Pwm
  part heart: Heartbeat
  pwm.beat -> heart.beat
}

deployment OnFpga "On the FPGA" {
  system PwmBoard
  platform PwmBoard
  binary bitstream "pwm_board_top.bit" on fpga {
    thread logic { runs pwm, heart }
  }
}
Diagram: PWM board
What archec draws from this code: PWM board

The FPGA parts of a system and its links between them are the top entity. A port that no link inside drives or reads is a port of the top. The deployment is optional. With one, a binary on a kind fpga part names the bitstream, and the top holds the parts its threads run. The chip of the kind fpga part is the device: archec synth builds for it.

Several clocks#

A clock's name is its domain. Parts whose clocks have different names are on different clocks, each a pin of the top:

component UartRx "UART receiver" {
  clock clk_uart 2MHz
  out bytes: data sends BYTE { depth 2 }
}
component Pwm "PWM" {
  clock clk 50MHz
  in bytes: data receives BYTE
}
system UartBoard "UART board" {
  part uart: UartRx
  part pwm:  Pwm
  uart.bytes -> pwm.bytes
}
Diagram: UART board
What archec draws from this code: UART board

archec makes each link between two clocks safe, in vhdl/arche_cdc.vhd:

The link carries It goes through What it costs
a bool signal two flip-flops of the reader's clock (arche_sync) The reader's logic sees a change on its third edge after it.
a message a two-phase handshake (arche_handshake): a request and an acknowledgement, each through two flip-flops; the fields are held still while they are read The receiver gets it two or three of its cycles after the sender's edge. The sender's port is free again two or three of its own cycles after the receiver took it.

A handshake was chosen over an asynchronous FIFO: it is small, it needs no memory, and it works for any two frequencies. It carries one message at a time, about one every three cycles of each clock. For more, give the sender's port a depth: it keeps the burst while the handshake carries it across.

archec check reports the links that cannot be made safe, or may lose something:

main.arche:42:3 error fast.level -> slow.level goes from clock clk_a to clock clk_b, and level is uint8: its 8 bits do not change at one instant for another clock, which could read a value that never was. Send it as a message (a handshake carries it across), or make it one bit (a bool goes through two flip-flops) [fpga-cdc]
main.arche:43:3 warning fast.flag -> slow.flag goes from clock clk_a to the slower clock clk_b, through two flip-flops: a pulse shorter than a cycle of clk_b (20 ns) can be missed — hold it for two cycles of clk_b, or send a message [fpga-cdc]

The simulator runs each clock with its own period and puts the same flip-flops on each crossing, so a case sees a message arrive on the same edge as in GHDL. All the clocks have an edge at time 0: in a test, the edges of a clock are at whole numbers of its period.

5. Generate the VHDL#

archec gen main.arche --target vhdl -o out
File What it is
vhdl/fpga_pwm_pkg.vhd The model's data: constants, enums, a record per message, each component's states.
vhdl/pwm_comp.vhd, vhdl/heartbeat.vhd One entity and architecture per component.
vhdl/pwm_regs.vhd The AXI4-Lite register bank of Pwm.
vhdl/pwm_board_top.vhd The system's top: the parts and the bank, wired.
vhdl/arche_cdc.vhd Only with several clocks: the synchronisers of the links between them.
vhdl/tb/tb_<case>.vhd A testbench per test case.
vhdl/sources.txt The files in the order a tool compiles them.

It is VHDL-2008 with ieee.numeric_std. A component is one clocked process whose variables are the registers. Each piece names the model element it comes from:

entity pwm_comp is
  port (
    clk          : in  std_logic;  -- clock clk: 100 MHz
    rst_n        : in  std_logic;  -- reset, active low, asynchronous
    over_current : in  std_logic;  -- in over_current: bool "Over-current"
    pwm          : out std_logic;  -- out pwm: bool "PWM"
    beat_valid   : out std_logic;  -- out beat: sends a PERIOD_DONE
    beat_ready   : in  std_logic;  -- the receiver takes it
    beat_data    : out period_done_t;  -- the fields of PERIOD_DONE
    reg_ctrl     : in  std_logic_vector(31 downto 0);  -- memory CTRL @ 0x40000000: the bus writes it, the logic reads it
    …
    -- @arche Pwm.tick main.arche:80 fn
    procedure f_tick is  -- Every clock cycle
    begin
      if (over_current = '1') and (v_state /= pwm_st_tripped) then
        go(pwm_st_tripped);
      end if;
      if v_state = pwm_st_running then
        v_pwm := resize(v_counter, 32) < unsigned(reg_duty);

An entity is named after its component. Here it is pwm_comp, not pwm: a port has that name already.

Write your own VHDL between the USER CODE markers (Pwm.declarations, Pwm.cycle, Pwm.architecture). archec gen keeps what is between them when it writes the file again (regeneration.md).

6. Test it#

The test cases are the model's, written once:

test-plan TP-PWM "PWM generator" {
  case TC-TRIP "Over-current: low, until 1 µs without it" {
    verifies REQ-TRIP
    at 0ns do pwm.DUTY = 80
    at 20ns do pwm.CTRL = 1
    at 200ns expect pwm.pwm
    at 200ns do pwm.over_current = true
    at 210ns expect not pwm.pwm
    at 210ns expect pwm.state == Tripped
    at 500ns do pwm.over_current = false
    at 1490ns expect pwm.state == Tripped
    at 1500ns expect pwm.state == Running
  }
}
archec test main.arche                  # on the simulator
archec test main.arche --target vhdl    # on the VHDL, in GHDL

archec test runs the cases of a system with FPGA parts on the browser simulator, which steps the clocks (--sim web runs every case there).

archec test --target vhdl main.arche
  GHDL 6.0.0 (llvm jit) — ~/.arche/fpga/ghdl-6.0.0-darwin-arm64/ghdl/bin/ghdl (~/.arche/fpga)
PASS  TP-PWM/TC-DUTY        25 % duty  — 10 expectation(s), 204 cycle(s) of 10ns, 1.2 s
PASS  TP-PWM/TC-TRIP        Over-current: low, until 1 µs without it  — 9 expectation(s), 151 cycle(s) of 10ns, 1.2 s
…
5/5 passed on GHDL

Requirements: 4 verified by passing cases, 0 failing

--plan and --case choose the cases, as for any test run. In VS Code, Arche: Run FPGA Tests in GHDL runs them and shows the report in the Arche Status output; Arche: Generate Code… has the vhdl target.

How time is read#

A case is written in time; hardware counts cycles. With a clock of 10 ns the edge at 40 ns is cycle 4. The simulator and the testbench read a case the same way, so a line holds on both, at the same instant.

Line What happens
at t expect c The condition is read at t, just after the edge at t if a clock has one there.
within d expect c It is read after each edge of the window, and must hold once.
at t do part.signal = v The input is driven at t. The logic sees it on the part's next edge.
at t do part.REG = v The register is written over the bus. It is in the bank on the part's next edge, and the logic reads it one edge later.
at t do send host.port MSG { … } A message from a part outside the FPGA. It is received on the part's next edge, if its port is ready then.

Times go down to the picosecond: at 6.4ns, at 12800ps, within 800ps. A 156.25 MHz clock has its edges at 6.4 ns, 12.8 ns, 19.2 ns. A time need not be on an edge: with two clocks, at 20ns is an edge of one and between two edges of the other, and each part is read as it is then. A clock whose period is not a whole number of picoseconds (48 MHz: 20833.333 ps) runs at the nearest one, and archec check says so.

The bank answers a write before it takes the next: a write takes two cycles. One written too close to the one before waits, on both sides, and the test run says so.

In an expectation you read a part's variables, its signals, its registers and its state, and sent(MSG). A testbench sets what comes from outside: the top's input signals, the bus registers, messages from a part outside the FPGA. A case that sets a variable inside the logic, or is written in Python, is not run in GHDL. The run says why.

What it proves#

Each case that ran is evidence, at the place ghdl. That is a rung of the test ladder between the simulator and the board, and archec test --ladder runs it for a model with FPGA parts:

archec test --ladder main.arche
  ✓ sim     5 case(s) passed on the browser simulator
  – renode  skipped: no deployment with a binary on a board
  ✓ ghdl    5 case(s) passed on the FPGA's VHDL in GHDL 6.0.0
  – board   skipped: no deployment with a binary on a board
✓ ladder: held up to ghdl
$ archec status main.arche
REQ-TRIP  Trip on over-current
  satisfied by  Pwm (pwm)
  built into    arche-out/vhdl/pwm_comp.vhd:3-4,56-60
  highest rung  ghdl (sim ✓, renode –, ghdl ✓, board –)
  ✓ test    TP-PWM/TC-TRIP  ghdl     just now  9 expectation(s) held over 151 cycle(s), GHDL 6.0.0
  ✓ test    TP-PWM/TC-TRIP  web sim  just now

The record keeps the hash of the VHDL it ran. Change the model or the VHDL, and the proof is out of date until the case runs again.

Why, and why not#

Each run leaves a trace beside the VHDL, arche-out/vhdl/trace/<case>.trace, with cycle-accurate times: the states entered, the messages sent and received, the fields of what came, the sends dropped. A time is in nanoseconds from the start of the case, with its picoseconds after a point (arche-trace 6.4 send WORD 1). With several clocks they are on one time line. archec why, why-not and timing read it as they read a firmware's trace (why.md).

$ archec why main.arche --trace arche-out/vhdl/trace/tp_pwm_tc_trip.trace "pwm Tripped"
pwm Tripped  Running → Tripped: by a goto                   210 ns

$ archec why main.arche --trace arche-out/vhdl/trace/tp_pwm_tc_beat.trace
       0 ns  pwm starts in Idle
      40 ns  pwm Idle → Running [CTRL & ENABLE == ENABLE]  main.arche:108
    1030 ns  pwm sends PERIOD_DONE
    1040 ns  heart receives PERIOD_DONE periods: 1
…
$ archec why-not main.arche --trace arche-out/vhdl/trace/tp_pwm_tc_duty.trace "Running -> Idle"
pwm: Running -> Idle [CTRL & ENABLE == 0]  main.arche:109
  the guard [CTRL & ENABLE == 0] was never true while pwm was in Running (40 ns to 2040 ns): it is tried on every cycle — …

A trace has no values of the variables. archec why-not --test <case> runs the case on the simulator, which has them.

7. Synthesise it#

GHDL shows the VHDL does what the model says. archec synth shows it can be built: it synthesises the design for a device, places and routes it, and measures it.

archec synth main.arche
archec synth main.arche
  Yosys 0.71+39 with the GHDL plugin, nextpnr-ecp5 0.11.1 — ~/.arche/fpga/oss-cad-suite-20261116-darwin-arm64/oss-cad-suite/bin (~/.arche/fpga)

PwmBoard  pwm_board_top on LFE5U-25F-6BG381
  LUTs     257 of 24288  1 %
  FFs      163 of 24288  1 %
  BRAM       0 of 56  0 %
  DSP        0 of 28  0 %
  pins     101
  each component on its own (its ports free: more than its share of the top):
    Pwm        526 LUTs, 188 FFs  (pwm_comp + pwm_regs)
    Heartbeat  14 LUTs, 10 FFs  (heartbeat)
  ✓ clock clk: fmax 123.4 MHz, above the 100 MHz of Pwm, Heartbeat

✓ limit PwmBoard.luts <= 500  257 LUTs <= 500  REQ-FIT
✓ limit PwmBoard.ffs <= 300   163 FFs <= 300  REQ-FIT
✓ limit Pwm.fmax >= 100MHz    123.4 MHz >= 100 MHz  REQ-FIT
  evidence: 5 record(s) → .arche/evidence/synth.jsonl (archec status)
✓ PwmBoard synthesises for LFE5U-25F-6BG381 and meets its clock, 3 limit(s) kept

The steps are those of any open-source FPGA flow:

  1. archec writes the VHDL under arche-out/vhdl, as archec gen does.
  2. Yosys reads it through GHDL (the ghdl-yosys-plugin; with a Yosys that has no plugin, through ghdl --synth) and maps it to the device's cells (synth_ice40, synth_ecp5).
  3. nextpnr places and routes the top for the device and its package, and reports the highest frequency each clock can run at: its fmax.
  4. Each FPGA component is also synthesised on its own, with its register bank.

The tools' files and logs are in arche-out/synth/.

The device#

The device is the chip of the system's kind fpga part (its part-number when it has no chip):

component Fpga "FPGA" { kind fpga; chip "LFE5U-25F-6BG381" }
Diagram: FPGA
What archec draws from this code: FPGA
Family You write Tools
Lattice iCE40 iCE40UP5K-SG48, iCE40HX8K-CT256, iCE40LP8K-CM81, iCE5LP4K-SG48; short: up5k, hx8k synth_ice40, nextpnr-ice40, icepack
Lattice ECP5 LFE5U-25F-6BG381, LFE5UM-45F-7MG285, LFE5UM5G-85F-8BG381; short: ecp5-25f synth_ecp5, nextpnr-ecp5, ecppack

A name with no package takes the family's usual one (up5k is the SG48). A device archec does not know is a warning on the chip (synth-device). --device <name> asks for another device than the model's. Such a run is a question: it is printed, not recorded.

What it measures#

Word What is counted
luts 4-input look-up tables. On an ECP5 a carry cell counts for two.
ffs Flip-flops.
bram Block RAMs (4 kbit on an iCE40, 18 kbit on an ECP5).
dsp DSP blocks (a multiplier).
fmax The highest frequency the clock can run at, once placed and routed.

The cells are Yosys's count after mapping. "of 24288" is what the device has, from nextpnr.

A system's numbers are the top's: every FPGA part, wired. A component's numbers are of the component alone, with its register bank. Alone, every one of its ports is free, so nothing is simplified across them: a component takes more on its own than its share of the top. Here Pwm alone takes 526 LUTs and the whole top 257. A component's fmax is that of its clock in the top.

Limits in a requirement#

A requirement bounds what is measured, as it bounds a geometry's mass (cad.md):

requirement REQ-FIT "Fits the device" {
  text "The FPGA parts shall take at most 500 LUTs and 300 flip-flops of the device, and the PWM generator shall run at 100 MHz."
  limit PwmBoard.luts <= 500
  limit PwmBoard.ffs <= 300
  limit Pwm.fmax >= 100MHz
}

The name is an FPGA component or a system with FPGA parts. Bound a system for what the device must hold, and a component to budget it alone. A limit not kept is an error at its line, and archec synth exits 1:

✗ main.arche:49:3  REQ-FIT: Pwm runs at 35.91 MHz at most once placed and routed; the limit is >= 100 MHz

With no limit written, each clock is still checked against the frequency the model gives it. A clock too fast for the device is said at the component's clock.

Four devices#

The PWM generator of examples/fpga-pwm, measured with Yosys 0.71 and nextpnr 0.11.1 (the default seed), on a Mac:

Device LUTs FFs BRAM DSP Pins fmax of clk At 100 MHz
ECP5 LFE5U-25F-6BG381 (the model's) 257 of 24288 163 0 0 101, on the package 123.4 MHz met
ECP5 LFE5UM5G-85F-8BG381 257 of 83640 163 0 0 101, on the package 175.7 MHz met
iCE40 HX8K-CT256 183 of 7680 163 0 none 101, on the package 99.97 MHz missed by 0.03 MHz
iCE40 UP5K-SG48 183 of 5280 163 0 0 of 8 101, virtual 35.91 MHz not met

On an iCE40 the 69 carry cells sit beside the LUTs and are not counted in them. An iCE40 UP5K is a slow, low-power device: this design runs at about 36 MHz on it, so its clock clk 100MHz cannot be kept there. archec synth main.arche --device up5k says so, at the model:

✗ main.arche:67:3  Pwm's clock clk is 100 MHz: on iCE40UP5K-SG48 its logic runs at 35.91 MHz at most — a slower clock, a faster device, or less work in one cycle (a state more)

fmax moves by a few percent with nextpnr's seed (--seed). Keep a margin: a design at 99.97 MHz for 100 has none.

Virtual pins#

The top of the example has 101 pins: the AXI4-Lite bus of its registers is 96 of them. An ECP5 in a BG381 package has them. A UP5K in an SG48 has 39 pins for you, and nextpnr cannot place the top.

archec then places it with virtual pins. It wraps the top in a module that puts a register in front of each pin, but the clocks and the resets. The inputs become a shift register fed by one real pin. The outputs are folded into a signature read on another. This is what the design sees when the bus master is inside the FPGA (a soft processor, a bridge), not on its pins.

  • The cells counted are the design's alone, not the wrapper's.
  • fmax is measured with the wrapper. It is a little higher than with real pins, which hold the logic near the edge of the device: 102.9 MHz against 99.97 MHz on the HX8K.
  • There is no bitstream of it: it is a measure, not a design to load.

--virtual-pins asks for them on a device where the pins fit.

What it proves#

Each limit measured is evidence for its requirement, at the place synth <device>. Each FPGA component placed and routed is evidence for the requirements it satisfies, on the rung synth of the test ladder, above ghdl:

$ archec status main.arche --req REQ-TRIP --req REQ-FIT
REQ-TRIP  Trip on over-current
  When the over-current input is high, the PWM output shall be low within 2 clock cycles and stay low until the over-current input has been low for 1 µs.
  satisfied by  Pwm (pwm)
  built into    arche-out/vhdl/fpga_pwm_pkg.vhd:17-20, arche-out/vhdl/pwm_comp.vhd:3-4,56-60
  highest rung  synth (sim –, renode –, ghdl ✓, synth ✓, board –)
  ✓ test    TP-PWM/TC-TRIP  ghdl                  just now  9 expectation(s) held over 151 cycle(s), GHDL 6.0.0
  ✓ synth   synth Pwm       synth lfe5u-25f-6bg381  just now  526 LUTs, 188 FFs, fmax 123.4 MHz ≥ its clock's 100 MHz, on LFE5U-25F-6BG381

REQ-FIT   Fits the device
  The FPGA parts shall take at most 500 LUTs and 300 flip-flops of the device, and the PWM generator shall run at 100 MHz.
  highest rung  synth (sim –, renode –, synth ✓, board –)
  ✓ synth   Pwm.fmax       synth lfe5u-25f-6bg381  just now  123.4 MHz >= 100 MHz
  ✓ synth   PwmBoard.ffs   synth lfe5u-25f-6bg381  just now  163 FFs <= 300
  ✓ synth   PwmBoard.luts  synth lfe5u-25f-6bg381  just now  257 LUTs <= 500

A limit kept proves its requirement. A component synthesised does not prove the requirements it satisfies: their tests do. It says the hardware they ran as, in GHDL, can be built for the device and meets its clock. One that does not meet its clock fails them. The record keeps the hash of the VHDL: change the model, and it is out of date. A record for a device the model no longer names is not counted.

When synthesis fails#

archec writes the VHDL, so it synthesises. Your own VHDL in a USER CODE region may not. The error names the model element the line is of:

✗ synthesis of pwm_board_top for LFE5U-25F-6BG381 failed: no declaration for "no_such_signal"
    main.arche:64  component Pwm (your VHDL in the USER CODE region Pwm.cycle)
    arche-out/vhdl/pwm_comp.vhd:160
    the tools' logs: arche-out/synth/

A run that fails records nothing.

A bitstream#

--bitstream also writes the file to load: arche-out/synth/<top>.bin for an iCE40 (icepack), <top>.bit for an ECP5 (ecppack). Each pin of the top must be on the device, so the top must fit the package. Say which pin is which with --constraints: a .pcf file for an iCE40, a .lpf for an ECP5. archec does not write it: the store has no FPGA board yet to read the pins from. With no constraints nextpnr chooses the pins, and the run says the bitstream is not for a board.

A blinker for an iCEBreaker (an iCE40 UP5K, a 12 MHz clock on pin 35, a button on pin 10, a red LED on pin 11):

component Blink "Blink" {
  clock clk 12MHz
  reset rst_n active low async
  out led: bool "LED"
  fn main ```arche
    while true {
      led = not led
      wait 500ms
    }
  ```
}
component Fpga "FPGA" { kind fpga; chip "iCE40UP5K-SG48" }
system Board "Board" { part fpga: Fpga; part blink: Blink }
Diagram: Board
What archec draws from this code: Board
Try it
# icebreaker.pcf: the top's ports are clk, rst_n and <part>_<signal>
set_io clk 35
set_io rst_n 10
set_io blink_led 11
archec synth main.arche --bitstream --constraints icebreaker.pcf
Board  board_top on iCE40UP5K-SG48
  LUTs      39 of 5280  1 %
  FFs       25 of 5280  1 %
  …
  ✓ clock clk: fmax 60.08 MHz, above the 12 MHz of Blink
  bitstream: arche-out/synth/board_top.bin

Loading it on the board is yours. With the board plugged in:

~/.arche/fpga/oss-cad-suite-*/oss-cad-suite/bin/iceprog arche-out/synth/board_top.bin

(ecpprog or openFPGALoader for an ECP5 board.) This bitstream was built and packed here. It was not loaded on a board: nothing on this page ran on hardware, and the pin numbers above are from the board's documentation, not from a run.

The commands#

archec gen <main.arche> --target vhdl [-o generated] [--deployment D] [--check] [--diff]
archec test <main.arche> --target vhdl [--plan P]… [--case C]… [-o arche-out]
                         [--deployment D] [--json] [--verbose] [--no-record] [--timeout 600]
archec synth [main.arche] [--device <name>] [--system S] [--deployment D] [-o arche-out]
                          [--virtual-pins] [--bitstream [--constraints pins.pcf|pins.lpf]]
                          [--seed N] [--json] [--verbose] [--no-record] [--timeout 900]
archec synth --install-tools [--archive <file>]

archec test --target vhdl exits 0 when every case passed, 1 when one failed, and 2 when it could not run: no GHDL, no FPGA part, a model with errors. It writes the VHDL and the testbenches under <out>/vhdl even when GHDL is not there. --verbose shows what GHDL prints. --json gives the results as JSON, which are also in <out>/.archec/ghdl-results.json.

archec synth exits 0 when the design synthesises, meets its clocks and keeps its limits, 1 when it does not, and 2 when it could not run: no tools, no device named, no FPGA part, a model with errors. Its results are in <out>/.archec/synth-results.json (--json prints them). In VS Code, Arche: Synthesise FPGA Design runs it and shows the report in the Arche Status output.

Where GHDL comes from#

archec looks for GHDL in this order: ARCHE_GHDL (the program, or the folder a release was unpacked in), the extension's own folder, ~/.arche/fpga (ARCHE_FPGA_HOME), then the PATH. It never downloads it.

The platform builds of the extension carry an official GHDL release, checked against its sha256 when the extension is packaged (tools/fpga/targets.json):

Build GHDL Notes
darwin-arm64 6.0.0, LLVM JIT macOS 14 or later.
darwin-x64 5.1.1, mcode GHDL 6.0.0 has no build for Intel Macs: 5.1.1 is the last one.
linux-x64 6.0.0, mcode Built on Ubuntu 24.04: it needs glibc 2.38 or later.
win32-x64 6.0.0, mcode The UCRT build: Windows 10 or later.
linux-arm64 none GHDL publishes no build for it. Install GHDL: archec finds it on the PATH.

These builds need no compiler or linker on your machine. The generic arche-lang.vsix has no GHDL, and uses the one of the PATH.

To get the pinned release on a machine without the extension:

node tools/fpga/package.mjs --install     # into ~/.arche/fpga

GHDL is free software under the GPL (version 2 or later). The extension ships its release unmodified, beside its own files; fpga/NOTICE.txt says where its source is.

Where the synthesis tools come from#

archec synth needs Yosys with the ghdl-yosys-plugin, nextpnr for the device's family, and icepack or ecppack for a bitstream. The OSS CAD Suite of YosysHQ has them all in one folder. archec looks for them in this order: ARCHE_OSS_CAD_SUITE (the folder a suite is unpacked in), ~/.arche/fpga (ARCHE_FPGA_HOME), then the PATH.

The suite is large: about 500 MB to download, 1.8 GB unpacked. It is in no build of the extension, and archec does not download it: you do.

archec synth --install-tools     # says the file for your machine, and its sha256
curl -fLO https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-11-16/oss-cad-suite-darwin-arm64-20261116.tgz
archec synth --install-tools --archive oss-cad-suite-darwin-arm64-20261116.tgz

The release for each platform is pinned in tools/fpga/synth-targets.json (2026-11-16: Yosys 0.71, nextpnr 0.11.1). The file you give is checked against its sha256, then unpacked in ~/.arche/fpga, nowhere else. An archive with another hash is not unpacked.

Platform Pinned How its hash was checked
darwin-arm64 yes Downloaded here, its sha256 computed, the flow run on it.
darwin-x64, linux-x64, linux-arm64, win32-x64 yes The digest GitHub publishes for the release's file. Not downloaded, not run.

Tools you installed yourself work too (brew install yosys nextpnr, your distribution's packages). A Yosys with no GHDL plugin is used with the GHDL archec finds: the VHDL goes through ghdl --synth.

The suite's tools are free software: Yosys, nextpnr, Project IceStorm and Project Trellis under the ISC license, GHDL and its plugin under the GPL. archec starts them as commands. It ships none of them.

Limits: what it does not do yet#

  • Whole picoseconds. The simulator and the testbench count whole picoseconds. A 48 MHz clock (20833.333 ps) runs at 20833 ps there, and archec check says so. The VHDL itself has no period in it.
  • Between two clocks: one bit, or a message. A signal of several bits is refused: send it as a message. The handshake carries about one message every three cycles of each clock; there is no asynchronous FIFO. In a test all the clocks start in phase, at time 0: another phase is not tried. The simulator and GHDL have no metastability: the two flip-flops are there for the real device.
  • States: no region, no history. A state inside a state, its initial child and a choice are synthesised. A region, a history state, a fork, a join, an entry and an exit point are not.
  • A port with two senders needs an arbiter of yours: only its first link is wired. overflow drop-oldest and overflow block are not synthesised: a full port drops the message sent to it, or fn main waits.
  • A message carries fields. send port MSG { field: value }: a message declared as one value (message LEVEL: uint8) is not sent from a body.
  • Registers of 32 bits at most from a test. A testbench writes a register over the bus in one AXI4-Lite write, and the bank takes a write every two cycles. A memory block of more than 16 elements is a memory window of the bank, not wired to the component.
  • Not run in GHDL: a case that sets a variable inside the logic, uses a setup, a keyframe or a fault, or is written in Python.
  • Arche's own simulator does not step a clock. archec test runs the cases of a system with FPGA parts on the browser simulator instead; --sim python still asks for Arche's.
  • Synthesis for iCE40 and ECP5 only. archec synth knows these two families, which have open-source tools. For a Xilinx or an Intel device, give the VHDL (vhdl/sources.txt) to Vivado or Quartus yourself.
  • Pin constraints are yours. archec does not write a .pcf or .lpf file: the store has no FPGA board to read the pins from.
  • Never run on hardware. The design was simulated in GHDL, synthesised, placed, routed and packed. No bitstream was loaded on a board.
  • A component's share of the top is not measured. Its numbers are of the component synthesised alone.
  • Virtual pins on one clock each. A pin of the top is registered on the clock of the part it belongs to. With several clocks the fmax of each is reported.
  • No timing constraint between two clocks. A link between two clocks goes through the synchronisers of arche_cdc.vhd. nextpnr reports the paths from one clock to another apart: they count in neither clock's fmax, and archec synth writes no false-path or maximum-delay constraint for them. The flip-flops carry the async_reg attribute, which Vivado reads; in another tool, constrain the crossing yourself.
  • The synthesis tools were run on macOS (arm64) only. The other platforms' releases are pinned by the hash GitHub publishes.
  • The Windows build of GHDL is pinned and checked, and was not run by the tests of this feature.