Tutoriel : Générer et déboguer des applications partenaires

• Installez CMake et Ninja pour Windows ou pour Linux.

• Installez Visual Studio Code pour Windows ou pour Linux.
• Installez CMake et Ninja pour Windows ou pour Linux.

• Installez Visual Studio et l’extension Azure Sphere.

• Visual Studio 2022 : si vous utilisez Visual Studio 2022, installez la chaîne d’outils incorporée GNU Arm (arm-none-eabi) à partir du site web du développeur Arm.
• Visual Studio 2019 : la chaîne d’outils est automatiquement installée avec l’extension Azure Sphere pour Visual Studio sur Visual Studio 2019. Si vous utilisez Visual Studio 2019, passez à Configurer le matériel pour afficher la sortie. Toutefois, si vous avez installé la chaîne d’outils GNU Arm Embedded manuellement, Visual Studio utilise la version que vous avez installée.

Pour installer la chaîne d’outils sur le site web du développeur Arm, recherchez la chaîne d’outils INCORPORÉe GNU Arm (arm-none-eabi) qui inclut le compilateur pour le processeur ARM Cortex-M4. Suivez les instructions qui s’y trouvent pour télécharger et installer le compilateur pour votre plateforme de système d’exploitation.

Par défaut, Visual Studio Code recherche la chaîne d’outils et doit trouver la version que vous avez installée. Si vous rencontrez des problèmes de build liés à la chaîne d’outils, case activée Préférences>Paramètres>Extensions>AzureSphere pour vous assurer que « Azure Sphere : Arm Gnu Path » identifie le répertoire d’installation de GNU Arm Embedded Toolchain.

1. Démarrez Visual Studio. Sélectionnez Ouvrir un dossier local, puis accédez au dossier dans lequel vous avez extrait les applications IntercoreComms.

   Important

   Si vous utilisez Visual Studio 2022 version 17.1 ou ultérieure et que vous avez extrait l’exemple IntercoreComms avant la version 22.02 d’Azure Sphere, vous devez ajouter un fichier CMakeWorkspaceSettings.json à votre dossier de projet de niveau supérieur.

2. Si vous n’utilisez pas de RDB MT3620, mettez à jour les fichiers app_manifest.json pour les applications, ainsi que le fichier de définition matérielle et le fichier deCMakeLists.txt pour que l’application de haut niveau corresponde à votre matériel.

3. Si la génération de CMake ne démarre pas automatiquement, sélectionnez le fichier CMakeLists.txt.

4. Dans Visual Studio, afficher>la sortie>Afficher la sortie de : la sortie CMake doit afficher les messages CMake generation started et CMake generation finished.

5. Sélectionnez Générer>tout. Si le menu n’est pas présent, ouvrez Explorateur de solutions, cliquez avec le bouton droit sur le fichier CMakeLists.txt, puis sélectionnez Générer. L’emplacement de sortie des IntercoreComms_HL & applications IntercoreComms RT s’affiche dans la fenêtre Sortie .

6. Sélectionnez Sélectionner l’élément>de démarrage IntercoreComms (Tous les cœurs).

7. Sélectionnez Déboguer>Déboguer ou appuyez sur F5 pour déployer et déboguer les applications.

8. Dans la fenêtre Sortie , Sélectionnez la sortie à partir du menu, sélectionnez Sortie de l’appareil. La fenêtre Sortie doit afficher la sortie de l’application de haut niveau :

   Remote debugging from host 192.168.35.1, port 58817
   High-level intercore comms application
   Sends data to, and receives data from a real-time capable application.
   Received 19 bytes: rt-app-to-hl-app-07
   Sending: hl-app-to-rt-app-00
   Sending: hl-app-to-rt-app-01
   

9. L’émulateur de terminal connecté doit afficher la sortie du programme compatible en temps réel :

   Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
   Message size: 19 bytes:
   Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30
   Text: hl-app-to-rt-app-00
   Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
   Message size: 19 bytes:
   Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:31
   Text: hl-app-to-rt-app-01
   

10. Utilisez le débogueur pour définir des points d’arrêt, inspecter les variables et essayer d’autres tâches de débogage.

1. Dans Visual Studio Code, ouvrez le dossier dans lequel vous avez extrait les applications IntercoreComms. Visual Studio Code détecte le fichier intercore.code-workspace et vous demande si vous souhaitez ouvrir l’espace de travail. Sélectionnez Ouvrir l’espace de travail pour ouvrir simultanément l’application en temps réel et l’application générale.

2. Si vous n’utilisez pas de RDB MT3620, mettez à jour les fichiers app_manifest.json pour les applications, ainsi que le fichier de définition matérielle et le fichier deCMakeLists.txt pour que l’application de haut niveau corresponde à votre matériel.

