1    /*
     2     * Copyright (c) 2013-2015, 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    /*
    35     *  ======== LoggerMin.xdc ========
    36     */
    37    import xdc.runtime.ILogger;
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Log;
    40    import xdc.runtime.Diags;
    41    import xdc.runtime.Types;
    42    import xdc.runtime.Log;
    43    
    44    import ti.uia.runtime.EventHdr;
    45    
    46    /*!
    47     *  ======== LoggerMin ========
    48     *  This general purpose logger is useful in situations where a very small
    49     *  memory overhead is required.
    50     *
    51     *  The logger stores all events in a single buffer with a compact
    52     *  UIAPacket event packet structure that allows them to be sent directly
    53     *  to System Analyzer via JTAG.
    54     *
    55     *  LoggerMin was designed to have as minimal impact as possible on an
    56     *  application when calling a Log function. There are several configuration
    57     *  parameters that allow an application to get the optimal performance in
    58     *  exchange for certain restrictions.
    59     *
    60     *  Interrupts are disabled during the duration of the log call.
    61     *
    62     *  NOTE:  It is recommended that you use {@link ti.uia.sysbios.LoggingSetup LoggingSetup}
    63     *  to configure the Logger. Set
    64     *  {@link ti.uia.sysbios.LoggingSetup#loggerType LoggingSetup.loggerType}
    65     *  to {@link ti.uia.sysbios.LoggingSetup#LoggerType_MIN LoggingSetup.LoggerType_MIN}
    66     *  to specify that the Logger is based on LoggerMin.
    67     *
    68     *  @a(Examples)
    69     *  The following XDC configuration statements
    70     *  create a logger module, and assign it as the default logger for all
    71     *  modules.
    72     *
    73     *  @p(code)
    74     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    75     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    76     *  var LoggerMin = xdc.useModule('ti.uia.loggers.LoggerMin');
    77     *
    78     *  LoggerMin.bufSize = 256;
    79     *  LoggerMin.timestampSize = LoggerMin.TimestampSize_32b;
    80     *  Defaults.common$.logger = LoggerMin.create();
    81     *  @p
    82     *
    83     *  @a(Examples)
    84     *  The following XDC configuration statements show how to use LoggingSetup
    85     *  with LoggerMin.
    86     *
    87     *  @p(code)
    88     *
    89     *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
    90     *  LoggingSetup.loggerType = LoggingSetup.LoggerType_MIN;
    91     *
    92     *  @p
    93     */
    94    
    95    @ModuleStartup
    96    @Template("./LoggerMin.xdt")
    97    @CustomHeader
    98    module LoggerMin inherits ILogger {
    99    
   100        /*!
   101         *  ======== TimestampSize ========
   102         *  Enum of size of timestamps to log with events.
   103         */
   104        enum TimestampSize {
   105            TimestampSize_NONE = 0, /*! No timestamps will be logged with events */
   106            TimestampSize_32b = 1,  /*! 32-bit timestamp */
   107            TimestampSize_64b = 2   /*! 64-bit timestamp */
   108        };
   109    
   110        /*!
   111         *  @_nodoc
   112         *  ======== ModuleView ========
   113         */
   114        metaonly struct ModuleView {
   115            Bool       isEnabled;
   116            String     timestampSize;
   117            Int        bufferSize;
   118        }
   119    
   120        metaonly struct RecordView {
   121            Int     sequence;
   122            Long    timestampRaw;
   123            String  modName;
   124            String  text;
   125            Int     eventId;
   126            String  eventName;
   127            IArg    arg0;
   128            IArg    arg1;
   129            IArg    arg2;
   130            IArg    arg3;
   131            IArg    arg4;
   132            IArg    arg5;
   133            IArg    arg6;
   134            IArg    arg7;
   135        }
   136    
   137        /*!
   138         *  @_nodoc
   139         *  ======== rovViewInfo ========
   140         */
   141        @Facet
   142        metaonly config ViewInfo.Instance rovViewInfo =
   143            ViewInfo.create({
   144                viewMap: [
   145                    ['Module',
   146                        {
   147                            type: ViewInfo.MODULE,
   148                            viewInitFxn: 'viewInitModule',
   149                            structName: 'ModuleView'
   150                        }
   151                    ],
   152                    ['Records',
   153                        {
   154                            type: xdc.rov.ViewInfo.MODULE_DATA,
   155                            viewInitFxn: 'viewInitRecords',
   156                            structName: 'RecordView'
   157                        }
   158                    ]
   159                ]
   160            });
   161    
   162        /*!
   163         *  ======== RtaData ========
   164         *  Data added to the RTA MetaData file to support System Analyzer
   165         */
   166        @XmlDtd metaonly struct RtaData {
   167            Int instanceId;
   168        }
   169    
   170        /*! @_nodoc
   171         *  ======== getLoggerInstanceId ========
   172         *  returns the id of this logger instance
   173         *  (always 1 for LoggerMin)
   174         */
   175        metaonly function getLoggerInstanceId(inst);
   176    
   177        /*!
   178         *  @_nodoc
   179         *  ======== initBuffer ========
   180         *  Initializes the UIA packet header portion of the buffer.
   181         *
   182         *  @param(buffer)    Pointer to the buffer that LoggerMin will
   183         *                    fill with Log events. The first four 32-bit words
   184         *                    will contain the UIAPacket_Hdr structure.
   185         *
   186         *  @param(endpointId)   Used to initialize the UIA source address. For
   187         *                    a single core device, this will generally be 0.
   188         *                    For multi-core devices, it generally corresponds
   189         *                    to the DNUM (on C6xxxx deviecs) or the Ipc
   190         *                    MultiProc id. It must be unique for all cores and
   191         *                    match the configuration in the System Analyzer
   192         *                    endpoint configuration.
   193         */
   194        @Macro Void initBuffer(Ptr buffer, UInt16 endpointId);
   195    
   196        /*!
   197         *  @_nodoc
   198         *  ======== flush ========
   199         */
   200        @DirectCall
   201        Void flush();
   202    
   203        /*!
   204         *  ======== bufSize ========
   205         *  LoggerMin buffer size in MAUs (Minimum Addressable Units e.g.
   206         *  Bytes).
   207         *
   208         *  The buffer size must be less than 65536 bytes.
   209         *
   210         *  NOTE: the buffer size must contain an integer number of 32-bit words
   211         *  (e.g. if a MAU = 1 byte, then the buffer size must be a multiple of 4).
   212         *  The buffer size must also be at least maxEventSize + 64.
   213         */
   214        config SizeT bufSize = 512;
   215    
   216        /*!
   217         *  ======== bufSection ========
   218         *  Section name for the buffer managed by the static instance.
   219         *
   220         *  The default section is the 'dataMemory' in the platform.
   221         */
   222        metaonly config String bufSection = null;
   223    
   224        /*!
   225         * @_nodoc
   226         *  ======== numCores ========
   227         *  Number of cores running the same image with an instance in shared memory
   228         *
   229         *  A common use case is to have the same binary image (e.g. .out file)
   230         *  run on multiple cores of multi-core device. This causes a problem if the
   231         *  logger's buffer is in shared memory (e.g. DDR). Since the image is the
   232         *  same for all the cores, each core will attempt to write to the same
   233         *  buffer in the shared memory. To avoid this, either the logger's buffers
   234         *  must be in non-shared memory or by setting the numCores parameter to
   235         *  the number of cores on the device.
   236         *
   237         *  Note: the `{@link #bufSection}` along with the Program.sectMap is how
   238         *  a logger instance's buffer is placed into specific memory.
   239         *
   240         *  Setting numCores to a value great than 1 signals LoggerCircBuf to
   241         *  statically set aside additional memory ((x numCores) to allow each
   242         *  core to have `{@link #transferBufSize}` amount of memory.
   243         *
   244         *  Warning: setting this parameter to a value greater than one should only
   245         *  be done when there is a single image used on multiple cores of a
   246         *  multi-core device AND the logger instance's buffer is in shared memory.
   247         *  While functionally it will still work, memory will be wasted if both
   248         *  these conditions are not met.
   249         *
   250         *  The default is 1, which means do not reserve any additional memory
   251         *  for the logger.
   252         */
   253        config Int numCores = 1;
   254    
   255        /*!
   256         *  ======== memoryAlignmentInMAUs ========
   257         *  Memory Alignment in MAUs (Minimum Addressable Units)
   258         *
   259         *  Specifies alignment to use when allocating the internal packet buffer
   260         *  Set to 1 if no alignment is required.
   261         */
   262        metaonly config Int memoryAlignmentInMAUs = 1;
   263    
   264        /*!
   265         *  ======== timestampSize ========
   266         *  Configure the size of the timestamp to use.
   267         *  For minimum event footprint, configure as TimestampSize_32b (default).
   268         *
   269         *  Having a timestamp allows an instrumentation host (e.g.
   270         *  System Analyzer) to display events with the correct system time.
   271         */
   272        config TimestampSize timestampSize = TimestampSize_32b;
   273    
   274        /*!
   275         * @_nodoc
   276         *  ======== L_test ========
   277         *  Event used to benchmark write0.
   278         */
   279        config xdc.runtime.Log.Event L_test = {
   280            mask: xdc.runtime.Diags.USER1,
   281            msg: "LoggerMin Test"
   282        };
   283    
   284        /*!
   285         *  ======== supportLoggerDisable ========
   286         *  Allow Logger instances to be enabled/disabled during runtime.
   287         *
   288         *  LoggerMin footprint is smaller when supportLoggerDisable is
   289         *  false.
   290         */
   291        config Bool supportLoggerDisable = false;
   292    
   293        /*!
   294         *  @_nodoc
   295         *  ======== endpointId ========
   296         *  An id indicating which core in a multicore device the logger is in
   297         *  (For C6X devices, set this to the DNUM value)
   298         */
   299        config Bits16 endpointId = 0;
   300    
   301        /*!
   302         *  @_nodoc
   303         *  ======== loggerInstanceId ========
   304         *  An id indicating which logger this is for applications with multiple loggers
   305         *  (Required for metadata generation - RtaData)
   306         */
   307        config Bits16 loggerInstanceId = 0;
   308    
   309        /*!
   310         *  @_nodoc
   311         *  ======== write ========
   312         */
   313        @DirectCall
   314        Void write(xdc.runtime.Log.Event evt,
   315                    xdc.runtime.Types.ModuleId mid,
   316                    IArg numBytes,
   317                    IArg a1, IArg a2, IArg a3, IArg a4,
   318                    IArg a5, IArg a6, IArg a7, IArg a8);
   319    
   320        /*!
   321         *  @_nodoc
   322         *  ======== initDecoder ========
   323         *  Initialize the Java LoggerMinDecoder for use in the LoggerMin
   324         *  'Records' ROV view.
   325         */
   326        function initDecoder();
   327    
   328    instance:
   329    
   330        /*!
   331         *  ======== create ========
   332         *  Create a `LoggerMin` logger
   333         */
   334        create();
   335    
   336        /*!
   337         *  ======== write0 ========
   338         *  Process a log event with 0 arguments.
   339         */
   340        @DirectCall
   341        override Void write0(xdc.runtime.Log.Event evt,
   342                    xdc.runtime.Types.ModuleId mid);
   343    
   344        /*!
   345         *  ======== write1 ========
   346         *  Process a log event with 1 argument.
   347         */
   348        @DirectCall
   349        override Void write1(xdc.runtime.Log.Event evt,
   350                    xdc.runtime.Types.ModuleId mid,
   351                    IArg a1);
   352    
   353        /*!
   354         *  ======== write2 ========
   355         *  Process a log event with 2 arguments.
   356         */
   357        @DirectCall
   358        override Void write2(xdc.runtime.Log.Event evt,
   359                    xdc.runtime.Types.ModuleId mid,
   360                    IArg a1, IArg a2);
   361    
   362        /*!
   363         *  ======== write4 ========
   364         *  Process a log event with 4 arguments.
   365         */
   366        @DirectCall
   367        override Void write4(xdc.runtime.Log.Event evt,
   368                    xdc.runtime.Types.ModuleId mid,
   369                    IArg a1, IArg a2, IArg a3, IArg a4);
   370    
   371        /*!
   372         *  ======== write8 ========
   373         *  Process a log event with 8 arguments.
   374         */
   375        @DirectCall
   376        override Void write8(xdc.runtime.Log.Event evt,
   377                    xdc.runtime.Types.ModuleId mid,
   378                    IArg a1, IArg a2, IArg a3, IArg a4,
   379                    IArg a5, IArg a6, IArg a7, IArg a8);
   380    
   381    
   382        @DirectCall
   383        override Bool enable();
   384    
   385        @DirectCall
   386        override Bool disable();
   387    
   388    internal:
   389    
   390        /*
   391         *  ======== getContents =========
   392         *  For testing.
   393         *  Fills buffer that is passed in with unread data, up to size MAUs
   394         *  in length.
   395         *
   396         *  The logger is responsible for ensuring that no partial event records
   397         *  are stored in the buffer.  Bytes are in target endianness.
   398         *
   399         *  @param(hdrBuf)   Ptr to a buffer that is at least <size> MAUs in length
   400         *  @param(size)     The max number of MAUs to be read into the buffer
   401         *  @param(cpSize)   The number of MAUs actually copied
   402         *
   403         *  @a(return)       returns false if logger has no more records to read
   404         */
   405        Bool getContents(Object *obj, Ptr hdrBuf, SizeT size, SizeT *cpSize);
   406    
   407        /*
   408         *  ======== isEmpty =========
   409         *  For testing.
   410         *
   411         *  returns true if the Logger buffer is empty, otherwise false.
   412         */
   413        Bool isEmpty(Object *obj);
   414    
   415        /*
   416         *  ======== genTimestamp ========
   417         *  Write out the timestamp, depending on whether it's 64 bit,
   418         *  32 bit, or disabled.
   419         */
   420        Ptr genTimestamp(Ptr writePtr);
   421    
   422        struct Module_State {
   423            Bool        enabled;          /* Enabled state */
   424            Bool        empty;
   425            UInt16      numBytesInPrevEvent;
   426            UInt16      droppedEvents;    /* Currently not used */
   427            Char        packetBuffer[];
   428            /*
   429             *  DO NOT RENAME the following elements - they are used by System
   430             *  Analyzer JTAG Transport
   431             */
   432            UInt32      *start;        /* Ptr to start of event log buffer */
   433            UInt32      *write;        /* Ptr to write location */
   434            UInt32      *end;          /* Ptr to end of the buffer */
   435            UInt16      eventSequenceNum;  /* event sequence number */
   436            UInt16      pktSequenceNum;
   437            EventHdr.HdrType eventType;
   438        };
   439    
   440        struct Instance_State {
   441        };
   442    }