1    /*
     2     * Copyright (c) 2013, 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     *  ======== LoggingSetup.xdc ========
    36     */
    37    
    38    package ti.uia.sysbios;
    39    
    40    /*!
    41     *  ======== LoggingSetup ========
    42     *  Module to aid in configuring SYSBIOS logging using UIA and System Analyzer
    43     * @p
    44     * The LoggingSetup module automates the process of configuring an application
    45     * to use UIA events, and configures SYS/BIOS modules to capture user-specified
    46     * information such as CPU Load, Task Load and Task Execution so that it can
    47     * be displayed by System Analyzer.  It also automates the creation of
    48     * infrastructure modules such as loggers, the ServiceManager and RTA modules
    49     * to enable the capture and upload of the events over a user-specified transport.
    50     * Both JTAG and Non-JTAG transports are supported.
    51     * @p
    52     *  The following configuration script demonstrates the use of the LoggingSetup
    53     *  module in the XDC configuration file for the application:
    54     *
    55     * @a(Example)
    56     * Example 1: Configuring an application to use the default settings provided
    57     * by LoggingSetup.  The following default settings are automatically applied:
    58     * @p(blist)
    59     *    - Logging UIA events from user-provided C code.  User provided C code is
    60     *    treated as part of the xdc.runtime.Main module.  A circular buffer of
    61     *    size {@link #mainLoggerSize} Bytes is enabled by default to support
    62     *    this.
    63     *   - Event logging is enabled for the SYS/BIOS Load and Task modules in order
    64     *   to allow System Analyzer to display CPU Load, Task Load, and Task Execution
    65     *   information.  Logging of SWI and HWI events is disabled by default.
    66     *   In order to optimize event capture and minimize event loss, two loggers
    67     *   are created: one to store events from the SYS/BIOS Load module
    68     *   and the other to store events from other SYS/BIOS modules.
    69     *   - Multicore event correlation is enabled by default.  This enables the
    70     *    {@link ti.uia.runtime.LogSync LogSync} module and creation of a dedicated
    71     *    logger for sync point events with a default circular buffer size of
    72     *    {@link ti.uia.runtime.LogSync#defaultSyncLoggerSize LogSync.defaultSyncLoggerSize} Bytes.
    73     *   - The Event Upload Mode is configured for UploadMode_JTAGSTOPMODE.  This
    74     *    allows events to be uploaded when the target halts via JTAG.
    75     *  @p
    76     *  @p(code)
    77     *  // the Log module provides logging APIs for use by the user's software
    78     *  var Log = xdc.useModule('xdc.runtime.Log');
    79     *  // the LoggingSetup module's default settings configure much of the UIA infrastructure.
    80     *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
    81     *  @p
    82     *  @p(html)
    83     *  <hr />
    84     *  @p
    85     * @a(Example)
    86     * Example 2: A number of 'template' applications come with the UIA product, that
    87     * provide predefined XDC configuration scripts and C code for use in new
    88     * projects.  These templates provide good examples of how to configure
    89     * the various modules that are involved in setting up the UIA infrastructure,
    90     * including the LoggingSetup module.
    91     * They can also be generated directly by CCS, using the CCS TI Resource
    92     * Explorer.  The following steps show how to use CCSv5.x.x to generate a
    93     * new project that configures the NDK to provide an Ethernet transport for
    94     * uploading events from the target to the host. :
    95     * @p(blist)
    96     *   - View / TI Resource Explorer : Opens the TI Resource Explorer.
    97     *   - Expand the System Analyzer (UIA Target) section
    98     *   - Expand the C6000, C64xx Multicore DSP, and EVMC6472 sections.
    99     *   - Expand the Single-core Examples and select Stairstep Ethernet.
   100     *   - Import the Stairstep Ethernet example into CCS.
   101     *   - Open the configuration file to see how LoggingSetup is configured
   102     *   with the NDK to use Ethernet as a transport for UIA events and
   103     *   commands.
   104     */
   105    metaonly module LoggingSetup
   106    {
   107    
   108        /*!
   109         *  ======== UploadMode ========
   110         *  Modes for uploading events to the host.
   111         *
   112         *  By default, events are uploaded using the JTAG connection in
   113         *  stop-mode. Events are uploaded over JTAG when the target halts. This
   114         *  mode requires that JTAG connections are supported by the target.
   115         *  If you want to use Ethernet, probe points, a simulator, or some other
   116         *  method for uploading events, you can specify one of those upload
   117         *  methods by configuring the  {@link #eventUploadMode} parameter.
   118         *  For example, you could use the following if you were running a
   119         *  simulator:
   120         *  @p(code)
   121         *  var LoggingSetup =
   122         *  xdc.useModule('ti.uia.sysbios.LoggingSetup');
   123         *  LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_SIMULATOR;
   124         *  @p
   125         *
   126         *  @c(UploadMode_SIMULATOR)
   127         *  Simulator. Events are uploaded when logged. The target is briefly
   128         *  halted when the event is uploaded. This is equivalent to using
   129         *  UploadMode_PROBEPOINT.
   130         *
   131         *  @c(UploadMode_PROBEPOINT)
   132         *  Probepoint. Events are uploaded over JTAG when logged. The target is briefly
   133         *  halted when the event is uploaded. This mode can also be used
   134         *  with a simulator.
   135         *
   136         *  @c(UploadMode_JTAGSTOPMODE)
   137         *  Events are uploaded over JTAG when the target halts. This mode can
   138         *  also be used with a simulator.
   139         *
   140         *  @c(UploadMode_JTAGRUNMODE)
   141         *  Events are Uploaded over JTAG while the target is running. This mode is
   142         *  supported for C6x devices only.
   143         *
   144         *  @c(UploadMode_NONJTAGTRANSPORT)
   145         *  Events are uploaded over the non-JTAG transport specified by the
   146         *  {@link ti.uia.runtime.ServiceMgr#transportType ServiceMgr.transportType}
   147         *  parameter while the target is running.
   148         *
   149         *  @c(UploadMode_NONJTAG_AND_JTAGSTOPMODE)
   150         *  Events are uploaded over a non-JTAG transport specified by the
   151         *  {@link ti.uia.runtime.ServiceMgr#transportType ServiceMgr.transportType}
   152         *  parameter while the target is running. When the target is halted,
   153         *  events are uploaded over JTAG.
   154         *
   155         *  @c(UploadMode_STREAMER)
   156         *  Events are logged to a {@link LoggerStreamer} logger.
   157         *  The application must manage the buffers sent to the host.
   158         *
   159         *  @c(UploadMode_STREAMER2)
   160         *  Events are logged to {@link LoggerStreamer2} loggers.
   161         *  The application must manage the buffers sent to the host.
   162         *
   163         *  @c(UploadMode_IDLE)
   164         *  Events are logged to the {@link LoggerIdle} buffer, and uploaded in
   165         *  the idle loop. The user must specify the
   166         *  {@link LoggerIdle#transportType} and provide the
   167         *  {@link LoggerIdle#transportFxn}.
   168         */
   169        enum UploadMode {
   170            UploadMode_SIMULATOR = 1,    /*! Simulator. */
   171            UploadMode_PROBEPOINT = 2,   /*! Probepoint. */
   172            UploadMode_JTAGSTOPMODE = 3, /*! JTAG Stop Mode. */
   173            UploadMode_JTAGRUNMODE = 4,  /*! JTAG Run Mode (C6x only). */
   174            UploadMode_NONJTAGTRANSPORT = 5, /*! Non-JTAG transport */
   175            UploadMode_NONJTAG_AND_JTAGSTOPMODE = 6, /*! Non-JTAG transport and
   176                                                      *  JTAG Stop Mode. */
   177            UploadMode_STREAMER = 7,      /*! LoggerStreamer */
   178            UploadMode_IDLE = 8,          /*! Upload in Idle loop */
   179            UploadMode_STREAMER2 = 9      /*! LoggerStreamer2 */
   180        }
   181    
   182        /*!
   183         *  ======== loadLogger ========
   184         *  Logger used for the Load module Log events
   185         */
   186        config xdc.runtime.ILogger.Handle loadLogger = null;
   187    
   188        /*!
   189         *  ======== loadLoggerSize ========
   190         *  Size (in MAUs) of logger used for the Load module Log events.
   191         */
   192        metaonly config SizeT loadLoggerSize = 512;
   193    
   194        /*!
   195         *  ======== loadLogging ========
   196         *  Enable the Load module event logging.
   197         *
   198         *  If this is false, the events will be disabled. Otherwise the events
   199         *  will be enabled.
   200         *  Use the {@link #loadLoggingRuntimeControl} parameter
   201         *  to determine whether the state can be modified during runtime.
   202         */
   203        metaonly config Bool loadLogging = true;
   204    
   205        /*!
   206         *  ======== loadLoggingRuntimeControl ========
   207         *  Specify whether load logging can be enabled / disabled at runtime.
   208         *
   209         *  This determines what diags settings are applied to the module's diags
   210         *  mask. If 'false', the diags bits will be configured as
   211         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   212         *  bits will be configured as 'RUNTIME_ON'.
   213         *
   214         *  Use the {@link #loadLogging} parameter
   215         *  to determine whether the event is ON or OFF. For example, the
   216         *  following two lines set the Load module's events to 'ALWAYS_ON'.
   217         *
   218         *  @p(code)
   219         *  LoggingSetup.loadLogging = true;
   220         *  LoggingSetup.loadLoggingRuntimeControl = false;
   221         *  @p
   222         */
   223        metaonly config Bool loadLoggingRuntimeControl = true;
   224    
   225        /*!
   226         *  ======== mainLogger ========
   227         *  Logger used for main and non-XDC modules Log events
   228         */
   229        config xdc.runtime.ILogger.Handle mainLogger = null;
   230    
   231        /*!
   232         *  ======== mainLoggerSize ========
   233         *  Size (in MAUs) of logger used for the main and non-XDC modules Log events
   234         */
   235        metaonly config SizeT mainLoggerSize = 1024;
   236    
   237        /*!
   238         *  ======== mainLogging ========
   239         *  Enable main and non-XDC modules event logging
   240         *
   241         *  If this is false, the events will be disabled. Otherwise the events
   242         *  will be enabled. Use the {@link #mainLoggingRuntimeControl} parameter
   243         *  to determine whether the state can be modified during runtime.
   244         *
   245         *  The table below shows the initial values of the
   246         *  xdc.runtime.Main Diags mask settings, based on mainLogging and
   247         *  mainLoggingRuntimeControl configuration. These settins only
   248         *  apply to Diags masks that have not been set in the application's
   249         *  configuration file.  For example, this configuration code would
   250         *  cause xdc.runtime.Main's USER1 Diags mask to be unaffected by
   251         *  the settings of mainLogging and mainLoggingRuntimeControl:
   252         *
   253         *  @p(code)
   254         *  Diags.setMaskMeta('xdc.runtime.Main', Diags.USER1, Diags.RUNTIME_ON);
   255         *  @p
   256         *
   257         *  @p(html)
   258         *  <h3> Diags Mask Settings for xdc.runtime.Main </h3>
   259         *  <table border="1" cellpadding="3">
   260         *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   261         *  </colgroup>
   262         *    <tr><th colspan="2" rowspan="2">  </th><th colspan="2">  mainLoggingRuntimeControl </th></tr>
   263         *    <tr><th>  true   </th><th> false </th></tr>
   264         *    <tr><th rowspan="2">  mainLogging  </th><th>  true  </th><td> RUNTIME_ON</td>
   265         *    <td> ALWAYS_ON </td></tr>
   266         *    <tr><th> false </th><td>  RUNTIME_OFF  </td> <td> ALWAYS_OFF </td></tr>
   267         * </table>
   268         */
   269        metaonly config Bool mainLogging = true;
   270    
   271        /*!
   272         *  ======== mainLoggingRuntimeControl ========
   273         *  Specify whether main logging can be enabled / disabled at runtime.
   274         *
   275         *  This determines what diags settings are applied to the module's diags
   276         *  mask. If 'false' and {@link #mainLogging} is true, the diags bits will be configured as
   277         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   278         *  bits will be configured as 'RUNTIME_ON'.
   279         *
   280         *  Use the {@link #mainLogging} parameter
   281         *  to determine whether the event is ON or OFF. For example, the
   282         *  following two lines set the xdc.runtime.Main events to
   283         *  initially be 'RUNTIME_ON'.
   284         *
   285         *  @p(code)
   286         *  LoggingSetup.mainLogging = true;
   287         *  LoggingSetup.mainLoggingRuntimeControl = true;
   288         *  @p
   289         */
   290        metaonly config Bool mainLoggingRuntimeControl = true;
   291    
   292        /*!
   293         *  ======== sysbiosLogger ========
   294         *  Logger used for SYSBIOS modules Log events
   295         */
   296        config xdc.runtime.ILogger.Handle sysbiosLogger = null;
   297    
   298        /*!
   299         *  ======== sysbiosLoggerSize ========
   300         *  Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events
   301         */
   302        metaonly config SizeT sysbiosLoggerSize = 1024;
   303    
   304        /*!
   305         *  ======== sysbiosHwiLogging ========
   306         *  Enable SYSBIOS Hwi and Clock modules' event logging
   307         *
   308         *  If this is false, the events will be disabled. Otherwise the events
   309         *  will be enabled.
   310         *  Use the {@link #sysbiosHwiLoggingRuntimeControl} parameter
   311         *  to determine whether the state can be modified during runtime.
   312         */
   313        metaonly config Bool sysbiosHwiLogging = false;
   314    
   315        /*!
   316         *  ======== sysbiosHwiLoggingRuntimeControl ========
   317         *  Specify whether Hwi and Clock logging can be enabled / disabled at runtime
   318         *
   319         *  This determines what diags settings are applied to the module's diags
   320         *  mask. If 'false', the diags bits will be configured as
   321         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   322         *  bits will be configured as 'RUNTIME_ON'.
   323         *
   324         *  Use the {@link #sysbiosHwiLogging} parameter
   325         *  to determine whether the event is ON or OFF. For example, the
   326         *  following two lines set the Hwi module's events to 'ALWAYS_ON'.
   327         *
   328         *  @p(code)
   329         *  LoggingSetup.sysbiosHwiLogging = true;
   330         *  LoggingSetup.sysbiosHwiLoggingRuntimeControl = false;
   331         *  @p
   332         */
   333        metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
   334    
   335        /*!
   336         *  ======== sysbiosSwiLogging ========
   337         *  Enable SYSBIOS Swi module's event logging
   338         *
   339         *  If this is false, the events will be disabled. Otherwise the events
   340         *  will be enabled.
   341         *  Use the {@link #sysbiosSwiLoggingRuntimeControl} parameter
   342         *  to determine whether the state can be modified during runtime.
   343         */
   344        metaonly config Bool sysbiosSwiLogging = false;
   345    
   346        /*!
   347         *  ======== sysbiosSwiLoggingRuntimeControl ========
   348         *  Specify whether Swi logging can be enabled / disabled at runtime.
   349         *
   350         *  This determines what diags settings are applied to the module's diags
   351         *  mask. If 'false', the diags bits will be configured as
   352         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   353         *  bits will be configured as 'RUNTIME_ON'.
   354         *
   355         *  Use the {@link #sysbiosSwiLogging} parameter
   356         *  to determine whether the event is ON or OFF. For example, the
   357         *  following two lines initialize the Swi module's events to
   358         *  'RUNTIME_OFF'.
   359         *
   360         *  @p(code)
   361         *  LoggingSetup.sysbiosSwiLogging = false;
   362         *  LoggingSetup.sysbiosSwiLoggingRuntimeControl = true;
   363         *  @p
   364         */
   365        metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
   366    
   367        /*!
   368         *  ======== sysbiosTaskLogging ========
   369         *  Enable SYSBIOS Task module's event logging
   370         *
   371         *  If this is false, the events will be disabled. Otherwise the events
   372         *  will be enabled.
   373         *  Use the {@link #sysbiosTaskLoggingRuntimeControl} parameter
   374         *  to determine whether the state can be modified during runtime.
   375         */
   376        metaonly config Bool sysbiosTaskLogging = true;
   377    
   378        /*!
   379         *  ======== sysbiosTaskLoggingRuntimeControl ========
   380         *  Specify whether Task logging can be enabled / disabled at runtime.
   381         *
   382         *  This determines what diags settings are applied to the module's diags
   383         *  mask. If 'false', the diags bits will be configured as
   384         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   385         *  bits will be configured as 'RUNTIME_ON'.
   386         *
   387         *  Use the {@link #sysbiosTaskLogging} parameter
   388         *  to determine whether the event is ON or OFF. For example, the
   389         *  following two lines initialize the Task module's events to
   390         *  'ALWAYS_ON'.
   391         *
   392         *  @p(code)
   393         *  LoggingSetup.sysbiosTaskLogging = true;
   394         *  LoggingSetup.sysbiosTaskLoggingRuntimeControl = false;
   395         *  @p
   396         */
   397        metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
   398    
   399        /*!
   400         *  ======== overflowLoggerSize ========
   401         *  Size of logger used for overflow events when
   402         *  uploadMode is either JTAGRUNMODE or NONJTAG_AND_JTAGSTOPMODE
   403         */
   404        metaonly config SizeT overflowLoggerSize = 1024;
   405    
   406        /*!
   407         *  ========= eventUploadMode ========
   408         *  Event upload mode
   409         *
   410         *  See {@link LoggingSetup#UploadMode} for a description of the the
   411         *  different event upload modes.
   412         *
   413         *  @a(Example)
   414         *  This script configures the system to stream events from the
   415         *  target to the host over JTAG while the target is running.
   416         *  (Note that this mode is only supported for CPUs that
   417         *  support real-time JTAG accesses such as those in the C6X family,
   418         *  e.g. C64X+ and C66 CPUs)
   419         *
   420         *  @p(code)
   421         *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
   422         *  LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_JTAGRUNMODE;
   423         *
   424         */
   425        metaonly config UploadMode eventUploadMode = UploadMode_JTAGSTOPMODE;
   426    
   427        /*!
   428         * ======== disableMulticoreEventCorrelation ========
   429         * Set to true for single core applications.
   430         *
   431         * When set to true, the LoggingSetup module will not automatically
   432         * include the LogSync module.  The LogSync module is
   433         * required in order to enable events from multiple CPU cores
   434         * to be correlated with each other.
   435         * @see ti.uia.runtime.LogSync
   436         *
   437         */
   438        metaonly config Bool disableMulticoreEventCorrelation = false;
   439    
   440        /*! @_nodoc
   441         * ======== createLogger =========
   442         * Internal helper function that creates the type of logger
   443         * appropriate for the LoggingSetup.uploadMode that has been configured.
   444         *
   445         * @param(loggerSize): the size of the logger in MAUs
   446         * @param(loggerInstanceName): the name to assign to the logger instance
   447         * @param (loggerPriority): the IUIATransfer.Priority to assign to the logger instance
   448         * @a(return) returns the logger instance that was created
   449         */
   450         metaonly function createLogger(loggerSize,loggerInstanceName,loggerPriority);
   451    }