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. In addition, the
523 * `{@link Diags#setMaskEnabled Diags.setMaskEnabled}` configuration
524 * parameter must be set to `true` in order to load this function onto
525 * the target. Finally, the following configuration parameters must
526 * have the values indicated (which are their default 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(String 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 * ======== dictBase ========
710 * Array of module-id:diags-mask pairs in which each module is named
711 *
712 * This array, generated by Diags.xdt, is terminated by an element
713 * with modId == 0.
714 */
715 config DictElem *dictBase = null;
716
717 struct DictElem {
718 Types.ModuleId modId; /* statically computed module id */
719 Mask *maskAddr; /* module's diags mask address */
720 };
721 }
722 /*
723 * @(#) xdc.runtime; 2, 1, 0,359; 11-16-2011 11:00:14; /db/ztree/library/trees/xdc/xdc-y13x/src/packages/
724 */
725