Cortex M3 ITM Support for Concerto F28M35x

From Texas Instruments Wiki
Jump to: navigation, search

Summary

  • ITM stands for Instrumentation Trace Macrocell. It is developed by ARM Ltd. Please read Cortex M3 Technical Reference Manual for all the details.
  • ITM supports 2 types of data. Instrumentation data (software) and Data Watchpoint and Trace (DWT) data (hardware).
  • All the tooling supported is integrated in Code Composer Studio (CCS) 5.1 or later.
    • The user can write data to ITM stimulus port registers (up to 32 of them) and the data will be transmitted through the pins and collected by emulator. After all the data is captured the decoder will analyze and display the results in the CCS trace display. SDO's ITM decoder that comes with CCS has defined stimulus port 0 as a dedicated ASCII character channel and the other 31 ports as binary channels. This means the decoder interprets data sent to stimulus port 0 as ASCII character character data. The other 32 stimulus ports will be interpreted by the decoder as binary data only. A sample demo program is included here.
    • The user can configure and enable different types of DWT data\events in CCS's breakpoint manager. The DWT counter\event data will be transmitted through the pins and collected by the emulator. After the data is collected, it is analyzed by ITM decoder and results are shown in the CCS trace analyzer view. The ITM decoder can handle mix of instrumentation data and DWT data.

Hardware requirements

  • Emulator and Trace Receiver
  • JTAG Connector
    • It is recommended to put a TI-20 pin connector on the evaluation board. EMU0 to EMU4 signals should be connected to the TI-20 pin connector. In this configuration, 1 pin is used as clock pin and the other 4 pins are used as data pins. In general, ITM clock is configured to be running at 10MHz (default clock speed). In additional, data is transmitted at both edge of clock. As the result, the total bandwidth is 10Mhz X 2(double data rate) X 4(pins) = 10Mbytes/s
    • The minimum requirement is to have a TI-14 pin connector on board. EMU0 and EMU1 signals should be hooked up. In this configuration, 1 pin is used as clock pin and the other one is used as data pin. The total bandwidth will be a quarter of 4 data pins scenario listed above. Thus, assuming clock is running at 10Mhz, the total bandwidth in 1 pin configuration is 2.5MBytes\s
Note:
There are 20-to-14 pin adapters available (see Spectrum Digital website). A solution may be to populate the the most flexible solution on the board (with more signals available) in case you want to use trace capabilities. Then use the adapter to provide lower cost:
The idea is:
  • Use the 20-to-14 pin adapter and an XDS100v2 for most developers (low cost). The XDS100v2 is a 14 pin emulator.
  • Use the XDS560v2 for some specific cases where trace will be of use.

GEL Function

Note: This function is now included in the gel files supplied by TI.

An additional gel file ITM_PinEnable.gel needs to be loaded to Cortex M3. Execute EnablePinForITMTrace() gel function to configure GPIO pins to be used by ITM tracing.

How to collect ITM in CCSv5.1

Please be sure the proper hardware equipment is connected to the board. Also, that the specified CCS version is installed.

