1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 /*!
18 * ======== Diags ========
19 * Diagnostics manager
20 *
21 * Every XDC module has a "diagnostics mask" that allows clients to
22 * enable or disable diagnostics on a per module basis both at
23 * configuration time and at runtime. The `Diags` module manages a
24 * module's diagnostics mask.
25 *
26 * You use the `Diags` module to set and clear bits in a module's
27 * diagnostics mask for the purpose of controlling diagnostics
28 * within that module. Each bit corresponds to a "category" of diagnostic
29 * that can be individually enabled or disabled.
30 *
31 * A module's diagnostics mask controls both `{@link Assert}` and
32 * `{@link Log}` statements within that module. A module's diagnostics
33 * mask may also be used to conditionally execute blocks of code using
34 * the `{@link #query Diags_query()}` runtime function.
35 *
36 * A module's diagnostics mask can be set at configuration time and
37 * at runtime. The implementation of diagnostics is such that when they
38 * are permanently turned off at configuration time
39 * (`{@link #ALWAYS_OFF Mode.ALWAYS_OFF}`), an optimizer can
40 * completely eliminate the diagnostics code from the program. Similarly,
41 * if diagnostics are permanently turned on at configuration time
42 * (`{@link #ALWAYS_ON Mode.ALWAYS_ON}`), the optimizer can
43 * eliminate all runtime conditional checking and simply
44 * invoke the diagnostics code directly. Runtime checking of the
45 * diagnostics mask is performed only when the diagnostics are configured
46 * to be runtime modifiable (`{@link #RUNTIME_OFF Mode.RUNTIME_OFF}` or
47 * `{@link #RUNTIME_ON Mode.RUNTIME_ON}`).
48 *
49 * Each bit of the diagnostics mask is controlled by one of the following
50 * constants.
51 *
52 * @p(code)
53 * Constant Meaning
54 * --------------------------
55 * ENTRY Function entry
56 * EXIT Function exit
57 * LIFECYCLE Object life-cycle
58 * INTERNAL Internal diagnostics
59 * ASSERT Assert checking
60 * STATUS Warning or Error events
61 * USER1 User defined diagnostics
62 * USER2 User defined diagnostics
63 * USER3 User defined diagnostics
64 * USER4 User defined diagnostics
65 * USER5 User defined diagnostics
66 * USER6 User defined diagnostics
67 * USER7 User defined diagnostics
68 * INFO Informational event
69 * USER8 User defined diagnostics
70 * ANALYSIS Analysis event
71 * @p
72 *
73 * These constants can be used from either JavaScript configuration
74 * scripts or C code and, therefore, have two "names". For example,
75 * to reference the ENTRY constant from JavaScript you must use
76 * `Diags.ENTRY` whereas from C you would use `Diags_ENTRY`.
77 *
78 * The `ENTRY` and `EXIT` categories are for log statements at the entry and
79 * exit points, respectively, to each function within a module. This
80 * is useful for tracking the execution flow of your program.
81 *
82 * The `LIFECYCLE` category is for log events at the create/construct
83 * and delete/destruct points of each instance object for the module.
84 * This is useful for tracking the life-cycle of a module instance object.
85 *
86 * `ASSERT` and `INTERNAL` are unique in that they are not related to logging,
87 * but instead control the Assert statements in a module. These categories
88 * control the two classes of asserts:
89 *
90 * @p(blist)
91 * - Public asserts, which have an `{@link Assert#Id Assert_Id}` and
92 * are documented in the module's reference pages. These asserts are
93 * on by default and are meant to help developers validate code that
94 * invokes a module's functions.
95 * - Internal asserts, which have no `{@link Assert#Id Assert_Id}`.
96 * These asserts are off by default and are typically used only when
97 * developing code. That is, like the standard C assert() mechanism,
98 * these asserts are not part of a deployed application.
99 * @p
100 *
101 * When a module has enabled the `ASSERT` category (which is enabled by
102 * default) in its diagnostics mask, the module executes all of its public
103 * assert statements. To enable internal asserts, you must enable both the
104 * `ASSERT` and `INTERNAL` categories.
105 *
106 * The `ASSERT` and `INTERNAL` categories are not intended for use as log
107 * event categories. If an event is defined with either of these categories,
108 * you will receive a validation error during configuration.
109 *
110 * The `STATUS` category is used for error and warning type events. The
111 * four event levels within the `STATUS` category have defined meanings,
112 * see {@link #EMERGENCY}
113 *
114 * The `INFO` category is used for generic informational events. Any event
115 * which does not belong to a more specific category of events may simply
116 * be an `INFO` event.
117 *
118 * The `ANALYSIS` category is used for events related to benchmarks and
119 * performance analysis.
120 *
121 * The `USER1`-`6` categories are available to each module writer to use as
122 * he or she wishes.
123 *
124 * The USER7 and USER8 categories are still defined, but their bits have been
125 * repurposed for the INFO and ANALYSIS categories, respectively, so the use
126 * of USER7 and USER8 has been deprecated.
127 *
128 * @a(Examples)
129 * Configuration example: The following XDC configuration statements set
130 * a module's diagnostics mask in a configuration script. (In this case,
131 * the `Task` module of the `ti.sysbios.knl` package is used.) In this
132 * example, the `ENTRY` bit is turned on and the `EXIT` bit is turned off.
133 * Both bits are configured to be runtime modifiable.
134 *
135 * @p(code)
136 * var Diags = xdc.useModule('xdc.runtime.Diags');
137 * var Task = xdc.useModule('ti.sysbios.knl.Task');
138 *
139 * Task.common$.diags_ENTRY = Diags.RUNTIME_ON;
140 * Task.common$.diags_EXIT = Diags.RUNTIME_OFF;
141 * @p
142 *
143 * @p(html)
144 * <hr />
145 * @p
146 *
147 * Runtime example: The following C code shows how to disable and
148 * reenable `ENTER` diagnostics at runtime for the `ti.sysbios.knl.Task`
149 * module configured in the previous example. The first call to
150 * `{@link Diags#setMask Diag_setMask()}` enables entry diagnostics
151 * (`"+E"`) for just the `ti.sysbios.knl.Task` module; any call to any
152 * `Task` method in the application causes an "entry" `Log` event to be
153 * generated. The second call disables ("-E") the generation of these
154 * events. See `{@link #setMask Diags_setMask()}` for a complete
155 * description of the strings accepted by this function.
156 *
157 * @p(code)
158 * #include <xdc/runtime/Diags.h>
159 * :
160 * Diags_setMask("ti.sysbios.knl.Task+E");
161 * :
162 * Diags_setMask("ti.sysbios.knl.Task-E");
163 * @p
164 *
165 * @p(html)
166 * <hr />
167 * @p
168 *
169 * Configuration example: The following XDC configuration statements
170 * turn on asserts in the entire program.
171 *
172 * @p(code)
173 * var Diags = xdc.useModule('xdc.runtime.Diags');
174 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
175 *
176 * Defaults.diags_ASSERT = Diags.ALWAYS_ON;
177 * @p
178 *
179 * @p(html)
180 * <hr />
181 * @p
182 *
183 * Configuration example: Using the
184 * `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function, the
185 * following XDC configuration statements turn on asserts in all
186 * of the modules whose name begins with "`ti.sysbios.`" In this case,
187 * no change to the application code is necessary to enable these
188 * events. It is important to note that, while the configuration
189 * step must be re-run and the application must be re-linked, no
190 * application sources need to be recompiled.
191 *
192 * @p(code)
193 * var Diags = xdc.useModule('xdc.runtime.Diags');
194 * Diags.setMaskMeta("ti.sysbios.%", Diags.ASSERT, Diags.ALWAYS_ON);
195 * @p
196 */
197
198 @CustomHeader
199 @Template("./Diags.xdt")
200 @DirectCall
201 @RomConsts
202
203 module Diags {
204
205 /*!
206 * ======== Mode ========
207 * Diagnostics mask bit value used at configuration time.
208 *
209 * At run-time a module's diagnostics mask is an ordinary data word
210 * with each bit value being 0 or 1 indicating whether or not the
211 * corresponding diagnostic is disabled or enabled. At configuration
212 * time, however, each bit of the diagnostics mask can be
213 * placed in one of several `Mode`s; these modes determine its initial
214 * runtime value and whether or not the bit is modifiable at runtime.
215 *
216 * When setting a module's diagnostics mask at configuration time,
217 * use one of the enumerated values of type `Mode`. These
218 * values will either set or clear a bit in the mask and also define
219 * if the bit can be changed at run-time. For example, using
220 * `ALWAYS_OFF` as the bit value means that bit cannot be set
221 * at run-time. This fact can be used by an optimizer to perform
222 * constant-folding and dead-code elimination.
223 */
224 metaonly enum Mode {
225 ALWAYS_OFF, //! permanently disabled
226 ALWAYS_ON, //! permanently enabled
227 RUNTIME_OFF, //! run-time settable, initially disabled
228 RUNTIME_ON //! run-time settable, initially enabled
229 };
230
231 /*! Type used to specify bits in the diags mask. */
232 typedef Types.DiagsMask Mask;
233
234 const Mask ENTRY = 0x0001; //! Function entry
235 const Mask EXIT = 0x0002; //! Function exit
236 const Mask LIFECYCLE = 0x0004; //! Object life-cycle
237 const Mask INTERNAL = 0x0008; //! Internal diagnostics
238
239 const Mask ASSERT = 0x0010; //! Assert checking
240
241 const Mask STATUS = 0x0080; //! Warning or error event
242
243 /*! @_nodoc */
244 const Mask LEVEL = 0x0060; //! Mask to retrieve the level bits
245
246 const Mask USER1 = 0x0100; //! User defined diagnostics
247 const Mask USER2 = 0x0200; //! User defined diagnostics
248 const Mask USER3 = 0x0400; //! User defined diagnostics
249 const Mask USER4 = 0x0800; //! User defined diagnostics
250
251 const Mask USER5 = 0x1000; //! User defined diagnostics
252 const Mask USER6 = 0x2000; //! User defined diagnostics
253 const Mask USER7 = 0x4000; //! Alias for informational event
254 const Mask INFO = USER7; //! Informational event
255 const Mask USER8 = 0x8000; //! Alias for analysis event
256 const Mask ANALYSIS = USER8; //! Analysis (e.g., benchmark) event
257
258 /*!
259 * ======== ALL ========
260 * Mask of all diagnostics categories, including both logging and asserts
261 */
262 const Mask ALL = 0xFF9F;
263
264 /*!
265 * ======== ALL_LOGGING ========
266 * Mask of all logging diagnostic categories (does not include asserts)
267 */
268 const Mask ALL_LOGGING = ALL & (~ASSERT) & (~INTERNAL);
269
270 /*!
271 * ======== EventLevel =========
272 * The level of an event.
273 *
274 * The diagnostics bits each represent a different category of event,
275 * for example: an analysis event, a lifecycle event, or an informational
276 * event. Within each of these categories, events may have one of four
277 * levels to enable filtering based on the level of information desired.
278 *
279 * The meaning of these levels and the distinction between them is left
280 * open to the user. Depending on the meaning given, different terminology
281 * may be used to describe them--they may be levels of detail, priority,
282 * severity, etc. The heirarchy of the events is set such that `LEVEL1` is
283 * the highest priority and `LEVEL4` is the lowest. That is, enabling
284 * `LEVEL4` events implies that events of all four levels will be logged.
285 * @p(dlist)
286 * - `LEVEL1`
287 * Least detail, highest priority, most severe, etc.
288 * - `LEVEL2`
289 * - `LEVEL3`
290 * - `LEVEL4`
291 * Most detail, lowest priority, least severe, etc.
292 * @p
293 * The `STATUS` bit is the only category where the levels are given
294 * explicit meaning to ensure consistency. Within the `STATUS` category,
295 * the meaning of the levels is defined by the constants `EMERGENCY`,
296 * `CRITICAL`, `ERROR`, and `WARNING`.
297 *
298 * Events which don't define a level will receive `LEVEL1` by default.
299 */
300 enum EventLevel {
301 LEVEL1 = 0x0,
302 LEVEL2 = 0x20,
303 LEVEL3 = 0x40,
304 LEVEL4 = 0x60
305 };
306
307 /*!
308 * ======== EMERGENCY ========
309 * A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'
310 *
311 * For STATUS events only, the meaning of the four EventLevels has been
312 * defined. These constants are simply aliases for the four event levels.
313 *
314 * The highest three levels are different severities of an error event.
315 * For example, an EMERGENCY event may represent an unrecoverable system
316 * failure, a CRITICAL event may require notification of an operator,
317 * and an ERROR may be a recoverable error.
318 *
319 * The lowest level is reserved for warnings, such as when a resource
320 * becomes dangerously low.
321 */
322 const EventLevel EMERGENCY = LEVEL1;
323
324 /*!
325 * ======== CRITICAL ========
326 * A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'
327 *
328 * See '{@link #EMERGENCY}' for details.
329 */
330 const EventLevel CRITICAL = LEVEL2;
331
332 /*!
333 * ======== ERROR ========
334 * A 'LEVEL3' 'STATUS' event is defined as 'ERROR'
335 *
336 * See '{@link #EMERGENCY}' for details.
337 */
338 const EventLevel ERROR = LEVEL3;
339
340 /*!
341 * ======== WARNING ========
342 * A 'LEVEL4' 'STATUS' event is defined as 'WARNING'
343 *
344 * See '{@link #EMERGENCY}' for details.
345 */
346 const EventLevel WARNING = LEVEL4;
347
348 /*!
349 * ======== DiagsMaskView ========
350 * @_nodoc
351 */
352 metaonly struct DiagsMaskView {
353 String Module;
354 String logger;
355 String USER1;
356 String USER2;
357 String USER3;
358 String USER4;
359 String USER5;
360 String USER6;
361 String INFO;
362 String ANALYSIS;
363 String STATUS;
364 String ENTRY;
365 String EXIT;
366 String LIFECYCLE;
367 String INTERNAL;
368 String ASSERT;
369 }
370
371 /*!
372 * ======== rovViewInfo ========
373 * @_nodoc
374 */
375 @Facet
376 metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
377 xdc.rov.ViewInfo.create({
378 viewMap: [
379 ['DiagsMasks',
380 {
381 type: xdc.rov.ViewInfo.TREE_TABLE,
382 viewInitFxn: 'viewInitDiagsMasks',
383 structName: 'DiagsMaskView'
384 }
385 ]
386 ]
387 });
388
389 /*!
390 * ======== query ========
391 * Query the module's diagnostics mask against the given mask
392 *
393 * Use this query function to test the state of a module's
394 * diagnostics mask at runtime. This function will perform a logical
395 * `AND` operation on the module's diagnostics mask and the given mask.
396 * If any bits survive the operation, the function returns `true`.
397 *
398 * @p(code)
399 * result = moduleMask & givenMask ? true : false;
400 * @p
401 *
402 * This query function has a compile-time binding to the module's
403 * diagnostics mask. If the query function is part of the C code
404 * implementation of a module, then it will use that module's
405 * diagnostics mask. Otherwise, it will use the diagnostics mask
406 * of the `{@link Main xdc.runtime.Main}` module.
407 *
408 * The implementation of the diagnostics mask and the query function
409 * is such that an optimizer can take advantage of dead code elimination
410 * and/or constant folding to eliminate or reduce code size. For example,
411 * if the query function is used in a conditional test, and the given
412 * mask contains only bits which have been configured to be permanently
413 * off, then the code for the entire conditional statement can be removed
414 * at link time. If the bits in the given mask have been configured to be
415 * permanently on, then the conditional code can be removed leaving the
416 * body of the conditional as direct in-line code.
417 *
418 * @param(mask) mask of diagnostics bits to test
419 *
420 * This given mask is constructed by `OR`'ing together
421 * the desired bits of the diagnostics mask using the constants listed
422 * in the {@link #ALL Mask Summary} above. The module's diagnostics
423 * mask will be logically `AND`'ed with the given mask, and return `true`
424 * if the result is non-zero and `false` otherwise.
425 *
426 * @p(code)
427 * if (Diags_query(Diags_USER1 | Diags_USER4)) {
428 * :
429 * }
430 * @p
431 *
432 * @a(Examples)
433 * In the following example, the `{@link #USER1 USER1}` bit of the
434 * module's diagnostics mask has been configured to be permanently off,
435 * thus the entire conditional code block can be removed at link time.
436 * Note, the C code below is part of the module itself.
437 *
438 * Configuration Script
439 * @p(code)
440 * var Diags = xdc.useModule('xdc.runtime.Diags');
441 * var ModA = xdc.useModule('my.package.ModuleA');
442 * ModA.common$.diags_USER1 = Diags.ALWAYS_OFF;
443 * @p
444 *
445 * C Code, ModA.c
446 * @p(code)
447 * if (Diags_query(Diags_USER1)) { // this code removed
448 * ...additional code here... // this code removed
449 * } // this code removed
450 * @p
451 *
452 * @p(html)
453 * <hr />
454 * @p
455 *
456 * In the following example, the `{@link #USER1 USER1}` bit of the
457 * module's diagnostics mask has been configured to be permanently on,
458 * thus the conditional code can be removed leaving the code contained
459 * within the conditional statement. Note, the C code below is part of
460 * the module itself.
461 *
462 * Configuration Script
463 * @p(code)
464 * var Diags = xdc.useModule('xdc.runtime.Diags');
465 * var ModA = xdc.useModule('my.package.ModuleA');
466 * ModA.common$.diags_USER1 = Diags.ALWAYS_ON;
467 * @p
468 *
469 * C Code, ModA.c
470 * @p(code)
471 * if (Diags_query(Diags_USER1) { // this code removed
472 * ...additional code here... // this code remains
473 * } // this code removed
474 * @p
475 *
476 */
477 @Macro Bool query(Mask mask);
478
479 /*!
480 * ======== getLevel ========
481 * Get the event level set in the given mask
482 *
483 * See '{@link #EventLevel}' for a description of event levels.
484 *
485 * @param(mask) mask of diagnostics bits to read filter level from.
486 */
487 @Macro EventLevel getLevel(Mask mask);
488
489 /*!
490 * ========= compareLevels ========
491 * Returns false if levelA is lower than levelB
492 *
493 * This API is intended to be used to determine if a given event
494 * passes a filtering threshold and should be logged. Conceptually (though
495 * not necessarily in implementation), this API is equivalent to the
496 * expression (levelA < levelB). The values of the EventLevels have
497 * internal meaning, so a direct comparison of two levels should not done;
498 * this API must be used to correctly compare them.
499 *
500 * LEVEL1 is the highest level and LEVEL4 is the lowest. So LEVEL4 is
501 * less than LEVEL3, which is less than LEVEL2, which is less than LEVEL1.
502 */
503 @Macro Bool compareLevels(EventLevel levelA, EventLevel levelB);
504
505 /*!
506 * ======== setMask ========
507 * Set a module's diagnostics mask at runtime
508 *
509 * Use the given control string to set or clear bits in a module's
510 * diagnostics mask. The control string defines one or more actions
511 * where each action modifies the diagnostics mask in one or more
512 * modules. Each action can either set, clear, or assign a module's
513 * diagnostics mask. To both set and clear bits in the same diagnostics
514 * mask requires two actions, or you can assign the entire mask
515 * explicitly in one action. Each action can specify a given module or
516 * a set of modules using name prefix matching.
517 *
518 * @a(Warning)
519 *
520 * Each bit of a module's diagnostics mask that is to be modified at
521 * runtime, must be configured to be runtime modifiable in the
522 * program's configuration script. Use either `{@link #Mode RUNTIME_OFF}`
523 * or `{@link #Mode RUNTIME_ON}` as the configuration value for the
524 * desired bit in the diagnostics mask. Also, the following configuration
525 * parameters must have the values indicated (which are their default
526 * values):
527 *
528 * @p(blist)
529 * - `{@link IModule#common$ <module>.common$.namedModule} = true;`
530 * - `{@link Text#isLoaded} = true;`
531 * @p
532 *
533 * Note: any error that occurs during the parsing of the control string
534 * causes `Diags_setMask()` to return without processing the remainder
535 * of the control string.
536 *
537 * @param(control) diagnostic mask control string
538 *
539 * This control string defines one or more actions
540 * where each action consists of a module name, an operator character,
541 * and a list of bit specifiers. Use the `%` character as a wildcard
542 * to turn the module name into a prefix matching pattern for a set
543 * of modules. Multiple actions are separated with the `;` character.
544 *
545 * @p
546 * The control string has the following format:
547 *
548 * @p(code)
549 * <module[%]><op><bits>[;<module[%]><op><bits>]
550 * @p
551 *
552 * Specify individual module names explicitly (e.g.
553 * `ti.sysbios.knl.Task`), or match multiple modules using a prefix
554 * matching pattern specified with the `%` character (e.g.
555 * `ti.sysbios.knl.%`).
556 *
557 * @p
558 * The operator is specified with a single character from the following
559 * table.
560 *
561 * @p(code)
562 * Operator Description
563 * --------------------------------------------------
564 * + Set only the specified bits (other bits preserved)
565 * - Clear only the specified bits (other bits preserved)
566 * = Assign the entire mask to the given value where the
567 * specified bits are set and all other bits are cleared
568 * @p
569 *
570 * The bits are specified with a list of characters from the following
571 * table. Refer to the {@link #ALL Mask Summary} for a list of each
572 * bit of the diagnostics mask.
573 *
574 * @p(code)
575 * Control Diagnostics
576 * Character Constant Description
577 * --------------------------------------------------
578 * E ENTRY Function entry
579 * X EXIT Function exit
580 * L LIFECYCLE Object life-cycle
581 * I INTERNAL Internal diagnostics
582 * A ASSERT Assert checking
583 * Z ANALYSIS Analysis event
584 * F INFO Informational event
585 * S STATUS Status (error, warning) event
586 * 1 USER1 User defined diagnostics
587 * 2 USER2 User defined diagnostics
588 * 3 USER3 User defined diagnostics
589 * 4 USER4 User defined diagnostics
590 * 5 USER5 User defined diagnostics
591 * 6 USER6 User defined diagnostics
592 * 7 USER7 User defined diagnostics
593 * 8 USER8 User defined diagnostics
594 * @p
595 *
596 * @a(Examples)
597 * The following example demonstrates how to set a module's diagnostics
598 * mask (the `Task` module in this case) at runtime. In this example, the
599 * `{@link #USER1 USER1}` bit is turned on. Note that the module's
600 * `{@link #USER1 USER1}` diagnostics bit must be configured to be runtime
601 * modifiable. In this instance, the bit is initialized to off.
602 *
603 * Configuration Script
604 * @p(code)
605 * var Diags = xdc.useModule('xdc.runtime.Diags');
606 * var Task = xdc.useModule('ti.sysbios.knl.Task');
607 * Task.common$.diags_USER1 = Diags.RUNTIME_OFF;
608 * @p
609 *
610 * C Code
611 * @p(code)
612 * Diags_setMask("ti.sysbios.knl.Task+1");
613 * @p
614 *
615 * @p(html)
616 * <hr />
617 * @p
618 *
619 * The following example demonstrates the use of the `%` wildcard
620 * character to set the `{@link #USER1 USER1}` bit at runtime for
621 * all modules in the `ti.sysbios.knl` package. The meta-only
622 * `{@link #setMaskMeta Diags.setMaskMeta}` function is used to configure
623 * the `{@link #USER1 USER1}` bit to be runtime modifiable. The `setMask`
624 * function is used to actually set the `{@link #USER1 USER1}` bit at
625 * runtime in all the `ti.sysbios.knl` modules.
626 * Note the use of the `%` character in both functions to match all the
627 * module names within the given package.
628 *
629 * Configuration Script
630 * @p(code)
631 * var Diags = xdc.useModule('xdc.runtime.Diags');
632 * Diags.setMaskMeta("ti.sysbios.knl.%", Diags.USER1, Diags.RUNTIME_OFF);
633 * @p
634 *
635 * C Code
636 * @p(code)
637 * Diags_setMask("ti.sysbios.knl.%+1");
638 * @p
639 *
640 * @p(html)
641 * <hr />
642 * @p
643 *
644 * In the following example, the `{@link #ENTRY ENTRY}`,
645 * `{@link #EXIT EXIT}` and `{@link #LIFECYCLE LIFECYCLE}` trace is
646 * enabled for all modules in the `ti.sysbios.knl` package but is
647 * initially off; i.e., no events will occur until explicitly turned
648 * on at runtime.
649 *
650 * At runtime the call to `Diags_setMask` turns on
651 * `{@link #ENTRY ENTRY}` and `{@link #EXIT EXIT}` trace and turns off
652 * `{@link #LIFECYCLE LIFECYCLE}` trace for all modules in
653 * the application for which trace has been enabled during
654 * configuration. In this case, the only modules that can generate
655 * events are those in the `ti.sysbios.knl` package.
656 *
657 * Configuration Script
658 * @p(code)
659 * var Diags = xdc.useModule('xdc.runtime.Diags');
660 * Diags.setMaskMeta("ti.sysbios.knl.%",
661 * Diags.ENTRY | Diags.EXIT | Diags.LIFECYCLE, Diags.RUNTIME_OFF);
662 * @p
663 *
664 * C Code
665 * @p(code)
666 * Diags_setMask("%+EX;%-L");
667 * @p
668 */
669 Void setMask(CString control);
670
671 /*!
672 * ======== setMaskMeta ========
673 * Set the module's diagnostics mask at config time
674 *
675 * @param(pattern) module prefix or regular expression
676 *
677 * The `pattern` is used to match a module's name. If `pattern` is
678 * specified as a string, then name prefix matching is used. The
679 * pattern may also be a regular expression. Only the masks of the
680 * modules matching `pattern` are set.
681 *
682 * @param(mask) diagnostic fields to modify
683 *
684 * The `mask` is used to determine which fields in the diags mask are
685 * modified. Each field specified in the mask is set to the given
686 * `mode` value.
687 *
688 * @param(mode) mode to assign to the specified `mask` fields
689 */
690 metaonly Void setMaskMeta(Any pattern, Mask mask, Mode mode);
691
692 internal:
693
694 /*!
695 * ======== setMaskEnabled ========
696 * Controls the ability to set the diags mask at run-time
697 *
698 * This configuration parameter allows whole program optimizers to reduce
699 * the code size. The default is `false`, which means the diags mask will
700 * not be modified at run-time and thus the code is not needed.
701 *
702 * For now, this should be internal because its value is determined
703 * automatically, rather than through user's input. See CQ19111 for more
704 * details.
705 */
706 config Bool setMaskEnabled = false;
707
708 709 710 711 712 713 714
715 config DictElem *dictBase = null;
716
717 struct DictElem {
718 Types.ModuleId modId;
719 Mask *maskAddr;
720 };
721 }
722 723 724
725