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    module LoggerCallback inherits ILogger {
    44    
    45        /*!
    46         *  ======== OutputFxn ========
    47         *  Character output callback function signature
    48         *
    49         *  The first argument is the parameter returned by the call to
    50         *  `createInstFxn`.
    51         *  The second argument is a pointer to `{@link Log#EventRec}` record.
    52         *  The third argument is the number of arguments in`{@link Log#EventRec}`
    53         *
    54         *  Note: Only evt and arg fields in `Log_EventRec` record are filled and
    55         *        passed to the user supplied function.
    56         */
    57        typedef Void (*OutputFxn)(UArg, Log.EventRec *, Int);
    58    
    59        /*!
    60         *  ======== defaultOutput ========
    61         *  Default output function (always does nothing)
    62         */
    63        extern Void defaultOutput(UArg, Log.EventRec *, Int)
    64            = xdc_runtime_LoggerCallback_defaultOutput;
    65    
    66        /*!
    67         *  ======== CreateInstFxn ========
    68         *  Logger instance create callback function signature
    69         *
    70         *  `{@link LoggerCallback#arg} is passed as an argument to this function.
    71         *  The return value from this function will be passed as an argument
    72         *  to the `outputFxn`. In case of multiple LoggerCallback instances, the
    73         *  return value can be used in `outputFxn` to differentiate among the
    74         *  instances.
    75         */
    76        typedef UArg (*CreateInstFxn)(UArg);
    77    
    78        /*!
    79         *  ======== defaultCreate ========
    80         *  Default create function (always returns 0)
    81         */
    82        extern UArg defaultCreate(UArg) = xdc_runtime_LoggerCallback_defaultCreate;
    83        
    84        /*!
    85         *  ======== outputFxn ========
    86         *  User supplied character callback function
    87         *
    88         *  This function is called when the `Log` module needs to output an event.
    89         *  e.g. `{@link Log#write4()}` or `{@link Log#print2()}`
    90         *
    91         *  By default, this function is configured with a default output function.
    92         *  The default function does nothing and returns.
    93         */
    94        config OutputFxn outputFxn = "&xdc_runtime_LoggerCallback_defaultOutput";
    95    
    96        /*!
    97         *  ======== createInstFxn ========
    98         *  User supplied logger instance create function
    99         *
   100         *  This function is called when the `{@link LoggerCallback#create}` is
   101         *  called.
   102         *
   103         *  By default, this function is configured with a default create function.
   104         *  The default create function always returns `0`.
   105         */
   106        config CreateInstFxn createInstFxn = "&xdc_runtime_LoggerCallback_defaultCreate";
   107    
   108    instance:
   109    
   110        /*!
   111         *  ======== create ========
   112         *  Create a `LoggerCallback` logger instance
   113         */
   114        create();
   115    
   116        /*!
   117         *  ======== arg ========
   118         *  User supplied argument for the user supplied create function.
   119         *
   120         *  This user supplied argument will be passed back as an argument to the
   121         *  `createInstFxn` function. It can be used by the
   122         *  `{@link LoggerCallback#createInstFxn}` function at runtime to
   123         *  differentiate between the multiple logger instances configured in the
   124         *  user config script.
   125         *
   126         *  The user can skip configuring this argument. In such a case, the
   127         *  default value `0` will be passed back as an argument to the
   128         *  `createInstFxn` function. 
   129         */
   130        config UArg arg = 0;
   131    
   132    internal:
   133    
   134        struct Instance_State {
   135            Bool enabled;  /* Logger state */
   136            UArg context;  /* Logger instance */
   137            UArg arg;      /* Logger instance create argument */
   138        };
   139    }
   140    /*
   141     *  @(#) xdc.runtime; 2, 1, 0,0; 2-8-2017 14:15:55; /db/ztree/library/trees/xdc/xdc-D05/src/packages/
   142     */
   143