Tutorial: Criar e depurar aplicações de parceiros

• Instale o CMake e o Ninja para Windows ou para Linux.

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

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

• Visual Studio 2022: se estiver a utilizar o Visual Studio 2022, instale o GNU Arm Embedded Toolchain (arm-none-eabi) a partir do site do programador arm.
• Visual Studio 2019: a cadeia de ferramentas é instalada automaticamente com a extensão do Azure Sphere para Visual Studio no Visual Studio 2019. Se estiver a utilizar o Visual Studio 2019, avance para Configurar hardware para apresentar a saída. No entanto, se instalou manualmente o GNU Arm Embedded Toolchain, o Visual Studio utilizará a versão que instalou.

Para instalar a cadeia de ferramentas no site do programador arm, localize a GNU Arm Embedded Toolchain (arm-none-eabi) que inclui o compilador para o processador Arm Cortex-M4. Siga as instruções para transferir e instalar o compilador para a sua plataforma de SO.

Por predefinição, o Visual Studio Code procura a cadeia de ferramentas e deverá encontrar a versão que instalou. Se encontrar problemas de compilação relacionados com a cadeia de ferramentas>, verifique AsExtensões de DefiniçõesdePreferências>>do AzureSphere para garantir que "Azure Sphere: Caminho do Arm Gnu" identifica o diretório de instalação da Cadeia de Ferramentas GNU Arm Embedded.

1. Inicie o Visual Studio. Selecione Abrir uma pasta local e navegue para a pasta onde extraiu as aplicações IntercoreComms.

   Importante

   Se estiver a utilizar a versão 17.1 ou posterior do Visual Studio 2022 e tiver extraído o exemplo IntercoreComms antes da versão 22.02 do Azure Sphere, tem de adicionar um ficheiro CMakeWorkspaceSettings.json à pasta de projeto de nível superior.

2. Se não estiver a utilizar um RDB MT3620, atualize os ficheiros de app_manifest.json para as aplicações e o ficheiro de definição de hardware e CMakeLists.txt ficheiro para a aplicação de alto nível para corresponder ao hardware.

3. Se a geração CMake não iniciar automaticamente, selecione o ficheiro CMakeLists.txt.

4. No Visual Studio, veja a saída Mostrar>Saída>de: A saída CMake deve mostrar as mensagens CMake generation started e CMake generation finished.

5. Selecione Criar>Tudo. Se o menu não estiver presente, abra Explorador de Soluções, clique com o botão direito do rato no ficheiro CMakeLists.txt e selecione Compilar. A localização de saída das aplicações IntercoreComms RT do IntercoreComms_HL & é apresentada na janela Saída .

6. Selecione Selecionar Item> de ArranqueIntercoreComando (Todos os núcleos).

7. Selecione Depurar>Depurar ou prima F5 para implementar e depurar as aplicações.

8. Na janela Saída , selecione Saída no menu, selecione Saída do Dispositivo. A janela Saída deve mostrar a saída da aplicação 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 ligado deve apresentar 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. Utilize o depurador para definir pontos de interrupção, inspecionar variáveis e experimentar outras tarefas de depuração.

1. No Visual Studio Code, abra a pasta onde extraiu as aplicações IntercoreComms. O Visual Studio Code deteta o ficheiro intercore.code-workspace e pergunta se pretende abrir a área de trabalho. Selecione Abrir Área de Trabalho para abrir a aplicação em tempo real e a aplicação de alto nível ao mesmo tempo.

2. Se não estiver a utilizar um RDB MT3620, atualize os ficheiros de app_manifest.json para as aplicações e o ficheiro de definição de hardware e CMakeLists.txt ficheiro para a aplicação de alto nível para corresponder ao hardware.

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

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

5. A janela de saída deve mostrar a saída da aplicação 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 ligado deve apresentar 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. Utilize as funcionalidades de depuração do Visual Studio Code para definir pontos de interrupção, inspecionar variáveis e experimentar outras tarefas de depuração.

Resolução de problemas

