Debug a real-time capable application

  • Article

RTApps are debugged using OpenOCD, which is installed with the Azure Sphere SDK, and the version of GDB that is installed as part of the ARM GNU Embedded Toolchain.

Debug RTApp with Visual Studio

  1. Ensure that your device is connected to your PC by USB. In the Set startup item menu, select Azure Sphere App (RT Core) where Azure Sphere App is the name of your current real-time capable application or press F5.

    Remote GDB Debugger button

  2. If you are prompted to build the project, select Yes. Visual Studio compiles the real-time capable application, creates an image package, sideloads it onto the board, and starts it in debug mode. Sideloading means that the application is delivered directly from the PC over a wired connection, rather than delivered through the cloud.

    Note the image ID of the image package in the View > Output > Show output from: Build output When you are ready to create a deployment, you will need to know the path to the image package.

  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.

Visual Studio sets up connections between the GDB server and OpenOCD so that you can use the standard Visual Studio debugging interface (F5, F6, F9 for breakpoints and so forth) on an RTApp, in the same way as on a high-level app.

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.

Debug RTApp with Visual Studio Code

Visual Studio Code is debugged by pressing F5 or running the debug command from the debug view on the left bar. In the samples, the .vscode/launch.json already exists, so debugging will start immediately. In a new app, debugging will first ask whether this is an HLApp or RTApp, and create a .vscode/launch.json from your answer. Debugging will then be enabled.

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.

Debug RTApp using the CLI

  1. Start the application for debugging:

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

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

  2. Navigate to the Openocd folder for the sysroot that the application was built with. In this Quickstart, the sysroot is 5+Beta2004. 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\5+Beta2004\tools\openocd and on Linux, at /opt/azurespheresdk/Sysroots/5+Beta2004/tools/sysroots/x86_64-pokysdk-linux/usr/bin/openocd.

  3. 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"

  4. Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell.

  5. Navigate to the folder that contains the application .out file and start arm-none-eabi-gdb, which is part of the ARM GNU 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

  6. The OpenOCD server provides a GDB server interface on :4444. Set the target for debugging.

    target remote :4444

  7. Run any gdb commands you choose.

Develop with partner apps

When you load an application onto the Azure Sphere device, the Azure Sphere deployment tools by default delete all existing applications. To prevent this from happening when you develop applications that communicate with each other, you need to mark the applications as partners. When you deploy one of the applications, its partners will not be deleted. See Mark applications as partners for details.

Troubleshooting

If you encounter problems, see Troubleshooting real-time capable applications.