🚀 Cocotb Exemples - Testbench Hardware Complet

Un projet complet de démonstration de cocotb 2.0.1 avec 3 exemples pratiques de vérification matérielle en VHDL. Idéal pour comprendre les concepts clés : simulation hardware, interfaces AXI-Stream, et traitement d'image en temps réel.

---

📋 Table des matières

• Aperçu
• Prérequis
• Installation
• Les 4 Démos
• Utilisation
• Architecture du projet
• Résolution de problèmes

---

🎯 Aperçu

Ce projet démontre 4 scénarios de test matériel avec cocotb :

#	Démo	Description	Concept clé
1	🔄 Compteur	Contrôle d'horloge et arrêt dynamique sur condition	Event-based simulation
2	📊 AXI-Stream	Interface de flux de données avec gain 2x + Matplotlib	Protocol verification
3	🖼️ Image Pipeline	Traitement multi-étages (RGB→BW→Inverse)	Signal hierarchy
4	🎮 Sandbox	Template prêt à modifier pour vos propres designs	Learn & Experiment

Tous les tests passent ✅ sur GHDL 7.0.0-dev avec cocotb 2.0.1

---

📦 Prérequis

Système

• Linux ou Windows 10+
• Python 3.11+
• Git

Logiciels requis

• GHDL 7.0.0+ : Installation
• Miniconda/Anaconda : Installation

Vérification des dépendances

# Vérifier GHDL
ghdl --version

# Vérifier Python
python --version

# Vérifier Conda
conda --version

---

🔧 Installation

1. Cloner le repo

git clone https://github.com/Vstick/Cocotb_exemple.git
cd Cocotb_exemple

2. Créer l'environnement conda

conda env create -f environment.yml
conda activate cocotb_demo

3. Configuration optionnelle (Windows)

Si vous avez des erreurs de DLL sur Windows, vérifiez que GHDL est dans votre PATH :

# Ajouter GHDL au PATH permanent (Windows)
$env:PATH += ";C:\Users\<votre_user>\ghdl\bin;C:\Users\<votre_user>\ghdl\lib"

---

🎮 Les 4 Démos

Démo 1 : 🔄 Compteur avec arrêt dynamique

Description : Un compteur 8-bit avec horloge générée par cocotb qui s'arrête automatiquement quand le compteur atteint 32.

Concepts :

• Génération d'horloge avec Clock()
• Vérification de signaux
• Arrêt conditionnel de la simulation

Fichiers :

• VHDL: 01-Compteur/counter.vhd
• Test: 01-Compteur/test_counter.py

Résultats :

✅ TEST PASSÉ - 660.00ns
🎯 Cible atteinte : 32! Arrêt de la simulation.

---

Démo 2 : 📊 Flux AXI-Stream & Matplotlib

Description : Un module matériel qui reçoit des données via AXI-Stream, les multiplie par 2, et retourne le résultat. Validation avec graphique matplotlib.

Concepts :

• Interface AXI-Stream (tvalid/tready/tdata)
• Abstraction du bus avec classe helper
• Génération de graphiques de validation

Fichiers :

• VHDL: 02-AXI/axi_gain.vhd
• Test: 02-AXI/test_axi_data.py
• Helper: axi_helper.py (classe AxiStreamBusSimple)

Résultats :

✅ TEST PASSÉ - 150.00ns
📊 Graphique généré: 02-AXI/sim_build/resultat_verification.png

Graphique : Affiche côte à côte les données d'entrée et le résultat (x2)

---

Démo 3 : 🖼️ Traitement d'image multi-fichiers

Description : Pipeline 3 étages :

1. RGB to Grayscale : Convertit RGB en niveaux de gris
2. Pixel Invert : Inverse les couleurs

Injection d'image 64x64, traitement pixel par pixel, sortie 3 images PNG.

Concepts :

• Hiérarchie de signaux (accès via dut.submodule.signal.value)
• Traitement d'images en temps réel
• Capture de signaux internes

Fichiers :

• VHDL: 03-Image/image_top.vhd, rgb_to_bw.vhd, pixel_invert.vhd
• Test: 03-Image/test_image_pipeline.py

Résultats :

