Using Embedded Trace Macrocell (ETM) – KBA90952

Version: *A

 

Question: The PSoC® Creator™ DWR System Editor has an Embedded Trace (ETM) option. How do I use this feature?

 

Answer:

The ARM® Cortex™-M3 CPU in PSoC 5LP has the following blocks that enable several code execution tracing features:

  •   ETM (Embedded Trace Macrocell) – This is used for instruction tracing.
  •   DWT (Data Watchpoint and Trace) – This monitors and traces data reads and writes. It also detects read and write events to trigger instruction tracing on or off.
  •   ITM (Instrumentation Trace Macrocell) – This enables printf style debugging to trace events.
  •   TPIU (Trace Port Interface Unit) – This is the hardware interface for sending trace records.
  •   SWV (Single Wire Viewer) – This is the hardware interface for sending printf style debugging records.

Refer to www.arm.com for details on these blocks. You must set up each of them before you can do tracing.

PSoC Creator helps you to set up your PSoC 5LP device for tracing, but does not include support for capturing and analyzing the data.

To use the tracing features, you must export your PSoC Creator project to one of the following third-party IDEs:

Both debug and trace units have a 20-pin connector. If your target board has dual 10-pin connectors such as are on the Cypress PSoC 5LP kits (CY8CKIT-010 or CY8CKIT-050), then you must make an adapter using one of the schematics shown in Figure 1 and Figure 2:

Figure 1. Schematic for Keil ULINKpro Adaptor
Figure 2. Schematic for IAR I-jet Trace Adaptor

  IAR Trace adoptor

Setting up the Trace Port Interface Unit (TPIU)

The TPIU (also called Traceport) is a 5-pin interface with one clock and four data lines. The pins are available only on PSoC 5LP port pins P2[7:3]. To reserve and configure these pins for the TPIU, do the following:

  1.   Add a Pins Component to your design.
  2.   Configure this Component as five pins, each pin with the configuration shown in Figure 3 and Figure 4:  
        
    1.     Strong Drive Digital Output
    2.   
    3.     No HW Connection
         
           Figure 3. Setting Up a Pins Component for TPIU
          
         
         
           Figure 4. Configure Strong Drive for Pins Component
          
        
    4.  
  3.   In the project DWR window, Pins tab, connect the Component pins to physical port pins P2[7:3].

Note: Do NOT check the ETM box in the PSoC Creator DWR window, System tab. Checking the box reserves P2[7:3] and thus prevents the Pins Component pins from being assigned to those physical pins. This is OK if you want to manually configure the port pin registers, but configuring a Pins Component is easier and is the recommended method.

Note: The PSoC 5LP device datasheet specifies the TPIU and SWV pins’ maximum frequencies at 33 MHz. To keep the signals on these pins from exceeding the maximum frequencies, TRACECLK, one of the TPIU signals (pin P2[3]), is always bus clock / 4.

Setting up the Embedded Trace Macrocell (ETM)

To set up the ETM block, add the following two lines to your initialization code:

/* set up PSoC registers for tracing */CY_SET_REG8(CYDEV_MFGCFG_MLOGIC_DEBUG, 0x8); /* swv_clk_sel = CPU_clk / 2 */CY_SET_REG32(CYDEV_PANTHER_TRACE_CFG, 2); /* trace mode enable, SWV mode disable */

There is a third register, CYDEV_PANTHER_DEBUG_CFG, which controls (in bit 0) whether to stall the CPU when the ETM FIFO is full. You can leave it at its default value of 1 (stall the CPU). If you set the bit to 0, then the CPU is not stalled, leading to possibly losing some trace records.

Setting up the Instrumentation Trace Macrocell (ITM)

To set up the ITM block for printf-style debugging, redirect the outputs of printf() and putchar() to ITM port 0, by overriding the compiler library function fputc().

1. For Keil μVision only, add this code to your project:

#define ITM_Port8(n)  (*((volatile uint8  *)(0xE0000000+4*n)))#define ITM_Port16(n) (*((volatile uint16 *)(0xE0000000+4*n)))#define ITM_Port32(n) (*((volatile uint32 *)(0xE0000000+4*n)))#define DEMCR         (*((volatile uint32 *)(0xE000EDFC)))#define TRCENA        0x01000000 struct __FILE { int handle; }; FILE __stdout;/************************************************************************* * Function Name: fputc() ************************************************************************** * Summary: Overrides the fputc() library function to output to ITM port 0. * * Parameters: the character to be displayed *             a file handling structure (for stdout) * * Return: the input character. * *************************************************************************/int fputc(int ch, FILE *f) {     if (DEMCR & TRCENA) {         while (ITM_Port32(0) == 0);         ITM_Port8(0) = ch;     }     return ch; }

