1 2 3 4 5 6 7 8 9 10 11 12
13 14 15 16 17 18 19 20
21
22 /*!
23 * ======== Diags ========
24 * Diagnostics manager
25 *
26 * Every XDC module has a "diagnostics mask" that allows clients to
27 * enable or disable diagnostics on a per module basis both at
28 * configuration time and at runtime. The `Diags` module manages a
29 * module's diagnostics mask.
30 *
31 * You use the `Diags` module to set and clear bits in a module's
32 * diagnostics mask for the purpose of controlling diagnostics
33 * within that module. Each bit corresponds to a "type" of diagnostic
34 * that can be individually enabled or disabled.
35 *
36 * A module's diagnostics mask controls both `{@link Assert}` and
37 * `{@link Log}` statements within that module. A module's diagnostics
38 * mask may also be used to conditionally execute blocks of code using
39 * the `{@link #query Diags_query()}` runtime function.
40 *
41 * A module's diagnostics mask can be set at configuration time and
42 * at runtime. The implementation of diagnostics is such that when they
43 * are permanently turned off at configuration time
44 * (`{@link #ALWAYS_OFF Mode.ALWAYS_OFF}`), an optimizer can
45 * completely eliminate the diagnostics code from the program. Similarly,
46 * if diagnostics are permanently turned on at configuration time
47 * (`{@link #ALWAYS_ON Mode.ALWAYS_ON}`), the optimizer can
48 * eliminate all runtime conditional checking and simply
49 * invoke the diagnostics code directly. Runtime checking of the
50 * diagnostics mask is performed only when the diagnostics are configured
51 * to be runtime modifiable (`{@link #RUNTIME_OFF Mode.RUNTIME_OFF}` or
52 * `{@link #RUNTIME_ON Mode.RUNTIME_ON}`).
53 *
54 * Each bit of the diagnostics mask is controlled by one of the following
55 * constants.
56 *
57 * @p(code)
58 * Constant Meaning
59 * --------------------------
60 * ENTRY Function entry
61 * EXIT Function exit
62 * LIFECYCLE Object life-cycle
63 * INTERNAL Internal diagnostics
64 * ASSERT Assert checking
65 * USER1 User defined diagnostics
66 * USER2 User defined diagnostics
67 * USER3 User defined diagnostics
68 * USER4 User defined diagnostics
69 * USER5 User defined diagnostics
70 * USER6 User defined diagnostics
71 * USER7 User defined diagnostics
72 * USER8 User defined diagnostics
73 * @p
74 *
75 * These constants can be used from either JavaScript configuration
76 * scripts or C code and, therefore, have two "names". For example,
77 * to reference the ENTRY constant from JavaScript you must use
78 * `Diags.ENTRY` whereas from C you would use `Diags_ENTRY`.
79 *
80 * The `ENTRY` and `EXIT` bits control Log statements at the entry and
81 * exit points, respectively, to each function within a module. This
82 * is useful for tracking the execution flow of your program.
83 *
84 * The `LIFECYCLE` bit controls `Log` statements at the create/construct
85 * and delete/destruct points of each instance object for the module.
86 * This is useful for tracking the life-cycle of a module instance object.
87 *
88 * The `ASSERT` bit controls Assert statements in a module. There are
89 * two classes of asserts:
90 *
91 * @p(blist)
92 * - Public asserts, which have an `{@link Assert#Id Assert_Id}` and
93 * are documented in the module's reference pages. These asserts are
94 * on by default and are meant to help developers validate code that
95 * invokes a module's functions.
96 * - Internal asserts, which have no `{@link Assert#Id Assert_Id}`.
97 * These asserts are off by default and are typically used only when
98 * developing code. That is, like the standard C assert() mechanism,
99 * these asserts are not part of a deployed application.
100 * @p
101 *
102 * When a module has the `ASSERT` bit set (which is set by default) in
103 * its diagnostics mask, the module executes all of its public assert
104 * statements. To enable internal asserts, you must set both the `ASSERT`
105 * and `INTERNAL` bits.
106 *
107 * The `INTERNAL` bit is used to classify diagnostic code as being internal.
108 * That is to say, this class of diagnostics is undocumented and typically
109 * not used by client software.
110 *
111 * The `USER1`-`8` bits are available to each module writer to use as he or
112 * she wishes.
113 *
114 * @a(Examples)
115 * Configuration example: The following XDC configuration statements set
116 * a module's diagnostics mask in a configuration script. (In this case,
117 * the `Task` module of the `ti.sysbios.knl` package is used.) In this
118 * example, the `ENTRY` bit is turned on and the `EXIT` bit is turned off.
119 * Both bits are configured to be runtime modifiable.
120 *
121 * @p(code)
122 * var Diags = xdc.useModule('xdc.runtime.Diags');
123 * var Task = xdc.useModule('ti.sysbios.knl.Task');
124 *
125 * Task.common$.diags_ENTRY = Diags.RUNTIME_ON;
126 * Task.common$.diags_EXIT = Diags.RUNTIME_OFF;
127 * @p
128 *
129 * @p(html)
130 * <hr />
131 * @p
132 *
133 * Runtime example: The following C code shows how to disable and
134 * reenable `ENTER` diagnostics at runtime for the `ti.sysbios.knl.Task`
135 * module configured in the previous example. The first call to
136 * `{@link Diags#setMask Diag_setMask()}` enables entry diagnostics
137 * (`"+E"`) for just the `ti.sysbios.knl.Task` module; any call to any
138 * `Task` method in the application causes an "entry" `Log` event to be
139 * generated. The second call disables ("-E") the generation of these
140 * events. See `{@link #setMask Diags_setMask()}` for a complete
141 * description of the strings accepted by this function.
142 *
143 * @p(code)
144 * #include <xdc/runtime/Diags.h>
145 * :
146 * Diags_setMask("ti.sysbios.knl.Task+E");
147 * :
148 * Diags_setMask("ti.sysbios.knl.Task-E");
149 * @p
150 *
151 * @p(html)
152 * <hr />
153 * @p
154 *
155 * Configuration example: The following XDC configuration statements
156 * turn on asserts in the entire program.
157 *
158 * @p(code)
159 * var Diags = xdc.useModule('xdc.runtime.Diags');
160 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
161 *
162 * Defaults.diags_ASSERT = Diags.ALWAYS_ON;
163 * @p
164 *
165 * @p(html)
166 * <hr />
167 * @p
168 *
169 * Configuration example: Using the
170 * `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function, the
171 * following XDC configuration statements turn on asserts in all
172 * of the modules whose name begins with "`ti.sysbios.`" In this case,
173 * no change to the application code is necessary to enable these
174 * events. It is important to note that, while the configuration
175 * step must be re-run and the application must be re-linked, no
176 * application sources need to be recompiled.
177 *
178 * @p(code)
179 * var Diags = xdc.useModule('xdc.runtime.Diags');
180 * Diags.setMaskMeta("ti.sysbios.%", Diags.ASSERT, Diags.ALWAYS_ON);
181 * @p
182 */
183
184 @CustomHeader
185 @Template("./Diags.xdt")
186
187 module Diags {
188
189 /*!
190 * ======== Mode ========
191 * Diagnostics mask bit value used at configuration time.
192 *
193 * At run-time a module's diagnostics mask is an ordinary data word
194 * with each bit value being 0 or 1 indicating whether or not the
195 * corresponding diagnostic is disabled or enabled. At configuration
196 * time, however, each bit of the diagnostics mask can be
197 * placed in one of several `Mode`s; these modes determine its initial
198 * runtime value and whether or not the bit is modifiable at runtime.
199 *
200 * When setting a module's diagnostics mask at configuration time,
201 * use one of the enumerated values of type `Mode`. These
202 * values will either set or clear a bit in the mask and also define
203 * if the bit can be changed at run-time. For example, using
204 * `ALWAYS_OFF` as the bit value means that bit cannot be set
205 * at run-time. This fact can be used by an optimizer to perform
206 * constant-folding and dead-code elimination.
207 */
208 metaonly enum Mode {
209 ALWAYS_OFF, //! Bit is permanently cleared.
210 ALWAYS_ON, //! Bit is permanently set.
211 RUNTIME_OFF, //! Bit is cleared and modifiable at run-time.
212 RUNTIME_ON //! Bit is set and modifiable at run-time.
213 };
214
215 /*! Type used to specify bits in the diags mask. */
216 typedef Bits16 Mask;
217
218 const Mask ENTRY = 0x0001; //! Function entry
219 const Mask EXIT = 0x0002; //! Function exit
220 const Mask LIFECYCLE = 0x0004; //! Object life-cycle
221 const Mask INTERNAL = 0x0008; //! Internal diagnostics
222
223 const Mask ASSERT = 0x0010; //! Assert checking
224
225 const Mask USER1 = 0x0100; //! User defined diagnostics
226 const Mask USER2 = 0x0200; //! User defined diagnostics
227 const Mask USER3 = 0x0400; //! User defined diagnostics
228 const Mask USER4 = 0x0800; //! User defined diagnostics
229
230 const Mask USER5 = 0x1000; //! User defined diagnostics
231 const Mask USER6 = 0x2000; //! User defined diagnostics
232 const Mask USER7 = 0x4000; //! User defined diagnostics
233 const Mask USER8 = 0x8000; //! User defined diagnostics
234
235 const Mask ALL = 0xFFFF; //! Turn on all diagnostics
236
237 /*!
238 * ======== query ========
239 * Query the module's diagnostics mask against the given mask.
240 *
241 * Use this query function to test the state of a module's
242 * diagnostics mask at runtime. This function will perform a logical
243 * `AND` operation on the module's diagnostics mask and the given mask.
244 * If any bits survive the operation, the function returns `true`.
245 *
246 * @p(code)
247 * result = moduleMask & givenMask ? true : false;
248 * @p
249 *
250 * This query function has a compile-time binding to the module's
251 * diagnostics mask. If the query function is part of the C code
252 * implementation of a module, then it will use that module's
253 * diagnostics mask. Otherwise, it will use the diagnostics mask
254 * of the `{@link Main xdc.runtime.Main}` module.
255 *
256 * The implementation of the diagnostics mask and the query function
257 * is such that an optimizer can take advantage of dead code elimination
258 * and/or constant folding to eliminate or reduce code size. For example,
259 * if the query function is used in a conditional test, and the given
260 * mask contains only bits which have been configured to be permanently
261 * off, then the code for the entire conditional statement can be removed
262 * at link time. If the bits in the given mask have been configured to be
263 * permanently on, then the conditional code can be removed leaving the
264 * body of the conditional as direct in-line code.
265 *
266 * @param(mask) mask of diagnostics bits to test
267 *
268 * This given mask is constructed by `OR`'ing together
269 * the desired bits of the diagnostics mask using the constants listed
270 * in the {@link #ALL Mask Summary} above. The module's diagnostics
271 * mask will be logically `AND`'ed with the given mask, and return `true`
272 * if the result is non-zero and `false` otherwise.
273 *
274 * @p(code)
275 * if (Diags_query(Diags_USER1 | Diags_USER4)) {
276 * :
277 * }
278 * @p
279 *
280 * @a(Examples)
281 * In the following example, the `{@link #USER1 USER1}` bit of the
282 * module's diagnostics mask has been configured to be permanently off,
283 * thus the entire conditional code block can be removed at link time.
284 * Note, the C code below is part of the module itself.
285 *
286 * Configuration Script
287 * @p(code)
288 * var Diags = xdc.useModule('xdc.runtime.Diags');
289 * var ModA = xdc.useModule('my.package.ModuleA');
290 * ModA.common$.diags_USER1 = Diags.ALWAYS_OFF;
291 * @p
292 *
293 * C Code, ModA.c
294 * @p(code)
295 * if (Diags_query(Diags_USER1)) { // this code removed
296 * ...additional code here... // this code removed
297 * } // this code removed
298 * @p
299 *
300 * @p(html)
301 * <hr />
302 * @p
303 *
304 * In the following example, the `{@link #USER1 USER1}` bit of the
305 * module's diagnostics mask has been configured to be permanently on,
306 * thus the conditional code can be removed leaving the code contained
307 * within the conditional statement. Note, the C code below is part of
308 * the module itself.
309 *
310 * Configuration Script
311 * @p(code)
312 * var Diags = xdc.useModule('xdc.runtime.Diags');
313 * var ModA = xdc.useModule('my.package.ModuleA');
314 * ModA.common$.diags_USER1 = Diags.ALWAYS_ON;
315 * @p
316 *
317 * C Code, ModA.c
318 * @p(code)
319 * if (Diags_query(Diags_USER1) { // this code removed
320 * ...additional code here... // this code remains
321 * } // this code removed
322 * @p
323 *
324 */
325 @Macro Bool query(Mask mask);
326
327 /*!
328 * ======== setMask ========
329 * Set a module's diagnostics mask at runtime.
330 *
331 * Use the given control string to set or clear bits in a module's
332 * diagnostics mask. The control string defines one or more actions
333 * where each action modifies the diagnostics mask in one or more
334 * modules. Each action can either set, clear, or assign a module's
335 * diagnostics mask. To both set and clear bits in the same diagnostics
336 * mask requires two actions, or you can assign the entire mask
337 * explicitly in one action. Each action can specify a given module or
338 * a set of modules using name prefix matching.
339 *
340 * @a(Warning)
341 *
342 * Each bit of a module's diagnostics mask that is to be modified at
343 * runtime, must be configured to be runtime modifiable in the
344 * program's configuration script. Use either `{@link #Mode RUNTIME_OFF}`
345 * or `{@link #Mode RUNTIME_ON}` as the configuration value for the
346 * desired bit in the diagnostics mask. In addition, the
347 * `{@link Diags#setMaskEnabled Diags.setMaskEnabled}` configuration
348 * parameter must be set to `true` in order to load this function onto
349 * the target. Finally, the following configuration parameters must
350 * have the values indicated (which are their default values):
351 *
352 * @p(blist)
353 * - `{@link IModule#common$ <module>.common$.namedModule} = true;`
354 * - `{@link Text#isLoaded} = true;`
355 * @p
356 *
357 * Note: any error that occurs during the parsing of the control string
358 * causes `Diags_setmask()` to return without processing the remainder
359 * of the control string.
360 *
361 * @param(control) diagnostic mask control string
362 *
363 * This control string defines one or more actions
364 * where each action consists of a module name, an operator character,
365 * and a list of bit specifiers. Use the `%` character as a wildcard
366 * to turn the module name into a prefix matching pattern for a set
367 * of modules. Multiple actions are separated with the `;` character.
368 *
369 * @p
370 * The control string has the following format:
371 *
372 * @p(code)
373 * <module[%]><op><bits>[;<module[%]><op><bits>]
374 * @p
375 *
376 * Specify individual module names explicitly (e.g.
377 * `ti.sysbios.knl.Task`), or match multiple modules using a prefix
378 * matching pattern specified with the `%` character (e.g.
379 * `ti.sysbios.knl.%`).
380 *
381 * @p
382 * The operator is specified with a single character from the following
383 * table.
384 *
385 * @p(code)
386 * Operator Description
387 * --------------------------------------------------
388 * + Set only the specified bits (other bits preserved)
389 * - Clear only the specified bits (other bits preserved)
390 * = Assign the entire mask to the given value where the
391 * specified bits are set and all other bits are cleared
392 * @p
393 *
394 * The bits are specified with a list of characters from the following
395 * table. Refer to the {@link #ALL Mask Summary} for a list of each
396 * bit of the diagnostics mask.
397 *
398 * @p(code)
399 * Control Diagnostics
400 * Character Constant Description
401 * --------------------------------------------------
402 * E ENTRY Function entry
403 * X EXIT Function exit
404 * L LIFECYCLE Object life-cycle
405 * I INTERNAL Internal diagnostics
406 * A ASSERT Assert checking
407 * 1 USER1 User defined diagnostics
408 * 2 USER2 User defined diagnostics
409 * 3 USER3 User defined diagnostics
410 * 4 USER4 User defined diagnostics
411 * 5 USER5 User defined diagnostics
412 * 6 USER6 User defined diagnostics
413 * 7 USER7 User defined diagnostics
414 * 8 USER8 User defined diagnostics
415 * @p
416 *
417 * @a(Examples)
418 * The following example demonstrates how to set a module's diagnostics
419 * mask (the `Task` module in this case) at runtime. In this example, the
420 * `{@link #USER1 USER1}` bit is turned on. Note that the module's
421 * `{@link #USER1 USER1}` diagnostics bit must be configured to be runtime
422 * modifiable. In this instance, the bit is initialized to off.
423 *
424 * Configuration Script
425 * @p(code)
426 * var Diags = xdc.useModule('xdc.runtime.Diags');
427 * var Task = xdc.useModule('ti.sysbios.knl.Task');
428 * Task.common$.diags_USER1 = Diags.RUNTIME_OFF;
429 * @p
430 *
431 * C Code
432 * @p(code)
433 * Diags_setMask("ti.sysbios.knl.Task+1");
434 * @p
435 *
436 * @p(html)
437 * <hr />
438 * @p
439 *
440 * The following example demonstrates the use of the `%` wildcard
441 * character to set the `{@link #USER1 USER1}` bit at runtime for
442 * all modules in the `ti.sysbios.knl` package. The meta-only
443 * `{@link #setMaskMeta Diags.setMaskMeta}` function is used to configure
444 * the `{@link #USER1 USER1}` bit to be runtime modifiable. The `setMask`
445 * function is used to actually set the `{@link #USER1 USER1}` bit at
446 * runtime in all the `ti.sysbios.knl` modules.
447 * Note the use of the `%` character in both functions to match all the
448 * module names within the given package.
449 *
450 * Configuration Script
451 * @p(code)
452 * var Diags = xdc.useModule('xdc.runtime.Diags');
453 * Diags.setMaskMeta("ti.sysbios.knl.%", Diags.USER1, Diags.RUNTIME_OFF);
454 * @p
455 *
456 * C Code
457 * @p(code)
458 * Diags_setMask("ti.sysbios.knl.%+1");
459 * @p
460 *
461 * @p(html)
462 * <hr />
463 * @p
464 *
465 * In the following example, the `{@link #ENTRY ENTRY}`,
466 * `{@link #EXIT EXIT}` and `{@link #LIFECYCLE LIFECYCLE}` trace is
467 * enabled for all modules in the `ti.sysbios.knl` package but is
468 * initially off; i.e., no events will occur until explicitly turned
469 * on at runtime.
470 *
471 * At runtime the call to `Diags_setMask` turns on
472 * `{@link #ENTRY ENTRY}` and `{@link #EXIT EXIT}` trace and turns off
473 * `{@link #LIFECYCLE LIFECYCLE}` trace for all modules in
474 * the application for which trace has been enabled during
475 * configuration. In this case, the only modules that can generate
476 * events are those in the `ti.sysbios.knl` package.
477 *
478 * Configuration Script
479 * @p(code)
480 * var Diags = xdc.useModule('xdc.runtime.Diags');
481 * Diags.setMaskMeta("ti.sysbios.knl.%",
482 * Diags.ENTRY | Diags.EXIT | Diags.LIFECYCLE, Diags.RUNTIME_OFF);
483 * @p
484 *
485 * C Code
486 * @p(code)
487 * Diags_setMask("%+EX;%-L");
488 * @p
489 */
490 Void setMask(String control);
491
492 /*!
493 * ======== setMaskMeta ========
494 * Set the module's diagnostics mask at config time.
495 *
496 * @param(pattern) module prefix or regular expression
497 *
498 * The `pattern` is used to match a module's name. If `pattern` is
499 * specified as a string, then name prefix matching is used. The
500 * pattern may also be a regular expression. Only the masks of the
501 * modules matching `pattern` are set.
502 *
503 * @param(mask) diagnostic fields to modify
504 *
505 * The `mask` is used to determine which fields in the diags mask are
506 * modified. Each field specified in the mask is set to the given
507 * `mode` value.
508 *
509 * @param(mode) mode to assign to the specified `mask` fields
510 */
511 metaonly Void setMaskMeta(Any pattern, Mask mask, Mode mode);
512
513 internal:
514
515 /*!
516 * ======== setMaskEnabled ========
517 * Controls the ability to set the diags mask at run-time.
518 *
519 * This configuration parameter allows whole program optimizers to reduce
520 * the code size. The default is false, which means the diags mask will
521 * not be modified at run-time and thus the code is not needed.
522 *
523 * For now, this should be internal because its value is determined
524 * automatically, rather than through user's input. See CQ19111 for more
525 * details.
526 */
527 config Bool setMaskEnabled = false;
528
529 530 531 532 533 534 535
536 config DictElem *dictBase = null;
537
538 struct DictElem {
539 Types.ModuleId modId;
540 Bits16 *maskAddr;
541 };
542 }
543 544 545
546