✅ TEST PASSÉ - 40990.00ns
🖼️ Images générées:
   - input_color.png (original)
   - output_intermediaire_bw.png (après RGB→BW)
   - output_final_inverse.png (après inversion)

---

Démo 4 : 🎮 Sandbox - Modèle pour expérimenter

Description : Un template prêt à modifier pour que vous puissiez expérimenter avec vos propres designs VHDL. Inclut horloge, reset, et structure de test minimaliste.

Concepts :

• Setup minimal (clock, reset)
• Structure de test réutilisable
• Point de départ pour nouveaux projets
• Plateforme d'apprentissage pratique

Fichiers :

• VHDL: 04-Sandbox/sandbox_top.vhd
• Test: 04-Sandbox/test_sandbox.py
• Doc: 04-Sandbox/README.md (tutoriel complet)

Résultats :

✅ TEST PASSÉ - 170.00ns
🎮 Prêt à modifier pour vos designs !

Idées d'expérimentation :

• Compteur simple
• Multiplexeur
• Registre à décalage
• Machine à états
• Accumulateur

Consulter 04-Sandbox/README.md pour des exemples détaillés et des templates.

---

📖 Utilisation

Via Terminal

Exécuter une démo spécifique :

# Démo 1 : Compteur
python run_testbench.py --demo 1

# Démo 2 : AXI-Stream
python run_testbench.py --demo 2

# Démo 3 : Image Processing
python run_testbench.py --demo 3

# Démo 4 : Sandbox (votre terrain de jeu!)
python run_testbench.py --demo 4

Via Jupyter Notebook

Démo interactive avec visualisations inline :

jupyter notebook demo.ipynb

Fonctionnalités du notebook :

• ✅ Exécution des 4 démos dans des cellules séparées
• 📊 Affichage du graphique Matplotlib pour la démo 2
• 🖼️ Affichage des 3 images côte à côte pour la démo 3
• 🎮 Test du sandbox avec instructions de modification pour la démo 4
• 📝 Logs détaillés de chaque simulation

---

📁 Architecture du projet

Cocotb_exemple/
├── README.md                          # Ce fichier
├── environment.yml                    # Dépendances conda
├── config_demo.json                   # Configuration (chemins GHDL, env)
├── run_testbench.py                   # Script principal orchestrateur
├── axi_helper.py                      # Helper AXI-Stream (classe AxiStreamBusSimple)
├── demo.ipynb                         # Notebook Jupyter interactif
│
├── 01-Compteur/
│   ├── counter.vhd                    # Compteur 8-bit
│   ├── test_counter.py                # Test cocotb
│   └── sim_build/                     # Résultats simulation (ignoré par git)
│
├── 02-AXI/
│   ├── axi_gain.vhd                   # Module gain x2 (AXI-Stream)
│   ├── test_axi_data.py               # Test cocotb
│   └── sim_build/
│       └── resultat_verification.png  # Graphique matplotlib
│
└── 03-Image/
    ├── image_top.vhd                  # Top-level du pipeline
    ├── rgb_to_bw.vhd                  # Étage RGB → Grayscale
    ├── pixel_invert.vhd               # Étage inversion
    ├── test_image_pipeline.py         # Test cocotb
    └── sim_build/
        ├── input_color.png            # Image originale
        ├── output_intermediaire_bw.png # Après RGB→BW
        └── output_final_inverse.png   # Résultat final
│
├── 04-Sandbox/
│   ├── README.md                      # Guide sandbox avec idées d'expérimentation
│   ├── sandbox_top.vhd                # Template VHDL (à modifier!)
│   ├── test_sandbox.py                # Template test (à modifier!)
│   └── sim_build/                     # Résultats simulation
│
├── tuto/                              # 📚 Tutoriels cocotb
│   ├── README.md                      # Index et parcours d'apprentissage
│   ├── 01-SIGNAL_HIERARCHY.md         # Hiérarchie des signaux
│   ├── 02-TIMING_AND_SYNCHRONIZATION.md # Déclencheurs et timing
│   ├── 03-SIGNAL_OPERATIONS.md        # Manipulation de signaux
│   ├── 04-TESTING_PATTERNS.md         # Patterns de test
│   ├── 05-CLOCK_AND_RESET.md          # Gestion horloge et reset
│   └── 06-DEBUGGING_AND_INSPECTION.md # Débogage et inspection
│
└── SIGNAL_HIERARCHY.md                # Guide avancé hiérarchie (voir tuto/)

