Tutorial: Criar e depurar aplicativos parceiros

• Instale CMake e Ninja para Windows ou para Linux.

• Instale Visual Studio Code para Windows ou para Linux.
• Instale CMake e Ninja para Windows ou para Linux.

• Instale o Visual Studio e a extensão do Azure Sphere.

• Visual Studio 2022: se você estiver usando o Visual Studio 2022, instale o GNU Arm Embedded Toolchain (arm-none-eabi) no site do desenvolvedor do Arm.
• Visual Studio 2019: o conjunto de ferramentas é instalado automaticamente com a extensão do Azure Sphere para Visual Studio no Visual Studio 2019. Se você estiver usando o Visual Studio 2019, prossiga para Configurar hardware para exibir a saída. No entanto, se você instalou o GNU Arm Embedded Toolchain manualmente, o Visual Studio usará a versão instalada.

Para instalar o conjunto de ferramentas no site do desenvolvedor do Arm, localize o GNU Arm Embedded Toolchain (arm-none-eabi) que inclui o compilador para o processador ARM Cortex-M4. Siga as instruções para baixar e instalar o compilador para sua plataforma do sistema operacional.

Por padrão, Visual Studio Code pesquisa o conjunto de ferramentas e deve encontrar a versão instalada. Se você encontrar problemas de build relacionados ao conjunto de ferramentas, marcarExtensões de Configurações> dePreferências>>do AzureSphere para garantir que "Azure Sphere: Arm Gnu Path" identifique o diretório de instalação do GNU Arm Embedded Toolchain.

1. Inicie o Visual Studio. Selecione Abrir uma pasta local e navegue até a pasta em que você extraiu os aplicativos IntercoreComms.

   Importante

   Se você estiver usando o Visual Studio 2022 versão 17.1 ou posterior e extrair o exemplo IntercoreComms antes da versão 22.02 do Azure Sphere, você deverá adicionar um arquivo CMakeWorkspaceSettings.json à pasta de projeto de nível superior.

2. Se você não estiver usando um RDB MT3620, atualize os arquivos app_manifest.json para aplicativos e o arquivo de definição de hardware e CMakeLists.txt arquivo para o aplicativo de alto nível corresponder ao hardware.

3. Se a geração CMake não começar automaticamente, selecione o arquivo CMakeLists.txt.

4. No Visual Studio, exiba> asaída do Show deSaída> de: a saída do CMake deve mostrar as mensagens CMake generation started e CMake generation finished.

5. Selecione Compilar>Compilar Tudo. Se o menu não estiver presente, abra Gerenciador de Soluções, clique com o botão direito do mouse no arquivo CMakeLists.txt e selecione Compilar. O local de saída dos aplicativos RT do IntercoreComms_HL & IntercoreComms é exibido na janela Saída .

6. Selecione Selecionar Item> de InicializaçãoIntercoreComms (Todos os núcleos).

7. Selecione Depurar>Depurar ou pressione F5 para implantar e depurar os aplicativos.

8. Na janela Saída , selecione saída no menu, selecione Saída do Dispositivo. A janela Saída deve mostrar a saída de aplicativo de alto nível:

   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. O emulador de terminal conectado deve exibir a saída do programa com capacidade em tempo real:

   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. Use o depurador para definir pontos de interrupção, inspecionar variáveis e tentar outras tarefas de depuração.

1. Em Visual Studio Code, abra a pasta em que você extraiu os aplicativos IntercoreComms. Visual Studio Code detecta o arquivo intercore.code-workspace e pergunta se você deseja abrir o workspace. Selecione Abrir Workspace para abrir o aplicativo em tempo real e o aplicativo de alto nível ao mesmo tempo.

2. Se você não estiver usando um RDB MT3620, atualize os arquivos app_manifest.json para aplicativos e o arquivo de definição de hardware e CMakeLists.txt arquivo para o aplicativo de alto nível corresponder ao hardware.

3. Pressione F5 para iniciar o depurador. Se o projeto não tiver sido criado anteriormente ou se os arquivos tiverem sido alterados e a reconstrução for necessária, Visual Studio Code criará o projeto antes do início da depuração.

4. A janela de saída do Azure Sphere deve mostrar "Implantando imagem..." seguido pelos caminhos para o SDK e o compilador.

5. A janela de saída deve mostrar a saída de aplicativo de alto nível:

   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. O emulador de terminal conectado deve exibir a saída do programa com capacidade em tempo real:

   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. Use Visual Studio Code recursos de depuração para definir pontos de interrupção, inspecionar variáveis e tentar outras tarefas de depuração.

Solucionando problemas

O aplicativo pode começar a ser executado antes que o OpenOCD faça uma conexão. Como resultado, os pontos de interrupção definidos no início do código podem ser perdidos. Uma solução alternativa simples para isso é atrasar o início do aplicativo até que o OpenOCD se conecte.

