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.)
47 *
48 * The generation of UIAProfile events is controlled by a module's diagnostics
49 * mask, which is described in detail in `{@link xdc.runtime.Diags}`.
50 * `UIAProfile_enterFunction` events are generated only when the Diags.ENTRY bit
51 * in the module's diagnostics mask is set, and 'UIAProfile_exitFunction' events
52 * are generated only when the Diags.EXIT bit is set.
53 *
54 * The following configuration script demonstrates how the application might
55 * control the logging of events embedded in the `Mod` module at configuration
56 * time. In this case, the configuration script arranges for the `Log`
57 * statements within modules to always generate ENTRY and EXIT events.
58 * Without these configuration statements, no events would be generated
59 * by any modules.
60 *
61 * @a(Examples)
62 * Example 1: This is part of the XDC configuration file for the application:
63 *
64 * @p(code)
65 * var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
66 * var Diags = xdc.useModule('xdc.runtime.Diags');
67 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
68 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
69 * var logger = LoggerSys.create();
70 *
71 * Defaults.common$.diags_ENTRY = Diags.ALWAYS_ON;
72 * Defaults.common$.diags_EXIT = Diags.ALWAYS_ON;
73 * Defaults.common$.logger = logger;
74 * @p
75 *
76 * @p(html)
77 * <hr />
78 * @p
79 *
80 * Example 2: The following example configures a module to support logging
81 * of ENTRY and EXIT events, but defers the actual activation and deactivation of the
82 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
83 * function for details on specifying the control string.
84 *
85 * This is a part of the XDC configuration file for the application:
86 *
87 * @p(code)
88 * var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
89 * var Diags = xdc.useModule('xdc.runtime.Diags');
90 * var Mod = xdc.useModule('my.pkg.Mod');
91 *
92 * Mod.common$.diags_ENTRY = Diags.RUNTIME_OFF;
93 * Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
94 * @p
95 *
96 * This is a part of the C code for the application.
97 * The diags_ENTRY mask is set by "E", and the diags_EXIT mask is set by "X".
98 *
99 * @p(code)
100 * // turn on logging of ENTRY and EXIT events in the module
101 * Diags_setMask("my.pkg.Mod+EX");
102 *
103 * // turn off logging of ENTRY and EXIT events in the module
104 * Diags_setMask("my.pkg.Mod-EX");
105 * @p
106 *
107 *
108 */
109 module UIAProfile inherits IUIAEvent {
110
111 /*!
112 * ======== enterFunction ========
113 * Profiling event used to log the entry point of a function
114 *
115 * @a(Example)
116 * To add entry and exit hook functions to every function
117 * 1. Use the following compiler options when compiling the source
118 * @p(code)
119 * --entry_hook=functionEntryHook
120 * --entry_param=address
121 * --exit_hook=functionExitHook
122 * --exit_param=address
123 * @p
124 * 2. Add the following c code to implement the hook functions:
125 * The first parameter (the taskHandle) is set to 0 in this example.
126 * @see exitFunction for an example of how to log the current task ID
127 * for task-aware function profiling.
128 *
129 * @p(code)
130 * #include <xdc/runtime/Log.h>
131 * #include <ti/uia/events/UIAProfile.h>
132 * ...
133 * void functionEntryHook( void (*addr)() ){
134 * Log_write2(UIAProfile_enterFunction, 0,(IArg)addr);
135 * ...
136 * void functionExitHook( void (*addr)() ){
137 * Log_write2(UIAProfile_exitFunction, 0,(IArg)addr);
138 * }
139 * @p
140 * The following text will be displayed for the event:
141 * @p(code)
142 * enterFunction: taskHandle=0x0, adrs=0x820060
143 * exitFunction: taskHandle0x0, adrs=0x820060
144 * @p
145 * @param(taskHandle) task handle that identifies the currently active task (use 0 if not required)
146 * @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
147 */
148 config xdc.runtime.Log.Event enterFunction = {
149 mask: Diags.ENTRY,
150 msg: "enterFunction: taskHandle=0x%x, adrs=0x%x"
151 };
152
153 /*!
154 * ======== metaEventEnterFunction ========
155 * Metadata description of the enterFunction event
156 *
157 * @_nodoc
158 */
159 metaonly config DvtTypes.MetaEventDescriptor metaEventEnterFunction = {
160 versionId: "2.0",
161 analysisType: DvtTypes.DvtAnalysisType_START,
162 displayText: "enterFunction",
163 tooltipText: "function entry",
164 numParameters: 2,
165 paramInfo: [
166 { name: 'Qualifier',
167 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
168 dataTypeName: 'Int',
169 units: 'none',
170 isHidden: false
171 },
172 { name: 'FunctionAdrs',
173 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
174 dataTypeName: 'Int',
175 units: 'none',
176 isHidden: false
177 }
178 ]
179 };
180
181
182 /*!
183 * ======== exitFunction ========
184 * Profiling event used to log the exit point of a function
185 *
186 * @a(Example)
187 * To add entry and exit hook functions to every function
188 * 1. Use the following compiler options when compiling the source
189 * @p(code)
190 * --entry_hook=functionEntryHook
191 * --entry_param=address
192 * --exit_hook=functionExitHook
193 * --exit_param=address
194 * @p
195 * 2. Add the following c code to implement the hook functions:
196 * Task_selfMacro() is used to get the current task handle in this example.
197 * @see enterFunction for an example of how to save CPU by logging 0
198 * instead of the task handle if task-aware profiling is not required.
199 *
200 * @p(code)
201 * #include <xdc/runtime/Log.h>
202 * #include <ti/uia/events/UIAProfile.h>
203 * #include <ti/sysbios/knl/Task.h>
204 * ...
205 * void functionEntryHook( void (*addr)() ){
206 * Log_write2(UIAProfile_enterFunction, (IArg)Task_selfMacro(),(IArg)addr);
207 * ...
208 * void functionExitHook( void (*addr)() ){
209 * Log_write2(UIAProfile_exitFunction, (IArg)Task_selfMacro(),(IArg)addr);
210 * }
211 * @p
212 * The following text will be displayed for the event:
213 * @p(code)
214 * enterFunction: taskHandle=0x0, adrs=0x820060
215 * exitFunction: taskHandle=0x0, adrs=0x820060
216 * @p
217 * @param(taskHandle) task handle that identifies the currently active task (use 0 if not required)
218 * @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
219 */
220 config xdc.runtime.Log.Event exitFunction = {
221 mask: Diags.EXIT,
222 msg: "exitFunction: taskHandle=0x%x, adrs=0x%x"
223 };
224
225 /*!
226 * ======== metaEventExitFunction ========
227 * Metadata description of the exitFunction event
228 *
229 * @_nodoc
230 */
231 metaonly config DvtTypes.MetaEventDescriptor metaEventExitFunction = {
232 versionId: "2.0",
233 analysisType: DvtTypes.DvtAnalysisType_STOP,
234 displayText: "exitFunction",
235 tooltipText: "Marks the end of analysis for a module instance",
236 numParameters: 2,
237 paramInfo: [
238 { name: 'Qualifier',
239 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
240 dataTypeName: 'Int',
241 units: 'none',
242 isHidden: false
243 },
244 { name: 'FunctionAdrs',
245 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
246 dataTypeName: 'Int',
247 units: 'none',
248 isHidden: false
249 }
250 ]
251 };
252
253
254 }