---

🔍 Configuration

config_demo.json

Exemple sous Windows :

{
    "ghdl_bin": "C:/Users/maraninc/ghdl/bin",
    "ghdl_lib": "C:/Users/maraninc/ghdl/lib",
    "conda_env": "c:/Users/maraninc/miniconda3/envs/cocotb_demo"
}

Exemple sous Linux (les chemins d'accès doivent être adaptés à votre environnement) :

{
    "ghdl_bin": "/usr/bin",
    "ghdl_lib": "/usr/lib",
    "conda_env": "/home/leguig/miniconda3/envs/cocotb_demo"
}

Modifiez selon votre installation GHDL et conda.

environment.yml

Contient toutes les dépendances Python :

• cocotb 2.0.1 : Framework de vérification
• cocotb-tools : Runner GHDL
• matplotlib : Graphiques
• pillow : Traitement images
• jupyter/notebook : Notebooks interactifs

---

⚙️ Flux d'exécution

run_testbench.py
    ├── load_environment()           # Configure PATH + conda
    └── run_demo(demo_num)
        ├── Demo 1: test_counter.py
        ├── Demo 2: test_axi_data.py    → resultat_verification.png
        └── Demo 3: test_image_pipeline.py → 3 images PNG

---

🐛 Résolution de problèmes

❌ "ModuleNotFoundError: No module named 'cocotb'"

Solution :

conda activate cocotb_demo
pip install cocotb cocotb-tools

❌ "cannot import name '_entity' from 'cocotb'" (Démo 2)

Cause : cocotbext-axi 0.1.28 incompatible avec cocotb 2.0.1

Solution : Le projet utilise déjà axi_helper.py custom qui remplace la librairie cassée.

❌ "VPI DLL loading failed" (Windows)

Cause : GHDL pas dans PATH

Solution :

# Vérifier GHDL
ghdl --version

# Si erreur, ajouter au PATH
$env:PATH += ";C:\Users\<votre_user>\ghdl\bin;C:\Users\<votre_user>\ghdl\lib"

# Puis relancer
python run_testbench.py --demo 1

❌ "Images non trouvées après exécution" (Démo 3)

Cause : Le répertoire sim_build n'existe pas ou chemin incorrect

Solution :

# Vérifier que sim_build existe
dir 03-Image\sim_build

# Si vide, relancer la démo
python run_testbench.py --demo 3

⚠️ Avertissement "DeprecationWarning: The 'units' argument has been renamed to 'unit'"

Info : C'est un avertissement mineur, les tests fonctionnent correctement.

À corriger dans les sources :

# ❌ Ancien
Clock(dut.clk, 20, units="ns")

# ✅ Nouveau
Clock(dut.clk, 20, unit="ns")

---

📝 Notes importantes

Fichiers ignorés par Git

Le projet utilise un .gitignore complet pour ignorer :

• __pycache__/ - Cache Python
• sim_build/ - Résultats simulation
• *.pyc, *.pyo - Fichiers compilés Python
• .vscode/, .idea/ - Dossiers IDE

Compatibilité

• ✅ Linux & Windows 10+
• ✅ Python 3.11+
• ✅ cocotb 2.0.1
• ✅ GHDL 7.0.0-dev
• ✅ Jupyter Notebook

Performance

Démo	Temps sim	Real time	Ratio
Compteur	660ns	0s	∞
AXI-Stream	150ns	0.12s	1273 ns/s
Image (64x64)	40990ns	0.12s	341 kns/s

---

📚 Ressources

• cocotb Documentation
• GHDL Documentation
• AXI-Stream Protocol

---

📄 Licence

Libre d'utilisation à titre éducatif.

---

👤 Support

Pour toute question ou problème :

1. Vérifiez la section Résolution de problèmes ci-dessus
2. Consultez les logs détaillés : python run_testbench.py --demo X
3. Vérifiez les issues GitHub du projet