1. Insira o código a seguir no início do ponto de entrada do aplicativo RTCoreMain. Isso fará com que o aplicativo insira e permaneça em um while loop até que a variável f seja definida como true.

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

2. Pressione F5 para iniciar o aplicativo com a depuração e, em seguida, inicie a execução.

3. No painel Locals de depuração, altere o valor de f zero para um.

4. Passe o código como de costume.

Ao criar com a CLI, primeiro você cria e implanta o aplicativo com capacidade em tempo real e, em seguida, cria e implanta o aplicativo de alto nível.

Criar e implantar o aplicativo com capacidade em tempo real

1. Navegue até a pasta em que você extraiu os aplicativos IntercoreComms e selecione a pasta IntercoreComms/IntercoreComms_RTApp_MT3620_BareMetal.

2. Abra o arquivo app_manifest.json e verifique se a ID do componente do aplicativo de alto nível é mostrada no recurso AllowedApplicationConnections.

3. Abra uma interface de linha de comando usando o PowerShell, o Prompt de Comando do Windows ou o shell de comando do Linux. Navegue até o diretório de build do projeto.

4. No diretório de build do projeto, no prompt de comando, execute o CMake com os seguintes parâmetros:

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

   • --preset <preset-name>

     O nome predefinido de configuração de build, conforme definido em CMakePresets.json.

   • --build <cmake-path>

     O diretório binário que contém o cache CMake. Por exemplo, se você executar o CMake em um exemplo do Azure Sphere, o comando de build será cmake --build out/ARM-Debug.

   • <source-path>

     O caminho do diretório que contém os arquivos de origem do aplicativo de exemplo. No exemplo, o repositório de exemplos do Azure Sphere foi baixado em um diretório chamado AzSphere.

     Os parâmetros CMake são separados por espaços. O caractere de continuação de linha (^ para linha de comando do Windows, \ para linha de comando linux ou ' para PowerShell) pode ser usado para legibilidade, mas não é necessário.

   Os exemplos a seguir mostram os comandos CMake para o IntercoreComms RTApp:

   • Windows
   • Linux

   Prompt de Comando do 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. No diretório de build do projeto, no prompt de comando, execute o Ninja para criar o aplicativo e criar o arquivo de pacote de imagem.

   ninja -C out/ARM-Debug
   

   O Ninja coloca os arquivos de aplicativo e .imagepackage resultantes no diretório especificado.

   Você também pode invocar o Ninja por meio do CMake com o seguinte comando:

   cmake --build out/<binary-dir>
   

   Defina <binary-dir> como o diretório binário que contém o cache CMake. Por exemplo, se você executar o CMake em um exemplo do Azure Sphere, o comando de build será cmake --build out/ARM-Debug.

   Ao solucionar problemas, especialmente depois de fazer alterações nos comandos do CMake, exclua todo o build e tente novamente.

6. Exclua todos os aplicativos que já estão implantados no dispositivo:

   az sphere device sideload delete
   

7. No diretório de build do projeto, no prompt de comando, carregue o pacote de imagem que o ninja criou:

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

   O aplicativo começará a ser executado logo após ser carregado.

8. Obtenha a ID do componente para a imagem:

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

   O comando retorna todos os metadados do pacote de imagem. A ID do componente do aplicativo é exibida na seção Identidade do Tipo de Imagem do Aplicativo. Por exemplo:

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

Criar e implantar o aplicativo de alto nível

1. Navegue até a pasta em que você extraiu os aplicativos IntercoreComms e selecione a pasta IntercoreComms/IntercoreComms_HighLevelApp.

2. Abra o arquivo app_manifest.json e verifique se a ID do componente do RTApp é mostrada no recurso AllowedApplicationConnections.

3. Abra uma interface de linha de comando usando o PowerShell, o Prompt de Comando do Windows ou o shell de comando do Linux. Navegue até o diretório de build do projeto.

4. No diretório de build do projeto, no prompt de comando, execute o CMake com os seguintes parâmetros:

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

   • --preset <preset-name>

     O nome predefinido de configuração de build, conforme definido em CMakePresets.json.

   • --build <cmake-path>

     O diretório binário que contém o cache CMake. Por exemplo, se você executar o CMake em um exemplo do Azure Sphere, o comando de build será cmake --build out/ARM-Debug.

   • <source-path>

     O caminho do diretório que contém os arquivos de origem do aplicativo de exemplo. No exemplo, o repositório de exemplos do Azure Sphere foi baixado em um diretório chamado AzSphere.

     Os parâmetros CMake são separados por espaços. O caractere de continuação de linha (^ para linha de comando do Windows, \ para linha de comando linux ou ' para PowerShell) pode ser usado para legibilidade, mas não é necessário.

   Os exemplos a seguir mostram os comandos CMake para o aplicativo de alto nível IntercoreComms.

   • Windows
   • Linux

   Prompt de Comando do 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. No diretório de build do projeto, no prompt de comando, execute o Ninja para criar o aplicativo e criar o arquivo de pacote de imagem.

   ninja -C out/ARM-Debug
   

   O Ninja coloca os arquivos de aplicativo e .imagepackage resultantes no diretório especificado.

   Você também pode invocar o Ninja por meio do CMake com o seguinte comando:

   cmake --build out/<binary-dir>
   

   Defina <binary-dir> como o diretório binário que contém o cache CMake. Por exemplo, se você executar o CMake em um exemplo do Azure Sphere, o comando de build será cmake --build out/ARM-Debug.

   Ao solucionar problemas, especialmente depois de fazer alterações nos comandos do CMake, exclua todo o build e tente novamente.

6. No diretório de build do projeto, no prompt de comando, carregue o pacote de imagem que o ninja criou:

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

   O aplicativo começará a ser executado logo após ser carregado.

7. Obtenha a ID do componente para a imagem:

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

   O comando retorna todos os metadados do pacote de imagem. A ID do componente do aplicativo é exibida na seção Identidade do Tipo de Imagem do Aplicativo. Por exemplo:

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

Executar os aplicativos parceiros com a depuração habilitada

1. Pare o aplicativo em tempo real se ele estiver em execução.

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

2. Reinicie o aplicativo para depuração.

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

   Esse comando retorna o núcleo no qual o aplicativo está em execução.

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

3. Navegue até a pasta Openocd para o sysroot com o qual o aplicativo foi criado. Os sysroots são instalados na pasta de instalação do SDK do Azure Sphere. Por exemplo, no Windows, a pasta é instalada por padrão em C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\openocd e no Linux, em /opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux.

4. Execute openocd como mostra o exemplo a seguir. O exemplo pressupõe que o aplicativo esteja sendo executado no núcleo 0. Se o aplicativo estiver em execução no núcleo 1, substitua "targets io0" por "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. Abra um novo Prompt de Comando do Azure Sphere (CLI clássica do Windows Azure Sphere), prompt de comando padrão ou PowerShell (CLI do Windows Azure) ou janela de terminal (Linux).

6. Navegue até a pasta que contém o arquivo .out do aplicativo com capacidade em tempo real e inicie arm-none-eabi-gdb, que faz parte do GNU Arm Embedded Toolchain:

   • Windows
   • Linux

   Prompt de Comando do 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. O servidor OpenOCD fornece uma interface do servidor GDB em :4444. Defina o destino para depuração.

   target remote :4444

8. Agora você pode executar comandos gdb no aplicativo com capacidade em tempo real. Adicione um ponto de interrupção na função HandleSendTimerDeferred:

   break HandleSendTimerDeferred
   

9. O emulador de terminal conectado deve exibir a saída do aplicativo com capacidade em tempo real.

10. Abra um novo Prompt de Comando do Azure Sphere (CLI clássica do Windows Azure Sphere), prompt de comando padrão ou PowerShell (CLI do Windows Azure) ou janela de terminal (Linux).

11. Navegue até a pasta que contém o arquivo .imagepackage do aplicativo de alto nível.

12. Pare o aplicativo de alto nível se ele estiver em execução.

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

13. Reinicie o aplicativo de alto nível com a depuração.

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

14. Abra um emulador de terminal e estabeleça uma conexão Telnet ou TCP para 192.168.35.2 na porta 2342 para exibir a saída do aplicativo de alto nível.

15. Inicie gdb com o seguinte comando:

    • Windows
    • Linux

    Prompt de Comando do 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
    

    Nota

    O SDK do Azure Sphere é fornecido com vários sysroots para que os aplicativos possam direcionar diferentes conjuntos de API, conforme descrito em Versão de runtime do aplicativo, sysroots e APIs Beta. Os sysroots são instalados na pasta de instalação do SDK do Azure Sphere em Sysroots.

16. Defina o destino de depuração remota como endereço IP 192.168.35.2 na porta 2345:

    target remote 192.168.35.2:2345

17. Adicione um ponto de interrupção na função SendMessageToRTApp:

    break SendMessageToRTApp

18. Digite c para continuar, observe a saída no terminal Telnet/TCP e, em seguida, alterne para o prompt de comando ou a janela do terminal que contém a sessão de depuração do aplicativo em tempo real.

19. Digite c para continuar e observe a saída em sua sessão serial conectada.

Você pode trabalhar para frente e para trás entre sessões de depuração, alternando entre o aplicativo com capacidade em tempo real e o aplicativo de alto nível. Você deve ver uma saída semelhante à seguinte nas duas janelas de saída:

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

Para encerrar cada sessão de depuração, digite q no prompt do gdb.