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        /*!
   127         *  ======== UploadMode ========
   128         */
   129        enum UploadMode {
   130            UploadMode_SIMULATOR = 1, /* note that simulators use probe points */
   131            UploadMode_PROBEPOINT = 2,
   132            UploadMode_JTAGSTOPMODE = 3,
   133            UploadMode_JTAGRUNMODE = 4,
   134            UploadMode_NONJTAGTRANSPORT = 5,
   135            UploadMode_NONJTAG_AND_JTAGSTOPMODE = 6,
   136            UploadMode_STREAMER = 7,
   137            UploadMode_IDLE = 8
   138        }
   139            
   140        /*!
   141         *  ======== loadLogger ========
   142         *  Logger used for the Load module Log events
   143         */
   144        config xdc.runtime.ILogger.Handle loadLogger = null;
   145        
   146        /*!
   147         *  ======== loadLoggerSize ========
   148         *  Size (in MAUs) of logger used for the Load module Log events.
   149         */
   150        metaonly config SizeT loadLoggerSize = 512;
   151        
   152        /*!
   153         *  ======== loadLogging ========
   154         *  Enable the Load module event logging.
   155         *
   156         *  If this is false, the events will be disabled. Otherwise the events 
   157         *  will be enabled.
   158         *  Use the {@link #loadLoggingRuntimeControl} parameter 
   159         *  to determine whether the state can be modified during runtime.
   160         */
   161        metaonly config Bool loadLogging = true;
   162        
   163        /*!
   164         *  ======== loadLoggingRuntimeControl ========
   165         *  Specify whether load logging can be enabled / disabled at runtime.
   166         *
   167         *  This determines what diags settings are applied to the module's diags
   168         *  mask. If 'false', the diags bits will be configured as 
   169         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the 
   170         *  bits will be configured as 'RUNTIME_ON'.
   171         *
   172         *  Use the {@link #loadLogging} parameter 
   173         *  to determine whether the event is ON or OFF. For example, the
   174         *  following two lines set the Load modules events to 
   175         *  initially be 'ALWAYS_ON'.
   176         *
   177         *  @p(code)
   178         *  LoggingSetup.loadLogging = true;   
   179         *  LoggingSetup.loadLoggingRuntimeControl = false;
   180         *  @p
   181         */
   182        metaonly config Bool loadLoggingRuntimeControl = true;
   183        
   184        /*!
   185         *  ======== mainLogger ========
   186         *  Logger used for main and non-XDC modules Log events
   187         */
   188        config xdc.runtime.ILogger.Handle mainLogger = null;
   189        
   190        /*!
   191         *  ======== mainLoggerSize ========
   192         *  Size (in MAUs) of logger used for the main and non-XDC modules Log events
   193         */
   194        metaonly config SizeT mainLoggerSize = 1024;
   195        
   196        /*!
   197         *  ======== mainLogging ========
   198         *  Enable main and non-XDC modules event logging
   199         *
   200         *  If this is false, the events will be disabled. Otherwise the events 
   201         *  will be enabled.
   202         *  Use the {@link #mainLoggingRuntimeControl} parameter 
   203         *  to determine whether the state can be modified during runtime.
   204         */
   205        metaonly config Bool mainLogging = true;
   206        
   207        /*!
   208         *  ======== mainLoggingRuntimeControl ========
   209         *  Specify whether main logging can be enabled / disabled at runtime.
   210         *
   211         *  This determines what diags settings are applied to the module's diags
   212         *  mask. If 'false', the diags bits will be configured as 
   213         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the 
   214         *  bits will be configured as 'RUNTIME_ON'.
   215         *
   216         *  Use the {@link #mainLogging} parameter 
   217         *  to determine whether the event is ON or OFF. For example, the
   218         *  following two lines set the Load modules events to 
   219         *  initially be 'ALWAYS_ON'.
   220         *
   221         *  @p(code)
   222         *  LoggingSetup.mainLogging = true;   
   223         *  LoggingSetup.mainLoggingRuntimeControl = false;
   224         *  @p
   225         */
   226        metaonly config Bool mainLoggingRuntimeControl = true;
   227        
   228        /*!
   229         *  ======== sysbiosLogger ========
   230         *  Logger used for SYSBIOS modules Log events
   231         */
   232        config xdc.runtime.ILogger.Handle sysbiosLogger = null;
   233        
   234        /*!
   235         *  ======== sysbiosLoggerSize ========
   236         *  Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events
   237         */
   238        metaonly config SizeT sysbiosLoggerSize = 1024;
   239        
   240        /*!
   241         *  ======== sysbiosHwiLogging ========
   242         *  Enable SYSBIOS Hwi and Clock modules' event logging
   243         *
   244         *  If this is false, the events will be disabled. Otherwise the events 
   245         *  will be enabled.
   246         *  Use the {@link #sysbiosHwiLoggingRuntimeControl} parameter 
   247         *  to determine whether the state can be modified during runtime.
   248         */
   249        metaonly config Bool sysbiosHwiLogging = false;
   250        
   251        /*!
   252         *  ======== sysbiosHwiLoggingRuntimeControl ========
   253         *  Specify whether Hwi and Clock logging can be enabled / disabled at runtime
   254         *
   255         *  This determines what diags settings are applied to the module's diags
   256         *  mask. If 'false', the diags bits will be configured as 
   257         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the 
   258         *  bits will be configured as 'RUNTIME_ON'.
   259         *
   260         *  Use the {@link #sysbiosHwiLogging} parameter 
   261         *  to determine whether the event is ON or OFF. For example, the
   262         *  following two lines set the Load modules events to 
   263         *  initially be 'ALWAYS_ON'.
   264         *
   265         *  @p(code)
   266         *  LoggingSetup.sysbiosHwiLogging = true;   
   267         *  LoggingSetup.sysbiosHwiLoggingRuntimeControl = false;
   268         *  @p
   269         */
   270        metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
   271        
   272        /*!
   273         *  ======== sysbiosSwiLogging ========
   274         *  Enable SYSBIOS Swi module's event logging
   275         *
   276         *  If this is false, the events will be disabled. Otherwise the events 
   277         *  will be enabled.
   278         *  Use the {@link #sysbiosSwiLoggingRuntimeControl} parameter 
   279         *  to determine whether the state can be modified during runtime.
   280         */
   281        metaonly config Bool sysbiosSwiLogging = false;
   282        
   283        /*!
   284         *  ======== sysbiosSwiLoggingRuntimeControl ========
   285         *  Specify whether Swi logging can be enabled / disabled at runtime.
   286         *
   287         *  This determines what diags settings are applied to the module's diags
   288         *  mask. If 'false', the diags bits will be configured as 
   289         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the 
   290         *  bits will be configured as 'RUNTIME_ON'.
   291         *
   292         *  Use the {@link #sysbiosSwiLogging} parameter 
   293         *  to determine whether the event is ON or OFF. For example, the
   294         *  following two lines set the Load modules events to 
   295         *  initially be 'ALWAYS_ON'.
   296         *
   297         *  @p(code)
   298         *  LoggingSetup.sysbiosSwiLogging = true;   
   299         *  LoggingSetup.sysbiosSwiLoggingRuntimeControl = false;
   300         *  @p
   301         */
   302        metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
   303        
   304        /*!
   305         *  ======== sysbiosTaskLogging ========
   306         *  Enable SYSBIOS Task module's event logging
   307         *
   308         *  If this is false, the events will be disabled. Otherwise the events 
   309         *  will be enabled.
   310         *  Use the {@link #sysbiosTaskLoggingRuntimeControl} parameter 
   311         *  to determine whether the state can be modified during runtime.
   312         */
   313        metaonly config Bool sysbiosTaskLogging = true;
   314        
   315        /*!
   316         *  ======== sysbiosTaskLoggingRuntimeControl ========
   317         *  Specify whether Task 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 #sysbiosTaskLogging} parameter 
   325         *  to determine whether the event is ON or OFF. For example, the
   326         *  following two lines set the Load modules events to 
   327         *  initially be 'ALWAYS_ON'.
   328         *
   329         *  @p(code)
   330         *  LoggingSetup.sysbiosTaskLogging = true;   
   331         *  LoggingSetup.sysbiosTaskLoggingRuntimeControl = false;
   332         *  @p
   333         */
   334        metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
   335    
   336        /*!
   337         *  ======== overflowLoggerSize ========
   338         *  Size of logger used for overflow events when
   339         *  uploadMode is either JTAGRUNMODE or NONJTAG_AND_JTAGSTOPMODE
   340         */
   341        metaonly config SizeT overflowLoggerSize = 1024;
   342        
   343        /*!
   344         *  ========= eventUploadMode ========
   345         *  Event upload mode
   346         *  @p
   347         *  Upload_SIMULATOR: events are uploaded from the simulator 
   348         *  at the time the event is logged.  
   349         *  @p(blist)
   350         *   - Upload_PROBEPOINT: events are uploaded at the time the event 
   351         *  is logged. The target is briefly halted while the event is uploaded.
   352         *   - Upload_JTAGSTOPMODE: events are uploaded over JTAG when the target halts
   353         *   - Upload_JTAGRUNMODE: events are uploaded via JTAG while the target is running.
   354         *   - Upload_NONJTAGTRANSPORT: events are uploaded over a non-JTAG transport such
   355         *  as Ethernet.  @see RTA for info on how to use the NDK as a transport.
   356         *   - Upload_NONJTAG_AND_JTAGSTOPMODE: events are uploaded over a non-JTAG transport.
   357         *  When the target halts (e.g. due to a breakpoint), any events that have not
   358         *  been uploaded yet are uploaded via JTAG.
   359         *  @p 
   360         *  
   361         *  @a(Example)
   362         *  The following is an example of the configuration script used
   363         *  to configure the system to use LoggerCircBuf loggers in order to
   364         *  stream events from the target to the host while the target is running
   365         *  over JTAG.  (Note that this mode is only supported for CPUs that 
   366         *  support real-time JTAG accesses such as those in the C6X family, 
   367         *  e.g. C64X+ and C66 CPUs)
   368         *   
   369         *  @p(code)
   370         *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
   371         *  LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_JTAGRUNMODE;
   372         *   
   373         */
   374        metaonly config UploadMode eventUploadMode = UploadMode_JTAGSTOPMODE; 
   375    
   376        /*!
   377         * ======== disableMulticoreEventCorrelation ========
   378         * Set to true for single core applications.
   379         * 
   380         * When true the LoggingSetup module will not automatically
   381         * include the the LogSync module.  The LogSync module is
   382         * required in order to enable events from multiple CPU cores
   383         * to be correlated with each other.
   384         * @see ti.uia.runtime.LogSync  
   385         * 
   386         */
   387        metaonly config Bool disableMulticoreEventCorrelation = false;
   388       
   389        /*! @_nodoc
   390         * ======== createLogger =========
   391         * Internal helper function that creates the type of logger
   392         * appropriate for the LoggingSetup.uploadMode that has been configured.
   393         * 
   394         * @param(loggerSize): the size of the logger in MAUs
   395         * @param(loggerInstanceName): the name to assign to the logger instance
   396         * @param (loggerPriority): the IUIATransfer.Priority to assign to the logger instance
   397         * @a(return) returns the logger instance that was created
   398         */
   399         metaonly function createLogger(loggerSize,loggerInstanceName,loggerPriority);
   400    }
   401    
   402    /*
   403     *! Revision History
   404     *! ================
   405     *! 23-Jun-2010 toddm Started revision history
   406     */
   407