git.rot13.org Git - DSO138/blob - Libraries/CMSIS/CMSIS debug support.htm

   1 <html>\r
   2 \r
   3 <head>\r
   4 <title>CMSIS Debug Support</title>\r
   5 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">\r
   6 <meta name="GENERATOR" content="Microsoft FrontPage 6.0">\r
   7 <meta name="ProgId" content="FrontPage.Editor.Document">\r
   8 <style>\r
   9 <!--\r
  10 /*-----------------------------------------------------------\r
  11 Keil Software CHM Style Sheet\r
  12 -----------------------------------------------------------*/\r
  13 body         { color: #000000; background-color: #FFFFFF; font-size: 75%; font-family: \r
  14                Verdana, Arial, 'Sans Serif' }\r
  15 a:link       { color: #0000FF; text-decoration: underline }\r
  16 a:visited    { color: #0000FF; text-decoration: underline }\r
  17 a:active     { color: #FF0000; text-decoration: underline }\r
  18 a:hover      { color: #FF0000; text-decoration: underline }\r
  19 h1           { font-family: Verdana; font-size: 18pt; color: #000080; font-weight: bold; \r
  20                text-align: Center; margin-right: 3 }\r
  21 h2           { font-family: Verdana; font-size: 14pt; color: #000080; font-weight: bold; \r
  22                background-color: #CCCCCC; margin-top: 24; margin-bottom: 3; \r
  23                padding: 6 }\r
  24 h3           { font-family: Verdana; font-size: 10pt; font-weight: bold; background-color: \r
  25                #CCCCCC; margin-top: 24; margin-bottom: 3; padding: 6 }\r
  26 pre          { font-family: Courier New; font-size: 10pt; background-color: #CCFFCC; \r
  27                margin-left: 24; margin-right: 24 }\r
  28 ul           { list-style-type: square; margin-top: 6pt; margin-bottom: 0 }\r
  29 ol           { margin-top: 6pt; margin-bottom: 0 }\r
  30 li           { clear: both; margin-bottom: 6pt }\r
  31 table        { font-size: 100%; border-width: 0; padding: 0 }\r
  32 th           { color: #FFFFFF; background-color: #000080; text-align: left; vertical-align: \r
  33                bottom; padding-right: 6pt }\r
  34 tr           { text-align: left; vertical-align: top }\r
  35 td           { text-align: left; vertical-align: top; padding-right: 6pt }\r
  36 .ToolT       { font-size: 8pt; color: #808080 }\r
  37 .TinyT       { font-size: 8pt; text-align: Center }\r
  38 code         { color: #000000; background-color: #E0E0E0; font-family: 'Courier New', Courier; \r
  39                line-height: 120%; font-style: normal }\r
  40 /*-----------------------------------------------------------\r
  41 Notes\r
  42 -----------------------------------------------------------*/\r
  43 p.note       { font-weight: bold; clear: both; margin-bottom: 3pt; padding-top: 6pt }\r
  44 /*-----------------------------------------------------------\r
  45 Expanding/Contracting Divisions\r
  46 -----------------------------------------------------------*/\r
  47 #expand      { text-decoration: none; margin-bottom: 3pt }\r
  48 img.expand   { border-style: none; border-width: medium }\r
  49 div.expand   { display: none; margin-left: 9pt; margin-top: 0 }\r
  50 /*-----------------------------------------------------------\r
  51 Where List Tags\r
  52 -----------------------------------------------------------*/\r
  53 p.wh         { font-weight: bold; clear: both; margin-top: 6pt; margin-bottom: 3pt }\r
  54 table.wh     { width: 100% }\r
  55 td.whItem    { white-space: nowrap; font-style: italic; padding-right: 6pt; padding-bottom: \r
  56                6pt }\r
  57 td.whDesc    { padding-bottom: 6pt }\r
  58 /*-----------------------------------------------------------\r
  59 Keil Table Tags\r
  60 -----------------------------------------------------------*/\r
  61 table.kt     { border: 1pt solid #000000 }\r
  62 th.kt        { white-space: nowrap; border-bottom: 1pt solid #000000; padding-left: 6pt; \r
  63                padding-right: 6pt; padding-top: 4pt; padding-bottom: 4pt }\r
  64 tr.kt        {  }\r
  65 td.kt        { color: #000000; background-color: #E0E0E0; border-top: 1pt solid #A0A0A0; \r
  66                padding-left: 6pt; padding-right: 6pt; padding-top: 2pt; \r
  67                padding-bottom: 2pt }\r
  68 /*-----------------------------------------------------------\r
  69 -----------------------------------------------------------*/\r
  70 -->\r
  71 \r
  72 </style>\r
  73 </head>\r
  74 \r
  75 <body>\r
  76 \r
  77 <h1>CMSIS Debug Support</h1>\r
  78 \r
  79 <hr>\r
  80 \r
  81 <h2>Cortex-M3 ITM Debug Access</h2>\r
  82 <p>\r
  83   The Cortex-M3 incorporates the Instrumented Trace Macrocell (ITM) that provides together with \r
  84   the Serial Viewer Output trace capabilities for the microcontroller system. The ITM has \r
  85   32 communication channels which are able to transmit 32 / 16 / 8 bit values; two ITM \r
  86   communication channels are used by CMSIS to output the following information:\r
  87 </p>\r
  88 <ul>\r
  89         <li>ITM Channel 0: used for printf-style output via the debug interface.</li>\r
  90         <li>ITM Channel 31: is reserved for RTOS kernel awareness debugging.</li>\r
  91 </ul>\r
  92 \r
  93 <h2>Debug IN / OUT functions</h2>\r
  94 <p>CMSIS provides following debug functions:</p>\r
  95 <ul>\r
  96         <li>ITM_SendChar (uses ITM channel 0)</li>\r
  97         <li>ITM_ReceiveChar (uses global variable)</li>\r
  98         <li>ITM_CheckChar (uses global variable)</li>\r
  99 </ul>\r
 100 \r
 101 <h3>ITM_SendChar</h3>\r
 102 <p>\r
 103   <strong>ITM_SendChar</strong> is used to transmit a character over ITM channel 0 from \r
 104   the microcontroller system to the debug system. <br>\r
 105   Only a 8 bit value is transmitted.\r
 106 </p>\r
 107 <pre>\r
 108 static __INLINE uint32_t ITM_SendChar (uint32_t ch)\r
 109 {\r
 110   /* check if debugger connected and ITM channel enabled for tracing */\r
 111   if ((CoreDebug->DEMCR & CoreDebug_DEMCR_TRCENA)  &amp;&amp;\r
 112       (ITM-&gt;TCR & ITM_TCR_ITMENA)                  &amp;&amp;\r
 113       (ITM-&gt;TER & (1UL &lt;&lt; 0))  ) \r
 114   {\r
 115     while (ITM-&gt;PORT[0].u32 == 0);\r
 116     ITM-&gt;PORT[0].u8 = (uint8_t)ch;\r
 117   }  \r
 118   return (ch);\r
 119 }</pre>\r
 120 \r
 121 <h3>ITM_ReceiveChar</h3>\r
 122 <p>\r
 123   ITM communication channel is only capable for OUT direction. For IN direction\r
 124   a globel variable is used. A simple mechansim detects if a character is received.\r
 125   The project to test need to be build with debug information.\r
 126 </p>\r
 127 \r
 128 <p>\r
 129   The globale variable <strong>ITM_RxBuffer</strong> is used to transmit a 8 bit value from debug system\r
 130   to microcontroller system. <strong>ITM_RxBuffer</strong> is 32 bit wide to enshure a proper handshake.\r
 131 </p>\r
 132 <pre>\r
 133 extern volatile int ITM_RxBuffer;                    /* variable to receive characters                             */\r
 134 </pre>\r
 135 <p>\r
 136   A dedicated bit pattern is used to determin if <strong>ITM_RxBuffer</strong> is empty\r
 137   or contains a valid value.\r
 138 </p>\r
 139 <pre>\r
 140 #define             ITM_RXBUFFER_EMPTY    0x5AA55AA5 /* value identifying ITM_RxBuffer is ready for next character */\r
 141 </pre>\r
 142 <p>\r
 143   <strong>ITM_ReceiveChar</strong> is used to receive a 8 bit value from the debug system. The function is nonblocking.\r
 144   It returns the received character or '-1' if no character was available.\r
 145 </p>\r
 146 <pre>\r
 147 static __INLINE int ITM_ReceiveChar (void) {\r
 148   int ch = -1;                               /* no character available */\r
 149 \r
 150   if (ITM_RxBuffer != ITM_RXBUFFER_EMPTY) {\r
 151     ch = ITM_RxBuffer;\r
 152     ITM_RxBuffer = ITM_RXBUFFER_EMPTY;       /* ready for next character */\r
 153   }\r
 154   \r
 155   return (ch); \r
 156 }\r
 157 </pre>\r
 158 \r
 159 <h3>ITM_CheckChar</h3>\r
 160 <p>\r
 161   <strong>ITM_CheckChar</strong> is used to check if a character is received.\r
 162 </p>\r
 163 <pre>\r
 164 static __INLINE int ITM_CheckChar (void) {\r
 165 \r
 166   if (ITM_RxBuffer == ITM_RXBUFFER_EMPTY) {\r
 167     return (0);                                 /* no character available */\r
 168   } else {\r
 169     return (1);                                 /*    character available */\r
 170   }\r
 171 }</pre>\r
 172 \r
 173 \r
 174 <h2>ITM Debug Support in uVision</h2>\r
 175 <p>\r
 176   uVision uses in a debug session the <strong>Debug (printf) Viewer</strong> window to \r
 177   display the debug data.\r
 178 </p>\r
 179 <p>Direction microcontroller system -&gt; uVision:</p>\r
 180 <ul>\r
 181   <li>\r
 182     Characters received via ITM communication channel 0 are written in a printf style\r
 183     to <strong>Debug (printf) Viewer</strong> window.\r
 184   </li>\r
 185 </ul>\r
 186 \r
 187 <p>Direction uVision -&gt; microcontroller system:</p>\r
 188 <ul>\r
 189   <li>Check if <strong>ITM_RxBuffer</strong> variable is available (only performed once).</li>\r
 190   <li>Read character from <strong>Debug (printf) Viewer</strong> window.</li>\r
 191   <li>If <strong>ITM_RxBuffer</strong> empty write character to <strong>ITM_RxBuffer</strong>.</li>\r
 192 </ul>\r
 193 \r
 194 <p class="Note">Note</p>\r
 195 <ul>\r
 196   <li><p>Current solution does not use a buffer machanism for trasmitting the characters.</p>\r
 197   </li>\r
 198 </ul>\r
 199 \r
 200 <h2>RTX Kernel awareness in uVision</h2>\r
 201 <p>\r
 202   uVision / RTX are using a simple and efficient solution for RTX Kernel awareness.\r
 203   No format overhead is necessary.<br>\r
 204   uVsion debugger decodes the RTX events via the 32 / 16 / 8 bit ITM write access\r
 205   to ITM communication channel 31.\r
 206 </p>\r
 207 \r
 208 <p>Following RTX events are traced:</p>\r
 209 <ul>\r
 210   <li>Task Create / Delete event\r
 211     <ol>\r
 212       <li>32 bit access. Task start address is transmitted</li>\r
 213       <li>16 bit access. Task ID and Create/Delete flag are transmitted<br>\r
 214           High byte holds Create/Delete flag, Low byte holds TASK ID.\r
 215       </li>\r
 216     </ol>\r
 217   </li>\r
 218   <li>Task switch event\r
 219     <ol>\r
 220       <li>8 bit access. Task ID of current task is transmitted</li>\r
 221     </ol>\r
 222   </li>\r
 223 </ul>\r
 224 \r
 225 <p class="Note">Note</p>\r
 226 <ul>\r
 227   <li><p>Other RTOS information could be retrieved via memory read access in a polling mode manner.</p>\r
 228   </li>\r
 229 </ul>\r
 230 \r
 231 \r
 232 <p class="MsoNormal"><span lang="EN-GB">&nbsp;</span></p>\r
 233 \r
 234 <hr>\r
 235 \r
 236 <p class="TinyT">Copyright © KEIL - An ARM Company.<br>\r
 237 All rights reserved.<br>\r
 238 Visit our web site at <a href="http://www.keil.com">www.keil.com</a>.\r
 239 </p>\r
 240 \r
 241 </body>\r
 242 \r
 243 </html>