A retenir

JTAG est une norme de l'industrie pour vérifier les conceptions et tester les cartes de circuits imprimés après leur fabrication.

Comprendre Le JTAG en s'amusant

Nous avons fourni une animation qui peut être très utile pour mieux comprendre le JTAG

https://jugurthab.github.io/debug_linux_kernel/jtag-basic-operation.html

La version d'OpenOCD

Chaque nouvelle version d'OpenOCD supporte plus de cible (par exemple : le fichier de support de Raspberry PI 2 n'est disponible que depuis la version 0.8.0).

$ git clone git://repo.or.cz/openocd.git
$ cd openocd
$ ./bootstrap
$ ./configure --enable-ftdi # Inclure le support FTDI
$ make

Une fois les sources compilées, observons le contenu du répertoire racine d'OpenOCD et plus précisément le dossier : openocd/tcl (ou /usr/share/openocd/scripts/ si OpenOCD à été installé sur le système) comme le montre la figure suivante:

Le contenu peut se diviser en 3 parties :

• interface : contient les fichiers de configuration de l'adaptateur (aussi appelé dongle).
• target : on trouve les fichiers de configuration des différents processeurs ou dsp.
• board : définit la configuration de toute la plateforme (cpu, dsp et les mémoires comme SDRAM ou FLASH), les fichiers de ce dossier incluent généralement ceux du dossier target (c'est une bonne pratique pour réutiliser du code).

Utilisation de OpenOCD

Pour consulter la liste des commandes proposées par OpenOCD, il suffit de se positionner sur le dossier racine des sources et lancer :

$ openocd -h

Une liste d'option est proposée par OpenOCD :

• version (-v) : renvoie la version of OpenOCD
• file (-f) : indique à OpenOCD l'emplacement d'un fichier de configuration.
• debug (-d) : par défaut, OpenOCD affiche le minimum d'information mais en cas de problèmes, il est préférable d'augmenter la verbosité.
• log_output (-l) : on peut rediriger le résultat de OpenOCD vers un fichier, ce qui est très utile pour avoir de l'aide en cas d'erreurs (il faut penser à utiliser l'option -d).
• command (-c) : on peut fournir rapidement certaines instructions à la cible sans modifier les fichiers de configuration (utilisé pour les tests).

$ sudo ./src/openocd -f tcl/interface/fichier_config_adaptateur \
> -f tcl/dossier_target_ou_board/fichier_configuration_cible

Comme on peut le constater, OpenOCD à besoin de deux fichiers au minimum :

• tcl/interface/fichier_config_adaptateur : emplacement du fichier de configuration de l'adaptateur
• tcl/target_ou_board/fichier_configuration_cible : emplacement du fichier de configuration de la cible.

Bonne pratique pour démarrer OpenOCD

Parfois, certains fichiers ont besoin d'en charger d'autres, il faut alors indiquer à OpenOCD où les trouver (il suffit d'ajouter le chemin du dossier tcl) en ajoutant l'option -s comme suit :

$ sudo ./src/openocd -s tcl/ -f tcl/interface/fichier_config_adaptateur \
  -f tcl/target_ou_board/fichier_configuration_cible

Recommandation : il est toujours préférable d'inclure l'option -s (c'est souvent une source d'erreur).

Ce qu'il faut savoir sur OpenOCD

Lancement de OpenOCD

Si aucun des paramètres -f (ce paramètre indique où se trouvent les fichiers de configuration) ou -c n'est fourni , OpenOCD va chercher un fichier "openocd.cfg" dans les endroits suivants :

• Le dossier courant.
• Le dossier précisé avec -s (si ce paramètre est indiqué).
• dans le $HOME/openocd.cfg.

Mode verbeux de OpenOCD

OpenOCD peut avoir des difficultés à communiquer avec la cible (généralement à cause de problèmes de broches mal connectées), il est important d'activer ce mode pour pouvoir essayer de détecter la source du problème.

Pour utiliser le mode verbosité (une valeur entre 0 et 3) :

$ ./src/openocd --debug 3

Remarque : il ne faut pas oublier que dans ce cas, OpenOCD va chercher un fichier "openocd.cfg".

Quelques exemples de configuration

Configuration pour un STM32F407 - supportée par OpenOCD -

Le fichier de configuration du STM32F407 est déjà existant dans OpenOCD, il suffit juste de :

• • Connecter la cible (STM32F407) avec l'adaptateur : Cette étape est généralement la première raison de l'échec du débogage, il est impératif de la mener à bien.
    

    Pin ARM-USB-TINY-H	Pin STM32F407
    1 (VREF)	VDD (P1)
    3 (nTRST)	PB4 (P2)
    4 (GND)	GND (P1)
    5 (TDI)	PA15 (P2)
    7 (TMS)	PA13 (P2)
    9 (TCK)	PA14 (P2)
    13 (TDO)	PB3 (P2)

  • Lancer OpenOCD : On peut démarrer OpenOCD en lui indiquant l'emplacement du fichier de configuration de l'adaptateur (olimex-arm-usb-tiny-h.cfg) et de la cible (stm32f4x.cfg) :

$ sudo ./src/openocd -s tcl/ -f tcl/interface/ftdi/olimex-arm-usb-tiny-h.cfg -f \
> tcl/target/stm32f4x.cfg

La commande devra retourner un résultat semblable à l'image suivante :

Si la ligne "hardware has 6 breakpoints, 4 watchpoints" est présente alors OpenOCD a réussi à détecter la cible.

Remarque : Il est aussi possible de démarrer gdb et telnet sur d'autres ports (notamment si les ports par défaut sont déja occupés) avec l'option -c :

$ sudo ./src/openocd -s tcl/ -f tcl/interface/fichier_adapteur -f tcl/target/target_fichier \
> -c "gdb_port 7777" -c "telnet_port 8888"

Déboguer la cible

OpenOCD accepte des connexions telnet ou GDB comme illustré ci-dessous :

• GDB : il ne faut pas oublier d'utitiser un GDB compatible avec la cible
  • Se connecter à la cible : GDB à besoin de l'image du noyau cible (compilé avec les symboles de débogage) :

$ sudo gdb vmlinux_avec_symbole_de_debogage -q

• Arrêter la cible : il est important d'arrêter la cible, cela permet à OpenOCD de placer la plateforme en mode débogage pour pouvoir l'inspecter (voir l'image ci-dessous).
  
• Obtenir l'état des registres : On peut dumper le contenu des registres à tout moment (voir l'image ci-dessous).
  

• Telnet : Nous allons utiliser putty
  • Se connecter à la cible : les paramètres suivants seront utilisés avec putty :
    
  • Arrêter et obtenir l'état des registres : encore une fois, il faut toujours arrêter la cible avant d'aller plus loin comme le montre la figure ci dessous :
    

Configuration pour une Raspberry PI 3 - non supporté par openOCD -

Cette configuration n'est pas encore disponible en standard avec OpenOCD, et, de plus, nous avons besoin de configurer les ports de la Raspberry PI avant d'utiliser OpenOCD.

Raspberry PI 3 est une plate-forme intéressante, mais déboguer en JTAG nécéssite quelques ajustements.

1. Connecter la raspeberry PI 3 avec la sonde ARM-USB-TINY-H : (voir le tableau ci-dessous).
   

   Pin ARM-USB-TINY-H	GPIO Raspberry PI 3
   1 (VREF)	1 (DC Power)
   3 (nTRST)	15 (GPIO22)
   4 (GND)	9 (GROUND)
   5 (TDI)	7 (GPIO4)
   7 (TMS)	13 (GPIO27)
   9 (TCK)	22 (GPIO25)
   11 (RTCK)	16 (GPIO23)
   13 (TDO)	18 (GPIO24)

   et voici une illustration du schéma après le branchement :
   

2. Activation du débogage JTAG sur Raspberry PI 3 : par défaut, les ports de la Raspberry PI ne sont pas configurés pour accepter les connnnexions JTAG. La procédure disponible sur : https://sysprogs.com/VisualKernel/tutorials/raspberry/jtagsetup/ fournit une solution au problème. Cependant, quelques changement doivent être apportés au programme pour le faire fonctionner sur Raspberry PI 3.
   • Activer le débogage sur Raspberry PI : le code source est disponible sur : http://sysprogs.com/VisualKernel/legacy\_tutorials/raspberry/jtagsetup/JtagEnabler.cpp
   • Modifier le script : le code ne semble fonctionner que pour la Raspberry PI 1, une petite modification doit être faite. Ouvrez le fichier source et modifiez les lignes suivantes :

#define BCM2708_PERI_BASE 0x3F000000
#define GPIO_BASE (BCM2708_PERI_BASE + 0x200000)

• Compiler le programme : une fois les modifications effectuées, on peut compiler :

$ g++ -o JtagEnabler JtagEnabler.cpp

• Exécuter le programme sur Raspberry PI : une fois exécuté, le débogage JTAG sera disponible sur la Raspberry PI 3.
  

1. Obtenir le fichier de configuration OpenOCD bcm2837 :
   Le SoC de la Raspberry PI 3 est un Broadcom bcm2837, mais OpenOCD n'a pas de fichier de configuration pour ce dernier. AZO234 a déjà écrit les fichiers de configuration pour ce genre de processeurs. Les fichiers sont disponibles sur le lien suivant:

   https://github.com/AZO234/RaspberryPi_BareMetal/tree/master/rp_jtagenable/cfg/ARMv8

   Téléchargez le fichier compatible avec votre Raspberry PI 3, et copiez-le dans le dossier "target" de OpenOCD

2. Démarrer OpenOCD : maintenant, nous avons toutes les pièces nécessaires pour OpenOCD :

$ sudo ./src/openocd -s tcl/ -f tcl/interface/ftdi/olimex-arm-usb-tiny-h.cfg -f tcl/target/bcm2837_64.cfg

La commande retourne le résultat suivant :

1. Démarrer telnet ou GDB : OpenOCD reçoit les commandes à exécuter sur la cible avec Telnet ou GDB.
   Voici un exemple avec telnet, nous devons configurer putty comme suit :
   • adresse IP : 127.0.0.1
   • Port : 4444
   • Type de connexion : Telnet

   En cas de réussite de connexion, le message "Open On-Chip Debugger" sera affiché. Nous devons arrêter l'exécution de la cible avant de poursuivre l'opération (voir l'image ci dessous).
   

Création de fichiers de configuration OpenOCD pour de nouvelles cibles

Dans ce paragraphe, nous détaillons comment configurer une cible qui n'est pas supportée par OpenOCD.

Nous devons rappeler que OpenOCD utilise une approche modulaire pour organiser les fichiers. Les fichiers target contiennent la configuration concernant le chip (cpu, dsp, FPGA, ..., etc) et les fichiers board regroupent tous les paramètres d'une carte (y compris les fichiers target, configuration Flash et d'autres options spécifiques à la carte).

Pour créer de nouveaux fichiers OpenOCD nous devons écrire le fichier target puis le fichier board.

N.B : les commentaires sont définis par # dans OpenOCD.

Fichier target

OpenOCD a besoin de connaître les détails de notre SoC (CPU, DSP, ..., etc.). La création d'un fichier de configuration target peut être fait en 6 étapes :

Définir le nom du SOC : Techniquement, il est suffisant d'indiquer à OpenOCD le nom de notre chip comme ceci :

# indique le nom du chip (CPU, DSP, ..., etc)
set _CHIPNAME stm32f0407

Cepandant, on doit respecter une convention; les noms de variable d'un fichier target peuvent être écrasés et réécrits par un fichier board (qui les inclut) et donc la syntaxe à suivre est la suivante :

# indiquer le nom du chip (CPU, DSP, ..., etc) avec vérification de réécriture par le fichier board
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME stm32f0407
}

La condition if{ [info exists CHIPNAME] } vérifie si le fichier board a fournit une nouvelle valeur pour le nom, si c'est le cas on doit l'utiliser sinon on garde celle qui est définit dans le fichier target (dans notre cas stm32f0407). Remarque : les variables qui commencent par "_" (exemple : _CHIPNAME) designent des variables temporaires qui peuvent être réécrites par un fichier board.

Boutisme (endianness) : il faut indiquer l'organisation des octets :

#little ou big endian? OpenOCD considére little endian par défaut
if { [info exists ENDIAN] } {
set _ENDIAN $ENDIAN
} else {
set _ENDIAN little
}

Important : si ce paramètre n'est pas indiqué, OpenOCD considère le boutisme "little indian" par défaut.

Indiquer le TAP ID : Ce paramètre est facultatif mais peut aider lorsque la cible possède plusieurs chips (architecture SMP) :

# Tap ID controller (facultatif)
if { [info exists CPUTAPID] } {
set _CPUTAPID $CPUTAPID
} else {
set _CPUTAPID 0x4ba00477
}

Créer une instance d'un TAP ID : La syntaxe générale pour déclarer un nouveau processeur est la suivante :

jtag newtap $_CHIPNAME chip_type -irlen length -expected-id $_CPUTAPID

• jtag newtap $_CHIPNAME : définition d'un nouveau contrôleur TAP .
• chip_type : représente l'objet pouvant être débogué par le contrôleur TAP (cpu, dsp).
• -irlen length (instruction register length) : taille du registre d'instruction (JTAG).
• -expected-id $_CPUTAPID : force OpenOCD à controler le TAP ID pour vérifier qu'on débogue le bon processeur (utile pour différencier des processeurs dans un environement SMP).

Voici l'exemple de notre carte cible :

#create a tap ID controller
jtag newtap $_CHIPNAME cpu -irlen 4 -expected-id $_CPUTAPID

Pour OpenOCD cela veut dire : "il existe un contrôleur TAP avec un ID ($_CPUTAPID) que je doit vérifier. Ce contrôleur débogue un CPU qui se nomme $_CHIPNAME, la taille du registre d'instruction est 4".

Créer une instance du SOC : il faut aussi définir le type du chip :

target create $_TARGETNAME architecure -chain-position $_TARGETNAME

• target create $_TARGETNAME : définit un nouveau processeur, dsp, ..., etc.
• architecure : désigne l'architecure du processeur : avr, cortex_m, arm11, ..., etc.
• -chain-position $_TARGETNAME : pointe vers le TAP qui contrôle ce processeur.

Par exemple :

set _TARGETNAME $_CHIPNAME.cpu
target create $_TARGETNAME cortex_m -chain-position $_TARGETNAME

Configuration de la mémoire interne-SDRAM (étape optionnelle) : certains processeurs peuvent utiliser une mémoire interne (onchip memory) :

$_TARGETNAME configure -work-area-phys 0x00200000 -work-area-size 0x8000 -work-area-backup 0

• $_TARGETNAME configure : déclarer une SDRAM
• -work-area-phys début_adresse : indique le début d'adresse de la SDRAM
• -work-area-size taille : quantité de mémoire disponible à partir du début d'adresse (-work-area-phys)
• -work-area-backup oui_ou_non : indique si la SDRAM peut avoir une sauvegarde

Fichier Board

1. Définir la vitesse de communication de l'adaptateur : Il est préférable de consulter le site du constructeur.
   

   Remarque : généralement une vitesse minimale de 8 KHz est utilisée en cas d'incertitude ou de difficulté à obtenir ce paramètre.

2. Inclure le fichier target : comme déja mentionné, le fichier Board reprend le fichier (ou les fichiers si plusieurs processeurs existent sur la cible) target et l'inclut comme montré ci-dessous :
   source [find my-custum-script-target.cfg]

   On peut ajouter plus de fichiers target (autant qu'il y'a de chips sur la platforme).

3. Configurer la mémoire Flash : Après avoir ajouté le fichier target, on peut configurer la mémoire flash et l'initialiser.
   1. Identifier la technologie mémoire FLASH : jusqu'à présent, OpenOCD supporte 3 types de mémoire Flash; Nor, Nand, mFlash.
   2. Lorsque le type de la mémoire est identifié : il suffit de recopier la commande de configuration de la mémoire Flash du manuel d'utilisation d'OpenOCD (les commandes sont organisées selon le driver utilisé par la mémoire Flash).
      • Nor : il existe deux cas de figure :
        • External : http://openocd.org/doc/html/Flash-Commands.html#External-Flash
        • Internal : http://openocd.org/doc/html/Flash-Commands.html#Internal-Flash-_0028Microcontrollers_0029
      • Nand : http://openocd.org/doc/html/Flash-Commands.html#NAND-Driver-List
      • mFlash : http://openocd.org/doc/html/Flash-Commands.html#mFlash

   Dans notre cas, la carte possède une mémoire Flash de type Nor interne, le driver associé est : stm32f2x. le manuel OpenOCD propose la ligne qu'on doit ajouter.

   flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME

   Cependant, on doit toujours garder la convention d'OpenOCD et permettre à nos variables d'être modifiées lorsque nos fichiers sont inclus dans d'autres, on doit toujours écrire :

#declare the nor flash mapping
set _FLASHNAME $_CHIPNAME.flash
flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME

Les sources sont disponibles sur : https://github.com/jugurthab/Linux_kernel_debug/tree/master/debug-examples/Chap5-JTAG-OpenOCD-Debug/stm32f2x-OpenOCD-File-From-Scratch

OESdebug, une interface de configuration pour openOCD

OpenOCD est assez ardu à prendre en main et demande de la pratique, OESdebug est un générateur de script OpenOCD. Nous allons l'utiliser pour ajouter un nouveau SoC (fichier target d'un avr AT32UC3C-EK) qui n'existe pas sous OpenOCD.

Prendre en main OESdebug

• Détection d'OPENOCD : OESDebug est un programme wrapper sur OpenOCD, la première étape est d'essayer de détecter ce dernier (voir l'image ci-dessous).
  

  Si OpenOCD à été compilé à partir des sources, on doit indiquer à OESdebug le dossier root des sources.

• Support d'adaptateur : il suffit de sélectionner notre dongle dans la liste (voir l'image ci-dessous).
  
• Support Target et Board : AT32UC3C-EK n'existe pas dans OpenOCD, nous devons le créer. il suffit de renseigner les champs demandés (voir l'image ci-dessous).
  

  Important : Les champs "IR" et "CPU TAP ID" peuvent être découverts par une option offerte par OpenOCD (Autoprobe feature), avec OESdebug, il suffit d'aller dans le menu "Tools" puis "Discover TAP ID"

  N.B : Il est possible de configurer la SDRAM et la mémoire Flash en cochant la case "Enable Memory Config"

