summaryrefslogtreecommitdiff
path: root/Libraries/CMSIS/CMSIS debug support.htm
blob: efda685be6666d01c97e541d252ec53de4d0c33a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
<html>

<head>
<title>CMSIS Debug Support</title>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 6.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<style>
<!--
/*-----------------------------------------------------------
Keil Software CHM Style Sheet
-----------------------------------------------------------*/
body         { color: #000000; background-color: #FFFFFF; font-size: 75%; font-family: 
               Verdana, Arial, 'Sans Serif' }
a:link       { color: #0000FF; text-decoration: underline }
a:visited    { color: #0000FF; text-decoration: underline }
a:active     { color: #FF0000; text-decoration: underline }
a:hover      { color: #FF0000; text-decoration: underline }
h1           { font-family: Verdana; font-size: 18pt; color: #000080; font-weight: bold; 
               text-align: Center; margin-right: 3 }
h2           { font-family: Verdana; font-size: 14pt; color: #000080; font-weight: bold; 
               background-color: #CCCCCC; margin-top: 24; margin-bottom: 3; 
               padding: 6 }
h3           { font-family: Verdana; font-size: 10pt; font-weight: bold; background-color: 
               #CCCCCC; margin-top: 24; margin-bottom: 3; padding: 6 }
pre          { font-family: Courier New; font-size: 10pt; background-color: #CCFFCC; 
               margin-left: 24; margin-right: 24 }
ul           { list-style-type: square; margin-top: 6pt; margin-bottom: 0 }
ol           { margin-top: 6pt; margin-bottom: 0 }
li           { clear: both; margin-bottom: 6pt }
table        { font-size: 100%; border-width: 0; padding: 0 }
th           { color: #FFFFFF; background-color: #000080; text-align: left; vertical-align: 
               bottom; padding-right: 6pt }
tr           { text-align: left; vertical-align: top }
td           { text-align: left; vertical-align: top; padding-right: 6pt }
.ToolT       { font-size: 8pt; color: #808080 }
.TinyT       { font-size: 8pt; text-align: Center }
code         { color: #000000; background-color: #E0E0E0; font-family: 'Courier New', Courier; 
               line-height: 120%; font-style: normal }
/*-----------------------------------------------------------
Notes
-----------------------------------------------------------*/
p.note       { font-weight: bold; clear: both; margin-bottom: 3pt; padding-top: 6pt }
/*-----------------------------------------------------------
Expanding/Contracting Divisions
-----------------------------------------------------------*/
#expand      { text-decoration: none; margin-bottom: 3pt }
img.expand   { border-style: none; border-width: medium }
div.expand   { display: none; margin-left: 9pt; margin-top: 0 }
/*-----------------------------------------------------------
Where List Tags
-----------------------------------------------------------*/
p.wh         { font-weight: bold; clear: both; margin-top: 6pt; margin-bottom: 3pt }
table.wh     { width: 100% }
td.whItem    { white-space: nowrap; font-style: italic; padding-right: 6pt; padding-bottom: 
               6pt }
td.whDesc    { padding-bottom: 6pt }
/*-----------------------------------------------------------
Keil Table Tags
-----------------------------------------------------------*/
table.kt     { border: 1pt solid #000000 }
th.kt        { white-space: nowrap; border-bottom: 1pt solid #000000; padding-left: 6pt; 
               padding-right: 6pt; padding-top: 4pt; padding-bottom: 4pt }
tr.kt        {  }
td.kt        { color: #000000; background-color: #E0E0E0; border-top: 1pt solid #A0A0A0; 
               padding-left: 6pt; padding-right: 6pt; padding-top: 2pt; 
               padding-bottom: 2pt }
/*-----------------------------------------------------------
-----------------------------------------------------------*/
-->

</style>
</head>

<body>

<h1>CMSIS Debug Support</h1>

<hr>

<h2>Cortex-M3 ITM Debug Access</h2>
<p>
  The Cortex-M3 incorporates the Instrumented Trace Macrocell (ITM) that provides together with 
  the Serial Viewer Output trace capabilities for the microcontroller system. The ITM has 
  32 communication channels which are able to transmit 32 / 16 / 8 bit values; two ITM 
  communication channels are used by CMSIS to output the following information:
</p>
<ul>
	<li>ITM Channel 0: used for printf-style output via the debug interface.</li>
	<li>ITM Channel 31: is reserved for RTOS kernel awareness debugging.</li>
</ul>

<h2>Debug IN / OUT functions</h2>
<p>CMSIS provides following debug functions:</p>
<ul>
	<li>ITM_SendChar (uses ITM channel 0)</li>
	<li>ITM_ReceiveChar (uses global variable)</li>
	<li>ITM_CheckChar (uses global variable)</li>
</ul>

<h3>ITM_SendChar</h3>
<p>
  <strong>ITM_SendChar</strong> is used to transmit a character over ITM channel 0 from 
  the microcontroller system to the debug system. <br>
  Only a 8 bit value is transmitted.
</p>
<pre>
static __INLINE uint32_t ITM_SendChar (uint32_t ch)
{
  /* check if debugger connected and ITM channel enabled for tracing */
  if ((CoreDebug->DEMCR & CoreDebug_DEMCR_TRCENA)  &amp;&amp;
      (ITM-&gt;TCR & ITM_TCR_ITMENA)                  &amp;&amp;
      (ITM-&gt;TER & (1UL &lt;&lt; 0))  ) 
  {
    while (ITM-&gt;PORT[0].u32 == 0);
    ITM-&gt;PORT[0].u8 = (uint8_t)ch;
  }  
  return (ch);
}</pre>

<h3>ITM_ReceiveChar</h3>
<p>
  ITM communication channel is only capable for OUT direction. For IN direction
  a globel variable is used. A simple mechansim detects if a character is received.
  The project to test need to be build with debug information.
</p>

<p>
  The globale variable <strong>ITM_RxBuffer</strong> is used to transmit a 8 bit value from debug system
  to microcontroller system. <strong>ITM_RxBuffer</strong> is 32 bit wide to enshure a proper handshake.
</p>
<pre>
extern volatile int ITM_RxBuffer;                    /* variable to receive characters                             */
</pre>
<p>
  A dedicated bit pattern is used to determin if <strong>ITM_RxBuffer</strong> is empty
  or contains a valid value.
</p>
<pre>
#define             ITM_RXBUFFER_EMPTY    0x5AA55AA5 /* value identifying ITM_RxBuffer is ready for next character */
</pre>
<p>
  <strong>ITM_ReceiveChar</strong> is used to receive a 8 bit value from the debug system. The function is nonblocking.
  It returns the received character or '-1' if no character was available.
</p>
<pre>
static __INLINE int ITM_ReceiveChar (void) {
  int ch = -1;                               /* no character available */

  if (ITM_RxBuffer != ITM_RXBUFFER_EMPTY) {
    ch = ITM_RxBuffer;
    ITM_RxBuffer = ITM_RXBUFFER_EMPTY;       /* ready for next character */
  }
  
  return (ch); 
}
</pre>

<h3>ITM_CheckChar</h3>
<p>
  <strong>ITM_CheckChar</strong> is used to check if a character is received.
</p>
<pre>
static __INLINE int ITM_CheckChar (void) {

  if (ITM_RxBuffer == ITM_RXBUFFER_EMPTY) {
    return (0);                                 /* no character available */
  } else {
    return (1);                                 /*    character available */
  }
}</pre>


<h2>ITM Debug Support in uVision</h2>
<p>
  uVision uses in a debug session the <strong>Debug (printf) Viewer</strong> window to 
  display the debug data.
</p>
<p>Direction microcontroller system -&gt; uVision:</p>
<ul>
  <li>
    Characters received via ITM communication channel 0 are written in a printf style
    to <strong>Debug (printf) Viewer</strong> window.
  </li>
</ul>

<p>Direction uVision -&gt; microcontroller system:</p>
<ul>
  <li>Check if <strong>ITM_RxBuffer</strong> variable is available (only performed once).</li>
  <li>Read character from <strong>Debug (printf) Viewer</strong> window.</li>
  <li>If <strong>ITM_RxBuffer</strong> empty write character to <strong>ITM_RxBuffer</strong>.</li>
</ul>

<p class="Note">Note</p>
<ul>
  <li><p>Current solution does not use a buffer machanism for trasmitting the characters.</p>
  </li>
</ul>

<h2>RTX Kernel awareness in uVision</h2>
<p>
  uVision / RTX are using a simple and efficient solution for RTX Kernel awareness.
  No format overhead is necessary.<br>
  uVsion debugger decodes the RTX events via the 32 / 16 / 8 bit ITM write access
  to ITM communication channel 31.
</p>

<p>Following RTX events are traced:</p>
<ul>
  <li>Task Create / Delete event
    <ol>
      <li>32 bit access. Task start address is transmitted</li>
      <li>16 bit access. Task ID and Create/Delete flag are transmitted<br>
          High byte holds Create/Delete flag, Low byte holds TASK ID.
      </li>
    </ol>
  </li>
  <li>Task switch event
    <ol>
      <li>8 bit access. Task ID of current task is transmitted</li>
    </ol>
  </li>
</ul>

<p class="Note">Note</p>
<ul>
  <li><p>Other RTOS information could be retrieved via memory read access in a polling mode manner.</p>
  </li>
</ul>


<p class="MsoNormal"><span lang="EN-GB">&nbsp;</span></p>

<hr>

<p class="TinyT">Copyright © KEIL - An ARM Company.<br>
All rights reserved.<br>
Visit our web site at <a href="http://www.keil.com">www.keil.com</a>.
</p>

</body>

</html>