Cartes de registres
Une carte de registres indique où se trouve chaque registre matériel d'une
part, et ce que signifie chacun de ses bits. archec gen --target regmap
l'écrit à partir des blocs memory de la part qui ont une adresse. Elle est
écrite une fois pour chaque côté qui doit s'accorder dessus : le logiciel qui
lit et écrit les registres, le matériel qui les contient, et les outils et
documents entre les deux. Tous viennent des mêmes blocs : une modification du
modèle se répercute donc partout à la fois.
Une première carte#
enum TimerMode { ONE_SHOT, PERIODIC, PWM = 3 }
component Timer "Timer peripheral" {
/// Control: start, mode and the interrupt enable.
memory CTRL @ 0x4300_0000 : uint32 rw {
enable: bool bits "0"
mode: TimerMode = PERIODIC bits "2:1"
prescale: uint8 = 4 bits "23:16"
}
memory STATUS @ 0x4300_0004 : uint32 r { running: bool bits "0" }
memory COMPARE @ 0x4300_0010 : uint16[4] rw
memory BUFFER @ 0x4300_0100 : uint32[128] rw
}archec gen main.arche --target regmap -o generated
generated/regmap/timer/timer_regs.h
generated/regmap/timer/timer_regs.vhd
generated/regmap/timer/timer_regs.sv
generated/regmap/timer/timer.xml
generated/regmap/timer/timer.rdl
generated/regmap/timer/timer.md
L'en-tête C donne la position de chaque champ, et des macros pour le lire et l'écrire :
#define TIMER_CTRL_MODE_SHIFT 1u
#define TIMER_CTRL_MODE_MASK 0x6u
#define TIMER_CTRL(base) (*TIMER_CTRL_PTR(base))
#define TIMER_COMPARE(base, i) (*TIMER_COMPARE_PTR(base, i))
timer.md présente la carte sous forme de document :
| Offset | Adresse | Bloc | Accès | Taille | Reset | Dans le banc | Description |
|---|---|---|---|---|---|---|---|
0x0000 |
0x43000000 |
CTRL | rw | 4 o | 0x40002 |
registre | Control: start, mode and the interrupt enable. |
0x0004 |
0x43000004 |
STATUS | r | 4 o | 0x0 |
registre | |
0x0010 |
0x43000010 |
COMPARE | rw | 4 × 2 o | 0x0 |
registre | |
0x0100 |
0x43000100 |
BUFFER | rw | 128 × 4 o | 0x0 |
port mémoire |
Les fichiers#
Pour chaque carte, dans regmap/<part>/ :
| Fichier | Contenu |
|---|---|
<part>_regs.h |
C, pour C11 et C++ (voir plus bas). |
<part>_regs.vhd |
VHDL-93 : un package des offsets et des positions de champs, et le banc de registres, un esclave AXI4-Lite. |
<part>_regs.sv |
SystemVerilog : le même banc, port pour port. |
<part>.xml |
IP-XACT (IEEE 1685-2014) : la carte mémoire. Elle contient les registres avec leurs champs, valeurs de reset, accès et valeurs énumérées. Les mémoires sont des blocs d'adresses à part entière. |
<part>.rdl |
SystemRDL 2.0 : la carte d'adresses, pour PeakRDL et les autres outils RDL. |
<part>.md |
La carte mémoire sous forme de document : un tableau des blocs, puis les champs de chaque bloc. |
L'en-tête C contient :
- la base,
TIMER_BASE. Vous pouvez la définir avant d'inclure l'en-tête ; - l'offset, l'adresse, la taille d'élément, le nombre d'éléments et la valeur de reset de chaque bloc ;
- les
_SHIFT,_WIDTH,_MASK,_GET(v)et_SET(v, x)de chaque champ ; - les valeurs d'un champ de type enum ;
- des macros d'accès qui prennent un pointeur de base :
TIMER_CTRL(base),TIMER_COMPARE(base, i). Un bloc en lecture seule estconst volatile; - une struct de toute la carte, à plaquer sur la base ;
- des assertions statiques qui placent chaque bloc de cette struct à son offset.
Un record dont les champs occupent des octets entiers devient sa propre struct, et sa taille est vérifiée par assertion. Un bloc de mémoire partagée décrit octet par octet en est un exemple.
Une carte porte le nom de sa part. Quand deux parts ont le même nom, la carte
porte aussi le nom des parts qui les entourent (kria_shm, kriakr260_shm).
Sa base est l'adresse du premier bloc, alignée sur une page de 4 Kio. Les
offsets partent de là.
Le modèle#
- Un bloc
memorycontient un élément (: uint32) ou plusieurs (: uint16[4], oucount 80). Il se trouve à l'adresse qui suit@. - Son élément a la taille de son type, ou
sizeoctets. Un record de champs dont tous lesbitssont donnés fait 4 octets. - Après le type,
rw,r(ro) ouw(wo) indique qui peut le lire ou l'écrire sur le bus. Sans accès précisé, c'estrw. reset 0x…est la valeur de l'élément au reset. La valeur propre d'un champ (mode: TimerMode = PERIODIC) la remplace.- Un champ se place à
bits "hi:lo", ou àbits "3"pour un seul bit. - Un champ sans
bitsoccupe les octets qui suivent le champ précédent : sasize, sinon la taille de son type. Un record décrit octet par octet, comme une mémoire partagée, n'a donc pas besoin debits. - Un bloc sans adresse n'est pas dans la carte. Une note le signale.
archec check avertit de tout ce qui mettrait deux côtés en désaccord :
| Code | Quand |
|---|---|
memory-overlap |
deux blocs d'une part se chevauchent |
memory-misaligned |
un bloc d'éléments de 2, 4 ou 8 octets n'est pas sur un multiple de la taille de ses éléments. Un bus le lirait ou l'écrirait en deux accès, pas d'un coup. |
memory-field-width |
un champ dépasse les bits d'un élément, ou est plus large que son type (uint8 bits "15:4"), ou ses bits ne se lisent pas comme "hi:lo" |
memory-field-overlap |
deux champs partagent un bit |
Le banc#
Le banc de registres est le côté matériel : les registres en VHDL ou en SystemVerilog, derrière un bus. Ce bus est AXI4-Lite.
Pourquoi AXI4-Lite plutôt qu'un bus générique simple ? En pratique, les parts qui ont des cartes de registres se trouvent sur un Zynq ou un Kria. Le côté processeur (PS) y accède à la logique programmable (PL) par AXI. Le packager d'IP de Vivado et ses interconnexions parlent AXI, tout comme les outils des autres fabricants de FPGA. Un bus générique demanderait un pont écrit à la main de chaque côté. AXI4-Lite est en outre léger : une lecture et une écriture à la fois, des données sur 32 bits, des strobes d'octets.
Chaque octet de chaque élément est une voie d'octet (byte lane) d'un mot de 32 bits. Les registres de 8, 16, 32 et 64 bits s'écrivent et se lisent donc de la même façon, regroupés ou non.
WSTRBn'écrit que les octets qu'il désigne.rw: un registre que le bus écrit et relit, sur<block>_o.w: un registre que le bus écrit et qui se relit à 0, sur<block>_o.r: une valeur que le matériel pilote sur<block>_i. Les écritures sont ignorées.Un bloc accessible en écriture a un strobe d'écriture par élément,
<block>_wr. Il passe à l'état haut pendant un cycle après une écriture dans l'élément.Un bloc de plus de 16 éléments, ou d'éléments de plus de 8 octets, est une mémoire, pas des registres. Le banc décode sa plage et transmet chaque accès à un port dédié, comme le ferait une RAM double port synchrone :
<block>_waddr,_wdata,_wstrbet_wepour écrire ;<block>_raddr,_reet_rdatapour lire. La donnée lue arrive un cycle après_re.
Les adresses sont des offsets en octets dans la mémoire.
Les registres sortent du reset (
s_axi_aresetnà l'état bas) avec leurs valeurs de reset.Une adresse absente de la carte répond SLVERR.
Les adresses partent de la base de la carte : l'interconnexion retire la base.
s_axi_awaddrn'est donc pas plus large que ce dont la carte a besoin.
Vérifié#
Les tests (test/regmap.test.js) :
- compilent les en-têtes de la fixture et d'examples/autonomous-car en C11 et
en C++17 avec
-Wall -Wextra -Werror, ce qui valide les assertions statiques. Les en-têtes d'un projet privé sont aussi compilés quand on donne son dossier au test ; - construisent chaque banc SystemVerilog avec iverilog ;
- simulent le banc de la fixture face à des lectures et écritures AXI4-Lite : valeurs de reset, strobes d'octets, une entrée en lecture seule dans les voies hautes, un port mémoire, SLVERR ;
- analysent le VHDL avec ghdl quand il est installé ;
- vérifient l'IP-XACT avec xmllint.
Le SystemRDL et l'IP-XACT de ces cartes ont aussi été relus par systemrdl-compiler et par l'importeur IP-XACT de PeakRDL. Les deux ont retrouvé les blocs, les champs et les valeurs de reset donnés par le modèle.
Dans un composant FPGA#
Un composant doté d’une horloge (fpga.md) lit et pilote ses registres
par leur nom dans ses corps. archec gen --target vhdl écrit le même banc VHDL
à côté du composant et le câble dans le top du système : les registres rw et
w entrent dans le composant, les registres r en sortent, les broches
AXI4-Lite sont sur le top. Un cas de test qui fixe un registre l’écrit par ce
bus.
Limites#
- Le modèle ne sait pas encore exprimer un accès au niveau du champ (un champ en lecture seule dans un registre en lecture-écriture), ni des champs « write-1-to-clear » ou « read-to-clear ».
- Le bus du banc est uniquement AXI4-Lite, sur 32 bits. Il n'y a ni APB, ni Avalon, ni Wishbone.
- La carte d'une part n'a pas de base propre dans le modèle : la base est l'adresse de son premier bloc.