Autres pages › fpga

Autres pages

Composants FPGA

Extension — hors de la promesse de stabilité 1.0 (fpga ; le cœur)

Un composant qui a une horloge est du matériel. Vous l'écrivez comme tout autre composant : des ports, des variables, des fonctions dans le langage d'action, une machine à états, des cas de test. archec lit le même modèle de trois façons. Le simulateur l'exécute cycle par cycle. archec gen --target vhdl l'écrit en VHDL synthétisable. archec test --target vhdl exécute ses cas de test sur ce VHDL, dans GHDL. archec synth le synthétise, le place et le route pour un circuit, et dit ce qu'il occupe et à quelle vitesse il tourne.

Cette page construit un générateur PWM : un bloc de registres qu'un processeur écrit, une entrée de surintensité qui coupe la sortie, et une LED de battement. Le modèle terminé est examples/fpga-pwm/main.arche. Un second, examples/fpga-uart/main.arche, a deux horloges : un récepteur UART sur sa propre horloge règle le rapport cyclique d'un PWM sur une autre.

Ce qu'il vous faut#

Écrire, vérifier, simuler et générer ne demandent rien de plus qu'archec. Exécuter le VHDL demande GHDL, un simulateur VHDL libre. La synthèse demande Yosys et nextpnr (d'où ils viennent). arche-lang ne télécharge ni l'un ni les autres.

  • Dans VS Code, installez la version de l'extension faite pour votre machine (arche-lang-darwin-arm64.vsix, -darwin-x64, -linux-x64 ou -win32-x64). Elle contient GHDL.
  • Sans l'extension, installez GHDL (brew install ghdl, apt install ghdl, ou une version décompressée dans ~/.arche/fpga). archec accepte aussi ARCHE_GHDL=/path/to/ghdl.

D'où vient GHDL donne les versions et les plateformes.

1. Un composant avec une horloge#

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"
}
Diagramme : PWM generator
Ce qu’archec dessine depuis ce code : PWM generator
Vous écrivez Sens
clock clk 100MHz Le composant est un composant FPGA. clk est le nom de l'horloge, 100MHz sa fréquence. Chaque front montant est un cycle.
reset rst_n active low async Sa remise à zéro : un nom, active high ou active low, sync ou async. Sans ligne reset, c'est rst, active à l'état haut, synchrone.
step tick La fonction appelée à chaque cycle, comme le step d'un thread est appelé à chaque période.
in over_current: bool Un signal : un port dont le type est un type de données.
var counter: uint8 = 0 Un registre. Sa première valeur est sa valeur à la remise à zéro.

clock 10ms, avec une seule valeur, garde son ancien sens : la période d'un composant qui n'est pas du matériel.

Signaux et largeurs#

Un port typé par une donnée est un signal de cette largeur. Dans un corps, c'est un nom, comme une variable : un signal in se lit, un signal out s'affecte.

