TP complet Vitis : piloter les LED par UART | FPGAPourTous
Résumé
TP complet Vitis : piloter les LED par UART
Créer une plateforme, un domaine standalone et une application Cortex-A53 pour commander les quatre LED de la ZCU104 depuis le terminal série.
Objectif du TP
Ce tutoriel construit un projet Vitis complet, depuis l'import du matériel jusqu'au test sur la carte.
À la fin du TP, un caractère envoyé à 115200 bauds avec le protocole UART commande les quatre LED utilisateur de la ZCU104. Les caractères + et - déplacent le centre d'un motif lumineux. Les caractères 0 à 3 inversent l'état d'une LED.
Matériel et fichiers nécessaires
Le TP cible une carte ZCU104 et le cœur psu_cortexa53_0 du Zynq UltraScale+ MPSoC. Il utilise Vitis 2022.2 et un domaine standalone. Ce domaine exécute une application bare-metal, donc directement sur le processeur sans Linux.
Le fichier matériel fpt_zcu104_base.xsa est indispensable. Cette archive décrit les processeurs, les périphériques, les adresses et le bitstream transmis à Vitis. Un autre XSA peut employer des noms ou un routage des LED différents.
Avant de commencer, préparer les éléments suivants.
Élément
Valeur utilisée dans ce TP
Carte
ZCU104
Connexion
USB JTAG et USB UART
Mode de boot
JTAG
Position de SW6
ON, ON, ON, ON
Processeur
psu_cortexa53_0
Système
standalone
Description matérielle
fpt_zcu104_base.xsa
Débit série
115200 bauds
GPIO des LED
XPAR_FPT_LED_BANK_DEVICE_ID
Adresse observée dans le BSP fourni
0xA0010000
La valeur 0xA0010000 permet de contrôler la cohérence avec le projet fourni. Le programme utilise le symbole généré par le BSP et ne recopie pas cette adresse.
Étape 1 : créer le workspace
Lancer Vitis 2022.2. Dans la fenêtre de sélection du workspace, choisir un dossier vide. Par exemple :
C:\zynq-workspaces\workspace_zynq_led
Le workspace est le dossier de travail de Vitis. Il regroupe les projets et les métadonnées de l'IDE, mais ne contient encore ni plateforme ni application.
Étape 2 : créer la plateforme
Dans la barre d'outils, ouvrir le menu placé à côté de Create New, puis choisir Platform Project.
Saisir zynq_led_platform comme nom de plateforme. Éviter les espaces.
Dans l'écran matériel, choisir Create a new platform from hardware (XSA). Sélectionner ensuite le fichier fpt_zcu104_base.xsa préparé dans les ressources du TP.
Renseigner les paramètres suivants.
Champ
Valeur
Operating system
standalone
Processor
psu_cortexa53_0
Boot components
Création du FSBL pour le processeur cible
Cliquer sur Finish pour lancer la génération. Vitis produit alors la plateforme, le domaine standalone, le BSP et les composants de démarrage selon les choix précédents.
Point de contrôle
La plateforme doit afficher le matériel importé et un domaine associé au Cortex-A53 numéro 0. Si le processeur n'est pas proposé, vérifier que le fichier sélectionné est bien le XSA de la ZCU104.
Étape 3 : créer l'application et le projet système
Ouvrir de nouveau le menu Create New, puis choisir Application Project.
Dans l'assistant, sélectionner la plateforme zynq_led_platform. Utiliser les valeurs suivantes.
Champ
Valeur
Application project name
zynq_led_app
System project
Create New
System project name
zynq_led_system
Processor
psu_cortexa53_0
Domain
Domaine standalone de la plateforme
Template
Empty Application (C)
Cliquer sur Finish. L'application est maintenant liée au BSP de la plateforme.
Étape 4 : vérifier le matériel vu par le BSP
Développer le BSP dans l'Explorer et ouvrir xparameters.h. Rechercher FPT_LED_BANK.
Le projet fourni contient les définitions suivantes.
init_platform() appelle la préparation définie dans le fichier platform.c du projet. Son contenu dépend du processeur et de la plateforme. Il peut gérer les caches ou une UART 16550, mais il ne remplace pas initialize_led_output(), qui initialise explicitement l'AXI GPIO de ce TP.
cleanup_platform() exécute le nettoyage prévu par platform.c. Dans ce programme, elle est appelée uniquement si l'initialisation du GPIO échoue. La boucle while (1) ne se termine pas pendant le fonctionnement normal, donc aucun appel placé après cette boucle ne pourrait être exécuté.
XUartPs_IsReceiveData vérifie si un caractère est disponible sans bloquer la boucle. Cette propriété est nécessaire car le motif lumineux doit continuer à être rafraîchi lorsqu'aucune commande n'arrive.
XGpio_Initialize associe l'objet user_leds à l'instance générée dans le BSP. XGpio_SetDataDirection configure le canal 1 en sortie. Un zéro dans le registre de direction représente une sortie.
Le mode DISPLAY_HOLD conserve une image binaire. Le mode DISPLAY_FADE utilise une modulation de largeur d'impulsion, ou PWM, réalisée par logiciel sur 32 phases. Plus une LED reste active pendant ces phases, plus sa luminosité moyenne paraît élevée.
Étape 7 : construire le projet
Enregistrer main.c. Faire un clic droit sur zynq_led_app, puis choisir Build Project. Le même résultat peut être obtenu avec l'icône en forme de marteau et la configuration Debug.
La console doit terminer par un message de build réussi et afficher la taille des sections du fichier ELF.
text data bss dec hex filename... ... ... ... ... zynq_led_app.elfBuild Finished
Erreur : symbole GPIO introuvable
Si XPAR_FPT_LED_BANK_DEVICE_ID n'existe pas, le XSA n'expose pas l'instance GPIO attendue ou le BSP n'a pas été régénéré. Ne pas remplacer le symbole au hasard. Ouvrir xparameters.h et identifier l'instance GPIO réellement exportée.
Erreur : référence UART inconnue
Vérifier que xuartps_hw.h est disponible dans le BSP du Cortex-A53 et que STDIN_BASEADDRESS est défini.
Le build ne reflète pas la correction
Vitis 2022.2 ne reconstruit pas nécessairement le projet à chaque sauvegarde. Relancer explicitement Build Project.
Étape 8 : préparer la ZCU104
Éteindre la carte. Connecter les câbles USB destinés au JTAG et à l'UART. Placer les quatre interrupteurs de SW6 sur ON pour sélectionner le mode JTAG, puis mettre la carte sous tension.
Dans le gestionnaire de périphériques du poste, repérer le port série associé à la carte. Plusieurs ports peuvent apparaître. Celui qui affiche la console du PS doit être sélectionné dans Vitis.
Étape 9 : créer la configuration d'exécution
Faire un clic droit sur zynq_led_app, puis choisir Run As et Run Configurations.
Créer une configuration Single Application Debug. Dans l'onglet Target Setup, vérifier qu'un bitstream est présent et que l'option Program FPGA ou Program Device est active.
Cliquer sur Run. Vitis initialise la cible, programme la PL et charge zynq_led_app.elf dans la mémoire de la plateforme.
Étape 10 : ouvrir le terminal série
Si la vue n'est pas affichée, ouvrir Window, puis Show View, développer Xilinx et choisir Vitis Serial Terminal.
Créer une connexion avec le bouton +. Sélectionner le port de la ZCU104 et configurer 115200 bauds. Conserver les autres paramètres par défaut.
Après le lancement, le terminal doit afficher :
Zynq LED console readyUse +, -, or a digit from 0 to 3
Étape 11 : valider le comportement
Réaliser les essais dans cet ordre.
Commande
Résultat attendu
+
Le centre du motif se déplace vers la LED suivante
-
Le centre du motif se déplace vers la LED précédente
0
La LED 0 change d'état
1
La LED 1 change d'état
2
La LED 2 change d'état
3
La LED 3 change d'état
x
Le terminal affiche Unsupported command
Lorsque le centre atteint une extrémité, une nouvelle commande dans la même direction conserve l'indice dans la plage 0 à 3.
Étape 12 : diagnostic complet
Si le terminal reste vide, vérifier le port série, le débit, le mode JTAG et la configuration d'exécution.
Si le terminal fonctionne mais pas les LED, vérifier XPAR_FPT_LED_BANK_DEVICE_ID, la programmation du bitstream, le canal GPIO et la présence de l'adresse 0xA0010000 dans le BSP.
Si les LED s'allument mais que le motif scintille, modifier uniquement la limite de wait_count. Cette temporisation agit sur la vitesse du PWM logiciel. Elle ne change pas la logique de sélection.
Si une commande numérique provoque une LED inattendue, comparer l'ordre logique des bits avec l'ordre physique des LED sur la carte. Le GPIO écrit un vecteur. Le routage du bitstream détermine la LED associée à chaque bit.
Exercices d'ingénierie
Remplacer le PWM logiciel par un timer matériel.
Ajouter une commande c qui éteint les quatre LED.
Mémoriser le dernier mode et l'afficher sur demande avec ?.
Mesurer la fréquence réelle de rafraîchissement avec une ILA.
Séparer le code dans console.c, led_output.c et main.c sans modifier le comportement.
À retenir
Une application Vitis repose sur une plateforme, un domaine, un projet d'application et un projet système. Le XSA fournit le matériel. Le BSP fournit les symboles et les pilotes. Le build produit un ELF. La configuration d'exécution programme la cible et charge ce fichier par JTAG.