A aplicação pode começar a ser executada antes de o OpenOCD efetuar uma ligação. Como resultado, os pontos de interrupção definidos no início do código podem não ser apresentados. Uma solução simples para isto é atrasar o início da aplicação até que o OpenOCD se ligue.

1. Insira o seguinte código no início do ponto de entrada da aplicação RTCoreMain. Isto fará com que a aplicação introduza e permaneça num while ciclo até que a variável f esteja definida como true.

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

2. Prima F5 para iniciar a aplicação com a depuração e, em seguida, invada a execução.

3. No painel Depuração Locais , altere o valor de f zero para um.

4. Siga o código como habitualmente.

Ao criar com a CLI, primeiro cria e implementa a aplicação com capacidade em tempo real e, em seguida, compila e implementa a aplicação de alto nível.

Criar e implementar a aplicação com capacidade em tempo real

1. Navegue para a pasta onde extraiu as aplicações IntercoreComms e, em seguida, selecione a pasta IntercoreComms/IntercoreComms_RTApp_MT3620_BareMetal.

2. Abra o ficheiro app_manifest.json e verifique se o ID de componente da aplicação de alto nível é apresentado na capacidade AllowedApplicationConnections.

3. Abra uma interface de linha de comandos com o PowerShell, a Linha de Comandos do Windows ou a shell de comandos do Linux. Navegue para o diretório de compilação do projeto.