• Génération du fichier config : Il suffit de cliquer sur le bouton "Generate File" pour générer le fichier de configuration (voir l'image ci-dessous).
  
• Brancher la carte cible avec l'adaptateur : Nous devons connecter le dongle et la carte cible comme suit :
  

  Pin ARM-USB-TINY-H	Pin AT32UC3C
  1 (VREF)	7 (VSUPP)
  3 (nTRST)	8
  4 (GND)	2
  5 (TDI)	9
  7 (TMS)	5
  9 (TCK)	1
  13 (TDO)	3

  Remarque : la datasheet du "AT32UC3C-EK" est disponible sur ce lien http://www.farnell.com/datasheets/1511964.pdf

• Lancer OpenOCD : Aprés la génération du fichier de configuration, on peut démarrer OpenOCD (en cliquant sur le boutton "Start OpenOCD").

Quelques options de OESdebug

• La fonction Autoprobe : OpenOCD permet de récupérer le "TAP ID" et la taille du registre d'instruction. En effet, ces derniers sont parfois difficiles à obtenir. OESdebug nous permet d'utiliser cette fonctionnalité en toute simplicité.
  1. Connecter la cible et le dongle.
  2. Choisir le fichier de configuration du dongle (voir l'image ci-dessous).
     
  3. Dans le menu "tools", choisir "Dicover TAP ID".
  4. Récupérer le TAP ID : OpenOCD renvoie le résultat (voir l'image ci-dessous).
     
      

  Dans l'exemple ci dessus, OpenOCD a identifié deux TAP ID (0x4ba00477 et 0x06413041). OpenOCD nous propose même comment intégrer ces informations dans un script OpenOCD.

  Enfin, pour permettre à OpenOCD de dialoguer avec le contrôleur TAP (qui posséde un ID 0x4ba00477), on doit écrire :

  jtag newtap auto0 tap -irlen 4 -expected-id 0x4ba00477
  

  Mais il faut toujours suivre les conventions des script OpenOCD et bien nommer ses variables comme suit:

  jtag newtap $_CHIPNAME tap -irlen 4 -expected-id $_CPUTAPID
  

   

  Important : La fonction autoprobe nécéssite la présence du signal RCLK pour fonctionner.

• Partager les scripts générés : les scripts obtenus avec OESdebug peuvent être partagés. L'onglet "Config File" permet d'enregistrer les fichiers de configuration obtenus.
  Ensuite, il faut choisir le dossier où les fichiers seront sauvegardés (il est recommandé de laisser le répertoire par défaut "savedConfig") puis de cliquer sur "Save file". l'opération produira deux fichiers :
  • cfg : est le fichier de configuration qui peut être utilisé avec OpenOCD.
  • oes : pour repopuler l'interface graphique avec la configuration exacte qui a été faite pour produire le fichier cfg.

  On peut désormais partager nos fichiers (.cfg et .oes). Pour charger les fichiers dans OESdebug, il suffit d'aller dans l'onglet "OpenOCD support" et de sélectionner "Load config" et choisir le fichier cfg (le fichier oes sera chargé au même temps).

Conclusion

Cet article nous a permis de découvrir le débogage JTAG avec OpenOCD. Nous avons appréhendé son utilisation ainsi que la création de fichiers de configuration from scratch. Il existe d'autres manières de déboguer un noyau Linux que nous couvrirons dans d'autres articles. L'outil OESdebug permet de faciliter la configuration de OpenOCD, il est encore jeune, nous vous invitons donc à proposer des axes d'améliorations, des corrections pour cet outil.

Enfin, si vous configurez de nouvelles interfaces, n'hésitez pas à partager votre travail auprès d'OpenOCD.