Enabling debugging for unsupported boards

Many devices are natively supported by pyOCD, allowing you to flash and debug programs without further customization. Some devices require a CMSIS-Pack to interact with pyOCD. This section explains how to enable your device to flash and debug programs with a CMSIS-Pack in Mbed Studio.

For further information on CMSIS-Packs, see the CMSIS-Pack documentation.

Setting up a custom target in Mbed Studio to do debugging

Prerequisites

• By default, Arm Compiler 6 is used. You can alternatively use the Arm Embedded GCC Compiler. Make sure you have installed GCC and follow the steps described in Switching to GCC).

• Make sure your board is plugged in over USB. Mbed Studio should detect the board automatically and suggest a matching target. If the board is not detected, check that the firmware interface is working correctly. In order to do so, you can use the mbed-tools devices command from the terminal in Mbed Studio (go to Terminal > New Terminal). The devices command returns a list of connected devices. See the Mbed OS documentation for more details.

• Download a CMSIS-Pack for your device. The CMSIS-Packs available can be found on Arm Developer. Use the search functionality to find the correct CMSIS-Pack.

Setting up a custom target

Follow the steps described for Custom targets to set up a custom target for your device.

Make sure you do the following in the Manage Custom Targets dialog box:

• Select a USB-connected device in the USB device drop-down list.
• Type in a target name for your custom target in the Target name field.
• Select a build target (Build target drop-down list) and a debug target (Deploy and debug target drop-down list).
• In the Debug flags field, add the path to the CMSIS-Pack you've downloaded using --pack <Path to CMSIS-Pack>.

Once you've set up your custom target, you are ready to do debugging in Mbed Studio.

Testing if debugging works in Mbed Studio

Prerequisites

• Create a Blinky program in Mbed Studio (go to File > New Program... and select the mbed-os-example-blinky example program). If you are using a memory-constrained device, you may need to use the bare metal Blinky example instead of the full Blinky.

• Make sure your program can be compiled in Mbed Studio (Build program button, this will build the program without flashing it to the device).

• Make sure your program can be correctly deployed to your board (Run program button):

  • The build should start and complete without failure.
  • The compiled program should be correctly deployed to the board with a progress indicator.

Debugging

See Debugging with Mbed Studio to start debugging your program.

Beginning a debug session should build your program, reset your board and deploy the program.

A new pyOCD session should start with the Debug view displayed and some output in the Debug Console view.

Make sure that:

• There are no errors in the Debug Console view.
• You can set multiple breakpoints in the source code and the debugger stops when the breakpoints are hit.
• You can pause and restart the debugger.
• You can step over, into and out when navigating the code.
• Threads and their call stacks are correctly displayed in the Debug view when the debugger is paused.
• Variables are correctly displayed in the Debug view.

Once you've tested that Mbed Studio is able to debug your device, please consider making a request to add a new CMSIS-Pack for your device in the next release of Mbed Studio. You can do so by filling in the following form: Request to add support for Mbed Studio.

If debugging does not work as expected, you can try to flash and debug your program using the pyOCD command-line tool.

Enabling flashing and debugging using the pyOCD command-line tool

Flashing a program

If pyOCD doesn't natively support your device, it can still be used to flash a program if a CMSIS-Pack exists for the target you are using. When specifying to pyOCD which pack to use, you must also indicate the device_name for your device (pyOCD will look up for that device in the pack).

The device_name to use can be read from the targets.json file shipped with each Mbed OS program in the mbed-os/targets/ folder. In the example below, MK64FN1M0xxx12 is the device_name for the K64F board.

Look for "K64F" in the targets.json file:

  {
      "K64F": {
       ...
          "device_name": "MK64FN1M0xxx12",
      },
  }

Once you have determined the device_name for your device, pass its value to pyOCD using the --target parameter. You should also specify the path of the CMSIS-Pack you've downloaded.

From the terminal in Mbed Studio (go to Terminal > New Terminal), use the following command to flash your program to your device:

    pyocd flash --uid 0240123465489900 --target MK64FN1M0xxx12 --pack <Path to CMSIS-Pack> <Path to program>

Follow the steps below to enable debugging.

Debugging

From the terminal in Mbed Studio, use the following command to start a debug session:

  pyocd gdbserver --uid 0240123465489900 --erase=chip --port=4567 --target MK64FN1M0xxx12 --pack <Path to CMSIS-Pack>

Notes:

• If you are using a managed bootloader, replace --erase=chip by --erase=sector. See Creating and using a bootloader for more information.

• pyOCD emulates ST-Link for ST devices, which can be slow. It is therefore recommended to pass the following extra flags to pyOCD when interacting with ST devices:

      --frequency 1800000 -O connect_mode=under-reset
  

From the Debug Console view in Mbed Studio (go to View > Debug Console), run the following GDB command:

    gdb -q <Path to program .elf file>

Connect to the pyOCD remote port:

    gdb target remote localhost:4567

Download the program and symbol file:

    gdb load

Continue to debug using GDB commands (stepping through the code, reading registers and memory to confirm that debugging works correctly). For more details about all of the GDB commands you can use, see the GDB Command Reference.