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, plugs in the user defined functions, assign it as 
    24     *  the default logger for all modules, and enable `USER1` logging in all 
    25     *  all 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         *  ======== CreateInstFxn ========
    61         *  Logger instance create callback function signature
    62         *
    63         *  `{@link LoggerCallback#arg} is passed as an argument to this function.
    64         *  The return value from this function will be passed as an argument
    65         *  to the `outputFxn`. In case of multiple LoggerCallback instances, the 
    66         *  return value can be used in `outputFxn` to differentiate among the 
    67         *  instances.
    68         */
    69        typedef UArg (*CreateInstFxn)(UArg);
    70    
    71        /*!
    72         *  ======== outputFxn ========
    73         *  User supplied character callback function
    74         *
    75         *  This function is called when the `Log` module needs to output an event.
    76         *  e.g. `{@link Log#write4()}` or `{@link Log#print2()}`
    77         *
    78         *  By default, this function is configured with a default output function.
    79         *  The default function does nothing and returns. 
    80         */
    81        config OutputFxn outputFxn = "&xdc_runtime_LoggerCallback_defaultOutput";
    82    
    83        /*!
    84         *  ======== createInstFxn ========
    85         *  User supplied logger instance create function
    86         *
    87         *  This function is called when the `{@link LoggerCallback#create}` is 
    88         *  called.
    89         *
    90         *  By default, this function is configured with a default create function.
    91         *  The default create function returns `0` always.
    92         */
    93        config CreateInstFxn createInstFxn = "&xdc_runtime_LoggerCallback_defaultCreate";
    94    
    95    instance:
    96    
    97        /*!
    98         *  ======== create ========
    99         *  Create a `LoggerCallback` logger instance
   100         */
   101        create();
   102    
   103        /*!
   104         *  ======== arg ========
   105         *  User supplied argument for the user supplied create function.
   106         *
   107         *  This user supplied argument will be passed back as an argument to the
   108         *  `createInstFxn` function. It can be used by the
   109         *  `{@link LoggerCallback#createInstFxn}` function at runtime to 
   110         *  differentiate between the multiple logger instances configured in the 
   111         *  user config script.
   112         *
   113         *  The user can skip configuring this argument. In such a case, the 
   114         *  default value `0` will be passed back as an argument to the 
   115         *  `createInstFxn` function. 
   116         */
   117        config UArg arg = 0;
   118     
   119    internal:
   120    
   121        struct Instance_State {
   122            Bool enabled;  /* Logger state */
   123            UArg context;  /* Logger instance */
   124            UArg arg;      /* Logger instance create argument */ 
   125        };
   126    }
   127    /*
   128     *  @(#) xdc.runtime; 2, 1, 0,384; 9-3-2012 16:22:19; /db/ztree/library/trees/xdc/xdc-y35x/src/packages/
   129     */
   130