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
202 module Diags {
203
204 /*!
205 * ======== Mode ========
206 * Diagnostics mask bit value used at configuration time.
207 *
208 * At run-time a module's diagnostics mask is an ordinary data word
209 * with each bit value being 0 or 1 indicating whether or not the
210 * corresponding diagnostic is disabled or enabled. At configuration
211 * time, however, each bit of the diagnostics mask can be
212 * placed in one of several `Mode`s; these modes determine its initial
213 * runtime value and whether or not the bit is modifiable at runtime.
214 *
215 * When setting a module's diagnostics mask at configuration time,
216 * use one of the enumerated values of type `Mode`. These
217 * values will either set or clear a bit in the mask and also define
218 * if the bit can be changed at run-time. For example, using
219 * `ALWAYS_OFF` as the bit value means that bit cannot be set
220 * at run-time. This fact can be used by an optimizer to perform
221 * constant-folding and dead-code elimination.
222 */
223 metaonly enum Mode {
224 ALWAYS_OFF, //! permanently disabled
225 ALWAYS_ON, //! permanently enabled
226 RUNTIME_OFF, //! run-time settable, initially disabled
227 RUNTIME_ON //! run-time settable, initially enabled
228 };
229
230 /*! Type used to specify bits in the diags mask. */
231 typedef Types.DiagsMask Mask;
232
233 const Mask ENTRY = 0x0001; //! Function entry
234 const Mask EXIT = 0x0002; //! Function exit
235 const Mask LIFECYCLE = 0x0004; //! Object life-cycle
236 const Mask INTERNAL = 0x0008; //! Internal diagnostics
237
238 const Mask ASSERT = 0x0010; //! Assert checking
239
240 const Mask STATUS = 0x0080; //! Warning or error event
241
242 /*! @_nodoc */
243 const Mask LEVEL = 0x0060; //! Mask to retrieve the level bits
244
245 const Mask USER1 = 0x0100; //! User defined diagnostics
246 const Mask USER2 = 0x0200; //! User defined diagnostics
247 const Mask USER3 = 0x0400; //! User defined diagnostics
248 const Mask USER4 = 0x0800; //! User defined diagnostics
249
250 const Mask USER5 = 0x1000; //! User defined diagnostics
251 const Mask USER6 = 0x2000; //! User defined diagnostics
252 const Mask USER7 = 0x4000; //! Alias for informational event
253 const Mask INFO = USER7; //! Informational event
254 const Mask USER8 = 0x8000; //! Alias for analysis event
255 const Mask ANALYSIS = USER8; //! Analysis (e.g., benchmark) event
256
257 /*!
258 * ======== ALL ========
259 * Mask of all diagnostics categories, including both logging and asserts
260 */
261 const Mask ALL = 0xFF9F;
262
263 /*!
264 * ======== ALL_LOGGING ========
265 * Mask of all logging diagnostic categories (does not include asserts)
266 */
267 const Mask ALL_LOGGING = ALL & (~ASSERT) & (~INTERNAL);
268
269 /*!
270 * ======== EventLevel =========
271 * The level of an event.
272 *
273 * The diagnostics bits each represent a different category of event,
274 * for example: an analysis event, a lifecycle event, or an informational
275 * event. Within each of these categories, events may have one of four
276 * levels to enable filtering based on the level of information desired.
277 *
278 * The meaning of these levels and the distinction between them is left
279 * open to the user. Depending on the meaning given, different terminology
280 * may be used to describe them--they may be levels of detail, priority,
281 * severity, etc. The heirarchy of the events is set such that `LEVEL1` is
282 * the highest priority and `LEVEL4` is the lowest. That is, enabling
283 * `LEVEL4` events implies that events of all four levels will be logged.
284 * @p(dlist)
285 * - `LEVEL1`
286 * Least detail, highest priority, most severe, etc.
287 * - `LEVEL2`
288 * - `LEVEL3`
289 * - `LEVEL4`
290 * Most detail, lowest priority, least severe, etc.
291 * @p
292 * The `STATUS` bit is the only category where the levels are given
293 * explicit meaning to ensure consistency. Within the `STATUS` category,
294 * the meaning of the levels is defined by the constants `EMERGENCY`,
295 * `CRITICAL`, `ERROR`, and `WARNING`.
296 *
297 * Events which don't define a level will receive `LEVEL1` by default.
298 */
299 enum EventLevel {
300 LEVEL1 = 0x0,
301 LEVEL2 = 0x20,
302 LEVEL3 = 0x40,
303 LEVEL4 = 0x60
304 };
305
306 /*!
307 * ======== EMERGENCY ========
308 * A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'
309 *
310 * For STATUS events only, the meaning of the four EventLevels has been
311 * defined. These constants are simply aliases for the four event levels.
312 *
313 * The highest three levels are different severities of an error event.
314 * For example, an EMERGENCY event may represent an unrecoverable system
315 * failure, a CRITICAL event may require notification of an operator,
316 * and an ERROR may be a recoverable error.
317 *
318 * The lowest level is reserved for warnings, such as when a resource
319 * becomes dangerously low.
320 */
321 const EventLevel EMERGENCY = LEVEL1;
322
323 /*!
324 * ======== CRITICAL ========
325 * A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'
326 *
327 * See '{@link #EMERGENCY}' for details.
328 */
329 const EventLevel CRITICAL = LEVEL2;
330
331 /*!
332 * ======== ERROR ========
333 * A 'LEVEL3' 'STATUS' event is defined as 'ERROR'
334 *
335 * See '{@link #EMERGENCY}' for details.
336 */
337 const EventLevel ERROR = LEVEL3;
338
339 /*!
340 * ======== WARNING ========
341 * A 'LEVEL4' 'STATUS' event is defined as 'WARNING'
342 *
343 * See '{@link #EMERGENCY}' for details.
344 */
345 const EventLevel WARNING = LEVEL4;
346
347 /*!
348 * ======== DiagsMaskView ========
349 * @_nodoc
350 */
351 metaonly struct DiagsMaskView {
352 String Module;
353 String logger;
354 String USER1;
355 String USER2;
356 String USER3;
357 String USER4;
358 String USER5;
359 String USER6;
360 String INFO;
361 String ANALYSIS;
362 String STATUS;
363 String ENTRY;
364 String EXIT;
365 String LIFECYCLE;
366 String INTERNAL;
367 String ASSERT;
368 }
369
370 /*!
371 * ======== rovViewInfo ========
372 * @_nodoc
373 */
374 @Facet
375 metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
376 xdc.rov.ViewInfo.create({
377 viewMap: [
378 ['DiagsMasks',
379 {
380 type: xdc.rov.ViewInfo.TREE_TABLE,
381 viewInitFxn: 'viewInitDiagsMasks',
382 structName: 'DiagsMaskView'
383 }
384 ]
385 ]
386 });
387
388 /*!
389 * ======== query ========
390 * Query the module's diagnostics mask against the given mask
391 *
392 * Use this query function to test the state of a module's
393 * diagnostics mask at runtime. This function will perform a logical
394 * `AND` operation on the module's diagnostics mask and the given mask.
395 * If any bits survive the operation, the function returns `true`.
396 *
397 * @p(code)
398 * result = moduleMask & givenMask ? true : false;
399 * @p
400 *
401 * This query function has a compile-time binding to the module's
402 * diagnostics mask. If the query function is part of the C code
403 * implementation of a module, then it will use that module's
404 * diagnostics mask. Otherwise, it will use the diagnostics mask
405 * of the `{@link Main xdc.runtime.Main}` module.
406 *
407 * The implementation of the diagnostics mask and the query function
408 * is such that an optimizer can take advantage of dead code elimination
409 * and/or constant folding to eliminate or reduce code size. For example,
410 * if the query function is used in a conditional test, and the given
411 * mask contains only bits which have been configured to be permanently
412 * off, then the code for the entire conditional statement can be removed
413 * at link time. If the bits in the given mask have been configured to be
414 * permanently on, then the conditional code can be removed leaving the
415 * body of the conditional as direct in-line code.
416 *
417 * @param(mask) mask of diagnostics bits to test
418 *
419 * This given mask is constructed by `OR`'ing together
420 * the desired bits of the diagnostics mask using the constants listed
421 * in the {@link #ALL Mask Summary} above. The module's diagnostics
422 * mask will be logically `AND`'ed with the given mask, and return `true`
423 * if the result is non-zero and `false` otherwise.
424 *
425 * @p(code)
426 * if (Diags_query(Diags_USER1 | Diags_USER4)) {
427 * :
428 * }
429 * @p
430 *
431 * @a(Examples)
432 * In the following example, the `{@link #USER1 USER1}` bit of the
433 * module's diagnostics mask has been configured to be permanently off,
434 * thus the entire conditional code block can be removed at link time.
435 * Note, the C code below is part of the module itself.
436 *
437 * Configuration Script
438 * @p(code)
439 * var Diags = xdc.useModule('xdc.runtime.Diags');
440 * var ModA = xdc.useModule('my.package.ModuleA');
441 * ModA.common$.diags_USER1 = Diags.ALWAYS_OFF;
442 * @p
443 *
444 * C Code, ModA.c
445 * @p(code)
446 * if (Diags_query(Diags_USER1)) { // this code removed
447 * ...additional code here... // this code removed
448 * } // this code removed
449 * @p
450 *
451 * @p(html)
452 * <hr />
453 * @p
454 *
455 * In the following example, the `{@link #USER1 USER1}` bit of the
456 * module's diagnostics mask has been configured to be permanently on,
457 * thus the conditional code can be removed leaving the code contained
458 * within the conditional statement. Note, the C code below is part of
459 * the module itself.
460 *
461 * Configuration Script
462 * @p(code)
463 * var Diags = xdc.useModule('xdc.runtime.Diags');
464 * var ModA = xdc.useModule('my.package.ModuleA');
465 * ModA.common$.diags_USER1 = Diags.ALWAYS_ON;
466 * @p
467 *
468 * C Code, ModA.c
469 * @p(code)
470 * if (Diags_query(Diags_USER1) { // this code removed
471 * ...additional code here... // this code remains
472 * } // this code removed
473 * @p
474 *
475 */
476 @Macro Bool query(Mask mask);
477
478 /*!
479 * ======== getLevel ========
480 * Get the event level set in the given mask
481 *
482 * See '{@link #EventLevel}' for a description of event levels.
483 *
484 * @param(mask) mask of diagnostics bits to read filter level from.
485 */
486 @Macro EventLevel getLevel(Mask mask);
487
488 /*!
489 * ========= compareLevels ========
490 * Returns false if levelA is lower than levelB
491 *
492 * This API is intended to be used to determine if a given event
493 * passes a filtering threshold and should be logged. Conceptually (though
494 * not necessarily in implementation), this API is equivalent to the
495 * expression (levelA < levelB). The values of the EventLevels have
496 * internal meaning, so a direct comparison of two levels should not done;
497 * this API must be used to correctly compare them.
498 *
499 * LEVEL1 is the highest level and LEVEL4 is the lowest. So LEVEL4 is
500 * less than LEVEL3, which is less than LEVEL2, which is less than LEVEL1.
501 */
502 @Macro Bool compareLevels(EventLevel levelA, EventLevel levelB);
503
504 /*!
505 * ======== setMask ========
506 * Set a module's diagnostics mask at runtime
507 *
508 * Use the given control string to set or clear bits in a module's
509 * diagnostics mask. The control string defines one or more actions
510 * where each action modifies the diagnostics mask in one or more
511 * modules. Each action can either set, clear, or assign a module's
512 * diagnostics mask. To both set and clear bits in the same diagnostics
513 * mask requires two actions, or you can assign the entire mask
514 * explicitly in one action. Each action can specify a given module or
515 * a set of modules using name prefix matching.
516 *
517 * @a(Warning)
518 *
519 * Each bit of a module's diagnostics mask that is to be modified at
520 * runtime, must be configured to be runtime modifiable in the
521 * program's configuration script. Use either `{@link #Mode RUNTIME_OFF}`
522 * or `{@link #Mode RUNTIME_ON}` as the configuration value for the
523 * desired bit in the diagnostics mask. Also, the following configuration
524 * parameters must have the values indicated (which are their default
525 * values):
526 *
527 * @p(blist)
528 * - `{@link IModule#common$ <module>.common$.namedModule} = true;`
529 * - `{@link Text#isLoaded} = true;`
530 * @p
531 *
532 * Note: any error that occurs during the parsing of the control string
533 * causes `Diags_setMask()` to return without processing the remainder
534 * of the control string.
535 *
536 * @param(control) diagnostic mask control string
537 *
538 * This control string defines one or more actions
539 * where each action consists of a module name, an operator character,
540 * and a list of bit specifiers. Use the `%` character as a wildcard
541 * to turn the module name into a prefix matching pattern for a set
542 * of modules. Multiple actions are separated with the `;` character.
543 *
544 * @p
545 * The control string has the following format:
546 *
547 * @p(code)
548 * <module[%]><op><bits>[;<module[%]><op><bits>]
549 * @p
550 *
551 * Specify individual module names explicitly (e.g.
552 * `ti.sysbios.knl.Task`), or match multiple modules using a prefix
553 * matching pattern specified with the `%` character (e.g.
554 * `ti.sysbios.knl.%`).
555 *
556 * @p
557 * The operator is specified with a single character from the following
558 * table.
559 *
560 * @p(code)
561 * Operator Description
562 * --------------------------------------------------
563 * + Set only the specified bits (other bits preserved)
564 * - Clear only the specified bits (other bits preserved)
565 * = Assign the entire mask to the given value where the
566 * specified bits are set and all other bits are cleared
567 * @p
568 *
569 * The bits are specified with a list of characters from the following
570 * table. Refer to the {@link #ALL Mask Summary} for a list of each
571 * bit of the diagnostics mask.
572 *
573 * @p(code)
574 * Control Diagnostics
575 * Character Constant Description
576 * --------------------------------------------------
577 * E ENTRY Function entry
578 * X EXIT Function exit
579 * L LIFECYCLE Object life-cycle
580 * I INTERNAL Internal diagnostics
581 * A ASSERT Assert checking
582 * Z ANALYSIS Analysis event
583 * F INFO Informational event
584 * S STATUS Status (error, warning) event
585 * 1 USER1 User defined diagnostics
586 * 2 USER2 User defined diagnostics
587 * 3 USER3 User defined diagnostics
588 * 4 USER4 User defined diagnostics
589 * 5 USER5 User defined diagnostics
590 * 6 USER6 User defined diagnostics
591 * 7 USER7 User defined diagnostics
592 * 8 USER8 User defined diagnostics
593 * @p
594 *
595 * @a(Examples)
596 * The following example demonstrates how to set a module's diagnostics
597 * mask (the `Task` module in this case) at runtime. In this example, the
598 * `{@link #USER1 USER1}` bit is turned on. Note that the module's
599 * `{@link #USER1 USER1}` diagnostics bit must be configured to be runtime
600 * modifiable. In this instance, the bit is initialized to off.
601 *
602 * Configuration Script
603 * @p(code)
604 * var Diags = xdc.useModule('xdc.runtime.Diags');
605 * var Task = xdc.useModule('ti.sysbios.knl.Task');
606 * Task.common$.diags_USER1 = Diags.RUNTIME_OFF;
607 * @p
608 *
609 * C Code
610 * @p(code)
611 * Diags_setMask("ti.sysbios.knl.Task+1");
612 * @p
613 *
614 * @p(html)
615 * <hr />
616 * @p
617 *
618 * The following example demonstrates the use of the `%` wildcard
619 * character to set the `{@link #USER1 USER1}` bit at runtime for
620 * all modules in the `ti.sysbios.knl` package. The meta-only
621 * `{@link #setMaskMeta Diags.setMaskMeta}` function is used to configure
622 * the `{@link #USER1 USER1}` bit to be runtime modifiable. The `setMask`
623 * function is used to actually set the `{@link #USER1 USER1}` bit at
624 * runtime in all the `ti.sysbios.knl` modules.
625 * Note the use of the `%` character in both functions to match all the
626 * module names within the given package.
627 *
628 * Configuration Script
629 * @p(code)
630 * var Diags = xdc.useModule('xdc.runtime.Diags');
631 * Diags.setMaskMeta("ti.sysbios.knl.%", Diags.USER1, Diags.RUNTIME_OFF);
632 * @p
633 *
634 * C Code
635 * @p(code)
636 * Diags_setMask("ti.sysbios.knl.%+1");
637 * @p
638 *
639 * @p(html)
640 * <hr />
641 * @p
642 *
643 * In the following example, the `{@link #ENTRY ENTRY}`,
644 * `{@link #EXIT EXIT}` and `{@link #LIFECYCLE LIFECYCLE}` trace is
645 * enabled for all modules in the `ti.sysbios.knl` package but is
646 * initially off; i.e., no events will occur until explicitly turned
647 * on at runtime.
648 *
649 * At runtime the call to `Diags_setMask` turns on
650 * `{@link #ENTRY ENTRY}` and `{@link #EXIT EXIT}` trace and turns off
651 * `{@link #LIFECYCLE LIFECYCLE}` trace for all modules in
652 * the application for which trace has been enabled during
653 * configuration. In this case, the only modules that can generate
654 * events are those in the `ti.sysbios.knl` package.
655 *
656 * Configuration Script
657 * @p(code)
658 * var Diags = xdc.useModule('xdc.runtime.Diags');
659 * Diags.setMaskMeta("ti.sysbios.knl.%",
660 * Diags.ENTRY | Diags.EXIT | Diags.LIFECYCLE, Diags.RUNTIME_OFF);
661 * @p
662 *
663 * C Code
664 * @p(code)
665 * Diags_setMask("%+EX;%-L");
666 * @p
667 */
668 Void setMask(CString control);
669
670 /*!
671 * ======== setMaskMeta ========
672 * Set the module's diagnostics mask at config time
673 *
674 * @param(pattern) module prefix or regular expression
675 *
676 * The `pattern` is used to match a module's name. If `pattern` is
677 * specified as a string, then name prefix matching is used. The
678 * pattern may also be a regular expression. Only the masks of the
679 * modules matching `pattern` are set.
680 *
681 * @param(mask) diagnostic fields to modify
682 *
683 * The `mask` is used to determine which fields in the diags mask are
684 * modified. Each field specified in the mask is set to the given
685 * `mode` value.
686 *
687 * @param(mode) mode to assign to the specified `mask` fields
688 */
689 metaonly Void setMaskMeta(Any pattern, Mask mask, Mode mode);
690
691 internal:
692
693 /*!
694 * ======== setMaskEnabled ========
695 * Controls the ability to set the diags mask at run-time
696 *
697 * This configuration parameter allows whole program optimizers to reduce
698 * the code size. The default is `false`, which means the diags mask will
699 * not be modified at run-time and thus the code is not needed.
700 *
701 * For now, this should be internal because its value is determined
702 * automatically, rather than through user's input. See CQ19111 for more
703 * details.
704 */
705 config Bool setMaskEnabled = false;
706
707 708 709 710 711 712 713
714 config DictElem *dictBase = null;
715
716 struct DictElem {
717 Types.ModuleId modId;
718 Mask *maskAddr;
719 };
720 }
721 722 723
724