3. Appuyez sur F5 pour démarrer le débogueur. Si le projet n’a pas été généré précédemment, ou si les fichiers ont été modifiés et que la reconstruction est requise, Visual Studio Code génère le projet avant le démarrage du débogage.

4. La fenêtre de sortie Azure Sphere doit afficher « Déploiement de l’image... » suivis des chemins d’accès au SDK et au compilateur.

5. La fenêtre de sortie doit afficher la sortie de l’application de haut niveau :

   Remote debugging from host 192.168.35.1, port 58817
   High-level intercore comms application
   Sends data to, and receives data from a real-time capable application.
   Received 19 bytes: rt-app-to-hl-app-07
   Sending: hl-app-to-rt-app-00
   Sending: hl-app-to-rt-app-01
   

6. L’émulateur de terminal connecté doit afficher la sortie du programme compatible en temps réel :

   Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
   Message size: 19 bytes:
   Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30
   Text: hl-app-to-rt-app-00
   Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
   Message size: 19 bytes:
   Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:31
   Text: hl-app-to-rt-app-01
   

7. Utilisez les fonctionnalités de débogage de Visual Studio Code pour définir des points d’arrêt, inspecter des variables et essayer d’autres tâches de débogage.

Dépannage

L’application peut commencer à s’exécuter avant qu’OpenOCD n’établit une connexion. Par conséquent, les points d’arrêt définis au début du code peuvent être manqués. Une solution de contournement simple consiste à retarder le démarrage de l’application jusqu’à ce qu’OpenOCD se connecte.

1. Insérez le code suivant au début du point d’entrée de l’application RTCoreMain. Cela entraîne l’entrée et le maintien de l’application dans une while boucle jusqu’à ce que la variable f soit définie sur true.

   static _Noreturn void RTCoreMain(void)
   {
     .
     .
     .
    volatile bool f = false;
    while (!f) {
       // empty.
    }
     .
     .
     .
   }
   

2. Appuyez sur F5 pour démarrer l’application avec le débogage, puis passez à l’exécution.

3. Dans le volet Débogage local , remplacez la valeur de f zéro par un.

4. Parcourez le code comme d’habitude.

Lors de la génération avec l’interface CLI, vous devez d’abord générer et déployer l’application en temps réel, puis générer et déployer l’application de haut niveau.

Créer et déployer l’application en temps réel

1. Accédez au dossier dans lequel vous avez extrait les applications IntercoreComms, puis sélectionnez le dossier IntercoreComms/IntercoreComms_RTApp_MT3620_BareMetal.

2. Ouvrez le fichier app_manifest.json et vérifiez que l’ID de composant de l’application de haut niveau est affiché dans la fonctionnalité AllowedApplicationConnections.

3. Ouvrez une interface de ligne de commande à l’aide de PowerShell, de l’invite de commandes Windows ou de l’interpréteur de commandes Linux. Accédez au répertoire de build de votre projet.

