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 with
    61     *    a buffer size of 32 KBytes is enabled by default to support this.
    62     *   - Event logging is enabled for the SYS/BIOS Load and Task modules in order to
    63     *   allow System Analyzer to display CPU Load, Task Load, and Task Execution
    64     *   information.  Logging of SWI and HWI events is disabled by default.
    65     *   In order to optimize event capture and minimize event loss, two loggers
    66     *   are created: one to store events from the SYS/BIOS Load module
    67     *   and the other to store events from other SYS/BIOS modules.
    68     *   - Multicore event correlation is enabled by default.  This enables the
    69     *    LogSync module and creation of a dedicated logger for sync point events
    70     *    with a circular buffer size of 8 KBytes.
    71     *   - The Event Upload Mode is configured for NONJTAG_AND_JTAGSTOPMODE.  This
    72     *    allows events to be uploaded in real-time via the Non-JTAG transport
    73     *    specified by the ti.uia.runtime.ServiceManager module, and also be uploaded
    74     *    when the target halts via JTAG.  If the ServiceManager module is not
    75     *    used in the application, the transport falls back to JTAGSTOPMODE.
    76     *   - An Overflow logger will be automatically created to capture events that
    77     *    occurred while the transport was waiting to upload older events to the host.
    78     *    The logger's circular buffer size is set to 2K Bytes.
    79     *  @p
    80     *  @p(code)
    81     *  // the Log module provides logging APIs for use by the user's software
    82     *  var Log = xdc.useModule('xdc.runtime.Log');
    83     *  // the LoggingSetup module's default settings configure much of the UIA infrastructure.
    84     *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
    85     *  @p
    86     *  @p(html)
    87     *  <hr />
    88     *  @p
    89     * @a(Example)
    90     * Example 2: A number of 'template' applications are available that
    91     * provide predefined XDC configuration scripts and C code for use in new
    92     * projects.  These templates provide good examples of how to configure all
    93     * of the various modules that are involved in setting up the UIA infrastructure,
    94     * including the LoggingSetup module.  The templates can be downloaded from
    95     * the System Analyzer Wiki site at
    96     *  @p(html)
    97     *  <a href="http://processors.wiki.ti.com/index.php/System_Analyzer">
    98     * http://processors.wiki.ti.com/index.php/System_Analyzer</a>
    99     * @p
   100     * They can also be generated directly by CCS, using the CCS New Project
   101     * Wizard.  The following steps show how to use CCSv5.0.x to generate a new project
   102     * that configure the NDK to provide an Ethernet transport for uploading events
   103     * from the target to the host, please perform the following steps in CCS. :
   104     * @p(blist)
   105     *   - File / New / CCS Project : opens the 'New CCS Project' dialog
   106     *   - <enter a name for the project>
   107     *   - <select the type of project>
   108     *   - <accept defaults for Additional Project Settings>
   109     *   - <configure the project settings for compiler options, etc.>
   110     *   - For Project Templates, expand the UIA and System Analyzer Examples section
   111     *   - select evm6472: Stairstep for a single core with UIA to see how
   112     *   to configure the NDK to use Ethernet as a transport for UIA events and
   113     *   commands.
   114     *  - select evm6472: MessageQ (single image for all cores) with UIA
   115     *   to see how to create a multicore application that uses the same application
   116     *   software for all cores, and uses IPC to move event data from CPU cores 1-5
   117     *   to CPU core 0, with CPU core 0 using the NDK for Ethernet communications
   118     *   with the host.
   119     *  @p
   120     *
   121     *  @p(html)
   122     *  <hr />
   123     */
   124    metaonly module LoggingSetup
   125    {
   126    
   127        /*!
   128         *  ======== UploadMode ========
   129         */
   130        enum UploadMode {
   131            UploadMode_SIMULATOR = 1, /* note that simulators use probe points */
   132            UploadMode_PROBEPOINT = 2,
   133            UploadMode_JTAGSTOPMODE = 3,
   134            UploadMode_JTAGRUNMODE = 4,
   135            UploadMode_NONJTAGTRANSPORT = 5,
   136            UploadMode_NONJTAG_AND_JTAGSTOPMODE = 6,
   137            UploadMode_STREAMER = 7,
   138            UploadMode_IDLE = 8,
   139            UploadMode_STREAMER2 = 9
   140        }
   141    
   142        /*!
   143         *  ======== loadLogger ========
   144         *  Logger used for the Load module Log events
   145         */
   146        config xdc.runtime.ILogger.Handle loadLogger = null;
   147    
   148        /*!
   149         *  ======== loadLoggerSize ========
   150         *  Size (in MAUs) of logger used for the Load module Log events.
   151         */
   152        metaonly config SizeT loadLoggerSize = 512;
   153    
   154        /*!
   155         *  ======== loadLogging ========
   156         *  Enable the Load module event logging.
   157         *
   158         *  If this is false, the events will be disabled. Otherwise the events
   159         *  will be enabled.
   160         *  Use the {@link #loadLoggingRuntimeControl} parameter
   161         *  to determine whether the state can be modified during runtime.
   162         */
   163        metaonly config Bool loadLogging = true;
   164    
   165        /*!
   166         *  ======== loadLoggingRuntimeControl ========
   167         *  Specify whether load logging can be enabled / disabled at runtime.
   168         *
   169         *  This determines what diags settings are applied to the module's diags
   170         *  mask. If 'false', the diags bits will be configured as
   171         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   172         *  bits will be configured as 'RUNTIME_ON'.
   173         *
   174         *  Use the {@link #loadLogging} parameter
   175         *  to determine whether the event is ON or OFF. For example, the
   176         *  following two lines set the Load modules events to
   177         *  initially be 'ALWAYS_ON'.
   178         *
   179         *  @p(code)
   180         *  LoggingSetup.loadLogging = true;
   181         *  LoggingSetup.loadLoggingRuntimeControl = false;
   182         *  @p
   183         */
   184        metaonly config Bool loadLoggingRuntimeControl = true;
   185    
   186        /*!
   187         *  ======== mainLogger ========
   188         *  Logger used for main and non-XDC modules Log events
   189         */
   190        config xdc.runtime.ILogger.Handle mainLogger = null;
   191    
   192        /*!
   193         *  ======== mainLoggerSize ========
   194         *  Size (in MAUs) of logger used for the main and non-XDC modules Log events
   195         */
   196        metaonly config SizeT mainLoggerSize = 1024;
   197    
   198        /*!
   199         *  ======== mainLogging ========
   200         *  Enable main and non-XDC modules event logging
   201         *
   202         *  If this is false, the events will be disabled. Otherwise the events
   203         *  will be enabled.
   204         *  Use the {@link #mainLoggingRuntimeControl} parameter
   205         *  to determine whether the state can be modified during runtime.
   206         */
   207        metaonly config Bool mainLogging = true;
   208    
   209        /*!
   210         *  ======== mainLoggingRuntimeControl ========
   211         *  Specify whether main logging can be enabled / disabled at runtime.
   212         *
   213         *  This determines what diags settings are applied to the module's diags
   214         *  mask. If 'false', the diags bits will be configured as
   215         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   216         *  bits will be configured as 'RUNTIME_ON'.
   217         *
   218         *  Use the {@link #mainLogging} parameter
   219         *  to determine whether the event is ON or OFF. For example, the
   220         *  following two lines set the Load modules events to
   221         *  initially be 'ALWAYS_ON'.
   222         *
   223         *  @p(code)
   224         *  LoggingSetup.mainLogging = true;
   225         *  LoggingSetup.mainLoggingRuntimeControl = false;
   226         *  @p
   227         */
   228        metaonly config Bool mainLoggingRuntimeControl = true;
   229    
   230        /*!
   231         *  ======== sysbiosLogger ========
   232         *  Logger used for SYSBIOS modules Log events
   233         */
   234        config xdc.runtime.ILogger.Handle sysbiosLogger = null;
   235    
   236        /*!
   237         *  ======== sysbiosLoggerSize ========
   238         *  Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events
   239         */
   240        metaonly config SizeT sysbiosLoggerSize = 1024;
   241    
   242        /*!
   243         *  ======== sysbiosHwiLogging ========
   244         *  Enable SYSBIOS Hwi and Clock modules' event logging
   245         *
   246         *  If this is false, the events will be disabled. Otherwise the events
   247         *  will be enabled.
   248         *  Use the {@link #sysbiosHwiLoggingRuntimeControl} parameter
   249         *  to determine whether the state can be modified during runtime.
   250         */
   251        metaonly config Bool sysbiosHwiLogging = false;
   252    
   253        /*!
   254         *  ======== sysbiosHwiLoggingRuntimeControl ========
   255         *  Specify whether Hwi and Clock logging can be enabled / disabled at runtime
   256         *
   257         *  This determines what diags settings are applied to the module's diags
   258         *  mask. If 'false', the diags bits will be configured as
   259         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   260         *  bits will be configured as 'RUNTIME_ON'.
   261         *
   262         *  Use the {@link #sysbiosHwiLogging} parameter
   263         *  to determine whether the event is ON or OFF. For example, the
   264         *  following two lines set the Load modules events to
   265         *  initially be 'ALWAYS_ON'.
   266         *
   267         *  @p(code)
   268         *  LoggingSetup.sysbiosHwiLogging = true;
   269         *  LoggingSetup.sysbiosHwiLoggingRuntimeControl = false;
   270         *  @p
   271         */
   272        metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
   273    
   274        /*!
   275         *  ======== sysbiosSwiLogging ========
   276         *  Enable SYSBIOS Swi module's event logging
   277         *
   278         *  If this is false, the events will be disabled. Otherwise the events
   279         *  will be enabled.
   280         *  Use the {@link #sysbiosSwiLoggingRuntimeControl} parameter
   281         *  to determine whether the state can be modified during runtime.
   282         */
   283        metaonly config Bool sysbiosSwiLogging = false;
   284    
   285        /*!
   286         *  ======== sysbiosSwiLoggingRuntimeControl ========
   287         *  Specify whether Swi logging can be enabled / disabled at runtime.
   288         *
   289         *  This determines what diags settings are applied to the module's diags
   290         *  mask. If 'false', the diags bits will be configured as
   291         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   292         *  bits will be configured as 'RUNTIME_ON'.
   293         *
   294         *  Use the {@link #sysbiosSwiLogging} parameter
   295         *  to determine whether the event is ON or OFF. For example, the
   296         *  following two lines set the Load modules events to
   297         *  initially be 'ALWAYS_ON'.
   298         *
   299         *  @p(code)
   300         *  LoggingSetup.sysbiosSwiLogging = true;
   301         *  LoggingSetup.sysbiosSwiLoggingRuntimeControl = false;
   302         *  @p
   303         */
   304        metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
   305    
   306        /*!
   307         *  ======== sysbiosTaskLogging ========
   308         *  Enable SYSBIOS Task module's event logging
   309         *
   310         *  If this is false, the events will be disabled. Otherwise the events
   311         *  will be enabled.
   312         *  Use the {@link #sysbiosTaskLoggingRuntimeControl} parameter
   313         *  to determine whether the state can be modified during runtime.
   314         */
   315        metaonly config Bool sysbiosTaskLogging = true;
   316    
   317        /*!
   318         *  ======== sysbiosTaskLoggingRuntimeControl ========
   319         *  Specify whether Task logging can be enabled / disabled at runtime.
   320         *
   321         *  This determines what diags settings are applied to the module's diags
   322         *  mask. If 'false', the diags bits will be configured as
   323         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   324         *  bits will be configured as 'RUNTIME_ON'.
   325         *
   326         *  Use the {@link #sysbiosTaskLogging} parameter
   327         *  to determine whether the event is ON or OFF. For example, the
   328         *  following two lines set the Load modules events to
   329         *  initially be 'ALWAYS_ON'.
   330         *
   331         *  @p(code)
   332         *  LoggingSetup.sysbiosTaskLogging = true;
   333         *  LoggingSetup.sysbiosTaskLoggingRuntimeControl = false;
   334         *  @p
   335         */
   336        metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
   337    
   338        /*!
   339         *  ======== overflowLoggerSize ========
   340         *  Size of logger used for overflow events when
   341         *  uploadMode is either JTAGRUNMODE or NONJTAG_AND_JTAGSTOPMODE
   342         */
   343        metaonly config SizeT overflowLoggerSize = 1024;
   344    
   345        /*!
   346         *  ========= eventUploadMode ========
   347         *  Event upload mode
   348         *  @p
   349         *  Upload_SIMULATOR: events are uploaded from the simulator
   350         *  at the time the event is logged.
   351         *  @p(blist)
   352         *   - Upload_PROBEPOINT: events are uploaded at the time the event
   353         *  is logged. The target is briefly halted while the event is uploaded.
   354         *   - Upload_JTAGSTOPMODE: events are uploaded over JTAG when the target halts
   355         *   - Upload_JTAGRUNMODE: events are uploaded via JTAG while the target is running.
   356         *   - Upload_NONJTAGTRANSPORT: events are uploaded over a non-JTAG transport such
   357         *  as Ethernet.  @see RTA for info on how to use the NDK as a transport.
   358         *   - Upload_NONJTAG_AND_JTAGSTOPMODE: events are uploaded over a non-JTAG transport.
   359         *  When the target halts (e.g. due to a breakpoint), any events that have not
   360         *  been uploaded yet are uploaded via JTAG.
   361         *  @p
   362         *
   363         *  @a(Example)
   364         *  The following is an example of the configuration script used
   365         *  to configure the system to use LoggerCircBuf loggers in order to
   366         *  stream events from the target to the host while the target is running
   367         *  over JTAG.  (Note that this mode is only supported for CPUs that
   368         *  support real-time JTAG accesses such as those in the C6X family,
   369         *  e.g. C64X+ and C66 CPUs)
   370         *
   371         *  @p(code)
   372         *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
   373         *  LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_JTAGRUNMODE;
   374         *
   375         */
   376        metaonly config UploadMode eventUploadMode = UploadMode_JTAGSTOPMODE;
   377    
   378        /*!
   379         * ======== disableMulticoreEventCorrelation ========
   380         * Set to true for single core applications.
   381         *
   382         * When true the LoggingSetup module will not automatically
   383         * include the the LogSync module.  The LogSync module is
   384         * required in order to enable events from multiple CPU cores
   385         * to be correlated with each other.
   386         * @see ti.uia.runtime.LogSync
   387         *
   388         */
   389        metaonly config Bool disableMulticoreEventCorrelation = false;
   390    
   391        /*! @_nodoc
   392         * ======== createLogger =========
   393         * Internal helper function that creates the type of logger
   394         * appropriate for the LoggingSetup.uploadMode that has been configured.
   395         *
   396         * @param(loggerSize): the size of the logger in MAUs
   397         * @param(loggerInstanceName): the name to assign to the logger instance
   398         * @param (loggerPriority): the IUIATransfer.Priority to assign to the logger instance
   399         * @a(return) returns the logger instance that was created
   400         */
   401         metaonly function createLogger(loggerSize,loggerInstanceName,loggerPriority);
   402    }