Professional IDE debuggers provide great flexibility and multiple options for configuring debug of modern microcontrollers. But for software developers it is often challenging to correctly configure debug settings for their target system. Using debug description elements chip vendors can specify debug parameters applicable to a particular device and provide the default settings to be used by the debugger tool.

This chapter explains how to use the debug description elements.

Specify CPU debug connection

An important item that needs to be specified for an MCU is the debug connection to the CPU. For that debug element shall be used. This element is most commonly used in DFPs to specify the system view description file (.svd). But it also contains useful attributes to define the debug connection to the processor: __dp , __ap and Pname.

An example code below defines debug connection for a dual-core device with one debug port and 2 access ports: indexed as 0 for Cortex-M4 and 1 for Cortex-M0+.

<devices>
  <family Dfamily="LPC54114" Dvendor="NXP:11">    
    ...
    <device Dname="LPC54114J256">
      <processor Pname="CM0plus" Dcore="Cortex-M0+" Dfpu="NO_FPU" Dmpu="NO_MPU" Dendian="Little-endian" Dclock="100000000"/>
      <processor Pname="CM4" Dcore="Cortex-M4" Dfpu="SP_FPU" Dmpu="MPU" Dendian="Little-endian" Dclock="100000000"/>
      ...
      <debug svd="SVD/LPC54114_cm0plus.xml" Pname="CM0plus" __dp="0" __ap="1"/>
      <debug svd="SVD/LPC54114_cm4.xml" Pname="CM4" __dp="0" __ap="0"/>
          ...
    </device>
    ...
  </family>
</devices>

The same Pname identifier shall be used in debug element as defined in the corresponding processor element ('CM0plus' or 'CM4' in this example).

The numeric index values shall be typically specified for __dp attribute when multiple debug ports are available in the system and defined via debugport element. See Specify debug port for details about configuring debug ports.

For the __ap attribute the numeric index values shall be assigned based on the debug system implementation.

There's no need to specify all attributes in a single line at once, it can also be split over multiple assignments if it helps to better structure the sequences code. However the same Pname identifier shall be used. So the code below specifies the same debug connection for M4 processor as in the example above:

<debug Pname="CM4" svd="SVD/LPC54114_cm4.xml"/>
...
<debug Pname="CM4" __dp="0" __ap="0"/>
...

The attribute defaultResetSequence specifies the debug sequence that will be used by default to reset the device.

The debug IDE may also allow users to specify the reset type in the project options thus overwriting this default configuration. In multi-core systems Pname shall be used to ensure that the default reset sequence is set for a correct core.

Specify debug port

A microcontroller system can have one or more CoreSight debug ports with one or more supported debug protocols (for example JTAG and SWD). debugport element can be used to describe the debug ports capabilities.

For example if only Arm Serial Wire Debug (SWD) interface is supported, then debugport shall be defined only with swd child element and no jtag elements. The swd element is really simple and can only take an idcode attribute that needs to be explicitly provided when you want to override the value of the SWD debug port's DPIDR register that will be read from the device.

...
  <debugport __dp="0"/>
    <swd/>
  </debugport>
...

Vice versa is true as well, if only JTAG is supported then SWD shall not be listed in the debugport element.

The numeric value assinged to the __dp identifies the debug port and is for the user to choose. When describing JTAG chains it is recommended to use the tapindex as the __dp value to avoid confusion.

Debuggers can normally autodetect JTAG chains. But with some devices there is still a need to fully specify the JTAG chain to avoid potential detection issues by the debugger. Below is an example for the NXP IMX6 Solo X:

<debugport __dp="0">
  <jtag tapindex="0" idcode="0x4BA00477" irlen="4"/>
</debugport>
  
<debugport __dp="1">
  <jtag tapindex="1" idcode="0x4BA00477" irlen="4"/>
</debugport>
   
<debugport __dp="2">
  <jtag tapindex="2" idcode="0x00000000" irlen="4"/>
</debugport>
  
<debugport __dp="3">
  <jtag tapindex="3" idcode="0x0891C01D" irlen="5"/>
</debugport>
  
<debug Pname="Cortex-A9" __dp="1" __ap="0"/>
<debug Pname="Cortex-M4" __dp="0" __ap="0"/>

Even though only two debug ports are used to access the processor cores, the other debug ports available in the system are specified as well. In this case it is needed to provide debugger with correct irlen values thus allowing it to correctly scan the JTAG chain and access the processors.

The tapindex uniquely identifies the JTAG interface and typically its value is also used as the identifier for the debug port (__dp) index. Same as with the SWD the explicit specification of the idcode attribute is really necessary only when it needs to overwrite the IDCODe value read from the device. And irlen attribute may require explicit specification here if there're problems correctly obtaining its value from the device.

Default debugger configuration

To simplify the debugger configuration in an IDE the debugconfig element can be used to specify the default working debugger configuration that should be used as a starting point until the user explicitely makes project-specific changes.

For example the code below specifies SWD interface as default one with debug clock 5MHz. The debug port supports switching between SWD and JTAG debug protocols.

<devices>
  <family Dfamily="LPC54000 Series" Dvendor="NXP:11">
    <debugconfig default="swd" clock="5000000" swj="true"/>
    ...
  </family>
</devices>

Using debug it is also possible to specify the default reset type to be used. See Specify CPU debug connection for details.