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