1    /* 
     2     * Copyright (c) 2012, 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     *  ======== TraceUtil ========
    35     *  TraceUtil Configuration interface
    36     */
    37    @Template("./TraceUtil.xdt")
    38    
    39    @Gated
    40    
    41    metaonly module TraceUtil {
    42    
    43        /*!
    44         *  ======== PipeCmdAlias ========
    45         *  Alias' to use for the cmd pipe.
    46         */
    47        struct PipeCmdAlias {
    48            String alias;           /*! alias for a group of pipe commands */
    49            String cmds[];          /*! list of pipe commands for this alias */
    50        };
    51    
    52        /*!
    53         *  ======== Attrs ========
    54         *  Configuration attributes
    55         *
    56         *  This structure describes the initialization settings for the
    57         *  TraceUtil module; see TraceUtil.attrs.
    58         *
    59         *  @field(localTraceMask)  The trace mask to be used on the "local",
    60         *                          or application processor.
    61         *
    62         *  @field(localTraceFile)  The name of the file into which trace output
    63         *                          will be generated.  This can be a full path
    64         *                          (e.g. `/tmp/local.txt`), or a path relative
    65         *                          to the executing application.
    66         *
    67         *  @field(dsp0TraceMask)   The trace mask to be used on the "remote"
    68         *                          server.
    69         *
    70         *  @field(dsp0TraceFile)   The name of the file into which trace output
    71         *                          will be generated.  This can be a full path
    72         *                          (e.g. `/tmp/dsp0.txt`), or a path relative
    73         *                          to the executing application.
    74         *
    75         *  @field(dsp0BiosFile)    The name of the file into which DSP/BIOS log
    76         *                          output will be generated.  This can be a
    77         *                          full path (e.g. `/tmp/dspbios.dat`), or a
    78         *                          path relative to the executing application.
    79         *
    80         *  @field(traceFileFlags)  fopen flags used when opening the various
    81         *                          trace/log files.  See fopen() documentation
    82         *                          for details.  For example, to open the files
    83         *                          in "append" mode (i.e. add to existing file
    84         *                          content), use "a"; to open in "over-write"
    85         *                          mode, use "w".
    86         *
    87         *  @field(refreshPeriod)   The number of milliseconds to sleep before
    88         *                          reading the content off the remote servers.
    89         *                          This will vary based on the amount of trace
    90         *                          generated, and the size of the trace logs.
    91         *                          Failure to set this low enough will result
    92         *                          in data loss.
    93         */
    94        struct Attrs {
    95             String   localTraceMask;   /*! local tracing mask */
    96             String   localTraceFile;   /*! local tracing file */
    97             String   dsp0TraceMask;    /*! server's tracing mask */
    98             String   dsp0TraceFile;    /*! server's tracing file */
    99             String   dsp0BiosFile;     /*! server's BIOS tracing file */
   100             String   traceFileFlags;   /*! flags for fopen()ing trace files */
   101             Int      refreshPeriod;    /*! number of ms before two DSP data gets */
   102             String   cmdPipeFile;      /*! named pipe to read commands from */
   103             PipeCmdAlias cmdAliases[]; /*! any aliases for the pipe commands */
   104        };
   105    
   106        /* various pre-packaged tracing profiles (Configs) */
   107    
   108        /*!
   109         *  ======== NO_TRACING ========
   110         *  No tracing or logging of any kind
   111         */
   112        const Attrs NO_TRACING = {
   113            localTraceMask:    "*=",
   114            localTraceFile:    null,
   115            dsp0TraceMask:     "*=",
   116            dsp0TraceFile:     null,
   117            dsp0BiosFile:      null,
   118            traceFileFlags:    null,
   119            refreshPeriod:     0,
   120            cmdPipeFile:       "/tmp/cecmdpipe",
   121            cmdAliases: [ ],
   122        };
   123    
   124        /*!
   125         *  ======== DEFAULT_TRACING ========
   126         *  Tracing that prints warnings and errors on the standard output
   127         */
   128        const Attrs DEFAULT_TRACING = {
   129            localTraceMask:    "*=67",
   130            localTraceFile:    null,
   131            dsp0TraceMask:     "*=67",
   132            dsp0TraceFile:     null,
   133            dsp0BiosFile:      null,
   134            traceFileFlags:    null,
   135            refreshPeriod:     300,
   136            cmdPipeFile:       "/tmp/cecmdpipe",
   137            cmdAliases: [ ],
   138        };
   139    
   140        /*!
   141         *  ======== SOCRATES_TRACING ========
   142         *  Tracing appropriate for the SoC Analyzer data collection tool.
   143         *
   144         *  The default settings here place data files into the `/tmp` directory.
   145         *  `/tmp` typically provides faster write access than other file
   146         *  system files, so it is used to lower the overhead of tracing.
   147         *
   148         *  Using these default settings, the GPP and DSP generate approximately
   149         *  400 characters of trace in *each* the localTraceFile and
   150         *  dsp0TraceFile, for each round trip to/from the DSP.  This includes the
   151         *  typical `process()` and `control()` calls to each codec.
   152         *
   153         *  Using that figure, the user is encouraged to configure the
   154         *  refreshPeriod and System trace buffers appropriately, so as to reduce
   155         *  the likelyhood of data loss due to wrapping.
   156         *
   157         *  For example, consider an application which utilizes a 30
   158         *  frame-per-second video codec in parallel with a 50 frame-per-second
   159         *  audio codec.  Additionally, the audio codec requires calling `process()`
   160         *  *and* `control()` for each frame - the video only requires a single
   161         *  process() call.  This application alone will generate approximately
   162         *  ((50 * 2) + 30) * 400 = 52000 bytes of trace data each second.  If the
   163         *  default System trace buffer size is used (32768 bytes), the application
   164         *  needs to ensure the refresh period is less than 650 milliseconds
   165         *  *not including I/O overhead or potential for pre-emption*.
   166         */
   167        const Attrs SOCRATES_TRACING = {
   168            localTraceMask:    "*=67",
   169            localTraceFile:    "/tmp/cearmlog.txt",
   170            dsp0TraceMask:     "*=67",
   171            dsp0TraceFile:     "/tmp/cedsp0log.txt",
   172            dsp0BiosFile:      "/tmp/bioslog.dat",
   173    
   174            /* Open the file for writing.  Note, this over-writes existing files. */
   175            traceFileFlags:    "w",
   176    
   177            refreshPeriod:     0,
   178            cmdPipeFile:       "/tmp/cecmdpipe",
   179            cmdAliases: [
   180                {
   181                    alias: "socrates=on",
   182                    cmds:  [
   183                           "tracemask=*+5",
   184                           "dsp0tracemask=*+5,ti.bios+3",
   185                           "refreshperiod=200",
   186                    ],
   187                },
   188                {
   189                    alias: "socrates=off",
   190                    cmds:  [
   191                           "tracemask=*-5",
   192                           "refreshperiod=0",
   193                           "dsp0tracemask=*-5,ti.bios-3"
   194                    ],
   195                },
   196            ],
   197        };
   198    
   199        /*!
   200         *  ======== FULL_TRACING ========
   201         *  Enable all tracing.
   202         */
   203        const Attrs FULL_TRACING = {
   204            localTraceMask:    "*=01234567",
   205            localTraceFile:    "trace/cearmlog.txt",
   206            dsp0TraceMask:     "*=01234567,ti.bios=01324567",
   207            dsp0TraceFile:     "trace/cedsp0log.txt",
   208            dsp0BiosFile:      "trace/bioslog.dat",
   209            traceFileFlags:    "w",
   210            refreshPeriod:     100,
   211            cmdPipeFile:       "/tmp/cecmdpipe",
   212            cmdAliases: [ ],
   213        };
   214    
   215        /*!
   216         *  ======== attrs ========
   217         *  Tracing configuration; by default set to some very basic tracing
   218         */
   219        config Attrs attrs = DEFAULT_TRACING;
   220    }
   221    /*
   222     *  @(#) ti.sdo.ce.utils.trace; 1, 0, 1,1; 1-17-2012 23:17:59; /db/atree/library/trees/ce/ce-t03/src/ xlibrary
   223    
   224     */
   225