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-x64ou-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 aussiARCHE_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"
}| 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
}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
}
```
}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
}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"
}
}Ce que fait un cycle#
À chaque front montant, dans cet ordre :
fn main, quand le composant en a une : ses instructions jusqu'à son prochainwait.- Chaque message pris sur ce front : la transition qu'il déclenche, le
on-receivedu port, ses handlers. - Les transitions
on "after …"dont le temps est venu. - Les transitions qui ont une garde et pas de déclencheur. Elles sont essayées à chaque cycle.
- 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
}
```
}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 }
}
}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
}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 :
- archec écrit le VHDL sous
arche-out/vhdl, comme le faitarchec gen. - 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). - 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.
- 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" }| 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 }# 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 checkle 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-oldestetoverflow blockne sont pas synthétisés : un port plein abandonne le message qui lui est envoyé, oufn mainattend. - 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, unkeyframeou unfault, ou qui est écrit en Python. - Le simulateur d'Arche ne fait pas avancer une horloge.
archec testexécute à la place les cas d'un système qui a des parts FPGA sur le simulateur du navigateur ;--sim pythondemande toujours celui d'Arche. - La synthèse pour iCE40 et ECP5 seulement.
archec synthconnaî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
.pcfou.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, etarchec synthn'écrit pour eux aucune contrainte de faux chemin ou de délai maximal. Les bascules portent l'attributasync_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é.