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     *  ======== Log.xdc ========
    15     */
    16    
    17    /*!
    18     *  ======== Log ========
    19     *  Event logging manager
    20     *
    21     *  RTSC modules and the application code generate `{@link #Event Log_Event}`
    22     *  events by calling the `Log` module's functions. The `Log` module then
    23     *  passes those events to an `{@link ILogger}` instance assigned to the event
    24     *  originating module, specified by that module's configuration parameter
    25     *  `common$.logger`. `ILogger` instances handle events, usually converting
    26     *  events to `{@link #EventRec Log_EventRec}` records prior to recording,
    27     *  transmitting, or displaying them.
    28     *
    29     *  All events generated by a target module are stored and displayed by an
    30     *  `ILogger`, examples of which are instances of
    31     *  `{@link LoggerBuf xdc.runtime.LoggerBuf}` or
    32     *  `{@link LoggerSys xdc.runtime.LoggerSys}`. At runtime, modules
    33     *  generate events through this module, rather than invoking directly their
    34     *  `ILogger`s. By doing so,  modules can be configured to use different
    35     *  `ILogger` implementations without any changes to their source code.
    36     *
    37     *  A logger instance can accept `Log` events from any module, but a module
    38     *  can put `Log` events to only one logger instance. There can be one or
    39     *  more logger instances in a system. All `Log` calls that are not in a
    40     *  module are controlled by the module `{@link Main xdc.runtime.Main}`.
    41     *  For example, top-level application code or any existing sources that
    42     *  simply call the `Log` or `Assert` methods implicitly use the logger
    43     *  associated with the `Main` module.
    44     *
    45     *  The generation of a `Log` event is controlled by a module's diagnostics
    46     *  mask, which is described in details in `{@link Diags}`. Each `Log` event
    47     *  is associated with a mask. `Log` events are generated only when a
    48     *  particular bit is set in both the `Log` event mask and the module's
    49     *  diagnostics mask. For example, a `Log` event mask with the
    50     *  `{@link Diags#USER1 USER1}` bit set is generated only when the `USER1`
    51     *  bit is also set in the module's diagnostics mask.
    52     *
    53     *  There are two ways to generate `Log` events:
    54     *
    55     *  @p(blist)
    56     *  - `{@link #write8 Log_write()}`, which is tailored for module writers
    57     *  and takes full advantage of the XDC configuration model. For example,
    58     *  the message string associated with the `Log` event need not be a part of
    59     *  the final application, significantly reducing the "footprint overhead"
    60     *  of embedding diagnostics in deployed systems. The `Log_write[0-8]()`
    61     *  functions allow up to 8 values to be passed to the logger. They expect
    62     *  the logger to handle any formatting. A `Log` event type allows you to
    63     *  specify the type of event.
    64     *  - `{@link #print6 Log_print()}`, which is designed for arbitrary C code.
    65     *  The `Log_print[0-6]()` functions allow up to 6 values to be passed along
    66     *  with a printf-like format string to the logger. They handle printf-style
    67     *  formatting.
    68     *  @p
    69     *
    70     *  Both functions are controlled by the module's diagnostics mask. Their
    71     *  storage or output is defined by the logger that is assigned to the
    72     *  module that calls the `Log` methods or to the
    73     *  `{@link Main xdc.runtime.Main}` module if the caller is not part of a
    74     *  module.
    75     *
    76     *  The `Log` function call sites are implemented in such a way that an
    77     *  optimizer can completely eliminate `Log` code from the program if the
    78     *  `Log` functions have been permanently disabled at configuration time. If
    79     *  the `Log` functions are permanently turned on at configuration time,
    80     *  then the optimizer can eliminate all runtime conditional checking and
    81     *  simply invoke the `Log` functions directly. Runtime checking is performed
    82     *  only when the `Log` functions are configured to be runtime modifiable.
    83     *
    84     *  The Log calls can also be completely removed by defining the symbol
    85     *  `xdc_runtime_Log_DISABLE_ALL`. This can be done on the compile line, e.g.
    86     *  `-Dxdc_runtime_Log_DISABLE_ALL`. This will completely remove the `Log`
    87     *  statements from any code compiled with this flag, regardless of the
    88     *  application's logging configuration or your compiler's optimization
    89     *  settings.
    90     *
    91     *  It is also possible to remove all logging except for
    92     *  `{@link #error Log_error}`, `{@link #warning Log_warning}`, or
    93     *  `{@link #info Log_info}` statements. This is done by first defining
    94     *  `xdc_runtime_Log_DISABLE_ALL`, followed by defining one or more of the
    95     *  symbols below to leave that type of logging enabled:
    96     *  @p(blist)
    97     *  - `xdc_runtime_Log_ENABLE_ERROR`
    98     *  - `xdc_runtime_Log_ENABLE_WARNING`
    99     *  - `xdc_runtime_Log_ENABLE_INFO`
   100     *  @p
   101     *  For example, to disable all `Log` statements except for `Log_error`, add
   102     *  the following to the compile line:
   103     *  @p(code)
   104     *      -Dxdc_runtime_Log_DISABLE_ALL -Dxdc_runtime_Log_ENABLE_ERROR
   105     *  @p
   106     *
   107     *  @a(Examples)
   108     *  Example 1: The following example defines a `Log` event, uses that `Log`
   109     *  event in a module, and configures the program to generate the `Log`
   110     *  event. In this example, both `USER1` and `USER2` bits are set in the
   111     *  event mask. This means that if either bit is set in the module's
   112     *  diagnostics mask, then the `Log` event will be generated.
   113     *
   114     *  This is a part of the XDC specification file for the `Mod` module
   115     *  (Mod.xdc):
   116     *
   117     *  @p(code)
   118     *  import xdc.runtime.Diags;
   119     *  import xdc.runtime.Log;
   120     *
   121     *  config Log.Event L_someEvent = {
   122     *      mask: Diags.USER1 | Diags.USER2,
   123     *      level: Diags.LEVEL1,
   124     *      msg: "my log event message, arg1: 0x%x, arg2: 0x%x"
   125     *  };
   126     *  @p
   127     *
   128     *  This is a part of the C code implementation of the Mod module:
   129     *
   130     *  @p(code)
   131     *  #include <xdc/runtime/Log.h>
   132     *  UInt x, y;
   133     *
   134     *  Log_write2(Mod_L_someEvent, (IArg)x, (IArg)y);
   135     *  @p
   136     *
   137     *  The following configuration script demonstrates how the application might
   138     *  control the `Log` statements embedded in the `Mod` module at configuration
   139     *  time. In this case, the configuration script arranges for the `Log`
   140     *  statements within the `Mod` module (shown above) to always generate events.
   141     *  Without these configuration statements, no `Log` events would be generated
   142     *  by this module.
   143     *
   144     *  This is part of the XDC configuration file for the application:
   145     *
   146     *  @p(code)
   147     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   148     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
   149     *  var Mod = xdc.useModule('my.pkg.Mod');
   150     *  Mod.common$.diags_USER1 = Diags.ALWAYS_ON;
   151     *  Mod.common$.logger = LoggerSys.create();
   152     *  @p
   153     *
   154     *  @p(html)
   155     *  <hr />
   156     *  @p
   157     *
   158     *  Example 2: The following XDC configuration statements turn on enter
   159     *  and exit logging at configuration time for a module. Without any other
   160     *  changes in the runtime code, every time a module `Mod`'s function is
   161     *  being called or exits, an event will be logged.
   162     *
   163     *  @p(code)
   164     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   165     *  var Mod = xdc.useModule('my.pkg.Mod');
   166     *
   167     *  Mod.common$.diags_ENTER = Diags.ALWAYS_ON;
   168     *  Mod.common$.diags_EXIT = Diags.ALWAYS_ON;
   169     *  @p
   170     *
   171     *  @p(html)
   172     *  <hr />
   173     *  @p
   174     *
   175     *  Example 3: The following example configures a module to support enter and
   176     *  exit logging, but defers the actual activation and deactivation of the
   177     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
   178     *  function for details on specifying the control string.
   179     *
   180     *  This is a part of the XDC configuration file for the application:
   181     *
   182     *  @p(code)
   183     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   184     *  var Mod = xdc.useModule('my.pkg.Mod');
   185     *
   186     *  Mod.common$.diags_ENTER = Diags.RUNTIME_OFF;
   187     *  Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
   188     *  @p
   189     *
   190     *  This is a part of the C code for the application:
   191     *
   192     *  @p(code)
   193     *  // turn on enter and exit logging in the module
   194     *  Diags_setMask("my.pkg.Mod+EX");
   195     *
   196     *  // turn off enter and exit logging in the module
   197     *  Diags_setMask("my.pkg.Mod-EX");
   198     *  @p
   199     */
   200    
   201    @CustomHeader
   202    @DirectCall
   203    
   204    module Log {
   205    
   206        /*!
   207         *  ======== NUMARGS ========
   208         *  Maximum number of arguments supported in `Log` events.
   209         */
   210        const Int NUMARGS = 8;
   211    
   212        /*!
   213         *  ======== PRINTFID ========
   214         *  The `EventId` for `Log_print()` events
   215         */
   216        const EventId PRINTFID = 0;
   217    
   218        /*!
   219         *  ======== EventDesc ========
   220         *  `Log` event descriptor
   221         *
   222         *  Each `Log` event is defined by a `Log` event descriptor.
   223         *
   224         *  The `mask` defines which bits in the module's diagnostics mask
   225         *  enable this `Log` event.  Events "posted" via `Log_write` are only
   226         *  written to the underlying logger if one of the mask's bits matches
   227         *  the caller's module diagnostics settings (see
   228         *  `{@link xdc.runtime.Types#common$}`).
   229         *
   230         *  The 'level' defines the event level of the event. While the diags
   231         *  bits selected in the 'mask' signify the "category" of the event (e.g.
   232         *  Entry/Exit, Analysis, Info), the 'level' field allows you to assign
   233         *  a "priority" or "detail level" to the event relative to other events in
   234         *  that category. There are four event levels defined by
   235         *  '{@link xdc.runtime.Diags#EventLevel}'.
   236         *
   237         *  Filtering of events by level is handled by the ILogger implementation.
   238         *  ILogger implementations which also implement the {@link IFilterLogger}
   239         *  interface support filtering of events based on priority level.
   240         *
   241         *  Specifying an event level is optional. Events that don't specify a
   242         *  level will receive Diags.LEVEL1 by default, making them the highest
   243         *  priority and ensuring that they will not inadvertently be filtered out
   244         *  by level-based filtering.
   245         *
   246         *  The `msg` defines a printf style format string that defines how to
   247         *  render the arguments passed along the event in a `Log_write` call.
   248         *  For a description of the allowable format strings see
   249         *  `{@link #print6}`.
   250         *
   251         *  @see #write8
   252         *  @see #print6
   253         */
   254        metaonly struct EventDesc {
   255            Diags.Mask          mask;   /*! event enable mask */
   256            Diags.EventLevel    level;  /*! event level relative to other events */
   257            String              msg;    /*! event "printf" message format string */
   258        };
   259    
   260        /*!
   261         *  ======== EventRec ========
   262         *  The target representation of a recorded event
   263         *
   264         *  This structure defines how events are recorded on the target.
   265         */
   266        struct EventRec {
   267            Types.Timestamp64 tstamp;   /*! time event was written */
   268            Bits32 serial;              /*! serial number of event */
   269            Types.Event evt;            /*! target encoding of an Event */
   270            IArg arg[NUMARGS];          /*! arguments passed via Log_write/print */
   271        }
   272    
   273        /*!
   274         *  ======== Event ========
   275         *  `Log` event type
   276         *
   277         *  An `Event` is represented on the target as a 32-bit value that can
   278         *  be decoded offline to recover the `Event` information defined in
   279         *  a corresponding metaonly `EventDesc`.  In addition, `Event`s may be
   280         *  decoded at runtime via methods provided in this module; see
   281         *  `{@link #getMask}` and `{@link #getEventId}`.
   282         *
   283         *  When an event is "raised" a `{@link Types#Event Types_Event}` is
   284         *  created which has the same event ID as the `Log_Event` but also
   285         *  encodes the module ID of the caller.  This new event is passed to
   286         *  the underlying `{@link ILogger}` module along with any arguments
   287         *  associated with the event.
   288         *
   289         *  @see #getMask
   290         *  @see #getEventId
   291         */
   292        @Encoded typedef EventDesc Event;
   293    
   294        /*!
   295         *  ======== EventId ========
   296         *  Unique ID embedded in each `{@link #Event}`
   297         *
   298         *  This ID must be used to compare two `Event`s for equality.  Event
   299         *  ids are not guaranteed to remain constant between different
   300         *  configurations of an application.  For example, adding a module
   301         *  may cause the event ids of another module to change.
   302         *
   303         *  However, event ids declared by a module are guaranteed to be
   304         *  consecutive values starting from the first declared
   305         *  `{@link #Event Log_Event}` and increasing to the last declared
   306         *  event.  As a result, clients of a module can efficiently test ranges
   307         *  of events and modules can add new events, such as internal trace
   308         *  events, without breaking clients; simply be careful to add new events
   309         *  after any existing events in you module's `.xdc` specification.
   310         *
   311         *  @see #getEventId
   312         *  @see #Event
   313         */
   314        typedef Types.RopeId EventId;
   315    
   316        /*!
   317         *  ======== L_construct ========
   318         *  Lifecycle event posted when an instance is constructed
   319         */
   320        config Log.Event L_construct = {
   321            mask: Diags.LIFECYCLE,
   322            msg: "<-- construct: %p('%s')"
   323        };
   324    
   325        /*!
   326         *  ======== L_create ========
   327         *  Lifecycle event posted when an instance is created
   328         */
   329        config Log.Event L_create = {
   330            mask: Diags.LIFECYCLE,
   331            msg: "<-- create: %p('%s')"
   332        };
   333    
   334        /*!
   335         *  ======== L_destruct ========
   336         *  Lifecycle event posted when an instance is destructed
   337         */
   338        config Log.Event L_destruct = {
   339            mask: Diags.LIFECYCLE,
   340            msg: "--> destruct: (%p)"
   341        };
   342    
   343        /*!
   344         *  ======== L_delete ========
   345         *  Lifecycle event posted when an instance is deleted
   346         */
   347        config Log.Event L_delete = {
   348            mask: Diags.LIFECYCLE,
   349            msg: "--> delete: (%p)"
   350        };
   351    
   352        /*!
   353         *  ======== L_error ========
   354         *  Error event posted by Log_errorX API
   355         *
   356         *  This event is marked as a STATUS event and given the priority level
   357         *  of ERROR.
   358         *
   359         *  This event prints the Log call site (%$F) and a format string (%$S)
   360         *  which is recursively formatted with any additional arguments.
   361         */
   362        config Log.Event L_error = {
   363            mask: Diags.STATUS,
   364            level: Diags.ERROR,
   365            msg: "ERROR: %$F%$S"
   366        };
   367    
   368        /*!
   369         *  ======== L_warning ========
   370         *  Warning event posted by Log_warningX API
   371         *
   372         *  This event is marked as a STATUS event and given the priority level of
   373         *  WARNING.
   374         *
   375         *  This event prints the Log call site (%$F) and a format string (%$S)
   376         *  which is recursively formatted with any addition arguments.
   377         */
   378        config xdc.runtime.Log.Event L_warning = {
   379            mask: Diags.STATUS,
   380            level: Diags.WARNING,
   381            msg: "WARNING: %$F%$S"
   382        };
   383    
   384        /*!
   385         *  ======== L_info ========
   386         *  Info event posted by Log_infoX API
   387         *
   388         *  This event is marked as an INFO event. The event priority is not
   389         *  specified in the event definition. Rather, it is specified as an
   390         *  argument to the Log_infoX APIs.
   391         *
   392         *  This event prints the Log call site (%$F) and a format string (%$S)
   393         *  which is recursively formatted with any addition arguments.
   394         */
   395        config xdc.runtime.Log.Event L_info = {
   396            mask: Diags.INFO,
   397            msg: "%$F%$S"
   398        };
   399    
   400        /*!
   401         *  ======== L_start ========
   402         *  Benchmark event used to log the start of an operation
   403         *  @_nodoc
   404         *
   405         *  @a(Example)
   406         *   The following C code shows how to log a simple
   407         *   benchmark 'start' event along with a user-specified
   408         *   format string describing the event.
   409         *
   410         *  @p(code)
   411         *  #include <xdc/runtime/Log.h>
   412         *  ...
   413         *  Log_write2(Log_L_start, (IArg)"My benchmark event", (IArg)myUniqueId);
   414         *  Log_write2(Log_L_stop, (IArg)"My benchmark event", (IArg)myUniqueId);
   415         *  @p
   416         *
   417         *  @param(fmt)     a constant string that provides format specifiers for
   418         *                  up to 6 additional parameters
   419         *  @param(id)      a unique ID used to match benchmark start and stop
   420         *                  events
   421         */
   422        config xdc.runtime.Log.Event L_start = {
   423            mask: Diags.ANALYSIS,
   424            msg: "Start: %$S"};
   425    
   426        /*!
   427         *  ======== L_stop ========
   428         *  Benchmark event used to log the end of an operation
   429         *  @_nodoc
   430         *
   431         *  @a(Example)
   432         *   The following C code shows how to log a simple
   433         *   benchmark 'stop' event along with a user-specified
   434         *   format string describing the event.
   435         *
   436         *  @p(code)
   437         *  #include <xdc/runtime/Log.h>
   438         *  ...
   439         *  Log_write2(Log_L_start, (IArg)"My benchmark event", (IArg)myUniqueId);
   440         *  Log_write2(Log_L_stop, (IArg)"My benchmark event", (IArg)myUniqueId);
   441         *  @p
   442         *
   443         *  @param(fmt)     a constant string that provides format specifiers for
   444         *                  up to 6 additional parameters
   445         *  @param(id)      a unique ID used to match benchmark start and stop
   446         *                  events
   447         */
   448        config xdc.runtime.Log.Event L_stop = {
   449            mask: Diags.ANALYSIS,
   450            msg: "Stop: %$S"};
   451    
   452        /*!
   453         *  ======== L_startInstance ========
   454         *  Benchmark event used to log the start of an operation instance
   455         *  @_nodoc
   456         *
   457         *  Event parameter provides instance data to differentiate
   458         *  between multiple instances that can run in parallel.
   459         *
   460         *  @a(Example)
   461         *   The following C code shows how to log a benchmark
   462         *   'startInstance' event along with a user-specified
   463         *   instance identifier and a format string describing the event.
   464         *
   465         *  @p(code)
   466         *  #include <xdc/runtime/Log.h>
   467         *  ...
   468         *  Log_write3(Log_L_startInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
   469         *  ...
   470         *  Log_write3(Log_L_stopInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
   471         *  @p
   472         *  
   473         *  @param(fmt)     a constant string that provides format specifiers for
   474         *                  up to 6 additional parameters
   475         *  @param(id)      a unique ID used to match benchmark start and stop
   476         *                  events
   477         *  @param(instId)  a unique instance ID that can be used to match
   478         *                  instance events
   479         */
   480        config xdc.runtime.Log.Event L_startInstance = {
   481            mask: Diags.ANALYSIS,
   482            msg: "StartInstance: %$S"
   483        };
   484    
   485        /*!
   486         *  ======== L_stopInstance ========
   487         *  Benchmark event used to log the end of an operation instance
   488         *  @_nodoc
   489         *
   490         *  Event parameter provides instance data to differentiate
   491         *  between multiple instances that can run in parallel.
   492         *
   493         * @a(Example)
   494         *   The following C code shows how to log a benchmark
   495         *   'stopInstance' event along with a user-specified
   496         *   instance identifier and a format string describing the event.
   497         *
   498         *  @p(code)
   499         *  #include <xdc/runtime/Log.h>
   500         *  ...
   501         *  Log_write3(Log_L_startInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
   502         *  ...
   503         *  Log_write3(Log_L_stopInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
   504         *  @p
   505         *
   506         *  @param(fmt)     a constant string that provides format specifiers for
   507         *                  up to 6 additional parameters
   508         *  @param(id)      a unique ID used to match benchmark start and stop
   509         *                  events
   510         *  @param(instId)  a unique instance ID that can be used to match
   511         *                  instance events
   512         */
   513        config xdc.runtime.Log.Event L_stopInstance = {
   514            mask: Diags.ANALYSIS,
   515            msg: "StopInstance: %$S"
   516        };
   517    
   518        /*!
   519         *  ======== getMask ========
   520         *  Get the `Diags` mask for the specified (encoded) event
   521         *
   522         *  @param(evt) the `Log` event encoding a mask and event ID
   523         *
   524         *  @a(returns) `Diags` mask for the specified event
   525         */
   526        @Macro Diags.Mask getMask(Event evt);
   527    
   528        /*!
   529         *  ======== getRope ========
   530         *  Get RopeId of the Event.msg for the specified (encoded) event
   531         *  @_nodoc
   532         */
   533        @Macro Text.RopeId getRope(Event evt);
   534    
   535        /*!
   536         *  ======== getEventId ========
   537         *  Get event ID of the specified (encoded) event
   538         *
   539         *  This method is used to compare "known" `Log` events with
   540         *  "raised" `{@link Types#Event Types_Event}`.
   541         *
   542         *  @param(evt) the `Log` event encoding a mask and event ID
   543         *
   544         *  @a(returns) event ID of the specified event
   545         *
   546         *  @see Types#getEventId
   547         */
   548        @Macro EventId getEventId(Event evt);
   549    
   550        /*!
   551         *  ======== print0 ========
   552         *  Generate a `Log` "print event" with 0 arguments
   553         *
   554         *  @see #print6
   555         */
   556        @Macro Void print0(Diags.Mask mask, CString fmt);
   557    
   558        /*!
   559         *  ======== print1 ========
   560         *  Generate a `Log` "print event" with 1 argument
   561         *
   562         *  @see #print6
   563         */
   564        @Macro Void print1(Diags.Mask mask, CString fmt, IArg a1);
   565    
   566        /*!
   567         *  ======== print2 ========
   568         *  Generate a `Log` "print event" with 2 arguments
   569         *
   570         *  @see #print6
   571         */
   572        @Macro Void print2(Diags.Mask mask, CString fmt, IArg a1, IArg a2);
   573    
   574        /*!
   575         *  ======== print3 ========
   576         *  Generate a `Log` "print event" with 3 arguments
   577         *
   578         *  @see #print6
   579         */
   580        @Macro Void print3(Diags.Mask mask, CString fmt, IArg a1, IArg a2,
   581            IArg a3);
   582    
   583        /*!
   584         *  ======== print4 ========
   585         *  Generate a `Log` "print event" with 4 arguments
   586         *
   587         *  @see #print6
   588         */
   589        @Macro Void print4(Diags.Mask mask, CString fmt, IArg a1, IArg a2,
   590            IArg a3, IArg a4);
   591    
   592        /*!
   593         *  ======== print5 ========
   594         *  Generate a `Log` "print event" with 5 arguments
   595         *
   596         *  @see #print6
   597         */
   598        @Macro Void print5(Diags.Mask mask, CString fmt, IArg a1, IArg a2, 
   599            IArg a3, IArg a4, IArg a5);
   600    
   601        /*!
   602         *  ======== print6 ========
   603         *  Generate a `Log` "print event" with 6 arguments
   604         *
   605         *  As a convenience to C (as well as assembly language) programmers,
   606         *  the `Log` module provides a variation of the ever-popular `printf`
   607         *  function.
   608         *  The `print[0-6]` functions generate a `Log` "print event" and route
   609         *  it to the current module's logger.
   610         *
   611         *  The arguments passed to `print[0-6]` may be characters, integers,
   612         *  strings, or pointers.  However, because the declared type of the
   613         *  arguments is `{@link xdc IArg}`, all pointer arguments must be cast
   614         *  to an `IArg` type.  `IArg` is an integral type large enough to hold
   615         *  any pointer or an `int`.  So, casting a pointer to an `IArg` does
   616         *  not cause any loss of information and C's normal integer conversions
   617         *  make the cast unnecessary for integral arguments.
   618         *
   619         *  The format string can use the following conversion characters.
   620         *  However, it is important to recall that all arguments referenced by
   621         *  these conversion characters have been converted to an `IArg`
   622         *  prior to conversion; so, the use of "length modifiers" should be
   623         *  avoided.
   624         *
   625         *  @p(code)
   626         *  Conversion Character    Description
   627         *  ------------------------------------------------
   628         *  %c                      Character
   629         *  %d                      Signed integer
   630         *  %u                      Unsigned integer
   631         *  %x                      Unsigned hexadecimal integer
   632         *  %o                      Unsigned octal integer
   633         *  %s                      Character string
   634         *  %p                      Pointer
   635         *  %f                      Single precision floating point (float)
   636         *  @p
   637         *
   638         *  Format strings, while very convenient, are a well known source of
   639         *  portability problems: each format specification must precisely match
   640         *  the types of the arguments passed. Underlying "printf" functions use
   641         *  the format string to determine how far to advance through their
   642         *  argument list. For targets where pointer types and integers are the
   643         *  same size there are no problems.  However, suppose a target's pointer
   644         *  type is larger than its integer type. In this case, because integer
   645         *  arguments are widened to be of type `IArg`, a format specification of
   646         *  "%d" causes an underlying `printf()` implementation to read the
   647         *  extended part of the integer argument as part of the next argument(!).
   648         *
   649         *  To get around this problem and still allow the use of "natural"
   650         *  format specifications (e.g., `%d` and `%x` with optional width
   651         *  specifications), `{@link System#aprintf()}` is used which assumes
   652         *  that all arguments have been widened to be of type `IArg`.
   653         *
   654         *  See `{@link System#printf}` for complete details.
   655         *
   656         *  The `%f` format specifier is used to print a single precision float
   657         *  value. Note that `%f` assumes that sizeof(Float) <= sizeof(IArg).
   658         *  Most clients that interpret float values expect that they are
   659         *  represented in IEEE 754 floating point format. Therefore, it is
   660         *  recommended that the float values be converted into that format prior
   661         *  to supplying the values to `Log` functions in cases where targets do
   662         *  not generate the float values in IEEE 754 floating point format by
   663         *  default.
   664         *
   665         *  The first argument to a `Log_print` call is the diags category to be
   666         *  associated with the event.
   667         *
   668         *  It is also possible to associate an event level with the event to
   669         *  enable filtering of events based on event level. Conceptually, it is
   670         *  best to regard the event level as completely separate from the event's
   671         *  diags category; however, the priority value actually occupies a part
   672         *  of the diags mask. For this reason, it is possible to specify an event
   673         *  level by OR'ing the level with the diags mask. For example, to print
   674         *  an `Diags_INFO` event of `Diags_LEVEL2`, you'd simply write:
   675         *  (Diags_INFO | Diags_LEVEL2)
   676         *
   677         *  Specifying an event level is optional. `Log_print` calls which do not
   678         *  specify a level will receive the highest priority by default.
   679         *
   680         *  @param(mask)    enable bits and optional detail level for this event
   681         *  @param(fmt)     a `printf` style format string
   682         *  @param(a1)      value for first format conversion character
   683         *  @param(a2)      value for second format conversion character
   684         *  @param(a3)      value for third format conversion character
   685         *  @param(a4)      value for fourth format conversion character
   686         *  @param(a5)      value for fifth format conversion character
   687         *  @param(a6)      value for sixth format conversion character
   688         *
   689         *  @a(Examples)
   690         *  The following example demonstrates a typical usage.
   691         *  @p(code)
   692         *  String  list[];
   693         *  UInt    i;
   694         *
   695         *  Log_print2(Diags_USER2, "list[%u] = %s\n", i, (IArg)list[i]);
   696         *  @p
   697         *  Note that the `IArg` cast above is only necessary for pointer
   698         *  arguments; C's normal parameter conversions implicitly convert
   699         *  integral arguments.
   700         *
   701         *  To simplify the conversion from `float` arguments to `IArg`,
   702         *  the standard header `xdc/std.h` provides a macro, named floatToArg(),
   703         *  to do this conversion in a type safe manner.  So, the following
   704         *  statement will print "`float = 2.3456`":
   705         *  @p(code)
   706         *    Log_print1(Diags_USER1, "float = %f", floatToArg(2.34567));
   707         *  @p
   708         *
   709         *  Note that, if you are formatting events on the target, you must
   710         *  also add support for floating point to ASCII conversion to
   711         *  `{@link System#printf}`; for more information, see the
   712         *  `{@link System#extendedFormats}` reference documenation.  For example:
   713         *  @p(code)
   714         *      var System = xdc.useModule('xdc.runtime.System');
   715         *      System.extendedFormats = "%f";
   716         *  @p
   717         */
   718        @Macro Void print6(Diags.Mask mask, CString fmt, IArg a1, IArg a2, 
   719            IArg a3, IArg a4, IArg a5, IArg a6);
   720    
   721        /*!
   722         *  ======== error0 ========
   723         *  Generate a `Log` "error event" with 0 arguments
   724         *
   725         *  @see #error5
   726         */
   727        @Macro Void error0(CString fmt);
   728    
   729        /*!
   730         *  ======== error1 ========
   731         *  Generate a `Log` "error event" with 1 argument
   732         *
   733         *  @see #error5
   734         */
   735        @Macro Void error1(CString fmt, IArg a1);
   736    
   737        /*!
   738         *  ======== error2 ========
   739         *  Generate a `Log` "error event" with 2 arguments
   740         *
   741         *  @see #error5
   742         */
   743        @Macro Void error2(CString fmt, IArg a1, IArg a2);
   744    
   745        /*!
   746         *  ======== error3 ========
   747         *  Generate a `Log` "error event" with 3 arguments
   748         *
   749         *  @see #error5
   750         */
   751        @Macro Void error3(CString fmt, IArg a1, IArg a2, IArg a3);
   752    
   753        /*!
   754         *  ======== error4 ========
   755         *  Generate a `Log` "error event" with 4 arguments
   756         *
   757         *  @see #error5
   758         */
   759        @Macro Void error4(CString fmt, IArg a1, IArg a2, IArg a3,
   760            IArg a4);
   761    
   762        /*!
   763         *  ======== error5 ========
   764         *  Generate a `Log` "error event" with 5 arguments
   765         *
   766         *  The Log_error APIs are intended to allow users to easily log error
   767         *  events in their code. Similar to the Log_print APIs, Log_error does not
   768         *  require that you define an event. You simply pass an informative error
   769         *  string which can optionally be formatted with additional arguments. The
   770         *  error is logged with the predefined event {@link #L_error}.
   771         *
   772         *  Log_error prepends a string to the message which identifies it as an
   773         *  ERROR and specifies the filename and line number of the Log_error call
   774         *  site. A simple example:
   775         *
   776         *  @p(code)
   777         *  Log_error0("Invalid argument");
   778         *  @p
   779         *  This event will be formatted as (assuming that the above call was line
   780         *  35 of "MyCode.c")
   781         *  @p(code)
   782         *  ERROR at "MyCode.c", line 35: Invalid argument
   783         *  @p
   784         *
   785         *  Users may provide additional information in the error event, such as
   786         *  a predefined error code or details of the error. These additional
   787         *  values will be used to format the string passed to Log_error.
   788         *  @see #print6 for information about format strings.
   789         *
   790         *  Log_error does not use a variable length argument list--you must call
   791         *  the appropriate Log_errorX API based on the number of arguments.
   792         *
   793         *  @param(fmt)      a reference to a constant error string / fmt string
   794         *  @param(a1)       value for an additional parameter (e.g. an error code)
   795         *  @param(a2)       value for an additional parameter
   796         *  @param(a3)       value for an additional parameter
   797         *  @param(a4)       value for an additional parameter
   798         *  @param(a5)       value for an additional parameter
   799         *
   800         *  @a(Examples)
   801         *  The following example demonstrates a typical usage.
   802         *  @p(code)
   803         *  Int myArg;
   804         *
   805         *  Log_error1("Invalid argument: %d", myArg);
   806         *  @p
   807         *  The above event is formatted as, for example:
   808         *  @p(code)
   809         *  ERROR: "MyCode.c", line 35: Invalid argument: -1
   810         *  @p
   811         */
   812        @Macro Void error5(CString fmt, IArg a1, IArg a2, IArg a3,
   813            IArg a4, IArg a5);
   814    
   815        /*!
   816         *  ======== warning0 ========
   817         *  Generate a `Log` "warning event" with 0 arguments
   818         *
   819         *  @see #warning5
   820         */
   821        @Macro Void warning0(CString fmt);
   822    
   823        /*!
   824         *  ======== warning1 ========
   825         *  Generate a `Log` "warning event" with 1 argument
   826         *
   827         *  @see #warning5
   828         */
   829        @Macro Void warning1(CString fmt, IArg a1);
   830    
   831        /*!
   832         *  ======== warning2 ========
   833         *  Generate a `Log` "warning event" with 2 arguments
   834         *
   835         *  @see #warning5
   836         */
   837        @Macro Void warning2(CString fmt, IArg a1, IArg a2);
   838    
   839        /*!
   840         *  ======== warning3 ========
   841         *  Generate a `Log` "warning event" with 3 arguments
   842         *
   843         *  @see #warning5
   844         */
   845        @Macro Void warning3(CString fmt, IArg a1, IArg a2, IArg a3);
   846    
   847        /*!
   848         *  ======== warning4 ========
   849         *  Generate a `Log` "warning event" with 4 arguments
   850         *
   851         *  @see #warning5
   852         */
   853        @Macro Void warning4(CString fmt, IArg a1, IArg a2, IArg a3,
   854            IArg a4);
   855    
   856        /*!
   857         *  ======== warning5 ========
   858         *  Generate a `Log` "warning event" with 5 arguments
   859         *
   860         *  The Log_warning APIs provide the same features as the Log_error APIs,
   861         *  but are used to specifically log "warning" events.
   862         *  @see #error5
   863         *
   864         *  The Log_warning APIs are equivalent to the Log_error APIs except that
   865         *  they use the predefined {@link #L_warning} event. Log_warning prepends
   866         *  a string to the message which identifies it as a WARNING and specifies
   867         *  the filename and line number of the Log_warning call site.
   868         *
   869         *  @param(fmt)     reference to a constant warning string / fmt string
   870         *  @param(a1)      value for an additional parameter (e.g. a warning code)
   871         *  @param(a2)      value for an additional parameter
   872         *  @param(a3)      value for an additional parameter
   873         *  @param(a4)      value for an additional parameter
   874         *  @param(a5)      value for an additional parameter
   875         *
   876         *  @a(Examples)
   877         *  The following example demonstrates a typical usage.
   878         *  @p(code)
   879         *  Int myArg;
   880         *
   881         *  Log_warning1("Value may be too high: %d", myArg);
   882         *  @p
   883         *  The above event is formatted as:
   884         *  @p(code)
   885         *  WARNING: "MyCode.c", line 50: Value may be too high: 4096
   886         *  @p
   887         */
   888        @Macro Void warning5(CString fmt, IArg a1, IArg a2, IArg a3,
   889            IArg a4, IArg a5);      
   890            
   891        /*!
   892         *  ======== info0 ========
   893         *  Generate a `Log` "info event" with 0 arguments
   894         *
   895         *  @see #info5
   896         */
   897        @Macro Void info0(CString fmt);
   898    
   899        /*!
   900         *  ======== info1 ========
   901         *  Generate a `Log` "info event" with 1 argument
   902         *
   903         *  @see #info5
   904         */
   905        @Macro Void info1(CString fmt, IArg a1);
   906    
   907        /*!
   908         *  ======== info2 ========
   909         *  Generate a `Log` "info event" with 2 arguments
   910         *
   911         *  @see #info5
   912         */
   913        @Macro Void info2(CString fmt, IArg a1, IArg a2);
   914    
   915        /*!
   916         *  ======== info3 ========
   917         *  Generate a `Log` "info event" with 3 arguments
   918         *
   919         *  @see #info5
   920         */
   921        @Macro Void info3(CString fmt, IArg a1, IArg a2, IArg a3);
   922    
   923        /*!
   924         *  ======== info4 ========
   925         *  Generate a `Log` "info event" with 4 arguments
   926         *
   927         *  @see #info5
   928         */
   929        @Macro Void info4(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
   930    
   931        /*!
   932         *  ======== info5 ========
   933         *  Generate a `Log` "info event" with 5 arguments
   934         *
   935         *  The Log_info APIs are provided for easily logging generic
   936         *  "informational" events with call site information. They are similar to
   937         *  the Log_print APIs in that they do not require you to define an event--
   938         *  you simply pass an informative printf-style string which can optionally
   939         *  be formatted with additional arguments. The info record is logged with
   940         *  the predefined event '{@link #L_info}'.
   941         *
   942         *  The Log_info APIs log the {@link #L_info} event which uses the 'INFO'
   943         *  diags category. They do not allow you to specify an event priority.
   944         *
   945         *  Log_info prepends the filename and line number of the call site to the
   946         *  message.
   947         *
   948         *  @param(fmt)     reference to a constant event string / fmt string
   949         *  @param(a1)      value for an additional parameter (e.g. an event code)
   950         *  @param(a2)      value for an additional parameter
   951         *  @param(a3)      value for an additional parameter
   952         *  @param(a4)      value for an additional parameter
   953         *  @param(a5)      value for an additional parameter
   954         *
   955         *  @a(Examples)
   956         *  The following example demonstrates a typical usage.
   957         *  @p(code)
   958         *  Int load;
   959         *
   960         *  Log_info1("Current load: %d", load);
   961         *  @p
   962         *  The above event is formatted as, for example:
   963         *  @p(code)
   964         *  "MyCode.c", line 15: Current load: 25
   965         *  @p
   966         */
   967        @Macro Void info5(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4,
   968            IArg a5);    
   969                      
   970         /*!
   971         *  ======== put0 ========
   972         *  Unconditionally put the specified Log event with 0 arguments
   973         *
   974         *  @see #put8
   975         */
   976        @Macro Void put0(Log.Event evt, Types.ModuleId mid);
   977    
   978        /*!
   979         *  ======== put1 ========
   980         *  Unconditionally put the specified Log event and 1 argument
   981         *
   982         *  @see #put8
   983         */
   984        @Macro Void put1(Log.Event evt, Types.ModuleId mid, IArg a1);
   985    
   986        /*!
   987         *  ======== put2 ========
   988         *  Unconditionally put the specified Log event and 2 arguments
   989         *
   990         *  @see #put8
   991         */
   992         @Macro Void put2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
   993    
   994        /*!
   995         *  ======== put4 ========
   996         *  Unconditionally put the specified Log event and 4 arguments
   997         *
   998         *  @see #put8
   999         */
  1000        @Macro Void put4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
  1001                         IArg a3, IArg a4);
  1002    
  1003        /*!
  1004         *  ======== put8 ========
  1005         *  Unconditionally put the specified Log event and 8 arguments
  1006         *
  1007         *  This method unconditionally puts the specified `{@link Event}`
  1008         *  `evt` into the log. The `{@link Types#ModuleId}` `mid` should be the
  1009         *  module ID of the module which is putting the event.
  1010         *
  1011         *  @param(evt)     the Log event to put into the log
  1012         *  @param(mid)     module ID of the module putting the event
  1013         *  @param(a1)      value for first format conversion character
  1014         *  @param(a2)      value for second format conversion character
  1015         *  @param(a3)      value for third format conversion character
  1016         *  @param(a4)      value for fourth format conversion character
  1017         *  @param(a5)      value for fifth format conversion character
  1018         *  @param(a6)      value for sixth format conversion character
  1019         *  @param(a7)      value for seventh format conversion character
  1020         *  @param(a8)      value for eighth format conversion character
  1021         */
  1022        @Macro Void put8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
  1023                         IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
  1024    
  1025        /*!
  1026         *  ======== write0 ========
  1027         *  Generate a `Log` event with 0 arguments
  1028         *
  1029         *  @see #write8
  1030         */
  1031        @Macro Void write0(Event evt);
  1032    
  1033        /*!
  1034         *  ======== write1 ========
  1035         *  Generate a `Log` event with 1 argument
  1036         *
  1037         *  @see #write8
  1038         */
  1039        @Macro Void write1(Event evt, IArg a1);
  1040    
  1041        /*!
  1042         *  ======== write2 ========
  1043         *  Generate a `Log` event with 2 arguments
  1044         *
  1045         *  @see #write8
  1046         */
  1047        @Macro Void write2(Event evt, IArg a1, IArg a2);
  1048    
  1049        /*!
  1050         *  ======== write3 ========
  1051         *  Generate a `Log` event with 3 arguments
  1052         *
  1053         *  @see #write8
  1054         */
  1055        @Macro Void write3(Event evt, IArg a1, IArg a2, IArg a3);
  1056    
  1057        /*!
  1058         *  ======== write4 ========
  1059         *  Generate a `Log` event with 4 arguments
  1060         *
  1061         *  @see #write8
  1062         */
  1063        @Macro Void write4(Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
  1064    
  1065        /*!
  1066         *  ======== write5 ========
  1067         *  Generate a `Log` event with 5 arguments
  1068         *
  1069         *  @see #write8
  1070         */
  1071        @Macro Void write5(Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
  1072    
  1073        /*!
  1074         *  ======== write6 ========
  1075         *  Generate a `Log` event with 6 arguments
  1076         *
  1077         *  @see #write8
  1078         */
  1079        @Macro Void write6(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
  1080                            IArg a5, IArg a6);
  1081    
  1082        /*!
  1083         *  ======== write7 ========
  1084         *  Generate a `Log` event with 7 arguments
  1085         *
  1086         *  @see #write8
  1087         */
  1088        @Macro Void write7(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
  1089                            IArg a5, IArg a6, IArg a7);
  1090    
  1091        /*!
  1092         *  ======== write8 ========
  1093         *  Generate a `Log` event with 8 arguments
  1094         *
  1095         *  If the mask in the specified `Log` event has any bit set which is
  1096         *  also set in the current module's diagnostics mask, then this call to
  1097         *  write will "raise" the given `Log` event.
  1098         *
  1099         *  @param(evt)     the `Log` event to write
  1100         *  @param(a1)      value for first format conversion character
  1101         *  @param(a2)      value for second format conversion character
  1102         *  @param(a3)      value for third format conversion character
  1103         *  @param(a4)      value for fourth format conversion character
  1104         *  @param(a5)      value for fifth format conversion character
  1105         *  @param(a6)      value for sixth format conversion character
  1106         *  @param(a7)      value for seventh format conversion character
  1107         *  @param(a8)      value for eighth format conversion character
  1108         */
  1109        @Macro Void write8(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
  1110                            IArg a5, IArg a6, IArg a7, IArg a8);
  1111    
  1112        /*!
  1113         *  ======== doPrint ========
  1114         *  Render an event as text via `{@link System#printf System_printf}`
  1115         *
  1116         *  This method is not gated and may make more than one call to
  1117         *  `System_printf`.  This utility method is typically used within the
  1118         *  implementation of a logger which initializes
  1119         *  `{@link #EventRec Log_EventRec}` structures based on `Log` events
  1120         *  produced by the application.
  1121         *
  1122         *  @param(evRec)   a non`NULL` pointer to an initialized `Log_EventRec`
  1123         *                  structure to be formated via
  1124         *                  `{@link System#printf System_printf}`.
  1125         */
  1126        Void doPrint(EventRec *evRec);
  1127    
  1128        /*!
  1129         *  @_nodoc
  1130         *  ======== lookupEventMessage ========
  1131         *  Returns the format string for the event with the given id.
  1132         */
  1133        function lookupEventMessage(eventId);
  1134    
  1135        /*!
  1136         *  @_nodoc
  1137         *  ======== getTargetArgSize ========
  1138         *  Returns the target size of a record argument in bytes (not MAUs).
  1139         */
  1140        function getTargetArgSize();
  1141    
  1142        /*!
  1143         *  @_nodoc
  1144         *  ======== lookupEventName ========
  1145         */
  1146        function lookupEventName(eventId);
  1147    
  1148        /*!
  1149         *  @_nodoc
  1150         *  ======== lookupModuleName ========
  1151         */
  1152        function lookupModuleName(modId);
  1153    
  1154        /*!
  1155         *  @_nodoc
  1156         *  ======== getTargetEventRecSize ========
  1157         *  Returns the record size in bytes (not MAUs).
  1158         */
  1159        function getTargetEventRecSize();
  1160    
  1161    internal:
  1162    
  1163        /*
  1164         *  ======== idToInfo ========
  1165         *  Map event ID strings into a string of the form <eventName>::<eventMsg>
  1166         */
  1167        metaonly config String idToInfo[string] = [];
  1168    }
  1169    /*
  1170     *  @(#) xdc.runtime; 2, 1, 0,0; 2-8-2017 14:15:55; /db/ztree/library/trees/xdc/xdc-D05/src/packages/
  1171     */
  1172