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