Guides pratiques › Générer des cartes de registres

Guides pratiques

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
}
Diagramme : Timer peripheral
Ce qu’archec dessine depuis ce code : Timer peripheral
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 est const 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 memory contient un élément (: uint32) ou plusieurs (: uint16[4], ou count 80). Il se trouve à l'adresse qui suit @.
  • Son élément a la taille de son type, ou size octets. Un record de champs dont tous les bits sont donnés fait 4 octets.
  • Après le type, rw, r (ro) ou w (wo) indique qui peut le lire ou l'écrire sur le bus. Sans accès précisé, c'est rw.
  • 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 bits occupe les octets qui suivent le champ précédent : sa size, sinon la taille de son type. Un record décrit octet par octet, comme une mémoire partagée, n'a donc pas besoin de bits.
  • 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. WSTRB n'é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, _wstrb et _we pour écrire ;
    • <block>_raddr, _re et _rdata pour 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_awaddr n'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.