Ais-je bien téléchargé la dernière version de mon gateware dans ce montage ?
C’est un problème classique quand on fait de l’embarqué, entre l’éditeur de code, la génération du code bas niveau (Verilog dans le cas de Chisel) le logiciel de synthèse/placement-routage et le téléchargement du bitstream, il y a plein de façon de se tromper de version du logiciel s’exécutant réellement dans le montage. Et l’on peu passer des heures à chercher un bug dans son système en modifiant des lignes de code alors que le problème vient d’une même (vieille) version téléchargée éternellement.
Pour s’assurer que le gateware qui se trouve dans le FPGA soit bien le dernier généré il faut trouver une manière d’y enregistrer une valeur qui sera différente à chaque fois.
On pourrait mettre une version «en dur» dans nos sources, mais l’expérience montre que l’on oublie 4 fois sur 5 de l’incrémenter avant de générer le fichier. Toute bonne développeuse et tout bon développeur versionne son projet avec un gestionnaire de version. On pourrait du coup mettre le numéro de commit. Sauf que l’on ne commit pas toujours la modification avant de la tester.
Une autre astuce consiste à mettre la date EPOCH. De cette manière nous avons la date et l’heure précise de la synthèse du gateware. Cette solution est intéressante mais elle pose rapidement un problème d’occupation du FPGA. En effet, le temps en secondes filant assez rapidement nous avons besoin de registres de 32 bits minimum voir même 64bits. Ce qui est plutôt inutile pour compter les builds …
Compter les builds ?
La voila la solution toute simple, il suffit d’enregistrer un compteur dans un fichier texte. À chaque build, une fonction vient lire la valeur et l’incrémente. Pour rester à jour il nous suffit ensuite de versionner ce fichier avec le reste du code. Même si le nombre de build est grand, on n’aura rarement besoin d’en faire plus de quelques millier, ce qui rentrera très bien dans un registre de 16 bits voir moins.
Voici comment faire en Scala avec Chisel.
Dans un package avec les utilitaires «personnel» :
package myutil
On importe les packages d’entrées sorties pour lire/écrire dans les fichiers textes:
// Pour fromFile()
import scala.io.Source
// Pour PrintWriter()
import java.io._
Puis on crée une fonction de lecture écriture dans un objet personnel MyUtility :
def genCountVers(className: String = null): Option[Int] = {
if(className == null){
return None
}
println("generate counter for class " + className)
val filename = "src/main/scala/util/gen_count_vers.txt"
val versmap = scala.collection.mutable.Map[String,Int]()
/* read file to hashmap*/
val fp = Source.fromFile(filename)
for(v <- fp.getLines.map(_.split(",").map(_.trim))){
versmap(v(0)) = v(1).toInt
}
fp.close()
/* get and increment version */
val version = versmap.get(className)
if(version == None){
versmap(className) = 0
} else {
versmap(className) = version.get.toInt + 1
}
/* write back file*/
val fpw = new PrintWriter(new File(filename))
for ((hname, hvalue) <- versmap) {
fpw.write(hname + "," + hvalue + "\n")
}
fpw.close()
/* return version */
version match {
case Some(s) => Some(s.toInt + 1)
case None => Some(0)
}
}
La fonction genCountVers() va ouvrir le fichier texte gen_count_vers.txt, qui est un «CSV» composé du nom de classes et d’un numéro. Si le nom de la classe passé en paramètre n’existe pas la fonction va l’ajouter avec un compteur à zero.
Nous n’avons plus qu’a appeler la fonction genCounterVers() avec le nom de la classe (ou autre) de notre choix pour la fourrer dans un registre lisible via notre interface (spi, wisbone, i2c, jtag, …) directement sur le FPGA :
val buildnum = MyUtility.genCounterVers("MyTopClasse").get
class RValue (val cSize: Int = 16) extends Bundle {
val rvalue = Output(UInt(cSize.W))
val er = Output(UInt((cSize/2).W))
val part = Output(Bool()) /* set if value is partial */
}
And we want to make a register with initialized value we can use the new interface named BundleLiterals:
It can be usefull to be able to test code in console before launching the big compilation. It’s possible in directory where your project build.sbt is :
$ cd myproject/
$ sbt
sbt:myproject> console
scala>
And once in the scala console chisel import can be done :
In previous (french) article, I described a technic to integrate a Chisel3 component named « TapTempo » in the APF27 board. This board is made with an i.MX27 CPU and a Spartan3A FPGA.
To communicate with the FPGA, the i.MX27 is plugged on it with a memory bus named «WEIM». But the data signals used in WEIM are also connected on flash nand memory on the board, and this memory contain the Linux kernel and rootfs.
It’s not a problem if the FPGA « release » the data bus in high impedance when not used. Ant it’s the case when we use ctrl signal correctly (with oen signal -> output enable not)
In the first design, as tempo data are only output values read by the CPU, it was declared as « output » in chisel bundle :
class APF27TapTempo extends Module {
val io = IO(new Bundle {
val data = Output(UInt(16.W))
[...]
But with this data description, electrical value on physical data bus is continuously held by the FPGA. And when i.MX want to access nand flash memory it can’t. And we cannot start Linux as it require reading value in flash memory.
The solution is to set data bus as bidirectional signal and use WEIM signal oen to enable output on data bus, and when oen is not active the data bus is left on high impedance state ‘Z’.
In chisel, to manage bidirectional signal, we have to use the type « analog » as it :
class APF27TapTempo extends Module {
val io = IO(new Bundle {
val oen = Input(Bool())
val data = Analog(16.W)
[...]
And simply deactivate data when oen is ‘1’ ?
when(oen === '1'){
data := "bZZZZZZZZZZZZZZZZ"
}.otherwize {
data := taptempovalue
}
Would be so easy … But no, we can’t do that with Chisel3 🙁
In FPGA or ASIC, the high state value doesn’t exist in fact. All signals under FPGA must be input or output and set to ‘0’ or ‘1’. No other values are actually supported.
Other « high impedance » values like ‘Z’, ‘H’ or ‘L’ can’t be synthesized under the fpga. But these values (mostly ‘Z’ state in fact) can be synthesized on the boundary. If a bidirectional signal going out of FPGA, the xilinx synthesizer can instantiate an IOBUF and manage the high state.
Chisel doesn’t manage this high state. It’s a deliberate choice from chisel developers team to simplify Chisel3. But for some design, like on APF27 we need to implement it.
Verilog manage this kind of signal state, then we can write a verilog code to write ‘Z’ state and include it in our chisel design.
To do this, we use a module chisel type named BlackBox. And as we want to add directly verilog source in the chisel code we will add the Trait HasBlackBoxInline like described bellow :
// import verilog code with HasBlackBoxInline
import chisel3.util.{HasBlackBoxInline, HasBlackBoxResource}
...
// Describe blackbox with verilog code
class Apf27Bus extends BlackBox with HasBlackBoxInline {
val io = IO(new Bundle {
val dataout = Output(UInt(16.W))
val dataio = Analog(16.W)
val datain = Input(UInt(16.W))
val oe = Input(Bool())
})
setInline("Apf27Bus.v",
s"""
|module Apf27Bus(
| output [15:0] dataout,
| inout [15:0] dataio,
| input [15:0] datain,
| input oen);
|
| assign dataio = (oen == 'b0) ? datain : 'bzzzzzzzzzzzzzzzz;
| assign dataout = dataio;
|endmodule
""".stripMargin)
}
// Verilog will be written in separate file named Apf27Bus.v
...
// Then connect it in "Top" module
val iobuf = Module(new Apf27Bus)
io.data <> iobuf.io.dataio
iobuf.io.datain := dataout
iobuf.io.oen <> io.oen
As dataio is Analog type, we have to declare also analog on top bundle module :
class APF27TapTempo extends Module {
val io = IO(new Bundle {
val data = Analog(16.W)
val oen = Input(Bool())
val button = Input(Bool())
})
With this method, we keep all our sources codes in the chisel sources and our high ‘Z’ bidirectional port is correctly synthesized with classical commercials software.
All sources of this project described in this article are available on my github project TapTempoChisel.
Le «défi TapTempo» a été lancé sur LinuxFr il y a quelques semaines. L’objectif est de réaliser la mesure du tempo de l’appui sur une touche et de l’afficher simplement dans la console le résultat. La mesure du tempo s’effectue par défaut sur 5 appuis consécutif et affiche une moyenne en bpm (Beats Per Minute). L’idée est de réaliser la fonction dans divers langages informatiques pour que chacun puisse promouvoir son langage favoris. Beaucoup de langages ont été représenté jusqu’à présent, mais aucun langages de description matériel n’avait encore été proposé.
Pour palier ce gros manquement dans les langages représenté je vous propose ici de réaliser TapTempo en Chisel (version 3).
Architecture générale
L’idée ici n’est donc plus d’écrire un programme pour calculer le tempo mais de décrire l’architecture d’un composant matériel permettant de réaliser la fonction. Le matériel visé sera un FPGA, nous laissons de coté le développement sur ASIC. Même si une fois terminé il ne devrait pas y avoir de problème pour être porté sur un ASIC, si quelqu’un a suffisamment d’argent pour le claquer dans ce genre d’ânerie 😉
Le bloc fonctionnel de notre composant sera donc constitué d’une entrée button recevant le signal de l’appui sur un bouton permettant de faire le tempo. Dans un premier temps nous laisserons de coté les problèmes de métastabilité ainsi que de rebond. L’implémentation réel dans un FPGA nécessitera obligatoirement l’ajout d’un étage de synchronisation du signal d’entrée avec l’horloge ainsi que d’un bloc «anti-rebond», aucun bouton réel n’étant capable de faire un signal vraiment propre.
La sortie du bloc sera constitué d’un entier non signé bpm dont nous allons discuter la taille ci-dessous.
Et comme nous somme dans un FPGA il est indispensable de concevoir notre fonction synchrone d’une horloge, et souhaitable d’avoir un reset général.
Structure interne
La structure interne de TapTempo est donnée ci-dessous:
L’idée est de compter des ticks générés par timepulse au moyen du compteur count. Quand un appui sur le bouton est détecté, le compteur se remet à zéro et la valeur est enregistrée dans le tableau countx. À chaque coup d’horloge l’addition des 4 valeurs count est réalisée puis on divise par 4. La division par 4 est réalisable dans un FPGA au moyen d’un simple décalage à droite de 2. Vient la partie la plus compliqué : se servir de cette période moyenne pour diviser TMINUTE et obtenir la valeur du tempo en bmp.
Un peu de dimensionnement
On ne fonctionne pas dans un FPGA comme on fonctionne avec un pc, quand on fait des opérations sur des nombres il faut les dimensionner. Et il est fortement recommander d’utiliser des entiers, car le calcul flottant nécessite tout de suite une quantité de ressources phénoménale.
Notre objectif est de mesurer une cadence musicale en bpm que l’on puisse «taper à la main», si l’on regarde l’article wikipedia consacré au Tempo, on se rend vite compte qu’attendre les 200bpm est déjà pas mal. Disons que pour prendre une très large marge nous mettons la marge supérieur à 270bpm. Nous aurons donc en sortie une variable entière sur 9bits ( int(ln2(270))+1).
À 270bpm, le temps entre deux tempos est de ~222ms ce qui nous donnerais une fréquence de pulse de 4.5Hz. Cependant, si nous voulons une précision de 1bpm il va falloir augmenter cette fréquence , pour avoir un chiffre rond nous prendrons un temps de 1ms, soit une fréquence de 1kHz. Ce qui est un peu juste pour 270bpm, mais conviendra à la démonstration.
Décomposons le code
Le code se trouve sur le dépôt github suivant. Nous allons décrire la description du module à proprement parlé qui se trouve ici.
Dans l’entête du module nous allons retrouver le port d’entrée button ainsi que le port de sortie bpm. Point d’horloge ni de reset ici puisqu’en Chisel ces signaux sont implicite.
// default clock 100Mhz -> T = 10ns
class TapTempo(tclk_ns: Int, bpm_max: Int = 270) extends Module {
val io = IO(new Bundle {
// val bpm = Output(UInt(8.W))
val bpm = Output(UInt(9.W))
val button = Input(Bool())
})
Quelques constantes qui nous servirons ensuite :
/* Constant parameters */
val MINUTE_NS = 60*1000*1000*1000L
val PULSE_NS = 1000*1000
val TCLK_NS = tclk_ns
val BPM_MAX = bpm_max
/* usefull function */
def risingedge(x: Bool) = x && !RegNext(x)
Pour notre générateur de pulses il suffit d’utiliser une classe présente dans la bibliothèque «util» de chisel : Counter. Qui comme son nom l’indique … compte !
import chisel3.util.Counter
[...]
val (pulsecount, timepulse) = Counter(true.B, PULSE_NS/tclk_ns)
[...]
Ce compteur prend en paramètre un signal de comptage (ici true.B -> compte tout le temps) ainsi que la valeur max à atteindre.
L’instanciation de l’objet retourne un compteur ainsi qu’un signal qui passe à ‘1’ quand le compteur se remet à zero (quand il dépasse la valeur max).
Ce signal timepulse sera ensuite utilisé par un deuxième compteur 16 bits tp_count que nous allons écrire «à la main» cette fois.
On défini d’abord le registre de 16bits que l’ont initialise à 0 (0.asUInt(16.W))
val tp_count = RegInit(0.asUInt(16.W))
Puis on écrit le code décrivant le «comptage»:
when(timepulse) {
tp_count := tp_count + 1.U
}
when(risingedge(io.button)){
// enregistrement de la valeur du compteur.
countx(count_mux) := tp_count
count_mux := Mux(count_mux === 3.U, 0.U, count_mux + 1.U)
// remise à zéro du compteur
tp_count := 0.U
}
Ce deuxième compteur compte les pulse «timepulse» et se remet à 0 lorsqu’un front montant est détecté sur le bouton (quand on appuis sur le bouton).
Pour stocker les 4 valeurs permettant de réaliser une valeurs nous déclarons un vecteur de registres de 19 bits (pour gérer les retenues quand nous ferons l’addition):
val countx = RegInit(Vec(Seq.fill(4)(0.asUInt(19.W))))
Ainsi que le «pointeur» :
val count_mux = RegInit(0.asUInt(2.W))
La gestion de l’incrémentation du pointeur ainsi que de l’enregistrement du compteur se trouve dans le code du «compteur de pulse» que nous avons vu plus haut:
// enregistrement de la valeur du compteur.
countx(count_mux) := tp_count
count_mux := Mux(count_mux === 3.U, 0.U, count_mux + 1.U)
Pour faire la somme rien de plus simple, il suffit de faire ‘+’ :
val sum = Wire(UInt(19.W))
[...]
sum := countx(0) + countx(1) + countx(2) + countx(3)
Et la division par 4 se résume à un décalage:
val sum_by_4 = sum(18, 2)
Et nous arrivons à la partie la plus compliquée du design : diviser. Diviser est quelque chose de très compliqué dans un FPGA, on peut réaliser un design permettant d’effectuer une divisions en plusieurs cycles d’horloge, mais c’est tout de suite une très grosse usine à gaz.
Pour la division permettant de faire la moyenne des échantillons nous nous en étions sortie en faisant une division par une puissance de 2, qui se résume de fait à un simple décalage. Mais cette fois on ne pourra pas s’en sortir avec ce genre de pirouette. Car notre division à réaliser est la suivante :
Nombre de pulse dans une minute
------------------------------------- = valeur en bpm
moyenne des pulses mesuré (sum_by_4)
Pour nous en sortir la première idée serait de faire une table de valeurs pré-calculée pour chaque valeurs de sum_by_4. Ce qui se fait très simplement en scala avec une séquence :
val x = Seq.tabulate(pow(2,16).toInt-1)(n => ((MINUTE_NS/PULSE_NS)/(n+1)).U)
Sauf que le nombre de valeurs est particulièrement grand (2^16) et qu’on pourrait certainement factoriser un peut tout ça.
Pour réduire la taille ne notre tableau il faut prendre le problème à l’envers: combien de valeurs possible puis-je avoir en sortie ?
La réponse est simplement 269 puisque je peux aller de 1 à 270bpm. Nous allons donc réaliser un vecteur de 270 valeurs contenant la valeurs minimum du compteurs permettant d’atteindre notre résultat. Et nous mettrons ces valeurs dans 270 registres.
val bpm_calc = RegInit(Vec(x(0) +: Seq.tabulate(bpm_max)(n => x(n))))
Pour obtenir la valeur finale il faut ensuite générer 270 inéquations ayant pour résultat un vecteur de 270 bits :
Le résultat correspondra ensuite à l’index du dernier bit à 1 dans ce vecteur.
Pour récupérer cet index, une fonction très utile est fournie dans la bibliothèque «util» de chisel : le PriorityEncoder. Qui permet d’obtenir l’index du plus petit bit à 1 dans un vecteur… sauf que nous on veut le plus grand !
Mais ce n’est pas très grave, il suffit de retourner le vecteur avec Reverse puis de faire une soustraction pour avoir le résultat :
Pour être vraiment complet il faudrait ajouter la gestion des rebonds ainsi que la synchronisation du signal d’entrée puis tester la synthèse. Mais ce sont de nouvelles aventure qui continuerons peut-être dans un prochaine épisode 🙂 .
Quelque soit le langage HDL utilisé il est très important de se garder la possibilité d’intégrer des modules provenant d’autre langages et/ou n’ayant pas de descriptions HDL.
C’est par exemple le cas des primitives matériel permettant d’instancier des modules intégrés au FPGA du constructeur au moyen de «template» Verilog : sérialiseur/désérialiseur, PLL, entrées/sorties spécifiques, …
BlackBox
Pour intégrer ce genre de module dans son projet Chisel3 on utilise des «BlackBox». L’idée est de décrire les entrées/sorties du module ainsi que ses paramètres, et Chisel se chargera de convertir ça en une déclaration Verilog.
Le problème est assez classique sur les kits de développement de Xilinx qui sont cadencé par une horloge différentielle : Obligé d’instancier un buffer différentiel pour pouvoir récupérer l’horloge. Ce qui n’est pas prévu dans la classe Module de base de Chisel3 puisque l’horloge − tout comme le reset − est implicite.
D’après la documentation Xilinx, le buffer différentiel IBUFDS doit être instancié de la manière suivante en Verilog pour que le logiciel de synthèse le repère et l’instancie correctement:
Cette instanciation est composée de deux paramètres «generic» et de trois entrées sorties.
Une BlackBox() se comporte comme un Module() sans les horloges et reset implicites. De plus le nom des IO est recopié tel quel par Chisel, il n’ajoute pas le préfixe «io_» comme pour un module normale.
Pour déclarer ce buffer différentiel en Chisel il suffira donc d’écrire le code suivant:
import chisel3._
import chisel3.util._
import chisel3.experimental._
class IBUFDS extends BlackBox(
Map("DIFF_TERM" -> "TRUE",
"IOSTANDARD" -> "DEFAULT")) {
val io = IO(new Bundle {
val O = Output(Clock())
val I = Input(Clock())
val IB = Input(Clock())})
}
Le Map en paramètre de la class BlackBox() permet d’ajouter les paramètres «generic» et les entrées sortie sont déclarés par la variable io.
Il suffira alors de l’instancier dans notre module top :
val ibufds = Module(new IBUFDS)
ibufds.io.I := clock_p
ibufds.io.IB:= clock_n
Pour que le code Verilog soit correctement écrit dans le fichier final.
Top RawModule
Maintenant que nous avons notre entrée d’horloge, notre but est d’aller faire clignoter une led (quelle originalité !) en utilisant un compteur. Avec le module suivant:
class Blink extends Module {
val io = IO(new Bundle {
val led = Output(Bool())
})
val MAX_COUNT = 100000000
val count = Counter(MAX_COUNT)
count.inc()
io.led := 0.U
when(count.value <= UInt(MAX_COUNT)/2.U){
io.led := 1.U
}
}
Ce module étant un module «normal» l’horloge et le reset sont implicite, alors comment allons nous faire pour qu’il soit cadencé par la sortie du buffer IBUFDS ?
On peut simplement les intégrer dans un Module() classique que l’on appellera Top :
class Top extends Module {
val io = IO(new Bundle {
val clock_p = Input(Clock())
val clock_n = Input(Clock())
val led = Output(Bool())
})
val ibufds = Module(new IBUFDS)
ibufds.io.I := io.clock_p
ibufds.io.IB:= io.clock_n
val blink = Module(new Blink)
blink.clock := ibufds.io.O
blink.reset := 1'0
io.led := blink.io.led }
Notez que pour connecter explicitement l’horloge, la technique est en phase de développement mais il faut désormais utiliser la classe withClockAndReset() pour faire les choses proprement . Plutôt que :
Cette méthode va fonctionner mais elle va nous ajouter les signaux clock et reset implicites. Signaux qui ne serviront pas à grand chose dans notre cas et généreront des warning pénible dans le logiciel de synthèse:
C’est pour cela qu’une nouvelle hiérarchie de classe est en développement pour les Module().
Un module Top est un module un peu spécial en conception HDL. En effet, ce type de module se contente simplement de «relier des boites entre elles». Ce n’est que du tire-fils, pas besoin d’horloge, de registres et autre structures complexes ici.
Dans la nouvelle hiérarchie des classes Module nous avons donc une nouvelle classe appelée RawModule qui apparaît. Ce module n’a plus aucun signaux implicite et se contente de relier les fils. Dans le code Chisel précédent nous pouvons juste renommer Module en RawModule pour voir que les signaux reset et clock disparaissent:
class Top extends RawModule {
Nous obtenons alors une entête Verilog plus propre :
Nous avons tout de même ce préfixe «io_» disgracieux qui peu devenir pénible pour l’intégration, notamment dans certaine plate-forme où le pinout est déjà fourni pour des noms de pin précis.
Il est possible de les éviter avec les RawModule simplement en utilisant plusieurs variable IO() sans Bundle :
class Top extends RawModule {
val clock_p = IO(Input(Clock()))
val clock_n = IO(Input(Clock()))
val led = IO(Output(Bool()))
val ibufds = Module(new IBUFDS)
ibufds.io.I := clock_p
ibufds.io.IB:= clock_n
withClockAndReset(ibufds.io.O, false.B) {
val blink = Module(new Blink)
led := blink.io.led
}
}
De cette manière c’est le nom exact de la variable qui sera pris en compte pour générer le Verilog:
module Top(
input clock_p,
input clock_n,
output led
);
Et voila comment nous pouvons désormais faire un projet proprement écrit en Chisel de A à Z, ce qui n’était pas le cas avant où nous étions obligé d’encapsuler le projet dans des Top.v écrit à la main, et obligé de les modifier à chaque changement d’interface.
Le code décrit dans cet article se retrouve sur le Blinking Led Projet, dans le répertoire platform. Pour pouvoir le tester correctement, ne pas oublier de télécharger sa propre version de Chisel3 et de merger la branche modhier comme expliqué dans le README.
