1    /*
     2     * Copyright (c) 2013-2014, 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    /*
    36     *  ======== LoggerRunMode.xdc ========
    37     */
    38    import xdc.runtime.ILogger;
    39    import ti.uia.runtime.ILoggerSnapshot;
    40    import xdc.rov.ViewInfo;
    41    import xdc.runtime.Log;
    42    import xdc.runtime.Diags;
    43    import xdc.runtime.Types;
    44    import xdc.runtime.Log;
    45    import xdc.runtime.Error;
    46    
    47    
    48    /*!
    49     *  ======== LoggerRunMode ========
    50     *  General purpose logger enabling applications to stream data
    51     *  to an instrumentation host through JTAG or ethernet.
    52     *
    53     *  LoggerRunMode events can be streamed to an instrumentation
    54     *  host in real-time, for targets that support either real-time
    55     *  JTAG or UIA Ethernet transport.  Events can be uploaded without
    56     *  having to halt the target.
    57     *
    58     *  Each LoggerRunMode instance has its own buffer for events logged to that
    59     *  instance. By including the header file, ti/uia/runtime/LogUC.h, you
    60     *  can specify the LoggerRunMode instance that you want the event logged
    61     *  to.
    62     *
    63     *  The logger's buffer is split up into three or more 'packets' for
    64     *  more efficient streaming to the host.  While one packet is being
    65     *  read by the host, the others can be written to.  When a packet
    66     *  is filled, the logger starts writing to the next available packet.
    67     *  Each packet must be large enough to hold {@link #maxEventSize}
    68     *  bytes, plus an additional number of bytes (64) for a header.
    69     *  If the configured {@link #bufSize} is not big enough for three
    70     *  packets of this minimum size, {@link #bufSize} will be increased
    71     *  automatically.
    72     *
    73     *  The logger stores the events in a {@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr}
    74     *  structure that allows them to be sent directly to System Analyzer (e.g. via
    75     *  UDP), enabling
    76     *  efficient streaming of the data from the target to the host.  The first
    77     *  four 32-bit words contain a `{@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr}`
    78     *  structure. This struct is used by the host (e.g. System Analyzer in CCS)
    79     *  to help decode the data (e.g. endianess, length of data, etc.).
    80     *
    81     *  The size of the buffer includes the {@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr}.
    82     *  LoggerRunMode treats the buffer as a UInt32 array, so the application
    83     *  must guarantee the buffers are aligned on word addresses.  Alignment on
    84     *  cache line boundaries is recommended for best performance.
    85     *
    86     *  LoggerRunMode will overwrite older events if the host is not able
    87     *  to upload events quickly enough.
    88     *
    89     *  LoggerRunMode was designed to have as minimal impact as possible on an
    90     *  application  when calling a Log function. There are several configuration
    91     *  parameters that allow an application to get the optimal performance in
    92     *  exchange for certain restrictions.
    93     *
    94     *  Interrupts are disabled during the duration of the log call.
    95     *
    96     *  NOTE:  It is recommended that you use {@link ti.uia.sysbios.LoggingSetup LoggingSetup}
    97     *  to configure the Logger instances. For example to use LoggerRunMode with
    98     *  real-time JTAG transport, set
    99     *  {@link ti.uia.sysbios.LoggingSetup#loggerType LoggingSetup.loggerType}
   100     *  to {@link ti.uia.sysbios.LoggingSetup#LoggerType_JTAGRUNMODE LoggingSetup.LoggerType_JTAGRUNMODE}.
   101     *
   102     *  @a(Examples)
   103     *  The following XDC configuration statements
   104     *  create a logger module, and assign it as the default logger for all
   105     *  modules.
   106     *
   107     *  @p(code)
   108     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
   109     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   110     *  var LoggerRunMode = xdc.useModule('ti.uia.loggers.LoggerRunMode');
   111     *
   112     *  LoggerRunMode.isTimestampEnabled = true;
   113     *
   114     *  var loggerParams = new LoggerRunMode.Params();
   115     *
   116     *  Program.global.logger0 = LoggerRunMode.create(loggerParams);
   117     *  Defaults.common$.logger = Program.global.logger0;
   118     *
   119     *  @p
   120     *
   121     *  @a(Examples)
   122     *  The following C code demonstrates logging to different LoggerRunMode
   123     *  instances.
   124     *
   125     *  @p(code)
   126     *  #include <xdc/std.h>
   127     *  #include <xdc/runtime/Diags.h>
   128     *  #include <xdc/runtime/Log.h>
   129     *  #include <ti/uia/loggers/LoggerRunMode.h>
   130     *  #include <ti/uia/runtime/LogUC.h>
   131     *
   132     *  Int main(Int argc, String argv[])
   133     *  {
   134     *      Log_iwriteUC0(logger0, LoggerRunMode_L_test);
   135     *      Log_iwriteUC1(logger1, LoggerRunMode_L_test, 0x1000);
   136     *  }
   137     *
   138     *  @p
   139     *
   140     *  @a(Examples)
   141     *  The following XDC configuration statements show how to use LoggingSetup
   142     *  with LoggerRunMode.
   143     *
   144     *  @p(code)
   145     *
   146     *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
   147     *  LoggingSetup.loggerType = LoggingSetup.LoggingSetup_JTAGRUNMODE;
   148     *
   149     *  @p
   150     */
   151    
   152    @ModuleStartup
   153    @Template("./LoggerRunMode.xdt")
   154    @CustomHeader
   155    module LoggerRunMode inherits ILoggerSnapshot {
   156    
   157        /*!
   158         *  ======== TransportType ========
   159         *  This enum is used by the instrumentation host to determine what
   160         *  the transport is.
   161         */
   162        enum TransportType {
   163            TransportType_JTAG = 0,
   164            TransportType_ETHERNET = 1
   165        };
   166    
   167        /*!
   168         *  @_nodoc
   169         *  ======== ModuleView ========
   170         */
   171        metaonly struct ModuleView {
   172            Bool       isEnabled;
   173            Bool       isTimestampEnabled;
   174            String     transportType;
   175        }
   176    
   177        /*!
   178         *  @_nodoc
   179         *  ======== InstanceView ========
   180         */
   181        metaonly struct InstanceView {
   182            String    label;
   183            Bool      enabled;
   184            Int       bufferSize;
   185            SizeT     maxEventSize;
   186        }
   187    
   188        metaonly struct RecordView {
   189            Int     sequence;
   190            Long    timestampRaw;
   191            String  modName;
   192            String  text;
   193            Int     eventId;
   194            String  eventName;
   195            IArg    arg0;
   196            IArg    arg1;
   197            IArg    arg2;
   198            IArg    arg3;
   199            IArg    arg4;
   200            IArg    arg5;
   201            IArg    arg6;
   202            IArg    arg7;
   203        }
   204    
   205        /*!
   206         *  @_nodoc
   207         *  ======== rovViewInfo ========
   208         */
   209        @Facet
   210        metaonly config ViewInfo.Instance rovViewInfo =
   211            ViewInfo.create({
   212                viewMap: [
   213                    ['Module',
   214                        {
   215                            type: ViewInfo.MODULE,
   216                            viewInitFxn: 'viewInitModule',
   217                            structName: 'ModuleView'
   218                        }
   219                    ],
   220                    ['Instances',
   221                        {
   222                            type: ViewInfo.INSTANCE,
   223                            viewInitFxn: 'viewInitInstances',
   224                            structName: 'InstanceView'
   225                        }
   226                    ],
   227                    ['Records',
   228                        {
   229                            type: xdc.rov.ViewInfo.INSTANCE_DATA,
   230                            viewInitFxn: 'viewInitRecords',
   231                            structName: 'RecordView'
   232                        }
   233                    ]
   234                ]
   235            });
   236    
   237        /*!
   238         *  ======== RtaData ========
   239         *  Data added to the RTA MetaData file to support System Analyzer
   240         */
   241        @XmlDtd metaonly struct RtaData {
   242            Int instanceId;
   243        }
   244    
   245        /*!
   246         *  ======== transportType ========
   247         *  Transport used to send the records to an instrumentation host
   248         *
   249         *  This parameter is used to specify the transport that will
   250         *  be used to send the buffer to an instrumentation host (e.g. System
   251         *  Analyzer in CCS).
   252         *
   253         *  This parameter is placed into the generated UIA XML file. The
   254         *  instrumentation host can use the XML file to help it auto-detect as
   255         *  much as possible and act accordingly.
   256         */
   257        metaonly config TransportType transportType = TransportType_JTAG;
   258    
   259        /*!
   260         *  @_nodoc
   261         *  ======== customTransportType ========
   262         *  Custom transport used to send the records to an instrumentation host
   263         *
   264         *  If the desired transport is not in the `{@link #TransportType}` enum,
   265         *  and `{@link #transportType}` is set to `{@link #TransportType_CUSTOM}`,
   266         *  this parameter must be filled in with the correct transport name.
   267         *
   268         *  If `{@link #transportType}` is NOT set to
   269         *  `{@link #TransportType_CUSTOM}`, this parameter is ignored.
   270         */
   271        config String customTransportType = null;
   272    
   273        /*!
   274         *  ======== isTimestampEnabled ========
   275         *  Enable or disable logging the 64-bit local CPU timestamp
   276         *  at the start of each event
   277         *
   278         *  Having a timestamp allows an instrumentation host (e.g.
   279         *  System Analyzer) to display events with the correct system time.
   280         */
   281        config Bool isTimestampEnabled = true;
   282    
   283        /*!
   284         *  ======== supportLoggerDisable ========
   285         *  Allow LoggerRunMode instances to be enabled/disabled during runtime.
   286         *
   287         *  Setting supportLoggerDisable to true will increase the
   288         *  footprint of LoggerRunMode.
   289         */
   290        config Bool supportLoggerDisable = false;
   291    
   292        /*!
   293         *  @_nodoc
   294         *  ======== statusLogger ========
   295         *  For backwards compatibility with ti.uia.runtime.LoggerStopMode.
   296         */
   297        metaonly config xdc.runtime.IFilterLogger.Handle statusLogger = null;
   298    
   299        /*!
   300         *  @_nodoc
   301         *  ======== overflowLogger ========
   302         *  For backwards compatibility with ti.uia.runtime.LoggerStopMode.
   303         */
   304        metaonly config ILogger.Handle overflowLogger = null;
   305    
   306        /*!
   307         *  ======== level1Mask ========
   308         *  Mask of diags categories whose initial filtering level is Diags.LEVEL1
   309         *
   310         *  See '{@link #level4Mask}' for details.
   311         */
   312        config Diags.Mask level1Mask = 0;
   313    
   314        /*!
   315         *  ======== level2Mask ========
   316         *  Mask of diags categories whose initial filtering level is Diags.LEVEL2
   317         *
   318         *  See '{@link #level4Mask}' for details.
   319         */
   320        config Diags.Mask level2Mask = 0;
   321    
   322        /*!
   323         *  ======== level3Mask ========
   324         *  Mask of diags categories whose initial filtering level is Diags.LEVEL3
   325         *
   326         *  See '{@link #level4Mask}' for details.
   327         */
   328        config Diags.Mask level3Mask = 0;
   329    
   330        /*!
   331         *  ======== level4Mask ========
   332         *  Mask of diags categories whose initial filtering level is Diags.LEVEL4
   333         *
   334         *  If 'filterByLevel' is true, then all LoggerBuf instances will filter
   335         *  incoming events based on their event level.
   336         *
   337         *  The LoggerRunMode module allows for specifying a different filter level
   338         *  for every Diags bit. These filtering levels are module wide; LoggerBuf
   339         *  does not support specifying the levels on a per-instance basis.
   340         *
   341         *  The setFilterLevel API can be used to change the filtering levels at
   342         *  runtime.
   343         *
   344         *  The default filtering levels are assigned using the 'level1Mask' -
   345         *  'level4Mask' config parameters. These are used to specify, for each of
   346         *  the four event levels, the set of bits which should filter at that
   347         *  level by default.
   348         *
   349         *  The default filtering configuration sets the filter level to
   350         *  Diags.LEVEL4 for all logging-related diags bits so that all events are
   351         *  logged by default.
   352         */
   353        config Diags.Mask level4Mask = Diags.ALL_LOGGING;
   354    
   355        /*!
   356         *  @_nodoc
   357         *  ======== moduleToRouteToStatusLogger ========
   358         *  For backwards compatibility with ti.uia.runtime.LoggerStopMode.
   359         */
   360        metaonly config String moduleToRouteToStatusLogger = null;
   361    
   362        /*!
   363         * @_nodoc
   364         *  ======== L_test ========
   365         *  Event used to benchmark write0.
   366         */
   367        config xdc.runtime.Log.Event L_test = {
   368            mask: xdc.runtime.Diags.USER1,
   369            msg: "LoggerRunMode Test"
   370        };
   371    
   372        /*!
   373         * @_nodoc
   374         *  ======== E_badLevel ========
   375         *  Error raised if get or setFilterLevel receive a bad level value
   376         */
   377        config Error.Id E_badLevel = {
   378             msg: "E_badLevel: Bad filter level value: %d"
   379        };
   380    
   381        metaonly config Int cacheLineSizeInMAUs = 128;
   382    
   383        metaonly Int getNumInstances();
   384    
   385        /*!
   386         *  ======== numCores ========
   387         *  The number of C6X cores running the same image with an instance in
   388         *  shared memory.
   389         *
   390         *  A common use case is to have the same binary image (e.g. .out file)
   391         *  run on multiple cores of multi-core device. This causes a problem if the
   392         *  logger's buffer is in shared memory (e.g. DDR). Since the image is the
   393         *  same for all the cores, each core will attempt to write to the same
   394         *  buffer in the shared memory. To avoid this, either place the logger's
   395         *  buffers in non-shared memory, or set the numCores parameter to
   396         *  the number of cores on the device.
   397         *
   398         *  Note: Use the `{@link #bufSection}` along with the Program.sectMap to
   399         *  place a logger instance's buffer into specific memory.
   400         *
   401         *  Setting numCores to a value greater than 1 signals LoggerRunMode to
   402         *  statically set aside additional memory ((x numCores) to allow each
   403         *  core to have `{@link #transferBufSize}` amount of memory.
   404         *
   405         *  Warning: Setting this parameter to a value greater than one should only
   406         *  be done when there is a single image used on multiple cores of a
   407         *  multi-core device AND the logger instance's buffer is in shared memory.
   408         *  While functionally it will still work, memory will be wasted if both
   409         *  these conditions are not met.
   410         *
   411         *  The default is 1, which means do not reserve any additional memory
   412         *  for the logger.
   413         *
   414         */
   415        config Int numCores = 1;
   416    
   417        /*!
   418         *  @_nodoc
   419         *  ======== initDecoder ========
   420         *  Initialize the Java LoggerRunModeDecoder for use in the LoggerRunMode
   421         *  'Records' ROV view.
   422         */
   423        function initDecoder();
   424    
   425    
   426        /*!
   427         *  ======== cpuId=========
   428         *  CPU ID to put in the packet header as the endpoint ID.
   429         *
   430         *  Not required for C6X or C7X devices (uses DNUM).
   431         */
   432        metaonly config Int cpuId = 0;
   433    
   434        /*!
   435         *  @_nodoc
   436         *  ======== isUploadRequired ========
   437         *  Returns true if aprox. 1 second has elapsed since the last call to flush()
   438         */
   439        @DirectCall
   440        Bool isUploadRequired();
   441    
   442        /*!
   443         *  ======== idleHook ========
   444         *  Hook function that can be called by SysBios's Idle loop.
   445         *  This function ensures that events are uploaded in a timely manner even if
   446         *  they are logged infrequently.
   447         */
   448        @DirectCall
   449        Void idleHook();
   450    
   451        /*!
   452         *  ======== enableAutoConfigOfIdleHook ========
   453         *  If true, the ti.sysbios.knl.Idle module will automatically be
   454         *  configured to call LoggerRunMode\s idleHook function.
   455         *  This function ensures that events are uploaded in a timely manner even if
   456         *  they are logged infrequently.  Set to false if you do not
   457         *  wish to use the ti.sysbios.nk.Idle module.
   458         */
   459        metaonly config Bool enableAutoConfigOfIdleHook = true;
   460    
   461    instance:
   462    
   463        /*!
   464         *  ======== create ========
   465         *  Create a `LoggerRunMode` logger
   466         */
   467        create();
   468    
   469        /*!
   470         *  @_nodoc
   471         *  ======== initBuffer ========
   472         *  Initializes the UIA packet header.
   473         *
   474         *  This API is used to initialize a buffer before it is given to
   475         *  LoggerRunMode (via priming or exchange). The function initializes
   476         *  the {@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr} portion of the buffer.
   477         *
   478         *  @param(buffer)    Pointer to the buffer that LoggerRunMode will
   479         *                    fill with Log events. The first four 32-bit words
   480         *                    will contain the UIAPacket_Hdr structure.
   481         *
   482         *  @param(src)       Used to initialize the UIA source address. For
   483         *                    a single core device, this will generally be 0.
   484         *                    For multi-core devices, it generally corresponds
   485         *                    to the DNUM (on C6xxxx deviecs) or the Ipc
   486         *                    MultiProc id. It must be unique for all cores and
   487         *                    match the configuration in the System Analyzer
   488         *                    endpoint configuration.
   489         */
   490        Void initBuffer(Ptr buffer, UInt16 src);
   491    
   492        /*!
   493         *  @_nodoc
   494         *  ======== flush ========
   495         *  Force LoggerRunMode to use the next packet.
   496         */
   497        Void flush();
   498    
   499        /*!
   500         *  @_nodoc
   501         *  ======== prime ========
   502         *  Initializes the event buffer prior to event logging
   503         */
   504        @DirectCall
   505        Ptr prime();
   506    
   507        /*!
   508         *  @_nodoc
   509         *  ======== exchange ========
   510         *  Set the logger's write pointer to the next packet.
   511         */
   512        @DirectCall
   513        Ptr exchange(Ptr full, Ptr lastWritePtr);
   514    
   515    
   516        /*!
   517         *  @_nodoc
   518         *  ======== initQueueDescriptor ========
   519         *  Initialize the QueueDescriptor Header (for use
   520         *  with JTAGRUNMODE transport)
   521         *  @param(mid) the Logger's module ID
   522         */
   523        @DirectCall
   524        Void initQueueDescriptor(xdc.runtime.Types.ModuleId mid);
   525    
   526        /*!
   527         *  ======== instanceId ========
   528         *  Unique id of the LoggerRunMode instance.
   529         */
   530        config Int16 instanceId = 1;
   531    
   532        /*!
   533         *  @_nodoc
   534         *  ======== transferBufSize ========
   535         *  For backwards compatibility with ti.uia.runtime.LoggerStopMode, bufSize
   536         *  should be used instead.
   537         */
   538        config SizeT transferBufSize = 0;
   539    
   540         /*!
   541         *  ======== maxEventSize ========
   542         *  The maximum event size (in Maus) that can be written with a single
   543         *  event. Must be less than or equal to bufSize - 64.
   544         *
   545         *  The writeMemoryRange API checks to see if the event size required to
   546         *  write the block of memory is larger than maxEventSize.  If so, it will
   547         *  split the memory range up into a number of smaller blocks and log the
   548         *  blocks using separate events with a common snapshot ID in order to
   549         *  allow the events to be collated and the original memory block to be
   550         *  reconstructed on the host.
   551         */
   552        config SizeT maxEventSize = 512;
   553    
   554        /*!
   555         *  ======== bufSize ========
   556         *  LoggerRunMode instance's buffer size in MAUs (Minimum Addressable
   557         *  Units e.g. Bytes)
   558         *
   559         *  NOTE: the buffer size must contain an integer number of 32-bit words
   560         *  (e.g. if a MAU = 1 byte, then the buffer size must be a multiple of 4).
   561         *  The buffer size must also be at least maxEventSize + 64.
   562         */
   563        config SizeT bufSize = 1024;
   564    
   565        /*!
   566         *  ======== bufSection ========
   567         *  Section name for the buffer managed by the static instance.
   568         *
   569         *  The default section is the 'dataMemory' in the platform.
   570         */
   571        metaonly config String bufSection = null;
   572    
   573        /*!
   574         *  @_nodoc
   575         *  ======== bufHeap ========
   576         *  For backwards compatibility with ti.uia.runtime.LoggerStopMode.
   577         */
   578        metaonly config xdc.runtime.IHeap.Handle bufHeap = null;
   579    
   580        /*!
   581         *  ======== write0 ========
   582         *  Process a log event with 0 arguments.
   583         */
   584        @DirectCall
   585        override Void write0(xdc.runtime.Log.Event evt,
   586                    xdc.runtime.Types.ModuleId mid);
   587    
   588        /*!
   589         *  ======== write1 ========
   590         *  Process a log event with 1 argument.
   591         */
   592        @DirectCall
   593        override Void write1(xdc.runtime.Log.Event evt,
   594                    xdc.runtime.Types.ModuleId mid,
   595                    IArg a1);
   596    
   597        /*!
   598         *  ======== write2 ========
   599         *  Process a log event with 2 arguments.
   600         */
   601        @DirectCall
   602        override Void write2(xdc.runtime.Log.Event evt,
   603                    xdc.runtime.Types.ModuleId mid,
   604                    IArg a1, IArg a2);
   605    
   606        /*!
   607         *  ======== write4 ========
   608         *  Process a log event with 4 arguments.
   609         */
   610        @DirectCall
   611        override Void write4(xdc.runtime.Log.Event evt,
   612                    xdc.runtime.Types.ModuleId mid,
   613                    IArg a1, IArg a2, IArg a3, IArg a4);
   614    
   615        /*!
   616         *  ======== write8 ========
   617         *  Process a log event with 8 arguments.
   618         */
   619        @DirectCall
   620        override Void write8(xdc.runtime.Log.Event evt,
   621                    xdc.runtime.Types.ModuleId mid,
   622                    IArg a1, IArg a2, IArg a3, IArg a4,
   623                    IArg a5, IArg a6, IArg a7, IArg a8);
   624    
   625        /*!
   626         *  ======== setFilterLevel ========
   627         *  Sets the level of detail that instances will log.
   628         *
   629         *  Events with the specified level or higher will be logged, events
   630         *  below the specified level will be dropped.
   631         *
   632         *  Events are filtered first by diags category, then by level. If an
   633         *  event's diags category is disabled in the module's diags mask, then it
   634         *  will be filtered out regardless of level. The event will not even be
   635         *  passed to the logger.
   636         *
   637         *  This API allows for setting the filtering level for more than one
   638         *  diags category at a time. The mask parameter can be a single category
   639         *  or multiple categories combined, and the level will be set for all of
   640         *  those categories.
   641         *
   642         *  @param(mask) The diags categories to set the level for
   643         *  @param(filterLevel) The new filtering level for the specified
   644         *                      categories
   645         */
   646        @DirectCall
   647        override Void setFilterLevel(Diags.Mask mask, Diags.EventLevel filterLevel);
   648    
   649        /*!
   650         *  ======== getFilterLevel ========
   651         *  Returns the mask of diags categories currently set to the specified
   652         *  level.
   653         *
   654         *  See '{@link #setFilterLevel}' for an explanation of level filtering.
   655         */
   656        @DirectCall
   657        override Diags.Mask getFilterLevel(Diags.EventLevel level);
   658    
   659        /*!
   660         *  ======== getBufSize ========
   661         *  Returns the Log's configured buffer size.
   662         *
   663         *  @b(returns)     Log's configured buffer size.
   664         */
   665        @DirectCall
   666        SizeT getBufSize();
   667    
   668    internal:
   669        metaonly config Int maxId = 0;
   670    
   671        /*!
   672         *  ======== filterOutEvent ========
   673         */
   674        @DirectCall
   675        Bool filterOutEvent(Diags.Mask mask);
   676    
   677        /*!
   678         * ======== writeStart ========
   679         */
   680        @DirectCall
   681        Ptr writeStart(Object *obj, xdc.runtime.Log.Event evt,
   682                xdc.runtime.Types.ModuleId mid, UInt16 numBytes);
   683    
   684        struct Module_State {
   685            Bool        enabled;       /* Enabled state */
   686            Diags.Mask level1;
   687            Diags.Mask level2;
   688            Diags.Mask level3;
   689            Bits32     lastUploadTstamp;
   690        };
   691    
   692        struct Instance_State {
   693            Bool        enabled;       /* Enabled state */
   694            Int16       instanceId;
   695            Bool        primeStatus;   /* Has the Log been primed? */
   696            UInt32      bufSize;       /* Size of the buffer */
   697            UInt32      *buffer;       /* Ptr to buffer */
   698            UInt32      *write;        /* Ptr to write location */
   699            UInt32      *end;
   700            SizeT       maxEventSizeInBits32; /* Max event size in 32 bit words */
   701            SizeT       maxEventSize;         /* Max event size in target MAUs */
   702            UInt16      numBytesInPrevEvent;
   703            /*
   704             *  incremented by writeMemoryRange when event is too big to log or
   705             *  no buffers available
   706             */
   707            Bits32  droppedEvents;
   708            UInt16  eventSequenceNum;
   709            UInt16  pktSequenceNum;
   710    
   711            /*
   712             *  QueueDescriptor header for JTAG transports.  NULL for all
   713             *  other transports.
   714             */
   715            Char hdr[];
   716    
   717            /*
   718             *  Packet buffers for use with JTAG transports.  NULL for other
   719             *  transports
   720             */
   721            Char packetArray[];
   722            Int numPackets;
   723            UInt32 packetSize;
   724        };
   725    }