4. No diretório de compilação do projeto, na linha de comandos, execute CMake com os seguintes parâmetros:

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

   • --preset <preset-name>

     O nome predefinido da configuração da compilação, conforme definido no CMakePresets.json.

   • --build <cmake-path>

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

   • <source-path>

     O caminho do diretório que contém os ficheiros de origem da aplicação de exemplo. No exemplo, o repositório de exemplos do Azure Sphere foi transferido para um diretório chamado AzSphere.

     Os parâmetros CMake são separados por espaços. O caráter de continuação da linha (^ para a linha de comandos do Windows, \ para a linha de comandos do Linux ou ' para o PowerShell) pode ser utilizado para legibilidade, mas não é necessário.

   Os exemplos seguintes mostram os comandos CMake para o IntercoreComms RTApp:

   • Windows
   • Linux

   Linha de Comandos 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 compilação do projeto, na linha de comandos, execute Ninja para criar a aplicação e criar o ficheiro de pacote de imagem.

   ninja -C out/ARM-Debug
   

   Ninja coloca a aplicação resultante e os ficheiros .imagepackage no diretório especificado.

   Também pode invocar Ninja através de CMake com o seguinte comando:

   cmake --build out/<binary-dir>
   

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

   Ao resolver problemas, especialmente depois de efetuar alterações aos comandos CMake, elimine toda a sua criação e tente novamente.

6. Elimine todas as aplicações que já estejam implementadas no dispositivo:

   az sphere device sideload delete
   

7. No diretório de compilação do projeto, na linha de comandos, carregue o pacote de imagem que ninja criou:

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

   A aplicação começará a ser executada logo após ser carregada.

8. Obtenha o ID do componente da imagem:

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

   O comando devolve todos os metadados do pacote de imagem. O ID do componente da aplicação é apresentado na secção Identidade do Tipo de Imagem da Aplicação. Por exemplo:

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

Criar e implementar a aplicação de alto nível

1. Navegue para a pasta onde extraiu as aplicações IntercoreComms e, em seguida, selecione a pasta IntercoreComms/IntercoreComms_HighLevelApp.

2. Abra o ficheiro app_manifest.json e verifique se o ID do componente do RTApp é apresentado na capacidade AllowedApplicationConnections.

3. Abra uma interface de linha de comandos com o PowerShell, a Linha de Comandos do Windows ou a shell de comandos do Linux. Navegue para o diretório de compilação do projeto.

4. No diretório de compilação do projeto, na linha de comandos, execute CMake com os seguintes parâmetros:

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

   • --preset <preset-name>

     O nome predefinido da configuração da compilação, conforme definido no CMakePresets.json.

   • --build <cmake-path>

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

   • <source-path>

     O caminho do diretório que contém os ficheiros de origem da aplicação de exemplo. No exemplo, o repositório de exemplos do Azure Sphere foi transferido para um diretório chamado AzSphere.

     Os parâmetros CMake são separados por espaços. O caráter de continuação da linha (^ para a linha de comandos do Windows, \ para a linha de comandos do Linux ou ' para o PowerShell) pode ser utilizado para legibilidade, mas não é necessário.

   Os exemplos seguintes mostram os comandos CMake para a aplicação de alto nível IntercoreComms.

   • Windows
   • Linux

   Linha de Comandos 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 compilação do projeto, na linha de comandos, execute Ninja para criar a aplicação e criar o ficheiro de pacote de imagem.

   ninja -C out/ARM-Debug
   

   Ninja coloca a aplicação resultante e os ficheiros .imagepackage no diretório especificado.

   Também pode invocar Ninja através de CMake com o seguinte comando:

   cmake --build out/<binary-dir>
   

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

   Ao resolver problemas, especialmente depois de efetuar alterações aos comandos CMake, elimine toda a sua criação e tente novamente.

6. No diretório de compilação do projeto, na linha de comandos, carregue o pacote de imagem que ninja criou:

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

   A aplicação começará a ser executada logo após ser carregada.

7. Obtenha o ID do componente da imagem:

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

   O comando devolve todos os metadados do pacote de imagem. O ID do componente da aplicação é apresentado na secção Identidade do Tipo de Imagem da Aplicação. Por exemplo:

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

Executar as aplicações parceiras com a depuração ativada

1. Pare a aplicação em tempo real se estiver em execução.

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

2. Reinicie a aplicação para depuração.

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

   Este comando devolve o núcleo no qual a aplicação está em execução.

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

3. Navegue para a pasta Openocd para obter o sysroot com o qual a aplicação foi criada. Os sysroots são instalados na pasta de instalação do SDK do Azure Sphere. Por exemplo, no Windows, a pasta é instalada por predefiniçã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 seguinte exemplo. O exemplo pressupõe que a aplicação está em execução no núcleo 0. Se a aplicação 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 uma nova Linha de Comandos do Azure Sphere (CLI clássica do Windows Azure Sphere), uma linha de comandos padrão ou o PowerShell (CLI do Windows Azure) ou uma janela de terminal (Linux).

6. Navegue para a pasta que contém o ficheiro .out da aplicação em tempo real e inicie arm-none-eabi-gdbo , que faz parte da Cadeia de Ferramentas GNU Arm Embedded:

   • Windows
   • Linux

   Linha de Comandos 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 de servidor GDB em :4444. Defina o destino para depuração.

   target remote :4444

8. Agora pode executar comandos gdb para a aplicação com capacidade em tempo real. Adicione um ponto de interrupção na função HandleSendTimerDeferred:

   break HandleSendTimerDeferred
   

9. O emulador de terminal ligado deve apresentar o resultado da aplicação com capacidade em tempo real.

10. Abra uma nova Linha de Comandos do Azure Sphere (CLI clássica do Windows Azure Sphere), uma linha de comandos padrão ou o PowerShell (CLI do Windows Azure) ou uma janela de terminal (Linux).

11. Navegue para a pasta que contém o ficheiro .imagepackage de aplicação de alto nível.

12. Pare a aplicação de alto nível se estiver em execução.

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

13. Reinicie a aplicação 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 ligação Telnet ou TCP para 192.168.35.2 na porta 2342 para ver a saída da aplicação de alto nível.

15. Inicie a gdb com o seguinte comando:

    • Windows
    • Linux

    Linha de Comandos 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 as aplicações possam visar diferentes conjuntos de API, conforme descrito em Versão do runtime da aplicação, 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 para o 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. Escreva c para continuar, observe a saída no terminal Telnet/TCP e, em seguida, mude para a linha de comandos ou janela de terminal que contém a sua sessão de depuração da aplicação em tempo real.

19. Escreva c para continuar e observar a saída na sua sessão de série ligada.

Pode trabalhar entre sessões de depuração e alternar entre a aplicação com capacidade em tempo real e a aplicação de alto nível. Deverá ver um resultado semelhante ao 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 terminar cada sessão de depuração, escreva q na linha de comandos gdb.