1    /* 
     2     *  Copyright (c) 2012 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     *  ======== LoggerCallback.xdc ========
    15     */
    16    package xdc.runtime;
    17    /*!
    18     *  ======== LoggerCallback ========
    19     *  A logger that passes events to a user supplied callback function
    20     *
    21     *  @a(Examples)
    22     *  Configuration example: The following XDC configuration statements
    23     *  create a logger instance, plug in the user defined functions, assign it as
    24     *  the default logger for all modules, and enable `USER1` logging in all
    25     *  modules of the package `my.pkg`. See the
    26     *  `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function for details on
    27     *  specifying the module names.
    28     *
    29     *  @p(code)
    30     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    31     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    32     *  var LoggerCallback = xdc.useModule('xdc.runtime.LoggerCallback');
    33     *  LoggerCallback.outputFxn = "&userOutputFunc";
    34     *  LoggerCallback.createInstFxn = "&userCreateInstFunc";
    35     *
    36     *  var loggerParams = new Logger.Params();
    37     *  loggerParams.arg = 1;
    38     *  Defaults.common$.logger = LoggerCallback.create(loggerParams);
    39     *  Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);
    40     *  @p
    41     */
    42    @ModuleStartup
    43    @RomConsts
    44    
    45    module LoggerCallback inherits ILogger {
    46    
    47        /*!
    48         *  ======== OutputFxn ========
    49         *  Character output callback function signature
    50         *
    51         *  The first argument is the parameter returned by the call to
    52         *  `createInstFxn`.
    53         *  The second argument is a pointer to `{@link Log#EventRec}` record.
    54         *  The third argument is the number of arguments in`{@link Log#EventRec}`
    55         *
    56         *  Note: Only evt and arg fields in `Log_EventRec` record are filled and
    57         *        passed to the user supplied function.
    58         */
    59        typedef Void (*OutputFxn)(UArg, Log.EventRec *, Int);
    60    
    61        /*!
    62         *  ======== defaultOutput ========
    63         *  Default output function (always does nothing)
    64         */
    65        extern Void defaultOutput(UArg, Log.EventRec *, Int)
    66            = xdc_runtime_LoggerCallback_defaultOutput;
    67    
    68        /*!
    69         *  ======== CreateInstFxn ========
    70         *  Logger instance create callback function signature
    71         *
    72         *  `{@link LoggerCallback#arg} is passed as an argument to this function.
    73         *  The return value from this function will be passed as an argument
    74         *  to the `outputFxn`. In case of multiple LoggerCallback instances, the
    75         *  return value can be used in `outputFxn` to differentiate among the
    76         *  instances.
    77         */
    78        typedef UArg (*CreateInstFxn)(UArg);
    79    
    80        /*!
    81         *  ======== defaultCreate ========
    82         *  Default create function (always returns 0)
    83         */
    84        extern UArg defaultCreate(UArg) = xdc_runtime_LoggerCallback_defaultCreate;
    85        
    86        /*!
    87         *  ======== outputFxn ========
    88         *  User supplied character callback function
    89         *
    90         *  This function is called when the `Log` module needs to output an event.
    91         *  e.g. `{@link Log#write4()}` or `{@link Log#print2()}`
    92         *
    93         *  By default, this function is configured with a default output function.
    94         *  The default function does nothing and returns.
    95         */
    96        config OutputFxn outputFxn = "&xdc_runtime_LoggerCallback_defaultOutput";
    97    
    98        /*!
    99         *  ======== createInstFxn ========
   100         *  User supplied logger instance create function
   101         *
   102         *  This function is called when the `{@link LoggerCallback#create}` is
   103         *  called.
   104         *
   105         *  By default, this function is configured with a default create function.
   106         *  The default create function always returns `0`.
   107         */
   108        config CreateInstFxn createInstFxn = "&xdc_runtime_LoggerCallback_defaultCreate";
   109    
   110    instance:
   111    
   112        /*!
   113         *  ======== create ========
   114         *  Create a `LoggerCallback` logger instance
   115         */
   116        create();
   117    
   118        /*!
   119         *  ======== arg ========
   120         *  User supplied argument for the user supplied create function.
   121         *
   122         *  This user supplied argument will be passed back as an argument to the
   123         *  `createInstFxn` function. It can be used by the
   124         *  `{@link LoggerCallback#createInstFxn}` function at runtime to
   125         *  differentiate between the multiple logger instances configured in the
   126         *  user config script.
   127         *
   128         *  The user can skip configuring this argument. In such a case, the
   129         *  default value `0` will be passed back as an argument to the
   130         *  `createInstFxn` function. 
   131         */
   132        config UArg arg = 0;
   133    
   134    internal:
   135    
   136        struct Instance_State {
   137            Bool enabled;  /* Logger state */
   138            UArg context;  /* Logger instance */
   139            UArg arg;      /* Logger instance create argument */
   140        };
   141    }
   142    /*
   143     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:15; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   144     */
   145