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     * ======== UIAMetaData.xdc
    35     */
    36    
    37    import xdc.runtime.Types;
    38    
    39    /*!
    40     * Unified Arch. Hardware Interrupt Context Instrumentation
    41     *
    42     * The UIAHWICtx module defines context change events
    43     * and methods that allow tooling to identify hardware interrutp context
    44     * switches and to enable HWI-aware filtering, trace and
    45     * analysis.
    46     */
    47    
    48    module UIAMetaData {
    49    
    50        /*!
    51         *  ======== UploadMode ========
    52         */
    53        enum UploadMode {
    54            UploadMode_SIMULATOR = 1, /* note that simulators use probe points */
    55            UploadMode_PROBEPOINT = 2,
    56            UploadMode_JTAGSTOPMODE = 3,
    57            UploadMode_JTAGRUNMODE = 4,
    58            UploadMode_NONJTAGTRANSPORT = 5,
    59            UploadMode_CUSTOM = 6
    60        }
    61    
    62        /*!
    63         *  ======== cpuFreq ========
    64         *  CPU frequency in Hz
    65         *
    66         *  Use this configuration parameter to set the CPU frequency, for
    67         *  non-BIOS programs.
    68         *
    69         *  @a(Example)
    70         *  If CPU frequency is 720MHz, the following configuration script
    71         *  configures the proper clock frequency:
    72         *  @p(code)
    73         *     var UIAMetaData = xdc.useModule('ti.uia.runtime.UIAMetaData');
    74         *     UIAMetaData.cpuFreq.lo = 720000000;
    75         *  @p
    76         */
    77        metaonly config Types.FreqHz cpuFreq;
    78    
    79        /*!
    80         *  ======== timestampFreq ========
    81         *  Timestamp frequency in Hz
    82         *
    83         *  Use this configuration parameter to set the timestamp frequency, for
    84         *  non-BIOS programs.
    85         *
    86         *  @a(Example)
    87         *  If timestamp frequency is 720MHz, the following configuration script
    88         *  configures the proper timestamp frequency:
    89         *  @p(code)
    90         *     var UIAMetaData = xdc.useModule('ti.uia.runtime.UIAMetaData');
    91         *     UIAMetaData.timestampFreq.lo = 720000000;
    92         *  @p
    93         */
    94        metaonly config Types.FreqHz timestampFreq;
    95    
    96        metaonly function generateXML();
    97    
    98        /*!
    99         *  ======== genXmlEntry ========
   100         *  write an entry into an xml file
   101         *
   102         *  e.g. <myTag>myValue</myTag>\n
   103         */
   104        metaonly function genXmlEntry(indent, tag, value);
   105    
   106        /*!
   107         *  ======== genXmlEntryOpen ========
   108         *  write an entry into an xml file with a key field
   109         *
   110         *  e.g. <myTag myKeyName=myKeyValue>
   111         */
   112        metaonly function  genXmlEntryOpen(indent,  tag);
   113    
   114        /*!
   115         *  ======== genXmlEntryOpenWithKey ========
   116         *  write an entry into an xml file with a key field
   117         *
   118         *  e.g. <myTag myKeyName=myKeyValue>
   119         */
   120        metaonly function  genXmlEntryOpenWithKey(indent,tag,keyName,keyValue,value);
   121    
   122        /*!
   123         *  ======== genXmlEntryWithKey ========
   124         *  write an entry into an xml file with a key field
   125         *
   126         *  e.g. <myTag myKeyName=myKeyValue>myValue</myTag>\n
   127         */
   128         metaonly function  genXmlEntryWithKey(indent,tag,keyName,keyValue,value);
   129    
   130         /*!
   131          *  ======== genXmlComment ========
   132          *  add an XML style comment to the active xml file
   133          */
   134         metaonly function  genXmlComment(indent,  comment);
   135        /*!
   136         *  ======== genXmlEntryClose ========
   137         *  write an entry into an xml file with a key field
   138         *
   139         *  e.g. </myTag>\n
   140         */
   141        metaonly function  genXmlEntryClose(indent,  tag);
   142    
   143        /*!
   144         *  ======== setTransportFields ========
   145         *  Function to populate the transport fields
   146         *
   147         *  This function is used to populate the UIA XML file with
   148         *  transport information. It  writes <transport2> entries.
   149         *  The <transport2> is supported by System Analyzer in 5.2
   150         *  and later.
   151         *
   152         *  The parameters map directly to individual fields in the
   153         *  <transport2> entries. For example
   154         *
   155         *  @a(Example)
   156         *  UIAMetaData.setTransportFields(false, "UART", "UIAPACKET",
   157         *                      true, "timestamps=32bits,sequence=disabled");
   158         *
   159         *  would yield
   160         *
   161         * <transport2>
   162         *    <isMultiCoreTransport>false</isMultiCoreTransport>
   163         *    <supportControl>true</supportControl>
   164         *    <format>UIAPacket</format>
   165         *    <transportType>UART</transportType>
   166         *    <customFields>
   167         *       <timestamps>32bits</timestamps>
   168         *       <sequence>disabled</sequence>
   169         *    </customFields>
   170         * </transport2>
   171         *  @p
   172         *
   173         *  This function can be called multiple times.
   174         *
   175         *  @param(isMultiCoreTransport) Boolean whether it is a multicore
   176         *                               transport. If true, then multiple
   177         *                               cores route their events through
   178         *                               the transport on this core.
   179         *  @param(transportType)        The type of transport (e.g. UART)
   180         *  @param(format)               The format of the data (e.g. UIAPACKET)
   181         *  @param(supportControl)       Boolean whether the transport can receive
   182         *                               control messages from the instrumentation
   183         *                               host.
   184         *  @param(customFields)         Custom fields. Fields are comma separated.
   185         *                               Field name/values are separated by an
   186         *                               '='.
   187         */
   188        metaonly function setTransportFields(isMultiCoreTransport, uploadMode,
   189                                             transportType, format, supportControl,
   190                                             customFields);
   191    
   192        /*! @_nodoc
   193         * ======== setLoggingSetupConfigured ========
   194         * Called by the LoggingSetup module to indicate it is in the .cfg file
   195         *
   196         * Sets an internal metaonly flag that is used to determine the transport used.
   197         */
   198        metaonly function setLoggingSetupConfigured();
   199    
   200        /*! @_nodoc
   201         * ======== isLoggingSetupConfigured ========
   202         * Called by other modules to see if the LoggingSetup module is in the .cfg file
   203         *
   204         * Returns true if the LoggingSetup module can be used to determine the transport used.
   205         */
   206        metaonly function isLoggingSetupConfigured();
   207    
   208        /*! @_nodoc
   209         * ======== setLogSyncInfo ========
   210         * Called by the LogSync module to provide the module name and isEnabled flag
   211         */
   212        metaonly function setLogSyncInfo(moduleName, isEnabled);
   213    
   214        /*! @_nodoc
   215         * ======== setLoggingSetupName ========
   216         * Called by the LoggingSetup module to provide it's module name
   217         */
   218        metaonly function setLoggingSetupName(moduleName);
   219    
   220        /*!
   221         *  ======== overrideCpuFreq ========
   222         *  True if app has set cpuFreq.
   223         *
   224         *  @_nodoc
   225         */
   226        metaonly config bool overrideCpuFreq = false;
   227    
   228        /*!
   229         *  ======== overrideTimestampFreq ========
   230         *  True if app has set timestampFreq.
   231         *
   232         *  @_nodoc
   233         */
   234        metaonly config bool overrideTimestampFreq = false;
   235    }