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 import xdc.runtime.Diags;
38 import xdc.runtime.Types;
39 import ti.uia.events.DvtTypes;
40
41 /*!
42 * UIA Profile Events
43 *
44 * The UIAProfile module defines events that allow
45 * tooling to analyze the performance of the software
46 * (processing time, latency, etc.). These events are
47 * designed to be logged from function-entry and function-exit
48 * hook functions that are called by compiler-generated code
49 *
50 * TI compilers can be configured to either pass in a parameter
51 * to the hook functions containing either the address
52 * of the function or the name of the function.
53 *
54 * If the compiler is configured to pass in the address of the function,
55 * the `UIAProfile_enterFunctionAdrs` event should be logged by the
56 * entry hook function and the `UIAProfile_exitFunctionAdrs` event
57 * should be logged by the exit hook function.
58 *
59 * If the compiler is configured to pass in the name of the function,
60 * the `UIAProfile_enterFunctionName` event should be logged by the
61 * entry hook function and the `UIAProfile_exitFunctionName` event
62 * should be logged by the exit hook function.
63 *
64 * When logging events using the xdc.runtime.Log module, the generation
65 * of UIAProfile events is controlled by the `Diags.ENTRY` and `Diags.EXIT`
66 * flags in a module's diagnostics mask. (For more information on
67 * diagnostics masks, please see the xdc.runtime.Diags documentation.)
68 *
69 * By default, the UIAProfile module will automatically set both the
70 * `Main.common$.Diags_ENTRY` and `Main.common$.Diags_EXIT` flags to
71 * `Diags.ALWAYS_ON` if these flags have not been previously configured.
72 * To turn off these flags at configuration time, set
73 * `UIAProfile.enable = false;` To allow these flags to be configured
74 * at run time, set `UIAProfile.runtimeControl = true;`
75 *
76 * @a(Examples)
77 * Example 1: This is part of the XDC configuration file for the application:
78 *
79 * @p(code)
80 * var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
81 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
82 * @p
83 *
84 * @p(html)
85 * <hr />
86 * @p
87 *
88 * Example 2: The following example configures a module to support logging
89 * of ENTRY and EXIT events, but defers the actual activation and deactivation of the
90 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
91 * function for details on specifying the control string.
92 *
93 * This is a part of the XDC configuration file for the application:
94 *
95 * @p(code)
96 * var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
97 * UIAProfile.runtimeControl = true;
98 * UIAProfile.enable = false;
99 * @p
100 *
101 * This is a part of the C code for the application.
102 * The diags_ENTRY mask is set by "E", and the diags_EXIT mask is set by "X".
103 *
104 * @p(code)
105 * #include <xdc/runtime/Diags.h>
106 * #include <xdc/runtime/Main.h>
107 *
108 * // turn on logging of ENTRY and EXIT events in the module
109 * Diags_setMask("xdc.runtime.Main+EX");
110 *
111 * // turn off logging of ENTRY and EXIT events in the module
112 * Diags_setMask("xdc.runtime.Main-EX");
113 * @p
114 *
115 *
116 */
117 module UIAProfile inherits IUIAEvent {
118
119 /*!
120 * ======== enterFunctionAdrs ========
121 * Profiling event used to log the entry point of a function
122 *
123 * @a(Example)
124 * To add entry and exit hook functions to every function
125 * 1. Use the following compiler options when compiling the source
126 * @p(code)
127 * --entry_hook=functionEntryHook
128 * --entry_param=address
129 * --exit_hook=functionExitHook
130 * --exit_param=address
131 * @p
132 * 2. Add the following c code to implement the hook functions:
133 * The first parameter (the taskHandle) is set to 0 in this example.
134 * @see exitFunction for an example of how to log the current task ID
135 * for task-aware function profiling.
136 * In order to further reduce the CPU overhead of logging the
137 * UIAProfile events, you can use the LogUC.h APIs. For more info, please
138 * see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
139 * @p(code)
140 * #include <xdc/runtime/Log.h>
141 * #include <ti/uia/events/UIAProfile.h>
142 * ...
143 * void functionEntryHook( void (*adrs)() ){
144 * Log_write2(UIAProfile_enterFunctionAdrs, 0,(IArg)adrs);
145 * ...
146 * void functionExitHook( void (*adrs)() ){
147 * Log_write2(UIAProfile_exitFunctionAdrs, 0,(IArg)adrs);
148 * }
149 * @p
150 * The following text will be displayed for the event:
151 * @p(code)
152 * enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
153 * exitFunctionAdrs: taskHandle0x0, adrs=0x820060
154 * @p
155 * @param(taskHandle) task handle that identifies the currently active task (use 0 if not required)
156 * @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
157 */
158 config xdc.runtime.Log.Event enterFunctionAdrs = {
159 mask: Diags.ENTRY,
160 msg: "enterFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
161 };
162
163 /*!
164 * ======== metaEventEnterFunctionAdrs ========
165 * Metadata description of the enterFunctionAdrs event
166 *
167 * @_nodoc
168 */
169 metaonly config DvtTypes.MetaEventDescriptor metaEventEnterFunctionAdrs = {
170 versionId: "2.0",
171 analysisType: DvtTypes.DvtAnalysisType_START,
172 displayText: "enterFunctionAdrs",
173 tooltipText: "function entry",
174 numParameters: 2,
175 paramInfo: [
176 { name: 'Qualifier',
177 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
178 dataTypeName: 'Int',
179 units: 'none',
180 isHidden: false
181 },
182 { name: 'FunctionAdrs',
183 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
184 dataTypeName: 'Int',
185 units: 'none',
186 isHidden: false
187 }
188 ]
189 };
190
191
192 /*!
193 * ======== exitFunctionAdrs ========
194 * Profiling event used to log the exit point of a function
195 *
196 * @a(Example)
197 * To add entry and exit hook functions to every function
198 * 1. Use the following compiler options when compiling the source
199 * @p(code)
200 * --entry_hook=functionEntryHook
201 * --entry_param=address
202 * --exit_hook=functionExitHook
203 * --exit_param=address
204 * @p
205 * 2. Add the following c code to implement the hook functions:
206 * Task_selfMacro() is used to get the current task handle in this example.
207 * @see enterFunction for an example of how to save CPU by logging 0
208 * instead of the task handle if task-aware profiling is not required.
209 * In order to further reduce the CPU overhead of logging the
210 * UIAProfile events, you can use the LogUC.h APIs. For more info, please
211 * see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
212 * @p(code)
213 * #include <xdc/runtime/Log.h>
214 * #include <ti/uia/events/UIAProfile.h>
215 * #include <ti/sysbios/knl/Task.h>
216 * ...
217 * void functionEntryHook( void (*adrs)() ){
218 * Log_write2(UIAProfile_enterFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
219 * ...
220 * void functionExitHook( void (*adrs)() ){
221 * Log_write2(UIAProfile_exitFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
222 * }
223 * @p
224 * The following text will be displayed for the event:
225 * @p(code)
226 * enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
227 * exitFunctionAdrs: taskHandle=0x0, adrs=0x820060
228 * @p
229 * @param(taskHandle) task handle that identifies the currently active task (use 0 if not required)
230 * @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
231 */
232 config xdc.runtime.Log.Event exitFunctionAdrs = {
233 mask: Diags.EXIT,
234 msg: "exitFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
235 };
236
237 /*!
238 * ======== metaEventExitFunction ========
239 * Metadata description of the exitFunctionAdrs event
240 *
241 * @_nodoc
242 */
243 metaonly config DvtTypes.MetaEventDescriptor metaEventExitFunctionAdrs = {
244 versionId: "2.0",
245 analysisType: DvtTypes.DvtAnalysisType_STOP,
246 displayText: "exitFunctionAdrs",
247 tooltipText: "Marks the end of analysis for a module instance",
248 numParameters: 2,
249 paramInfo: [
250 { name: 'Qualifier',
251 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
252 dataTypeName: 'Int',
253 units: 'none',
254 isHidden: false
255 },
256 { name: 'FunctionAdrs',
257 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
258 dataTypeName: 'Int',
259 units: 'none',
260 isHidden: false
261 }
262 ]
263 };
264
265 /*!
266 * ======== enterFunctionName ========
267 * Profiling event used to log the entry point of a function
268 *
269 * @a(Example)
270 * To add entry and exit hook functions to every function
271 * 1. Use the following compiler options when compiling the source
272 * @p(code)
273 * --entry_hook=functionEntryHook
274 * --entry_param=name
275 * --exit_hook=functionExitHook
276 * --exit_param=name
277 * @p
278 * 2. Add the following c code to implement the hook functions:
279 * The first parameter (the taskHandle) is set to 0 in this example.
280 * @see exitFunction for an example of how to log the current task ID
281 * for task-aware function profiling.
282 * In order to further reduce the CPU overhead of logging the
283 * UIAProfile events, you can use the LogUC.h APIs. For more info, please
284 * see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
285 * @p(code)
286 * #include <xdc/runtime/Log.h>
287 * #include <ti/uia/events/UIAProfile.h>
288 * ...
289 * void functionEntryHook(const char* name ){
290 * Log_write2(UIAProfile_enterFunctionName, 0,(IArg)name);
291 * ...
292 * void functionExitHook(const char* name){
293 * Log_write2(UIAProfile_exitFunctionName, 0,(IArg)name);
294 * }
295 * @p
296 * The following text will be displayed for the event:
297 * @p(code)
298 * enterFunctionName: taskHandle=0x0, name=myFunctionName
299 * exitFunctionName: taskHandle0x0, name=myFunctionName
300 * @p
301 * @param(taskHandle) task handle that identifies the currently active task (use 0 if not required)
302 * @param(functionName) the (const char*) name of the function that is passed to the hook fn by the compiler
303 */
304 config xdc.runtime.Log.Event enterFunctionName = {
305 mask: Diags.ENTRY,
306 msg: "enterFunctionName: taskHandle=0x%x, name=%s"
307 };
308
309 /*!
310 * ======== metaEventEnterFunctionName ========
311 * Metadata description of the enterFunctionName event
312 *
313 * @_nodoc
314 */
315 metaonly config DvtTypes.MetaEventDescriptor metaEventEnterFunctionName = {
316 versionId: "2.0",
317 analysisType: DvtTypes.DvtAnalysisType_START,
318 displayText: "enterFunctionName",
319 tooltipText: "function entry",
320 numParameters: 2,
321 paramInfo: [
322 { name: 'Qualifier',
323 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
324 dataTypeName: 'Int',
325 units: 'none',
326 isHidden: false
327 },
328 { name: 'FunctionAdrs',
329 dataDesc: DvtTypes.DvtDataDesc_STRINGADRS,
330 dataTypeName: 'Int',
331 units: 'none',
332 isHidden: false
333 }
334 ]
335 };
336
337
338 /*!
339 * ======== exitFunctionName ========
340 * Profiling event used to log the exit point of a function
341 *
342 * @a(Example)
343 * To add entry and exit hook functions to every function
344 * 1. Use the following compiler options when compiling the source
345 * @p(code)
346 * --entry_hook=functionEntryHook
347 * --entry_param=name
348 * --exit_hook=functionExitHook
349 * --exit_param=name
350 * @p
351 * 2. Add the following c code to implement the hook functions:
352 * Task_selfMacro() is used to get the current task handle in this example.
353 * @see enterFunction for an example of how to save CPU by logging 0
354 * instead of the task handle if task-aware profiling is not required.
355 * In order to further reduce the CPU overhead of logging the
356 * UIAProfile events, you can use the LogUC.h APIs. For more info, please
357 * see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
358 * @p(code)
359 * #include <xdc/runtime/Log.h>
360 * #include <ti/uia/events/UIAProfile.h>
361 * #include <ti/sysbios/knl/Task.h>
362 * ...
363 * void functionEntryHook(const char* name){
364 * Log_write2(UIAProfile_enterFunctionName, (IArg)Task_selfMacro(),(IArg)name);
365 * ...
366 * void functionExitHook(const char* name){
367 * Log_write2(UIAProfile_exitFunctionName, (IArg)Task_selfMacro(),(IArg)name);
368 * }
369 * @p
370 * The following text will be displayed for the event:
371 * @p(code)
372 * enterFunctionName: taskHandle=0x0, adrs=myFunctionName
373 * exitFunctionName: taskHandle=0x0, name=myFunctionName
374 * @p
375 * @param(taskHandle) task handle that identifies the currently active task (use 0 if not required)
376 * @param(functionName) the (const char*) name of the function that is passed to the hook fn by the compiler
377 */
378 config xdc.runtime.Log.Event exitFunctionName = {
379 mask: Diags.EXIT,
380 msg: "exitFunctionName: taskHandle=0x%x, name=%s"
381 };
382
383 /*!
384 * ======== metaEventExitFunctionName ========
385 * Metadata description of the exitFunctionName event
386 *
387 * @_nodoc
388 */
389 metaonly config DvtTypes.MetaEventDescriptor metaEventExitFunctionName = {
390 versionId: "2.0",
391 analysisType: DvtTypes.DvtAnalysisType_STOP,
392 displayText: "exitFunctionName",
393 tooltipText: "Marks the end of analysis for a module instance",
394 numParameters: 2,
395 paramInfo: [
396 { name: 'Qualifier',
397 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
398 dataTypeName: 'Int',
399 units: 'none',
400 isHidden: false
401 },
402 { name: 'FunctionAdrs',
403 dataDesc: DvtTypes.DvtDataDesc_STRINGADRS,
404 dataTypeName: 'Int',
405 units: 'none',
406 isHidden: false
407 }
408 ]
409 };
410
411 /*!
412 * ======== runtimeControl ========
413 * Specify whether profile events can be enabled / disabled at runtime.
414 * (set to false by default)
415 *
416 * This determines what diags settings are applied to the module's diags
417 * mask.
418 * if the UIAProfile enable config property is true (default):
419 * If runtimeControl = 'false' the diags bits will be configured as
420 * ALWAYS_ON, meaning they can't be changed at runtime.
421 * If runtimeControl = 'true', the bits will be configured as 'RUNTIME_ON'.
422 *
423 * if the UIAProfile enable config property is false:
424 * If runtimeControl = 'false' the diags bits will be configured as
425 * ALWAYS_OFF, meaning they can't be changed at runtime.
426 * If runtimeControl = 'true', the bits will be configured as 'RUNTIME_OFF'.
427 */
428 metaonly config Bool runtimeControl = false;
429
430 /*!
431 * ======== enable ========
432 * Specify whether profile events are enabled or disabled
433 * (set to true by default)
434 *
435 * if the UIAProfile enable config property is true (default):
436 * If runtimeControl = 'false' the diags bits will be configured as
437 * ALWAYS_ON, meaning they can't be changed at runtime.
438 * If runtimeControl = 'true', the bits will be configured as 'RUNTIME_ON'.
439 *
440 * if the UIAProfile enable config property is false:
441 * If runtimeControl = 'false' the diags bits will be configured as
442 * ALWAYS_OFF, meaning they can't be changed at runtime.
443 * If runtimeControl = 'true', the bits will be configured as 'RUNTIME_OFF'.
444 */
445 metaonly config Bool enable = true;
446 }