Type Largeur
bool 1 bit (std_logic sur l'entité)
uint8, uint16, uint32, uint64 8 à 64 bits, non signé
int8 … int64 8 à 64 bits, signé
un enum les bits qu'il faut à ses littéraux
type Adc12 = uint16 { bits 12 } 12 bits : bits sur un type donne n'importe quelle largeur jusqu'à 64
type Adc12 = uint16 { bits 12 }

component Filter "Filter" {
  clock clk 50MHz
  in sample: Adc12
  out level: Adc12
}
Diagramme : Filter
Ce qu’archec dessine depuis ce code : Filter

Un tableau a une taille (var taps: uint8[4]). Les flottants et les chaînes n'ont pas de bits : le vérificateur le dit.

L'arithmétique a le même sens que dans le simulateur. Une expression est calculée en entier : la somme de deux uint8 a 9 bits, et un uint8 moins un uint8 peut être négatif. Elle est coupée à sa largeur là où elle est affectée : un compteur reboucle donc. Un décalage à gauche reste dans la largeur de ce qu'il décale. Une valeur d'un type avec bits 12 reboucle à 12 bits, dans le simulateur aussi.

Messages#

Un port qui envoie (sends) ou reçoit (receives) des messages reste ce qu'il est. Entre deux parts FPGA, un message est une poignée de main : valid venant de l'émetteur, avec les champs du message dans un enregistrement (data), et ready venant du récepteur.

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
    }
  ```
}
Diagramme : Heartbeat
Ce qu’archec dessine depuis ce code : Heartbeat

Un émetteur tient valid jusqu'à ready. Un récepteur est prêt quand il peut prendre le message : Quand le récepteur n'est pas prêt dit quand c'est le cas. Un port de messages qui n'est lié à rien à l'intérieur est un port de l'entité de tête. Dans un test, sent(MSG) compte les messages qu'un lien transporte.

Registres sur un bus#

Un bloc memory qui a une adresse est un registre que le processeur placé à côté du FPGA atteint par le bus. archec écrit le banc de registres AXI4-Lite (regmap.md) et le câble au composant.

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
}
Diagramme : Registers
Ce qu’archec dessine depuis ce code : Registers

Dans un corps, CTRL et DUTY se lisent : le bus les écrit (rw, w). STATUS s'affecte : la logique le pilote et le bus le lit (r).

2. Ce qu'il fait#

Les corps sont écrits dans le langage d'action, comme partout. Voici le tick du PWM et sa machine à états :

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"
  }
}
Diagramme : PWM generator
Ce qu’archec dessine depuis ce code : PWM generator

Ce que fait un cycle#

À chaque front montant, dans cet ordre :

  1. fn main, quand le composant en a une : ses instructions jusqu'à son prochain wait.
  2. Chaque message pris sur ce front : la transition qu'il déclenche, le on-receive du port, ses handlers.
  3. Les transitions on "after …" dont le temps est venu.
  4. Les transitions qui ont une garde et pas de déclencheur. Elles sont essayées à chaque cycle.
  5. La fonction step.

Un corps lit ce qu'il vient d'écrire, comme dans tout autre composant. Les sorties passent par un registre : ce qu'un cycle calcule se voit de l'extérieur à partir du cycle suivant.

Le temps se compte en cycles#

on "after 1us" vaut 100 cycles d'une horloge à 100 MHz. Une durée qui n'est pas un nombre entier de cycles est arrondie au cycle supérieur. Les durées descendent jusqu'à la picoseconde : 800ps, 6.4ns. fn main s'exécute seule, et son wait se compte de la même façon :

component Blink "Blink" {
  clock clk 100MHz
  out led: bool
  fn main ```arche
    while true {
      led = not led
      wait 500ns
    }
  ```
}
Diagramme : Blink
Ce qu’archec dessine depuis ce code : Blink

Gardez les attentes au premier niveau de fn main ou de sa boucle while true. Un wait placé ailleurs n'est pas synthétisé.

Des états dans des états#

Un état peut contenir des états, comme dans tout autre composant. Le matériel garde un seul registre : l'état le plus intérieur où il se trouve. Les états qui l'entourent s'en déduisent : state == On est donc vrai dans chaque état à l'intérieur de 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
}
Vous écrivez Ce que fait le matériel
On -> Off on STOP Prise dans n'importe quel état à l'intérieur de On. Chaque on-exit s'exécute de l'intérieur vers l'extérieur, puis l'action, puis chaque on-enter de l'extérieur vers l'intérieur.
Une transition vers Heating Elle entre dans son premier état (Low), ou dans celui marqué pseudo initial.
Heating -> Soak on "after 100ns" Compté depuis l'entrée dans Heating. Un changement d'état à l'intérieur ne relance pas le compte.
state Pick { pseudo choice } Quitté au cycle où il est atteint, par sa première transition dont la garde est vraie. Donnez-lui une dernière transition sans garde.
Une transition de l'état où il se trouve, et une d'un état qui l'entoure Celle de l'état le plus intérieur est essayée en premier.
goto Off dans un corps Les mêmes sorties et entrées qu'une transition depuis l'endroit où il se trouve.

Le simulateur et le VHDL les exécutent de la même façon. Une région (region left), un état d'historique, un fork et un join ne sont pas synthétisés : archec check le dit. Deux régions sont deux machines : faites de chacune un composant.

Quand le récepteur n'est pas prêt#

Un message est une poignée de main. L'émetteur tient valid et les champs jusqu'à ce que le ready du récepteur soit haut sur un front d'horloge.

Quand un récepteur est prêt.

Le port d'entrée Il prend un message
a un on-receive ou un handler pour lui à chaque cycle
n'a ni l'un ni l'autre, et des transitions sont déclenchées par lui dans les états que ces transitions quittent (et les états à l'intérieur)
a depth N tant qu'il en garde moins de N. Il les passe un par cycle à la règle ci-dessus.
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 prend un ITEM dans Idle. Dans Busy, son ready est bas et l'élément attend chez son émetteur. Avec in items: data receives ITEM { depth 3 }, trois éléments attendent dans le port lui-même.

Ce que fait un émetteur quand son port est plein. Un port de sortie garde un message jusqu'à ce qu'il soit pris, ou depth N messages.

Où se trouve le send Sans place sur le port
Au premier niveau de fn main, ou de sa boucle while true Il attend. main continue quand il y a de la place.
Partout ailleurs : la fonction step, un handler, une action, dans un if Le message est abandonné. Le cycle continue.

Un message abandonné n'est jamais silencieux. L'exécution des tests le dit, sur le simulateur et dans 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

Dans un cas, dropped(MSG) est le nombre de messages abandonnés : at 1us expect dropped(TICK) == 0. Un message qu'un test envoie depuis l'extérieur du FPGA (do send host.port MSG { … }) attend de la même façon, l'un derrière l'autre.

3. Ce qui ne peut pas être synthétisé#

archec check lit chaque corps d'un composant FPGA comme du matériel et dit ce qui ne peut pas être fabriqué, à l'endroit où c'est écrit :

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]
Refusé Écrivez à la place
float32, float64, un nombre comme 1.5 Un entier, ou une virgule fixe dans un entier.
Une string, une durée comme valeur Un enum ou un nombre ; wait et after comptent les cycles.
Un tableau sans taille var buf: uint8[8], ou une constante pour la taille.
while c { … } for i in 0..N { … } avec des bornes constantes, ou un état.
Une fonction qui s'appelle elle-même La boucle qu'elle représente.
port.op(…), un appel à une autre part Un message, ou un signal.
Un corps en Python ou en TypeScript Le langage d'action.

Une affectation qui perd des bits est un avertissement (fpga-width) : une valeur uint16 dans un uint8, le littéral 300 dans un uint8. counter += 1 n'en est pas un : un compteur reboucle à sa propre largeur, ici comme dans le simulateur. Une division par autre chose qu'une puissance de deux constante est aussi un avertissement (fpga-divide) : elle est synthétisée, sous la forme d'un circuit gros et lent.

Dans VS Code, ils apparaissent dans l'éditeur pendant que vous tapez.

4. Le système#

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 }
  }
}
Diagramme : PWM board
Ce qu’archec dessine depuis ce code : PWM board

Les parts FPGA d'un système et les liens entre elles forment l'entité de tête. Un port qu'aucun lien intérieur ne pilote ni ne lit est un port de l'entité de tête. Le déploiement est facultatif. Quand il y en a un, un binary sur une part kind fpga nomme le bitstream, et l'entité de tête contient les parts que ses threads exécutent. Le chip de la part kind fpga est le circuit visé : archec synth construit pour lui.

Plusieurs horloges#

Le nom d'une horloge est son domaine. Des parts dont les horloges ont des noms différents sont sur des horloges différentes, chacune une broche de l'entité de tête :

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
}
Diagramme : UART board
Ce qu’archec dessine depuis ce code : UART board

archec rend sûr chaque lien entre deux horloges, dans vhdl/arche_cdc.vhd :

Le lien transporte Il passe par Ce que cela coûte
un signal bool deux bascules de l'horloge du lecteur (arche_sync) La logique du lecteur voit un changement à son troisième front après lui.
un message une poignée de main à deux phases (arche_handshake) : une requête et un acquittement, chacun à travers deux bascules ; les champs sont tenus stables pendant qu'ils sont lus Le récepteur le reçoit deux ou trois de ses cycles après le front de l'émetteur. Le port de l'émetteur est de nouveau libre deux ou trois de ses propres cycles après que le récepteur l'a pris.

Une poignée de main a été préférée à une FIFO asynchrone : elle est petite, elle ne demande pas de mémoire, et elle marche pour deux fréquences quelconques. Elle transporte un message à la fois, environ un tous les trois cycles de chaque horloge. Pour plus, donnez un depth au port de l'émetteur : il garde la rafale pendant que la poignée de main la fait traverser.

archec check signale les liens qui ne peuvent pas être rendus sûrs, ou qui peuvent perdre quelque chose :

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]

Le simulateur fait tourner chaque horloge avec sa propre période et met les mêmes bascules sur chaque franchissement : un cas voit donc un message arriver sur le même front que dans GHDL. Toutes les horloges ont un front au temps 0 : dans un test, les fronts d'une horloge sont à des multiples entiers de sa période.

5. Générer le VHDL#

archec gen main.arche --target vhdl -o out
Fichier Ce que c'est
vhdl/fpga_pwm_pkg.vhd Les données du modèle : les constantes, les enums, un enregistrement par message, les états de chaque composant.
vhdl/pwm_comp.vhd, vhdl/heartbeat.vhd Une entité et une architecture par composant.
vhdl/pwm_regs.vhd Le banc de registres AXI4-Lite de Pwm.
vhdl/pwm_board_top.vhd L'entité de tête du système : les parts et le banc, câblés.
vhdl/arche_cdc.vhd Seulement avec plusieurs horloges : les synchroniseurs des liens entre elles.
vhdl/tb/tb_<case>.vhd Un banc de test par cas de test.
vhdl/sources.txt Les fichiers dans l'ordre où un outil les compile.

C'est du VHDL-2008 avec ieee.numeric_std. Un composant est un seul processus cadencé par l'horloge, dont les variables sont les registres. Chaque morceau nomme l'élément du modèle dont il vient :

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);

Une entité porte le nom de son composant. Ici c'est pwm_comp, et non pwm : un port porte déjà ce nom.

Écrivez votre propre VHDL entre les marqueurs USER CODE (Pwm.declarations, Pwm.cycle, Pwm.architecture). archec gen garde ce qui est entre eux quand il réécrit le fichier (regeneration.md).

6. Le tester#

Les cas de test sont ceux du modèle, écrits une seule fois :

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 exécute les cas d'un système qui a des parts FPGA sur le simulateur du navigateur, qui fait avancer les horloges (--sim web y exécute tous les cas).

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 et --case choisissent les cas, comme pour toute exécution de tests. Dans VS Code, Arche: Run FPGA Tests in GHDL les exécute et montre le rapport dans la sortie Arche Status ; Arche: Generate Code… propose la cible vhdl.

Comment le temps est lu#

Un cas est écrit en temps ; le matériel compte des cycles. Avec une horloge de 10 ns, le front à 40 ns est le cycle 4. Le simulateur et le banc de test lisent un cas de la même façon : une ligne est donc vraie des deux côtés, au même instant.

Ligne Ce qui se passe
at t expect c La condition est lue à t, juste après le front à t si une horloge en a un à cet instant.
within d expect c Elle est lue après chaque front de la fenêtre, et doit être vraie une fois.
at t do part.signal = v L'entrée est pilotée à t. La logique la voit au front suivant de la part.
at t do part.REG = v Le registre est écrit par le bus. Il est dans le banc au front suivant de la part, et la logique le lit un front plus tard.
at t do send host.port MSG { … } Un message venant d'une part extérieure au FPGA. Il est reçu au front suivant de la part, si son port est prêt à ce moment.

Les temps descendent jusqu'à la picoseconde : at 6.4ns, at 12800ps, within 800ps. Une horloge à 156,25 MHz a ses fronts à 6,4 ns, 12,8 ns, 19,2 ns. Un temps n'a pas besoin d'être sur un front : avec deux horloges, at 20ns est un front de l'une et tombe entre deux fronts de l'autre, et chaque part est lue telle qu'elle est à cet instant. Une horloge dont la période n'est pas un nombre entier de picosecondes (48 MHz : 20833,333 ps) tourne à la plus proche, et archec check le dit.

Le banc répond à une écriture avant de prendre la suivante : une écriture prend deux cycles. Une écriture trop proche de la précédente attend, des deux côtés, et l'exécution des tests le dit.

Dans une attente, vous lisez les variables d'une part, ses signaux, ses registres et son state, ainsi que sent(MSG). Un banc de test fixe ce qui vient de l'extérieur : les signaux d'entrée de l'entité de tête, les registres du bus, les messages venant d'une part extérieure au FPGA. Un cas qui fixe une variable à l'intérieur de la logique, ou qui est écrit en Python, n'est pas exécuté dans GHDL. L'exécution dit pourquoi.

Ce que cela prouve#

Chaque cas exécuté est une preuve, au lieu ghdl. C'est un barreau de l'échelle de test, entre le simulateur et la carte, et archec test --ladder le parcourt pour un modèle qui a des parts FPGA :

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

L'enregistrement garde le hash du VHDL qu'il a exécuté. Modifiez le modèle ou le VHDL, et la preuve est périmée jusqu'à ce que le cas soit exécuté de nouveau.

Pourquoi, et pourquoi pas#

Chaque exécution laisse une trace à côté du VHDL, arche-out/vhdl/trace/<case>.trace, avec des temps exacts au cycle près : les états atteints, les messages envoyés et reçus, les champs de ce qui est arrivé, les envois abandonnés. Un temps est en nanosecondes depuis le début du cas, avec ses picosecondes après un point (arche-trace 6.4 send WORD 1). Avec plusieurs horloges, ils sont sur une seule ligne de temps. archec why, why-not et timing la lisent comme ils lisent la trace d'un firmware (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 — …

Une trace ne contient pas les valeurs des variables. archec why-not --test <case> exécute le cas sur le simulateur, qui les a.

7. Le synthétiser#

GHDL montre que le VHDL fait ce que dit le modèle. archec synth montre qu'il peut être construit : il synthétise le design pour un circuit, le place et le route, et le mesure.

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

Les étapes sont celles de tout flot FPGA open source :

  1. archec écrit le VHDL sous arche-out/vhdl, comme le fait archec gen.
  2. Yosys le lit à travers GHDL (le ghdl-yosys-plugin ; avec un Yosys sans plugin, par ghdl --synth) et le projette sur les cellules du circuit (synth_ice40, synth_ecp5).
  3. nextpnr place et route l'entité de tête pour le circuit et son boîtier, et donne la fréquence la plus haute à laquelle chaque horloge peut tourner : son fmax.
  4. Chaque composant FPGA est aussi synthétisé seul, avec son banc de registres.

Les fichiers et les journaux des outils sont dans arche-out/synth/.

Le circuit#

Le circuit est le chip de la part kind fpga du système (son part-number quand elle n'a pas de chip) :

component Fpga "FPGA" { kind fpga; chip "LFE5U-25F-6BG381" }
Diagramme : FPGA
Ce qu’archec dessine depuis ce code : FPGA
Famille Vous écrivez Outils
Lattice iCE40 iCE40UP5K-SG48, iCE40HX8K-CT256, iCE40LP8K-CM81, iCE5LP4K-SG48 ; en court : up5k, hx8k synth_ice40, nextpnr-ice40, icepack
Lattice ECP5 LFE5U-25F-6BG381, LFE5UM-45F-7MG285, LFE5UM5G-85F-8BG381 ; en court : ecp5-25f synth_ecp5, nextpnr-ecp5, ecppack

Un nom sans boîtier prend celui qui est habituel dans la famille (up5k est le SG48). Un circuit qu'archec ne connaît pas est un avertissement sur le chip (synth-device). --device <name> demande un autre circuit que celui du modèle. Une telle exécution est une question : elle est affichée, pas enregistrée.

Ce qu'il mesure#

Mot Ce qui est compté
luts Les tables de correspondance (LUT) à 4 entrées. Sur un ECP5, une cellule de retenue compte pour deux.
ffs Les bascules.
bram Les blocs de RAM (4 kbit sur un iCE40, 18 kbit sur un ECP5).
dsp Les blocs DSP (un multiplieur).
fmax La fréquence la plus haute à laquelle l'horloge peut tourner, une fois le design placé et routé.

Les cellules sont le compte de Yosys après la projection. « of 24288 » est ce que le circuit contient, d'après nextpnr.

Les nombres d'un système sont ceux de l'entité de tête : toutes les parts FPGA, câblées. Les nombres d'un composant sont ceux du composant seul, avec son banc de registres. Seul, chacun de ses ports est libre, et rien n'est simplifié à travers eux : un composant occupe plus, seul, que sa part de l'entité de tête. Ici Pwm seul occupe 526 LUTs et l'entité de tête entière 257. Le fmax d'un composant est celui de son horloge dans l'entité de tête.

Des limites dans une exigence#

Une exigence borne ce qui est mesuré, comme elle borne la masse d'une géométrie (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
}

Le nom est un composant FPGA ou un système qui a des parts FPGA. Bornez un système pour ce que le circuit doit contenir, et un composant pour lui donner un budget à lui seul. Une limite non tenue est une erreur à sa ligne, et archec synth sort avec 1 :

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

Sans limite écrite, chaque horloge est quand même vérifiée contre la fréquence que le modèle lui donne. Une horloge trop rapide pour le circuit est signalée au clock du composant.

Quatre circuits#

Le générateur PWM de examples/fpga-pwm, mesuré avec Yosys 0.71 et nextpnr 0.11.1 (la graine par défaut), sur un Mac :

Circuit LUTs FFs BRAM DSP Broches fmax de clk À 100 MHz
ECP5 LFE5U-25F-6BG381 (celui du modèle) 257 sur 24288 163 0 0 101, sur le boîtier 123,4 MHz tenu
ECP5 LFE5UM5G-85F-8BG381 257 sur 83640 163 0 0 101, sur le boîtier 175,7 MHz tenu
iCE40 HX8K-CT256 183 sur 7680 163 0 aucun 101, sur le boîtier 99,97 MHz manqué de 0,03 MHz
iCE40 UP5K-SG48 183 sur 5280 163 0 0 sur 8 101, virtuelles 35,91 MHz non tenu

Sur un iCE40, les 69 cellules de retenue sont à côté des LUTs et ne sont pas comptées avec elles. Un iCE40 UP5K est un circuit lent, à basse consommation : ce design y tourne à environ 36 MHz, et son clock clk 100MHz ne peut donc pas y être tenu. archec synth main.arche --device up5k le dit, dans le modèle :

✗ 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 bouge de quelques pour cent avec la graine de nextpnr (--seed). Gardez une marge : un design à 99,97 MHz pour 100 n'en a aucune.

Broches virtuelles#

L'entité de tête de l'exemple a 101 broches : le bus AXI4-Lite de ses registres en prend 96. Un ECP5 en boîtier BG381 les a. Un UP5K en SG48 a 39 broches pour vous, et nextpnr ne peut pas placer l'entité de tête.

archec la place alors avec des broches virtuelles. Il enveloppe l'entité de tête dans un module qui met un registre devant chaque broche, sauf les horloges et les remises à zéro. Les entrées deviennent un registre à décalage alimenté par une seule broche réelle. Les sorties sont repliées dans une signature lue sur une autre. C'est ce que voit le design quand le maître du bus est dans le FPGA (un processeur soft, un pont), et non sur ses broches.

  • Les cellules comptées sont celles du design seul, pas celles de l'enveloppe.
  • fmax est mesuré avec l'enveloppe. Il est un peu plus haut qu'avec des broches réelles, qui retiennent la logique près du bord du circuit : 102,9 MHz contre 99,97 MHz sur le HX8K.
  • Il n'en existe pas de bitstream : c'est une mesure, pas un design à charger.

--virtual-pins les demande sur un circuit où les broches tiennent.

Ce que cela prouve#

Chaque limite mesurée est une preuve pour son exigence, au lieu synth <device>. Chaque composant FPGA placé et routé est une preuve pour les exigences qu'il satisfait, sur le barreau synth de l'échelle de test, au-dessus de 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

Une limite tenue prouve son exigence. Un composant synthétisé ne prouve pas les exigences qu'il satisfait : leurs tests le font. Il dit que le matériel sous la forme duquel ils ont été exécutés, dans GHDL, peut être construit pour le circuit et tient son horloge. Un composant qui ne tient pas son horloge les fait échouer. L'enregistrement garde le hash du VHDL : modifiez le modèle, et il est périmé. Un enregistrement pour un circuit que le modèle ne nomme plus n'est pas compté.

Quand la synthèse échoue#

archec écrit le VHDL : il se synthétise donc. Votre propre VHDL dans une région USER CODE peut ne pas le faire. L'erreur nomme l'élément du modèle auquel la ligne appartient :

✗ 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/

Une exécution qui échoue n'enregistre rien.

Un bitstream#

--bitstream écrit aussi le fichier à charger : arche-out/synth/<top>.bin pour un iCE40 (icepack), <top>.bit pour un ECP5 (ecppack). Chaque broche de l'entité de tête doit être sur le circuit : l'entité de tête doit donc tenir dans le boîtier. Dites quelle broche est laquelle avec --constraints : un fichier .pcf pour un iCE40, un .lpf pour un ECP5. archec ne l'écrit pas : le store n'a pas encore de carte FPGA où lire les broches. Sans contraintes, nextpnr choisit les broches, et l'exécution dit que le bitstream n'est pas fait pour une carte.

Un clignotant pour une iCEBreaker (un iCE40 UP5K, une horloge à 12 MHz sur la broche 35, un bouton sur la broche 10, une LED rouge sur la broche 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 }
Diagramme : Board
Ce qu’archec dessine depuis ce code : Board
Essayer
# 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

Le charger sur la carte vous revient. Avec la carte branchée :

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

(ecpprog ou openFPGALoader pour une carte ECP5.) Ce bitstream a été construit et empaqueté ici. Il n'a pas été chargé sur une carte : rien sur cette page n'a tourné sur du matériel, et les numéros de broches ci-dessus viennent de la documentation de la carte, pas d'une exécution.

Les commandes#

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 sort avec 0 quand tous les cas ont réussi, 1 quand l'un a échoué, et 2 quand il n'a pas pu s'exécuter : pas de GHDL, pas de part FPGA, un modèle avec des erreurs. Il écrit le VHDL et les bancs de test sous <out>/vhdl même quand GHDL n'est pas là. --verbose montre ce que GHDL affiche. --json donne les résultats en JSON ; ils sont aussi dans <out>/.archec/ghdl-results.json.

archec synth sort avec 0 quand le design se synthétise, tient ses horloges et respecte ses limites, 1 quand ce n'est pas le cas, et 2 quand il n'a pas pu s'exécuter : pas d'outils, pas de circuit nommé, pas de part FPGA, un modèle avec des erreurs. Ses résultats sont dans <out>/.archec/synth-results.json (--json les affiche). Dans VS Code, Arche: Synthesise FPGA Design l'exécute et montre le rapport dans la sortie Arche Status.

D'où vient GHDL#

archec cherche GHDL dans cet ordre : ARCHE_GHDL (le programme, ou le dossier où une version a été décompressée), le dossier de l'extension, ~/.arche/fpga (ARCHE_FPGA_HOME), puis le PATH. Il ne le télécharge jamais.

Les versions de l'extension par plateforme contiennent une version officielle de GHDL, vérifiée contre son sha256 quand l'extension est empaquetée (tools/fpga/targets.json) :

Version GHDL Notes
darwin-arm64 6.0.0, LLVM JIT macOS 14 ou plus récent.
darwin-x64 5.1.1, mcode GHDL 6.0.0 n'existe pas pour les Mac Intel : la 5.1.1 est la dernière.
linux-x64 6.0.0, mcode Construite sur Ubuntu 24.04 : elle demande glibc 2.38 ou plus récent.
win32-x64 6.0.0, mcode La version UCRT : Windows 10 ou plus récent.
linux-arm64 aucun GHDL ne publie rien pour cette plateforme. Installez GHDL : archec le trouve dans le PATH.

Ces versions ne demandent ni compilateur ni éditeur de liens sur votre machine. Le arche-lang.vsix générique n'a pas de GHDL et utilise celui du PATH.

Pour obtenir la version épinglée sur une machine sans l'extension :

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

GHDL est un logiciel libre sous GPL (version 2 ou ultérieure). L'extension livre sa version sans la modifier, à côté de ses propres fichiers ; fpga/NOTICE.txt dit où se trouve son code source.

D'où viennent les outils de synthèse#

archec synth demande Yosys avec le ghdl-yosys-plugin, nextpnr pour la famille du circuit, et icepack ou ecppack pour un bitstream. L' OSS CAD Suite de YosysHQ les contient tous dans un seul dossier. archec les cherche dans cet ordre : ARCHE_OSS_CAD_SUITE (le dossier où une suite est décompressée), ~/.arche/fpga (ARCHE_FPGA_HOME), puis le PATH.

La suite est grosse : environ 500 Mo à télécharger, 1,8 Go décompressée. Elle n'est dans aucune version de l'extension, et archec ne la télécharge pas : vous le faites.

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

La version de chaque plateforme est épinglée dans tools/fpga/synth-targets.json (2026-11-16 : Yosys 0.71, nextpnr 0.11.1). Le fichier que vous donnez est vérifié contre son sha256, puis décompressé dans ~/.arche/fpga, nulle part ailleurs. Une archive qui a un autre hash n'est pas décompressée.

Plateforme Épinglée Comment son hash a été vérifié
darwin-arm64 oui Téléchargée ici, son sha256 calculé, le flot exécuté dessus.
darwin-x64, linux-x64, linux-arm64, win32-x64 oui Le condensé que GitHub publie pour le fichier de la version. Ni téléchargée, ni exécutée.

Les outils que vous avez installés vous-même marchent aussi (brew install yosys nextpnr, les paquets de votre distribution). Un Yosys sans plugin GHDL est utilisé avec le GHDL qu'archec trouve : le VHDL passe par ghdl --synth.

Les outils de la suite sont des logiciels libres : Yosys, nextpnr, Project IceStorm et Project Trellis sous licence ISC, GHDL et son plugin sous GPL. archec les lance comme des commandes. Il n'en livre aucun.

Limites : ce qu'il ne fait pas encore#

  • Des picosecondes entières. Le simulateur et le banc de test comptent des picosecondes entières. Une horloge à 48 MHz (20833,333 ps) y tourne à 20833 ps, et archec check le dit. Le VHDL lui-même ne contient aucune période.
  • Entre deux horloges : un bit, ou un message. Un signal de plusieurs bits est refusé : envoyez-le comme un message. La poignée de main transporte environ un message tous les trois cycles de chaque horloge ; il n'y a pas de FIFO asynchrone. Dans un test, toutes les horloges démarrent en phase, au temps 0 : une autre phase n'est pas essayée. Le simulateur et GHDL n'ont pas de métastabilité : les deux bascules sont là pour le circuit réel.
  • États : pas de région, pas d'historique. Un état dans un état, son enfant initial et un choix sont synthétisés. Une région, un état d'historique, un fork, un join, un point d'entrée et un point de sortie ne le sont pas.
  • Un port qui a deux émetteurs demande un arbitre que vous écrivez : seul son premier lien est câblé. overflow drop-oldest et overflow block ne sont pas synthétisés : un port plein abandonne le message qui lui est envoyé, ou fn main attend.
  • Un message transporte des champs. send port MSG { field: value } : un message déclaré comme une seule valeur (message LEVEL: uint8) n'est pas envoyé depuis un corps.
  • Des registres de 32 bits au plus depuis un test. Un banc de test écrit un registre par le bus en une seule écriture AXI4-Lite, et le banc prend une écriture tous les deux cycles. Un bloc mémoire de plus de 16 éléments est une fenêtre mémoire du banc, non câblée au composant.
  • Non exécuté dans GHDL : un cas qui fixe une variable à l'intérieur de la logique, qui utilise un setup, un keyframe ou un fault, ou qui est écrit en Python.
  • Le simulateur d'Arche ne fait pas avancer une horloge. archec test exécute à la place les cas d'un système qui a des parts FPGA sur le simulateur du navigateur ; --sim python demande toujours celui d'Arche.
  • La synthèse pour iCE40 et ECP5 seulement. archec synth connaît ces deux familles, qui ont des outils open source. Pour un circuit Xilinx ou Intel, donnez vous-même le VHDL (vhdl/sources.txt) à Vivado ou à Quartus.
  • Les contraintes de broches vous reviennent. archec n'écrit pas de fichier .pcf ou .lpf : le store n'a pas de carte FPGA où lire les broches.
  • Jamais exécuté sur du matériel. Le design a été simulé dans GHDL, synthétisé, placé, routé et empaqueté. Aucun bitstream n'a été chargé sur une carte.
  • La part d'un composant dans l'entité de tête n'est pas mesurée. Ses nombres sont ceux du composant synthétisé seul.
  • Des broches virtuelles sur une seule horloge chacune. Une broche de l'entité de tête passe par un registre sur l'horloge de la part à laquelle elle appartient. Avec plusieurs horloges, le fmax de chacune est donné.
  • Pas de contrainte de temps entre deux horloges. Un lien entre deux horloges passe par les synchroniseurs de arche_cdc.vhd. nextpnr donne à part les chemins d'une horloge à une autre : ils ne comptent dans le fmax d'aucune des deux, et archec synth n'écrit pour eux aucune contrainte de faux chemin ou de délai maximal. Les bascules portent l'attribut async_reg, que Vivado lit ; dans un autre outil, contraignez vous-même le franchissement.
  • Les outils de synthèse n'ont été exécutés que sur macOS (arm64). Les versions des autres plateformes sont épinglées par le hash que GitHub publie.
  • La version Windows de GHDL est épinglée et vérifiée, mais n'a pas été exécutée par les tests de cette fonctionnalité.