Share via

Debug partner applications

  • Article

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

  1. Ensure that your device is connected to your PC by USB. In the Set startup item menu, select Azure Sphere App (All Cores) where Azure Sphere App is the name of your top-level project or press F5.

    Remote GDB Debugger button

  2. If you are prompted to build the project, select Yes. Visual Studio compiles the partner applications, creates image packages, sideloads them onto the board, and starts them in debug mode. Sideloading means that the applications are delivered directly from the PC over a wired connection, rather than delivered through the cloud.

    Note the paths in the View > Output > Show output from: Build output, which indicates the location of the output image packages on your PC. When you are ready to create a deployment, you will need to know the paths to the image packages.

  3. By default, the Output window shows output from Device Output. To see messages from the debugger, select Debug from the Show output from: dropdown menu. You can also inspect the program disassembly, registers, or memory through the Debug > Windows menu.

If you have two RTApps, ensure that both are listed as partner apps in the top-level launch.vs.json file.

Use the Visual Studio debugger to set breakpoints, pause, step over, step into, restart, or stop the application.

While stopped at a breakpoint in your C source code, you can open a Disassembly window that shows the current address, the assembler mnemonic for the current command, and information such as the registers involved or the source-code command being executed.

To open the Disassembly window:

  1. Ensure that the C code source file containing the breakpoint is open in Visual Studio.
  2. Select Debug > Windows > Disassembly, or press Alt+8.

  1. Open the folder containing your partner applications. Visual Studio Code detects the workspace file and asks if you want to open the workspace. Select Open Workspace to open both the real-time application and high-level application at once.

  2. Right-click on either of the two CMakeLists.txt files and select Build All Projects.

  3. Click the Run icon in the Visual Studio Code Activity Bar.

  4. On the pulldown menu that appears at the top of the window on the left side of the screen, select Launch Azure Sphere Apps (gdb)(workspace).

  5. Press F5 to build and debug the project. If the project has not previously been built, or if files have changed and rebuilding is required, Visual Studio Code will build the project before debugging starts.

  6. Wait several seconds for Visual Studio Code to build the applications, create the image packages, deploy them to the board, and start them in debug mode. You'll see status updates in the Output pane along the way.

    First, CMake determines whether the applications need to be built. If so, focus shifts to the output window, which displays the output from CMake/Build.

    Next, the output pane shows the output from azsphere as it deploys the image package to the device. Finally, the Debug Console receives focus and shows gdb output.

Use the Visual Studio Code debugger to set breakpoints, pause, step over, step into, restart, or stop the application.

While stopped at a breakpoint in your C source code, you can open a Disassembly view that shows the current address, raw hex data, the assembler mnemonic for the current command, and information such as the registers involved or the source-code command being executed.

To open the Disassembly view:

  1. Ensure that the C code source file containing the breakpoint is open in a Visual Studio Code editor.
  2. Either right-click in the editor window and select Open Disassembly View or select View > Command Palette > Open Disassembly View.

  1. Stop the real-time capable application if it's running.

    azsphere device app stop --component-id <component id>

  2. Re-start the real-time capable application with debugging.

    azsphere device app start --component-id <component id>

    This command returns the core on which the application is running.

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

  3. Navigate to the Openocd folder for the sysroot that the application was built with. The sysroots are installed in the Azure Sphere SDK installation folder. For example, on Windows the folder is installed by default at C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\openocd and on Linux, at /opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux.

  4. Run openocd as the following example shows. The example assumes the app is running on core 0. If the app is running on core 1, replace "targets io0" with "targets io1".

    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. Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell.

  6. Navigate to the folder that contains the real-time capable application .out file and start arm-none-eabi-gdb, which is part of the GNU Arm Embedded Toolchain:

    Windows Command Prompt

    "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. The OpenOCD server provides a GDB server interface on :4444. Set the target for debugging.

    target remote :4444

  8. You can now run gdb commands. Add a breakpoint at the function HandleSendTimerDeferred:

    break HandleSendTimerDeferred

  9. The connected terminal emulator should display output from the real-time capable application.

  10. Open a new Azure Sphere Command Prompt (Windows) or terminal window (Linux).

  11. Navigate to the folder that contains the high-level application .imagepackage file.

  12. If the application is running, stop it and then restart it with debugging:

    azsphere device app stop --component-id <ComponentId>

    azsphere device app start --debug-mode --component-id <ComponentId>

  13. Open a terminal emulator and establish a Telnet or TCP connection to 192.168.35.2 at port 2342 to view the high-level app's output.

  14. Start gdb with the following command:

    Windows Command Prompt

    "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

    The Azure Sphere SDK ships with multiple sysroots so that applications can target different API sets, as described in Application runtime version, sysroots, and Beta APIs. The sysroots are installed in the Azure Sphere SDK installation folder under Sysroots.

  15. Set the remote debugging target to IP address 192.168.35.2 on port 2345:

    target remote 192.168.35.2:2345

  16. Add a breakpoint at the function SendMessageToRTApp:

    break SendMessageToRTApp

  17. Type c to continue, observe the output in your Telnet/TCP terminal, then switch to the command prompt or terminal window containing your real-time application debugging session.

  18. Type c to continue and observe the output in your connected serial session.

You can work back and forth between debugging sessions, switching between the real-time capable application and the high-level application. You should see output similar to the following in the two output windows:

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

To end each debugging session, type q at the gdb prompt.