4. À partir du répertoire de build de votre projet, à l’invite de commandes, exécutez CMake avec les paramètres suivants :

   cmake --preset <preset-name> <source-path>
   

   • --preset <preset-name>

     Nom prédéfini de configuration de build tel que défini dans CMakePresets.json.

   • --build <cmake-path>

     Répertoire binaire qui contient le cache CMake. Par exemple, si vous exécutez CMake sur un exemple Azure Sphere, la commande build est cmake --build out/ARM-Debug.

   • <source-path>

     Chemin d’accès du répertoire qui contient les fichiers sources de l’exemple d’application. Dans l’exemple, le référentiel d’exemples Azure Sphere a été téléchargé dans un répertoire appelé AzSphere.

     Les paramètres CMake sont séparés par des espaces. Le caractère de continuation de ligne (^ pour la ligne de commande Windows, \ pour la ligne de commande Linux ou ' pour PowerShell) peut être utilisé pour la lisibilité, mais n’est pas obligatoire.

   Les exemples suivants illustrent les commandes CMake pour l’application RTApp IntercoreComms :

   • Windows
   • Linux

   Invite de commandes Windows

    cmake ^
   --preset "ARM-Debug" ^
    "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"
   

   Windows PowerShell

    cmake `
   --preset "ARM-Debug" `
    "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"
   

5. À partir du répertoire de build de votre projet, à l’invite de commandes, exécutez Ninja pour générer l’application et créer le fichier de package d’image.

   ninja -C out/ARM-Debug
   

   Ninja place l’application et les fichiers .imagepackage obtenus dans le répertoire spécifié.

   Vous pouvez également appeler Ninja via CMake avec la commande suivante :

   cmake --build out/<binary-dir>
   

   Définissez <binary-dir> sur le répertoire binaire qui contient le cache CMake. Par exemple, si vous exécutez CMake sur un exemple Azure Sphere, la commande build est cmake --build out/ARM-Debug.

   Lors de la résolution des problèmes, en particulier après avoir apporté des modifications à vos commandes CMake, supprimez l’intégralité de votre build et réessayez.

6. Supprimez toutes les applications déjà déployées sur l’appareil :

   az sphere device sideload delete
   

7. À partir du répertoire de build de votre projet, à l’invite de commandes, chargez le package d’image créé par ninja :

   az sphere device sideload deploy --image-package <path-to-imagepackage>
   

   L’application commence à s’exécuter peu après son chargement.

8. Obtenez l’ID de composant pour l’image :

   az sphere image-package show --image-package <path-to-imagepackage>
   

   La commande retourne toutes les métadonnées du package d’image. L’ID de composant de l’application apparaît dans la section Identité pour le type d’image d’application. Par exemple :

   ...
     "Identity": {
       "ComponentId": "<component-id>",
       "ImageId": "<image-id>",
       "ImageType": "Application"
     },
   ...
   

Générer et déployer l’application de haut niveau

1. Accédez au dossier dans lequel vous avez extrait les applications IntercoreComms, puis sélectionnez le dossier IntercoreComms/IntercoreComms_HighLevelApp.

2. Ouvrez le fichier app_manifest.json et vérifiez que l’ID de composant rtApp est affiché dans la fonctionnalité AllowedApplicationConnections.

3. Ouvrez une interface de ligne de commande à l’aide de PowerShell, de l’invite de commandes Windows ou de l’interpréteur de commandes Linux. Accédez au répertoire de build de votre projet.

4. À partir du répertoire de build de votre projet, à l’invite de commandes, exécutez CMake avec les paramètres suivants :

   cmake --preset <preset-name> <source-path>
   

   • --preset <preset-name>

     Nom prédéfini de configuration de build tel que défini dans CMakePresets.json.

   • --build <cmake-path>

     Répertoire binaire qui contient le cache CMake. Par exemple, si vous exécutez CMake sur un exemple Azure Sphere, la commande build est cmake --build out/ARM-Debug.

   • <source-path>

     Chemin d’accès du répertoire qui contient les fichiers sources de l’exemple d’application. Dans l’exemple, le référentiel d’exemples Azure Sphere a été téléchargé dans un répertoire appelé AzSphere.

     Les paramètres CMake sont séparés par des espaces. Le caractère de continuation de ligne (^ pour la ligne de commande Windows, \ pour la ligne de commande Linux ou ' pour PowerShell) peut être utilisé pour la lisibilité, mais n’est pas obligatoire.

   Les exemples suivants illustrent les commandes CMake pour l’application de haut niveau IntercoreComms.

   • Windows
   • Linux

   Invite de commandes Windows

    cmake ^
    --preset "ARM-Debug" ^
    "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_HighLevelApp"
   

   Windows PowerShell

    cmake `
    --preset "ARM-Debug" `
    "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_HighLevelApp"
   

5. À partir du répertoire de build de votre projet, à l’invite de commandes, exécutez Ninja pour générer l’application et créer le fichier de package d’image.

   ninja -C out/ARM-Debug
   

   Ninja place l’application et les fichiers .imagepackage obtenus dans le répertoire spécifié.

   Vous pouvez également appeler Ninja via CMake avec la commande suivante :

   cmake --build out/<binary-dir>
   

   Définissez <binary-dir> sur le répertoire binaire qui contient le cache CMake. Par exemple, si vous exécutez CMake sur un exemple Azure Sphere, la commande build est cmake --build out/ARM-Debug.

   Lors de la résolution des problèmes, en particulier après avoir apporté des modifications à vos commandes CMake, supprimez l’intégralité de votre build et réessayez.

6. À partir du répertoire de build de votre projet, à l’invite de commandes, chargez le package d’image créé par ninja :

   az sphere device sideload deploy --image-package <package-name>
   

   L’application commence à s’exécuter peu après son chargement.

7. Obtenez l’ID de composant pour l’image :

   az sphere image-package show --image-package <path-to-imagepackage>
   

   La commande retourne toutes les métadonnées du package d’image. L’ID de composant de l’application apparaît dans la section Identité pour le type d’image d’application. Par exemple :

   ...
     "Identity": {
       "ComponentId": "<component-id>",
       "ImageId": "<image-id>",
       "ImageType": "Application"
     },
   ...
   

Exécuter les applications partenaires avec le débogage activé

1. Arrêtez l’application en temps réel si elle est en cours d’exécution.

   az sphere device app stop --component-id <component id>
   

2. Relancez l’application pour le débogage.

   az sphere device app start -- --debug-mode true --component-id <component id>
   

   Cette commande retourne le noyau sur lequel l’application s’exécute.

     <component id>
     App state: running
     Core        : Real-time 0
   

3. Accédez au dossier Openocd pour le sysroot avec lequel l’application a été générée. Les sysroots sont installés dans le dossier d’installation du Kit de développement logiciel (SDK) Azure Sphere. Par exemple, sur Windows, le dossier est installé par défaut sur C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\openocd et sur Linux, à l’adresse /opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux.

4. Exécutez openocd comme le montre l’exemple suivant. L’exemple suppose que l’application s’exécute sur le noyau 0. Si l’application s’exécute sur core 1, remplacez « targets io0 » par « targets io1 ».

   • Windows
   • Linux

      openocd -f mt3620-rdb-ftdi.cfg -f mt3620-io0.cfg -c "gdb_memory_map disable" -c "gdb_breakpoint_override hard" -c init -c "targets io0" -c halt -c "targets"
   

5. Ouvrez une nouvelle invite de commandes Azure Sphere (Cli classique Windows Azure Sphere), une invite de commandes standard ou PowerShell (Windows Azure CLI) ou une fenêtre de terminal (Linux).

6. Accédez au dossier qui contient le fichier .out de l’application en temps réel et démarrez arm-none-eabi-gdb, qui fait partie de la chaîne d’outils GNU Arm Embedded :

   • Windows
   • Linux

   Invite de commandes Windows

   "C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin\arm-none-eabi-gdb" IntercoreComms_RTApp_MT3620_BareMetal.out
   

   Windows PowerShell

    & "C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin\arm-none-eabi-gdb" IntercoreComms_RTApp_MT3620_BareMetal.out
   

7. Le serveur OpenOCD fournit une interface de serveur GDB sur :4444. Définissez la cible pour le débogage.

   target remote :4444

8. Vous pouvez maintenant exécuter des commandes gdb sur l’application compatible en temps réel. Ajoutez un point d’arrêt à la fonction HandleSendTimerDeferred :

   break HandleSendTimerDeferred
   

9. L’émulateur de terminal connecté doit afficher la sortie de l’application compatible en temps réel.

10. Ouvrez une nouvelle invite de commandes Azure Sphere (Cli classique Windows Azure Sphere), une invite de commandes standard ou PowerShell (Windows Azure CLI) ou une fenêtre de terminal (Linux).

11. Accédez au dossier qui contient le fichier .imagepackage de l’application de haut niveau.

12. Arrêtez l’application générale si elle est en cours d’exécution.

    az sphere device app stop --component-id <component id>
    

13. Relancez l’application de haut niveau avec le débogage.

    az sphere device app start --debug-mode true --component-id <component id> --debug-mode
    

14. Ouvrez un émulateur de terminal et établissez une connexion Telnet ou TCP à 192.168.35.2 sur le port 2342 pour afficher la sortie de l’application de haut niveau.

15. Démarrez gdb avec la commande suivante :

    • Windows
    • Linux

    Invite de commandes Windows

    "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb.exe" IntercoreComms_HighLevelApp.out
    

    Windows PowerShell

    & "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb.exe" IntercoreComms_HighLevelApp.out
    

    Note

    Le Kit de développement logiciel (SDK) Azure Sphere est fourni avec plusieurs sysroots afin que les applications puissent cibler différents ensembles d’API, comme décrit dans Version du runtime d’application, sysroots et API bêta. Les sysroots sont installés dans le dossier d’installation du Kit de développement logiciel (SDK) Azure Sphere sous Sysroots.

16. Définissez la cible de débogage distant sur l’adresse IP 192.168.35.2 sur le port 2345 :

    target remote 192.168.35.2:2345

17. Ajoutez un point d’arrêt à la fonction SendMessageToRTApp :

    break SendMessageToRTApp

18. Tapez c pour continuer, observez la sortie dans votre terminal Telnet/TCP, puis basculez vers l’invite de commandes ou la fenêtre de terminal contenant votre session de débogage d’application en temps réel.

19. Tapez c pour continuer et observer la sortie dans votre session série connectée.

Vous pouvez effectuer des allers-retours entre les sessions de débogage, en basculant entre l’application en temps réel et l’application de haut niveau. Vous devez voir une sortie similaire à ce qui suit dans les deux fenêtres de sortie :

Starting debugger....
                     Process /mnt/apps/25025d2c-66da-4448-bae1-ac26fcdd3627/bin/app created; pid = 40
                     Listening on port 2345
                                           Remote debugging from host 192.168.35.1, port 56522
              High-level intercore comms application
                                                    Sends data to, and receives data from a real-time capable application.
                                          Sending: hl-app-to-rt-app-00
                                                                      Sending: hl-app-to-rt-app-01

IntercoreComms_RTApp_MT3620_BareMetal
App built on: Nov 17 2020, 09:25:19
Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
Message size: 19 bytes:
Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30
Text: hl-app-to-rt-app-00

Pour mettre fin à chaque session de débogage, tapez q à l’invite gdb.