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        metaonly enum 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        metaonly struct 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        metaonly config 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