Avec Cocotb nous avons parfois des coroutines qui sont susceptible de rester «coincées» dans une boucle d’attente infinie. Si l’on y prête pas garde, on a vite fait de remplir son disque dur de traces totalement inutile.
# Une coroutine qui attend bien trop longtemps
async def too_long_coroutine(self):
await Timer(1, units="sec")
Pour éviter ce problème, l’idéal serait de pouvoir ajouter un «timeout» à l’appel de la coroutine susceptible de bloquer.
Ça tombe bien, cocotb a prévu un trigger pour ça : with_timeout()
from cocotb.triggers import with_timeout
await with_timeout(testcls.too_long_coroutine(), 100, "ns")
Sauf que python n’a pas trop l’air d’accord pour exécuter notre coroutine comme un trigger.
TypeError: All triggers must be instances of Trigger! Got: coroutine
C’est dommage, on perd beaucoup de l’intérêt de ce trigger !
La solution donnée par marlonjames est d’«empaquetter» la coroutine dans la fonction start_soon() comme ceci :
C’est dans la soirée du 8 juillet que l’annonce est tombée : la version 1.4.0 de CocoTB est sortie. Cette nouvelle version est une belle évolution de Cocotb avec une bonne intégration dans le système de paquets de Python ainsi que l’abandon de la prise en charge de Python 2. On peut aujourd’hui dire que CocoTB est une alternative sérieuse pour écrire ses bancs de test HDL.
CocoTB est une bibliothèque de cosimulation permettant d’écrire (en Python) des bancs de test pour la simulation numérique HDL (Hardware Description Language). Historiquement, les deux langages de descriptions HDL que sont Verilog et VHDL embarquent tout le nécessaire pour écrire des stimuli permettant de tester le composant en simulation. Cela permet d’avoir un seul langage pour décrire le composant et le tester. Le simulateur exécutera tout cela sans problème.
Mais cela amène beaucoup de confusion entre la partie du langage utilisable pour la simulation uniquement et la partie « description du matériel ». Dans le cas de la partie « matériel » on parle alors de code « synthétisable ». Cette confusion entre du code synthétisable ou non est source de grandes frustrations au moment de passer à la synthèse. En effet, cette belle structure de données que l’on aura développée et testée aux petits oignons s’écroulera au moment de la synthèse quand on se rendra compte que le code n’est pas synthétisable. Il faudra tout reprendre.
Une des idées derrière CocoTB est donc de changer de langage pour la simulation, comme cela les choses sont claires : on utilise le VHDL ou Verilog pour la partie du composant qui est synthétisable, et on passe au Python pour le banc de test. Ce n’est pas le seul logiciel à proposer ce genre d’approche. Avec Verilator, par exemple, on va écrire toute la partie banc de test en C++ ou en SystemC. La partie synthétisable sera écrite en Verilog et convertie en un objet C++ par Verilator.
La seconde idée de CocoTB est de ne pas réinventer la roue en réécrivant un énième simulateur HDL. Ce qui évite également d’avoir à choisir son camp entre Verilog et VHDL ou les deux (simulation mixte). Non, CocoTB va se contenter de piloter les simulateurs disponibles sur le marché. Les simulateurs libres que sont GHDL, Icarus et Verilator sont naturellement pris en charge, même si dans le cas de Verilator c’est très récent. La plupart des simulateurs commerciaux le sont également, ce qui est un argument pour l’introduire dans son bureau d’étude. En effet, les managers sont en général moyennement chauds pour virer un logiciel acquis à grands frais. Et l’on peut continuer à profiter des interfaces proposées par notre simulateur habituel pour exécuter le simulateur, visionner les chronogrammes, faire de la couverture de tests, etc. La version 1.4 de CocoTB introduit la gestion complète du simulateur Aldec Active HDL qui vient s’ajouter aux classiques de Cadence et de Mentor, Modelsim…
Les changements dans le code
Un gros changement initié depuis quelque versions déjà est l’utilisation du mot clef async en lieu et place du yield et du décorateur @coroutine. Python 3 gérant désormais l’asynchronisme, CocoTB l’utilise et le prend désormais complètement en charge. L’exemple donné dans le courriel de la publication est le suivant :
@cocotb.test()
async def my_first_test(dut):
"""Try accessing the design."""
dut._log.info("Running test!")
for cycle in range(10):
dut.clk <= 0
await Timer(1, units='ns')
dut.clk <= 1
await Timer(1, units='ns')
dut._log.info("Running test!")
Qui se serait écrit comme cela dans « l’ancien système » :
@cocotb.test()
def my_first_test(dut):
"""Try accessing the design."""
dut._log.info("Running test!")
for cycle in range(10):
dut.clk <= 0
yield Timer(1, units='ns')
dut.clk <= 1
yield Timer(1, units='ns')
dut._log.info("Running test!")
Cette écriture restant cependant valable.
Le gros avantage de cette nouvelle écriture est de ne plus avoir a réinventer la roue avec des décorateurs inutiles. Avec async et await, on utilise des interfaces intégrées à Python 3, ce qui évite tout un travail de gestion.
Installation
CocoTB est, depuis maintenant un certain temps, partie intégrante du système de gestion de paquets de Python pip. Et vous pouvez dès à présent l’installer sur votre système via la commande pip install :
$ python -m pip install cocotb
# Pour celles et ceux qui ont installé la version précédente n’oubliez pas le --upgrade
$ python -m pip install --upgrade cocotb
Et on peut vérifier la version grâce à la commande cocotb-config suivante :
cocotb-config --version
1.4.0
En plus de votre composant écrit en VHDL ou Verilog, deux fichiers supplémentaires sont nécessaires pour tester avec CocoTB : le Makefile et le script Python de test proprement dit.
Avec cette nouvelle version, le Makefile a encore été simplifié puisqu’il n’est plus nécessaire d’intégrer les en‑têtes C++. Ces en‑têtes sont nécessaires pour compiler les interfaces VPI/VHPI/FLI qui permettent de piloter les simulateurs. On compile désormais cette partie à l’installation de CocoTB. Dans les précédentes version, cette compilation ce faisait à chaque fois que l’on relançait les tests.
Si l’on prend l’exemple de l’antirebond en Verilog du Blinking Led Project, nous avons le Makefile suivant :
SIM=icarus # Nom du simulateur
export COCOTB_REDUCED_LOG_FMT=1 # Pour avoir des traces de log qui rentre dans l’écran
VERILOG_SOURCES = $(PWD)/../src/button_deb.v # Inclusion des fichiers HDL
TOPLEVEL=button_deb # Nom de l’entité
MODULE=test_$(TOPLEVEL) # Nom du script Python de test
include $(shell cocotb-config --makefile)/Makefile.sim
L’exemple est un composant permettant de ne pas compter les rebonds d’un bouton comme des appuis successifs. Le script de test en Python se trouve dans le dépôt Git du projet et se nomme test_buton_deb.py. Pour le lancer, il suffit de se rendre dans le répertoire blp/verilog/cocotb/ et de taper make :
$ make
[...]
0.00ns INFO Running test!
0.00ns INFO freq value : 95000 kHz
0.00ns INFO debounce value : 20 ms
0.00ns INFO Period clock value : 10000 ps
0.02ns INFO Reset complete
Un fichier de traces (chronogrammes) button_deb.vcd au format VCD est créé. Il peut être visionné en « temps réel » alors même que la simulation n’est pas terminée, grâce au visualiseur gtkwave :
$ gtkwave button_deb.vcd
Une organisation qui tourne
Le projet CocoTB est chapeauté par la FOSSi foundation qui fournit le « chef de projet » Philipp Wagner ainsi que des moyens financiers pour faire tourner des machines virtuelles de tests ainsi que pour payer les licences des simulateurs commerciaux.
Les statistiques de modification de cette version sont les suivantes :
Ces chiffres montrent que CocoTB est un projet qui fédère désormais une grosse communauté. C’est un projet mature qui compte dans le paysage des logiciels libres pour le matériel (FPGA et ASIC).
La simulation HDL génère assez vite des traces (waves) de plusieurs centaines de méga-octets, voir des dizaines de giga.
Ces traces sont le plus souvent au format VCD, qui n’est qu’un fichier texte répétant les même schéma au court du temps. Ces fichiers ayant énormément de redondance, ils se compressent très bien.
Si je prend par exemple un fichier vcd messignaux.vcd faisant ~500Mo :
$ ls messignaux.vcd
-rw-r--r-- 1 fabien fabien 504M avril 3 10:17 messignaux.vcd
Je compresse avec zip en environ 30 secondes:
$ zip -c messignaux.zip messignaux.vcd
adding: messignaux.vcd (deflated 89%)
$ ls -lha messignaux.zip
-rw-r--r-- 1 fabien fabien 56M avril 5 14:16 messignaux.zip
Et je réduis mon fichier à 56Mo soit un rapport de presque 10.
Avec gzip on gagne la même chose à une queue de vache près :
$ gzip messignaux.vcd
$ ls -lha messignaux.gz
-rw-r--r-- 1 fabien fabien 57M avril 3 10:17 messignaux.vcd.gz
Et avec xz alors là on réduit environs à 20 fois plus petit, … mais il faut plus de 5 minutes à xz pour faire la compression:
$ xz -z messignaux.vcd
$ ls -lha messignaux.vcd.xz
-rw-r--r-- 1 fabien fabien 27M avril 3 10:17 messignaux.vcd.xz
Bref, si vos traces de simulation prennent trop de place sur votre pc, n’hésitez pas à les compresser.
Pour l’installer sous linux, rien de plus simple :
$ wget ftp://icarus.com/pub/eda/verilog/v10/verilog-10.0.tar.gz
$ tar -zxvf verilog-10.0.tar.gz
$ cd verilog-10.0/
$ ./configure
$ make
$ sudo make install
Vérifier la bonne installation avec :
$ iverilog -v
Icarus Verilog version 10.0 (stable) (v10_0)
Copyright 1998-2015 Stephen Williams
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
iverilog: no source files.
Usage: iverilog [-ESvV] [-B base] [-c cmdfile|-f cmdfile]
[-g1995|-g2001|-g2005|-g2005-sv|-g2009|-g2012] [-g]
[-D macro[=defn]] [-I includedir]
[-M [mode=]depfile] [-m module]
[-N file] [-o filename] [-p flag=value]
[-s topmodule] [-t target] [-T min|typ|max]
[-W class] [-y dir] [-Y suf] source_file(s)
See the man page for details.
Plusieurs solutions de simulations s’offrent à nous quand on développe un composant en Verilog. On peut écrire le testbench en Verilog, de manière à être compatible avec la plupart des simulateurs du marché. Dans ce cas, le simulateur libre le plus célèbre est Icarus.
Mais la solution du «tout Verilog» est relativement lente en temps de simulation, et l’utilisation du langage Verilog est restrictive, en effet il n’est pas facile de s’approprier toutes les subtilités du langage.
C’est là que la solution de Verilator devient très intéressante. Verilator permet de convertir un modèle de composant écrit en Verilog synthétisable en un modèle C++. De cette manière, écrire le code du testbench revient à instancier notre composant dans un main() en C++ et à décrire nos tests avec toute la liberté qu’offre ce langage.
Mieux encore, il est possible d’écrire notre testbench en SystemC, et de profiter ainsi de cette librairie conçue pour la simulation de circuit numérique.
L’idée va être ici de mesurer le temps effectif de simulation de chacune de ses deux solutions. On se servira pour cela du composant d’antirebond du projet «blinking led project» (blp) disponible sur github.
Le composant synthétisable
Le composant button_deb commute sa sortie button_valid à chaque front montant du signal d’entrée button_in. Pour que le fonctionnement soit un peu plus complexe qu’une simple commutation, et surtout pour bien coller au fonctionnement réel, le composant est muni d’un antirebond de 20 ms (par défaut). Quand le premier front survient, un compteur est déclenché et aucun autre front n’est pris en compte pendant 20 ms.
Tout comme en VHDL, un testbench en Verilog se présente sous la forme d’un module sans entrée/sortie.
La première chose à définir est le temps, avec la directive `timescale:
`timescale 1ns/100ps;
Le premier chiffre indique le pas de simulation, cela correspondra au temps d’attente que l’on retrouvera tout au long du code avec l’«instruction» ‘#’. Le deuxième nombre indique la précision maximum.
Par exemple, pour simuler l’horloge à 95Mhz on écrira :
/* Make a regular pulsing clock. */
always
#5.263158 clk = !clk;
Mais comme la précision indiquée en début de code est de 100ps, seule le 5.2 sera pris en compte pour la simulation, ce qui dans notre cas est tout à fait suffisant.
La simulation de l’appui sur le bouton avec rebond se fait ensuite dans un process que l’on appel souvent «stimulis» par convention :
/* Stimulis */
initial begin
$display("begin stimulis");
$dumpfile("simu/button_deb_tb.vcd");
$dumpvars(1, clk, rst, button_in, button_valid, button);
$monitor("At time %t, value = %h (%0d)",
$time, button_in, button_in);
[...]
end
Le Verilog fourni tout un tas de primitive permettant de simplifier le debuggage. Notamment $display() et $monitor(), pour afficher du texte pendant la simulation. $display() ne fait qu’afficher du texte au moment où la fonction est appelée, alors que monitor va afficher le texte à chaque changement d’état de ses paramètres.
Les functions $dump* permettent de définir le format de fichiers des traces ainsi que les signaux a dumper. Dans ce cas précis on choisira le format vcd qui est un format non compressé, de manière à améliorer la comparaison avec verilator qui lui ne sait faire que du vcd. Mais cela génère vite de très gros fichiers, il sera préférable d’utiliser le format compressé lxt2, fst ou fsdb pour des simulations plus longues.
Pour factoriser un peu de code d’attente on décrit des tâches d’attentes wait_ms et wait_us :
/* some usefull functions */
task wait_us;
input integer another_time;
begin
repeat(another_time) begin
# 1_000;
end
end
endtask
task wait_ms;
[...]
Tâches qui seront appelées lors de la simulation des rebonds :
Icarus va ainsi créer un binaire exécutable nommé simu/button_deb que l’on lancera avec les arguments de dumps:
vvp simu/button_deb -lvcd
Le fichier de traces (VCD) généré fait une taille vénérable de 752Mo et peut être visualisé avec gtkwave en l’indiquant simplement en paramètre de la commande :
gtkwave simu/button_deb_tb.vcd
Sur un Lenovo T430, la simulation prend 1 minute et 17 secondes, ce qui est tout de même relativement lent pour une simulation d’appui sur un boutton 😉
Voyons maintenant ce que nous donne Verilator.
Le testbench C++
Un testbench Verilator se présente sous la forme d’un main() C++. Dans le main() du testbench nous instancierons l’objet correspondant au model verilog transformé par verilator.
Pour cela nous devons donc convertir notre bouton_deb.v en C++ au moyen de la commande Verilator suivante :
Cette commande va nous créer un projet avec le code source du modèle ainsi que le makefile pour compiler. Il suffira donc de se rendre dans le répertoire obj_dir et de faire «make» pour compiler le modèle.
Il ne nous restera plus qu’à instancier notre bouton dans notre testbench test_button_deb.cpp :
Vbutton_deb* top = new Vbutton_deb;
Ainsi que l’objet tfp pour les dump VCD:
VerilatedVcdC* tfp = new VerilatedVcdC;
Pour simuler notre objet «top» il faut assigner des valeurs aux signaux d’entrées :
top->rst = 1;
top->button_in = 0;
top->clk = 0;
Puis évaluer les sorties avec la méthode eval() :
top->eval();
À chaque front d’horloge il faut donc changer la valeur de clk et évaluer :
top->clk = !top->clk;
top->eval();
Dans tout ce que nous venons de voir le temps n’intervient pas. En réalité, le temps n’est tout simplement pas géré dans les modèles Verilator, le modèle ne fait qu’évaluer les sorties en fonction des entrées, c’est à nous de gérer le temps comme nous le souhaitons.
Nous allons donc gérer le temps au moment du dump des signaux en lui indiquant le temps en argument:
tfp->dump(10);
Pour éviter d’avoir à taper tout ça à chaque fois on pourra créer une fonction «time_pass» qui fait passer le temps, avec un compteur global pour incrémenter le temps:
#define BASE_TIME_NS ((1000*1000)/(CLK_FREQ*2))
int base_time = 0;
/* the time is passing */
void time_pass(VerilatedVcdC *tfp, Vbutton_deb *top) {
top->clk = !top->clk;
tfp->dump(base_time*BASE_TIME_NS);
top->eval();
base_time++;
}
À l’image du testbench verilog, on pourra aussi créer des fonctions d’attente wait_ms et wait_us:
/* wait for us */
void wait_us(VerilatedVcdC *tfp, Vbutton_deb *top, int timeus) {
int wait_time = 0;
while((wait_time * BASE_TIME_NS) < (timeus * 1000)) {
wait_time++;
time_pass(tfp, top);
}
}
/* wait for ms */
void wait_ms(VerilatedVcdC *tfp, Vbutton_deb *top, int timems) {
int wait_time = 0;
while((wait_time * BASE_TIME_NS) < (timems * 1000 * 1000)) {
wait_time++;
time_pass(tfp, top);
}
}
Le code simulant les rebonds du bouton ressemble ainsi à s’y méprendre au code Verilog:
Pour lancer la simulation on va d’abord compiler le tout :
make -C obj_dir/ -j -f Vbutton_deb.mk Vbutton_deb
Puis le lancer simplement comme un vulgaire binaire exécutable :
./Vbutton_deb
La simulation crée un fichier VCD de 654Mo que nous pouvons visualiser avec gtkwave.
Sur le même Lenovo T430 la simulation ne dure cette fois que 17 secondes, ce qui est très nettement plus rapide qu’Icarus !
Mieux, si on optimise le code à la compilation avec l’option -O3 :
La rapidité d’exécution est telle que certain réussissent à faire «tourner» un soft-core avec son programme, à des fréquences allant jusqu’à la centaine de kilohertz.
Formidable !
C’est un peu l’expression que l’on a lors des premiers tests de verilator, pouvoir faire de la simulation 20 fois plus rapidement qu’Icarus semble formidable. Surtout quand cela passe par de la simplicité d’écriture du testbench en C++ ou SystemC.
Néanmoins il faut relativiser un peu notre ferveur, Verilator a encore un gros point noir: il ne gère pas le temps. Verilator n’est capable que de gérer des modèle Verilog synthétisable. Mais si ce code synthétisable inclu des primitives du constructeurs : RAM, Multiplieur, … et surtout PLL. Verilator ne sera pas capable de les simuler.
En ce qui concerne les Ram ou les multiplieurs cela ne pose pas trop de problème dans la mesure ou il est assez simple de les inférer. Mais pour les PLL cela devient bien plus compliqué, et je ne parle même pas des composants spécifique au constructeur (Bus serie, transceiver, core, …).
Ce «bug» a été répertorié il y 5 ans déjà mais pour l’instant personne ne semble s’être attelé à la tâche. D’après un des auteur de Verilator ajouter cette fonctionnalité devrait prendre quelques mois de programmation et de test. Mais cela vaudrait quand même le coup !
