Debug a high-level application

  • Article

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

    Remote GDB Debugger button

  2. If you are prompted to build the project, select Yes. Visual Studio compiles the 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. You'll use the image ID later in Tutorial: Create a cloud deployment.

  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.

You can then 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. 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.

  2. Wait several seconds for Visual Studio Code to build the application, create an image package, deploy it to the board, and start it in debug mode. You'll see status updates in the Output pane along the way.

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

    Next, the Output pane shows the result as the image package is deployed to the device. Finally, the Debug Console receives focus and shows debugger 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.

To debug the application, stop it and then restart it with debugging:

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

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

You should see:

<ComponentID>
App state   : debugging
GDB port    : 2345
Output port : 2342
Core        : High-level
Command completed successfully in 00:00:00.9121174.

  1. Open a command prompt and use any Windows terminal client to establish a Telnet or raw TCP connection to read the output stream from the process. Specify 192.168.35.2 as the IP address and 2342 as the port.

  2. Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell. Start the gdb command-line debugger:

    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.

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

    target remote 192.168.35.2:2345

  4. Run any gdb commands you choose. For example:

    break main

    c

    The break and c commands set a breakpoint upon entry to main() and then continue execution after the breakpoint, respectively. Numerous sources of documentation are available for gdb.