2. For IAR, there is no need to add redirect code to your project; IAR project options can be set up to do this for you. Select Project > Options > General Options > Library Configuration, and set the stdout/stderr to Via SWO, as Figure 5 shows:

Figure 5. Setting Up IAR for ITM / SWO

nodeD4

3. With IAR, you can do either tracing through ETM/Traceport, or printf-style debugging through ITM/SWV. If you choose the latter, then change the initialization code to:

/* set up PSoC registers for ITM printf-style debug */CY_SET_REG8(CYDEV_MFGCFG_MLOGIC_DEBUG, 0xC); /* swv_clk_sel = CPU_clk / 2, swv_clk enable */CY_SET_REG32(CYDEV_PANTHER_TRACE_CFG, 2); /* trace mode enable, SWV mode disable */

4. At strategic places in your code, add the printf() or putchar() statements. For example:

printf("count = %u\r\n", count); putchar('x'); /* made it to this point in the code */

Setting up Data Watchpoint and Trace (DWT)

You need to configure only TPIU pins in your PSoC Creator project for DWT setup. No other changes are required in the project.

Keil μVision Setup

  1.   In μVision, set up the Trace tab as Figure 6 shows. Make the following changes:  
        
    •     Set the Core Clock to match your PSoC Creator project’s master clock setting.
    •   
    •     Select Trace Enable and ETM Trace Enable.
    •   
    •     If you are using ITM, select ITM Stimulus Ports, 31 and 0.
    •  
     
       Figure 6. Cortex-M Target Driver Setup in μVision - Trace Tab
       ETM_Test
     

       The rest of the settings are optional depending on your application; see the μVision Help documentation for details.

  2.   When all the setups are complete, open the µVision Trace Data window.
  3.   Download your project to flash, start the debugger, and step through the code starting at main(). After the following line is executed, trace data appears in the Trace Data window.
      CY_SET_REG32(CYDEV_PANTHER_TRACE_CFG, 2); /* trace mode enable, SWV mode disable */
  4.   To see printf() debug events from the ITM, open the Debug (printf) Viewer window and run the code. The output of your printf() and putchar() statements appear in this window.

Refer to μVision Help for more information about the advanced features of the μVision trace and debug system.

IAR Embedded Workbench Setup

  1.   In IAR, select whether to do tracing through ETM, or printf-style debugging through ITM. Select menu item Project > Options > I-jet/JTAGjet > Traces > Mode, as Figure 7 shows.  

       Figure 7. Trace Setup in IAR Project Options

     

       IjetnodeD4

  2.   When project options setups are complete, download your project to flash, and start the debugger. Open the ETM Trace window or the Terminal I/O window, for tracing or printf-style debugging, respectively.
  3.   If you are using trace with ETM:  
        
    1.     Select menu item I-jet/JTAGjet > ETM Trace Settings… . Confirm that a trace clock frequency equal to CPU clock / 4 is displayed, as Figure 8 shows:    

           Figure 8. ETM Trace Settings in IAR

         

           ETM Trace settings

        
    2.   
    3.     Step through the code starting at main(). After the following line is executed, trace data appears in the Trace Data window.
          CY_SET_REG32(CYDEV_PANTHER_TRACE_CFG, 2); /* trace mode enable, SWV mode disable */
    4.  
  4.   If you are using printf-style debugging with ITM:  
        
    1.     Select menu item I-jet/JTAGjet > SWO Configuration… . Confirm that ITM Stimulus Port 0 is enabled and routed to the Terminal I/O window, as Figure 9 shows.    

           Figure 9. SWO Configuration in IAR

         

           SWO configuration

         

           The rest of the settings are optional depending on your application; see the IAR Help documentation for details.

        
    2.   
    3.     Run the code. Printf() and putchar() output appears in the Terminal I/O window.
    4.  

Refer to IAR Help for more information about the advanced features of the IAR trace and debug system.