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 import xdc.runtime.Diags;
37
38 /*!
39 * UIA Standard Events
40 * @p
41 * The UIAEvt module defines events that allow
42 * tooling to display event information
43 * and filter events based on their priority.
44 * @p
45 * The events in this module have one of the following event priority levels:
46 * WARNING: used to indicate an unexpected or problematic situation such as when a resource
47 * becomes dangerously low
48 * INFO: used to indicate something of interest or of use in understanding the
49 * current state of the system or behaviour of the software
50 * DETAIL: used to indicate additional information that may be of interest
51 * in troubleshooting problems or improving the software
52 *@p
53 * For each priority level, two predefined event codes
54 * are provided: one for logging a single event code,
55 * and one for logging an event code along with a
56 * reference to a constant formatting string that can
57 * be used to format the text displayed for the event.
58 * The formatting string allows additional arguments
59 * to be displayed along with the event code when the
60 * event is rendered as text (e.g. by DVT).
61 *@p
62 * The following special formatting specifiers may be used in the
63 * msg field of an event's config specification:
64 * @p
65 * %$S - a string parameter that can provide additional formatting specifiers
66 * Note that $S use in strings passed in as a paramter is not supported.
67 *@p
68 * %$F - a specifier for a string parameter containing the file name (__FILE__) and
69 * an integer parameter containing the line number (__LINE__).
70 *@p
71 * The generation of UIAEvt events is controlled by a module's diagnostics
72 * mask, which is described in details in `{@link xdc.runtime.Diags}`.
73 * `UIAEvt` warning events are generated only when the Diags.STATUS bit is set
74 * in the module's diagnostics mask. The Diags.STATUS bit is set to ALWAYS_ON
75 * by default. 'UIAEvt' info and detail events are generated only when the
76 * Diags.INFO bit is set in the module's diagnostics mask.
77 *
78 * The following configuration script demonstrates how to enable use of
79 * UIAEvt events within an application. Since the Diags.STATUS bits are set
80 * to ALWAYS_ON by default, no explicit code is required to enable the
81 * Diags Masks for these events. The Diags.INFO bitmust be explicitly set
82 * in order to enable info and detail level events.
83 *
84 * This is part of the XDC configuration file for the application:
85 *
86 * @p(code)
87 * var UIAEvt = xdc.useModule('ti.uia.events.UIAEvt');
88 * var Diags = xdc.useModule('xdc.runtime.Diags');
89 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
90 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
91 * var logger = LoggerSys.create();
92 *
93 * Defaults.common$.logger = logger;
94 * Defaults.common$.diags_INFO = Diags.ALWAYS_ON;
95 * @p
96 *
97 * @p(html)
98 * <hr />
99 * @p
100 *
101 * Example 2: The following example configures a module to support logging
102 * of STATUS events and INFO events, but defers the actual activation and deactivation of the
103 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
104 * function for details on specifying the control string.
105 *
106 * This is a part of the XDC configuration file for the application:
107 *
108 * @p(code)
109 * var UIAEvt = xdc.useModule('ti.uia.events.UIAEvt');
110 * var Diags = xdc.useModule('xdc.runtime.Diags');
111 * var Mod = xdc.useModule('my.pkg.Mod');
112 *
113 * Mod.common$.diags_STATUS = Diags.RUNTIME_OFF;
114 * Mod.common$.diags_INFO = Diags.RUNTIME_OFF;
115 * @p
116 *
117 * This is a part of the C code for the application:
118 *
119 * @p(code)
120 * // turn on logging of STATUS events (S) and INFO events (F)
121 * // in the module
122 * Diags_setMask("my.pkg.Mod+SF");
123 *
124 * // turn off logging of STATUS events and INFO events in the module
125 * Diags_setMask("my.pkg.Mod-SF");
126 * @p
127 */
128 module UIAEvt inherits IUIAEvent {
129
130 /*!
131 * ======== warning ========
132 * Event to use to log a Warning Event Code
133 *
134 * @a(Example)
135 * The following C code shows how to log a legacy warning code as a UIA event.
136 *
137 * @p(code)
138 * #include <xdc/runtime/Log.h>
139 * #include <ti/uia/events/UIAEvt.h>
140 * ...
141 * Int myWarningCode = 0xBAD;
142 * ...
143 * Log_write1(UIAEvt_warning, myWarningCode);
144 * ...
145 * @p
146 * The following text is an example of what will be displayed for the event:
147 * @p(code)
148 * "WARNING: EventCode:0xBAD."
149 * @p
150 * @param(eventCode) integer that identifies the type of warning
151 * @param(fmt) a constant string that provides format specifiers for up to 6 additional parameters
152 *
153 * @see #warningWithStr
154 */
155 config xdc.runtime.Log.Event warning = {
156 mask: Diags.STATUS,
157 level: Diags.WARNING,
158 msg: "WARNING: EventCode:0x%x"
159 };
160
161 /*!
162 * ======== warningWithStr ========
163 * Event to use to log a Warning Event Code and fmt string
164 *
165 * @a(Example)
166 * The following C code shows how to log a legacy warning code and string as a UIA event.
167 * @p(code)
168 * #include <xdc/runtime/Log.h>
169 * #include <ti/uia/events/UIAEvt.h>
170 * ...
171 * Int myWarningCode = 0xBAD;
172 * String myWarningStr = "Legacy Warning String for warning 0xBAD";
173 * ...
174 * Log_write2(UIAEvt_warning,myWarningCode,(IArg)myWarningStr);
175 * ...
176 * @p
177 * The following text is an example of what will be displayed for the event:
178 * @p(code)
179 * "WARNING: EventCode:0xBAD. Legacy Warning String for warning 0xBAD"
180 * @p
181 * @param(eventCode) integer that identifies the type of warning event
182 * @param(fmt) a constant string that provides format specifiers for up to 6 additional parameters
183 *
184 * @see #warning
185 *
186 */
187 config xdc.runtime.Log.Event warningWithStr = {
188 mask: Diags.STATUS,
189 level: Diags.WARNING,
190 msg: "WARNING: EventCode:0x%x. %$S"
191 };
192
193 /*!
194 * ======== info ========
195 * Event to use to log an Informational Event Code
196 *
197 * @a(Example)
198 * The following C code shows how to log an informational event code as a UIA event.
199 *
200 * @p(code)
201 * #include <xdc/runtime/Log.h>
202 * #include <ti/uia/events/UIAEvt.h>
203 * ...
204 * Int myInfoCode = 0xC0DE;
205 * ...
206 * Log_write1(UIAEvt_info, myInfoCode);
207 * ...
208 * @p
209 * The following text is an example of what will be displayed for the event:
210 * @p(code)
211 * "INFO: EventCode:0xC0DE."
212 * @p
213 * @param(eventCode) integer that identifies the type of info event
214 *
215 * @see #infoWithStr
216 *
217 */
218 config xdc.runtime.Log.Event info = {
219 mask: Diags.INFO,
220 msg: "INFO: EventCode: 0x%x"
221 };
222
223 /*!
224 * ======== infoWithStr ========
225 * Event to use to log a Informational Event Code and format string
226 *
227 * @a(Example)
228 * The following C code shows how to log an informational event code
229 * and format string as a UIA event. It also shows how additional parameters
230 * can be logged along with the event and format string.
231 *
232 * @p(code)
233 * #include <xdc/runtime/Log.h>
234 * #include <ti/uia/events/UIAEvt.h>
235 * ...
236 * Int myInfoCode = 0xC0DE;
237 * Int anAdditionalParam = 0x6543;
238 * ...
239 * Log_write3(UIAEvt_infoWithStr, myInfoCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
240 * ...
241 * @p
242 * The following text is an example of what will be displayed for the event:
243 * @p(code)
244 * "INFO: EventCode:0xC0DE. Some descriptive text. anAdditionalParam=0x6543."
245 * @p
246 * @param(eventCode) integer that identifies the specific info event being logged
247 * @param(fmt) a constant string that provides format specifiers for up to 6 additional parameters
248 *
249 * @see #info
250 */
251 config xdc.runtime.Log.Event infoWithStr = {
252 mask: Diags.INFO,
253 msg: "INFO: EventCode:0x%x. %$S"
254 };
255
256 /*!
257 * ======== detail ========
258 * Event to use to log a Detail-level Event Code
259 *
260 * @a(Example)
261 * The following C code shows how to log a detail-level event code as a UIA event.
262 *
263 * @p(code)
264 * #include <xdc/runtime/Log.h>
265 * #include <ti/uia/events/UIAEvt.h>
266 * ...
267 * Int myEventCode = 0xE1;
268 * ...
269 * Log_write1(UIAEvt_detail, myEventCode);
270 * ...
271 * @p
272 * The following text is an example of what will be displayed for the event:
273 * @p(code)
274 * "DETAIL: EventCode:0xE1."
275 * @p
276 * @param(eventCode) integer that identifies the specific detail event being logged
277 *
278 * @see #detailWithStr
279 */
280 config xdc.runtime.Log.Event detail = {
281 mask: Diags.INFO,
282 level: Diags.LEVEL4,
283 msg: "DETAIL: EventCode:0x%x"
284 };
285
286 /*!
287 * ======== detailWithStr ========
288 * Event to use to log a Detail-level Event Code and fmt string
289 *
290 * @a(Example)
291 * The following C code shows how to log a detail-level event code
292 * and format string as a UIA event. It also shows how additional parameters
293 * can be logged along with the event and format string.
294 *
295 * @p(code)
296 * #include <xdc/runtime/Log.h>
297 * #include <ti/uia/events/UIAEvt.h>
298 * ...
299 * Int myEventCode = 0xE1;
300 * Int anAdditionalParam = 0x6543;
301 * ...
302 * Log_write3(UIAEvt_detailWithStr, myEventCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
303 * ...
304 * @p
305 * The following text is an example of what will be displayed for the event:
306 * @p(code)
307 * "DETAIL: EventCode:0xE1. Some descriptive text. anAdditionalParam=0x6543."
308 * @p
309 * @param(eventCode) integer that identifies the specific detail event being logged
310 * @param(fmt) a constant string that provides format specifiers for up to 6 additional parameters
311 *
312 * @see #detail
313 */
314 config xdc.runtime.Log.Event detailWithStr = {
315 mask: Diags.INFO ,
316 level: Diags.LEVEL4,
317 msg: "DETAIL: EventCode:0x%x. %$S"
318 };
319
320 /*!
321 * ======== intWithKey ========
322 * Event to use to log values to be analyzed as Statistics and / or Graphs
323 *
324 * @a(Example)
325 * Example 1:
326 * The following C code shows how to log an intWithKey event code
327 * that logs a value, a format string that defines the key, and
328 * parameters for use within the key format string.
329 *
330 * @p(code)
331 * #include <xdc/runtime/Log.h>
332 * #include <ti/uia/events/UIAEvt.h>
333 * ...
334 * Int myValue = 1001;
335 * Int myInstanceId = 0x6543;
336 * ...
337 * Log_write5(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=0x%x.",myInstanceId);
338 * ...
339 * @p
340 * The following text is an example of what will be displayed for the event:
341 * @p(code)
342 * "VALUE=1001 (AuxData=0,0) Key: InstanceId=0x6543."
343 *
344 * @a(Example)
345 * Example 2:
346 * The following C code shows how to log an intWithKey event code
347 * that logs a value, a format string that defines the key, and
348 * parameters for use within the key format string, including
349 * the file name and line of code that the event was logged at.
350 * This example uses a special format specifier, %$F, which
351 * is used to format two parameters (__FILE__ and __LINE__)
352 * in a way that tools will be able to display the line of code
353 * that the event was logged from in a source code editor
354 * when the user clicks on the event.
355 *
356 * @p(code)
357 * #include <xdc/runtime/Log.h>
358 * #include <ti/uia/events/UIAEvt.h>
359 * ...
360 * Int myValue = 1001;
361 * Int myInstanceId = 9876;
362 * ...
363 * Log_write7(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=%d, at %$F.",
364 * myInstanceId,(IArg)__FILE__,(IArg)__LINE__);
365 * ...
366 * // If you wish to log only the line number as a key, use the following:
367 * Log_write6(UIAEvt_intWithKey, myValue+1,0,0,(IArg)"InstanceId=%d, at line %d.",
368 * myInstanceId,(IArg)__LINE__);
369 * ...
370 * // If you wish to log only the file name as a key and the line number
371 * // as auxiliary data which is logged along with the event, use the following:
372 * Log_write6(UIAEvt_intWithKey, myValue+2,(IArg)__LINE__,0,(IArg)"InstanceId=%d, in file [%s].",
373 * myInstanceId,(IArg)__FILE__);
374 * @p
375 * The following text is an example of what will be displayed for the event,
376 * assuming it was logged from a file named demo.c at line 1234:
377 * @p(code)
378 * "VALUE=1001 (AuxData=0,0) Key: InstanceId=9876, at [../demo.c:1234] ."
379 * "VALUE=1002 (AuxData=0,0) Key: InstanceId=9876, at line 1234."
380 * "VALUE=1003 (AuxData=1234,0) Key: InstanceId=9876, in file [../demo.c]."
381 * @p
382 *
383 * @param(value) integer value that is to be analyzed
384 * @param(auxData1) auxiliary data that is to be displayed along with the event (use 0 if none)
385 * @param(auxData2) auxiliary data that is to be displayed along with the event (use 0 if none)
386 * @param(key) a constant string that provides format specifiers for up to 4 key entries
387 */
388 config xdc.runtime.Log.Event intWithKey = {
389 mask: Diags.ANALYSIS,
390 msg: "VALUE=%d (AuxData=%d, %d) Key:%$S"
391 };
392
393 /*!
394 * ======== metaEventStart ========
395 * Metadata description of the start event
396 *
397 * @_nodoc
398 */
399 metaonly config DvtTypes.MetaEventDescriptor metaEventIntWithKey = {
400 versionId: "2.0",
401 analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
402 displayText: "intWithKey",
403 tooltipText: "Value with a key string",
404 numParameters: 4,
405 paramInfo: [
406 { name: 'value',
407 dataDesc: DvtTypes.DvtDataDesc_VALUE,
408 dataTypeName: 'Int',
409 units: 'none',
410 isHidden: false
411 },
412 { name: 'aux1',
413 dataDesc: DvtTypes.DvtDataDesc_VALUE,
414 dataTypeName: 'Int',
415 units: 'none',
416 isHidden: false
417 },
418 { name: 'aux2',
419 dataDesc: DvtTypes.DvtDataDesc_VALUE,
420 dataTypeName: 'Int',
421 units: 'none',
422 isHidden: false
423 },
424 { name: 'key',
425 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
426 dataTypeName: 'String',
427 units: 'none',
428 isHidden: false
429 }
430 ]
431 };
432
433 }