1    /*
     2     * Copyright (c) 2012, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    
    33    /*
    34     *  ======== LoggerIdle.xdc ========
    35     */
    36    import xdc.runtime.ILogger;
    37    import xdc.runtime.Log;
    38    import xdc.rov.ViewInfo;
    39    
    40    /*!
    41     *  ======== LoggerIdle ========
    42     *  A logger which routes `Log` events to a users transport function.
    43     *
    44     *  This logger processes log events as they are generated, stores them in
    45     *  a buffer and durring idle sends a section of the buffer to the users
    46     *  transport function.  If you are seeing no log events or dropping too
    47     *  many events check that you are not logging too often and have enough idle
    48     *  time to send. LoggerIdle is compatable with StellarisWare and MWare
    49     *  devices. Example transports for UART (B92 and F28M35x) and USB (F28M35x)
    50     *  as well as initialization functions are included in the evmF28M35x.c files
    51     *  under the device folder in the ti.examples directory.
    52     *
    53     *  @a(Examples)
    54     *  Configuration example: The following XDC configuration statements
    55     *  create a logger module, and assign it as the default logger for all
    56     *  modules.
    57     *
    58     *  @p(code)
    59     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    60     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    61     *  var LoggerIdle =
    62                    xdc.useModule('ti.mcusdk.utils.LoggerIdle');
    63     *
    64     *  LoggerIdle.bufferSize = 60;
    65     *  LoggerIdle.timestamp = false;
    66     *  LoggerIdle.transportType = LoggerIdle.TransportType_UART;
    67     *  LoggerIdle.transportFxn = '&LoggerIdle_uartSend';
    68     *  var LoggerIdleParams = new LoggerIdle.Params();
    69     *  Defaults.common$.logger = LoggerIdle.create(LoggerIdleParams);
    70     *  @p
    71     */
    72    
    73    module LoggerIdle inherits ILogger {
    74    
    75        /*!
    76         *  ======== TransportType ========
    77         *  Used to specify the type of transport to use
    78         *
    79         *  This enum is used by the instrumentation host to determine what
    80         *  the transport is. It is not used by the target code.
    81         */
    82        enum TransportType {
    83            TransportType_UART = 0,
    84            TransportType_USB = 1,
    85            TransportType_ETHERNET = 2,
    86            TransportType_CUSTOM = 3
    87        };
    88    
    89        /*!
    90         *  @_nodoc
    91         *  ======== ModuleView ========
    92         */
    93        metaonly struct ModuleView {
    94            Bool       isEnabled;
    95            Bool       isTimestampEnabled;
    96            Int        bufferSize;
    97            UInt       sequenceNumber;
    98            String     transportType;
    99            String     customTransport;
   100        }
   101    
   102        metaonly struct RecordView {
   103            Int     sequence;
   104            Long    timestampRaw;
   105            String  modName;
   106            String  text;
   107            Int     eventId;
   108            String  eventName;
   109            IArg    arg0;
   110            IArg    arg1;
   111            IArg    arg2;
   112            IArg    arg3;
   113            IArg    arg4;
   114            IArg    arg5;
   115            IArg    arg6;
   116            IArg    arg7;
   117        }
   118    
   119        /*!
   120         *  @_nodoc
   121         *  ======== rovViewInfo ========
   122         */
   123        @Facet
   124        metaonly config ViewInfo.Instance rovViewInfo =
   125            ViewInfo.create({
   126                viewMap: [
   127                    ['Module',
   128                        {
   129                            type: ViewInfo.MODULE,
   130                            viewInitFxn: 'viewInitModule',
   131                            structName: 'ModuleView'
   132                        }
   133                    ],
   134                    ['Records',
   135                        {
   136                            type: xdc.rov.ViewInfo.MODULE_DATA,
   137                            viewInitFxn: 'viewInitRecords',
   138                            structName: 'RecordView'
   139                        }
   140                    ]
   141                ]
   142            });
   143    
   144        /*!
   145         *  ======== LoggerFxn ========
   146         *  Typedef for the transport function pointer.
   147         */
   148        typedef Int (*LoggerFxn)(UChar *, Int);
   149    
   150        /*!
   151         *  ======== bufferSize ========
   152         *  LoggerIdle buffer size in MAUS
   153         */
   154        config SizeT bufferSize = 256;
   155    
   156        /*!
   157         *  ======== isTimestampEnabled ========
   158         *  Enable or disable logging the 64b local CPU timestamp
   159         *  at the start of each event
   160         *
   161         *  Having a timestamp allows an instrumentation host (e.g.
   162         *  System Analyzer) to display events with the correct system time.
   163         */
   164        config Bool isTimestampEnabled = true;
   165    
   166        /*!
   167         *  ======== transportType ========
   168         *  Transport used to send the records to an instrumentation host
   169         *
   170         *  This parameter is used to specify the transport that the
   171         *  `{@link #transportFxn}` function will use to send the buffer to
   172         *  an instrumentation host (e.g. System Analyzer in CCS).
   173         *
   174         *  This parameter is placed into the generated UIA XML file. The
   175         *  instrumentation host can use the XML file to help it auto-detect as
   176         *  much as possible and act accordingly.
   177         *
   178         *  If the desired transport is not in the `{@link #TransportType}` enum,
   179         *  select `{@link #TransportType_CUSTOM}` and set the
   180         *  `{@link #customTransportType}` string with the desired string.
   181         */
   182        metaonly config TransportType transportType = TransportType_UART;
   183    
   184        /*!
   185         *  ======== customTransportType ========
   186         *  Custom transport used to send the records to an instrumentation host
   187         *
   188         *  If the desired transport is not in the `{@link #TransportType}` enum,
   189         *  and `{@link #transportType}` is set to `{@link #TransportType_CUSTOM}`,
   190         *  this parameter must be filled in with the correct transport name.
   191         *
   192         *  If `{@link #transportType}` is NOT set to
   193         *  `{@link #TransportType_CUSTOM}`, this parameter is ignored.
   194         */
   195        config String customTransportType = null;
   196    
   197        /*!
   198         *  ======== transportFxn ========
   199         *  User defined transport function responsible for transmitted the records
   200         */
   201        config LoggerFxn transportFxn = null;
   202    
   203        /*!
   204         *  @_nodoc
   205         *  ======== L_test ========
   206         *  Event used for benchmark tests
   207         */
   208        config xdc.runtime.Log.Event L_test = {
   209            mask: xdc.runtime.Diags.USER1,
   210            msg: "Test Event"
   211        };
   212    
   213    instance:
   214        /*!
   215         *  ======== create ========
   216         *  Create a `LoggerIdle` logger
   217         *
   218         *  The logger instance will route all log events it receives to
   219         *  the Uart.
   220         */
   221        create();
   222    
   223        @DirectCall
   224        override Void write0(xdc.runtime.Log.Event evt, xdc.runtime.Types.ModuleId mid);
   225    
   226        @DirectCall
   227        override Void write1(xdc.runtime.Log.Event evt, xdc.runtime.Types.ModuleId mid,
   228                                IArg a1);
   229    
   230        @DirectCall
   231        override Void write2(xdc.runtime.Log.Event evt, xdc.runtime.Types.ModuleId mid,
   232                                IArg a1, IArg a2);
   233    
   234        @DirectCall
   235        override Void write4(xdc.runtime.Log.Event evt, xdc.runtime.Types.ModuleId mid,
   236                                IArg a1, IArg a2, IArg a3, IArg a4);
   237    
   238        @DirectCall
   239        override Void write8(xdc.runtime.Log.Event evt, xdc.runtime.Types.ModuleId mid,
   240                                IArg a1, IArg a2, IArg a3, IArg a4,
   241                                IArg a5, IArg a6, IArg a7, IArg a8);
   242    
   243    internal:
   244    
   245        /*!
   246         *  ======== idleWrite =========
   247         *  Idle function that calls the transport function.
   248         */
   249        Void idleWrite();
   250    
   251        struct Module_State {
   252            LoggerFxn loggerFxn;
   253            Bool enabled;          /* If the logger is enabled or not */
   254            Bool empty;         /* True if there is data in the buffer */
   255            UInt idleSequence;     /* Sequence number for the log event */
   256            UInt bufferSize;       /* Size of the buffer in words */
   257            UInt32 idleBuffer[];   /* Stores log events to be sent */
   258            UInt32 *bufferRead;    /* Pointer to the first word to be read */
   259            UInt32 *bufferWrite;   /* Pointer to the next word to write to */
   260            UInt32 *bufferPad;     /* Pointer to the last word in the buffer when
   261                                      the buffer overflows into the 10 word pad */
   262            UInt32 *bufferEnd;     /* Pointer to begining of the buffer pad */
   263        };
   264    
   265        struct Instance_State {
   266        };
   267    }