Setup and collect ITM Instrumentation data

  • Launch F28M35H52C1 target configuration file in CCS.
  • Connect to Cortex M3.
  • Execute Gel functions to setup board. In addition, execute EnablePinForITMTrace() in ITM_PinEnable.gel to setup GPIO pins for ITM.
  • Load the application to Cortex M3. Because ITM Instrumentation data can only be generated by application running on the target, a target application is expected.
  • Select Tools->Trace Control to bring up "Trace System Control" window. Make sure Cortex M3 tab is selected.
  • Click Receiver button to bring up "Select Receiver" window and then select 560 V2 Trace as receiver. Click on OK button to exit from the window.
  • The "Trace System Control" window now has been updated with additional fields:
    • Select 4 pin as Port width if the board has a TI-20 pin header. Select 1 pin as Port width if the board has a TI-14 pin header.
    • It is recommended to use 4MB or 8MB as buffer size. The 560 v2 supports up to 64MB of memory buffer. However, the larger the buffer size, the longer it takes to complete decoding. Typically, 4MB of data will take about 15s to complete decoding; while16MB of data takes minutes to finish decoding.
    • It is recommended to select Circular buffer mode. In this mode, when incoming data exceeds predefined buffer size, older data will be erased to make room for newer data. This mode is best suited if user is interested in the latest data. In the other hand, if user in more interested in the initial trace data, then selecting Stop-on-full mode may be more suitable. In this mode, receiver will automatically stop capturing incoming trace data once its buffer is full.
    • It is recommended to enable "Synchronize with target" option. When this option is enabled, when target(Cortex M3) starts to run, the receiver is automatically activated to receive ITM data. When target then is halted, the receiver automatically stops capturing ITM data and then processes data. When this option is disabled, it is user's responsibility to start/stop capturing trace data by clicking on the start/stop button in Trace display.
  • After selecting all the options in "Trace System Control" window, click on "OK" button to apply the changes.
  • If Trace Display does not automatically come up, go to Tools->TraceAnalyzer->Open Trace Connection In New View->CortexM3 to bring up Trace Display tool. The ITM decoded data will be shown in this tool.
  • At this point, setup process is completed. User can run the application, which will write to ITM stimulus ports to generate ITM instrumentation message. After either halting the target or clicking on stop button in Trace Display, ITM data will be shown.



  • Please find the ITM Instrumentation demo code from this zip file ITM Instrumentation Demo.
    • In This demo file, ITM_put_string() is to transfer ASCII buffer to stimulus port0 only, which is dedicated as a ASCII port. Also, because stimulus port is 4 bytes, the LSB of string is placed as the MSB in 4 bytes data packet.
    • When a new line character is detected by decoder, the characters before the new line character will be displayed in one line and all characters after the line feed character will then be displayed in a new line.All message has to be terminated by a new line character (\n)
    • ITM_put_32() is to transfer a binary data as a 32 bit value word.
    • ITM_put_16() is to transfer a binary data as a 16 bit value short.
    • ITM_put_8() is to transfer a binary data as a 8 bit value byte.
    • The port number for all above 3 functions should not be port 0.

Setup and collect DWT Instrumentation data

  • The initial setup steps for collecting DWT data are identical to those steps mentioned in "Setup and collect ITM Instrumentation data" section. Please follow those steps to initialize ITM modules and emulator.
  • After finishing setup in Trace System Control window, the next step is to configure DWT module in breakpoint manager so that it will generate DWT data.
  • Launch Breakpoint manager by going to View->Breakpoints in CCS. In Breakpoints tab, select the down arrow on the right of three circles to bring up breakpoint menus and select "Trace DWT Event" from the menu.
  • Right click on the newly created item in breakpoints window and select "Breakpoint Properties...".
  • Expand the Type field under Hardware Configuration to see all the available selection for DWT data. The detail description of each type can be found in ARMv7-M Architecture Reference Manual, Data Watchpoint and Trace(DWT) support section.
  • After configuring DWT events, click on OK to exit property window. Make sure to enable to DWT configuration by checking the box in front of the entry in breakpoints manager window.
  • At this point, additional steps to configure DWT is completely. User can run an application to generate DWT data and then stop the recording to view data from Trace Display.

Screen shot

The following is a screen shot of a DWT configuration. The results are shown in the Trace Display window. This example contains both software instrumentation message (indicated in Domain column as "SW") and DWT message (indicated in Domain column as "DWT").


ITM SW DWT Results.jpg

FAQ

  • I cannot view TPIU and ITM registers in 0xE0040000 region and 0xE0000000 region from Cortex M3' memory view in CCS. Why?

Ans: It is most likely that those memory region is not defined as valid memory in CCS's memory map setting. Please modify the device gel file to use GEL_MapAddStr function to add 0xE0040000(size of 0x1000) and 0xE0000000 (size of 0xF000) with R/W privilege.

  • I do not see any Instrumentation message shown in Trace Display event though I am pretty sure I have done everything according the instruments. Why?

Ans: Please check the ITM Trace Control register (0xE0000E80 from Cortex M3 memory window). Please make sure ITMENA bit is set. In addition, TraceBusID have to be 0x1. Our decoder only recognized TraceBusID value of 1 for ITM data.

  • I see an message in Trace Status Column stating ITM_OVERFLOW occurred, what happened and how I can avoid overflow?

Ans: As mentioned in Hardware Requirements section, the ITM transmits data out to pins at the rate of between 2.5MBytes\s to 10MBytes\s. However, specially in the case of DWT message, the message is generated at a faster rate than ITM can transmit them out through pins. When overflow occurred, there are some ITM messages are dropped. The solution is either to increase output bandwidth (by increase the number of trace pins or increase output clock), or reduce DWT event generating rate.