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