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