1    /*
     2     *  Copyright 2013 by Texas Instruments Incorporated.
     3     *
     4     */
     5    
     6    /*
     7     * Copyright (c) 2013 Texas Instruments Incorporated - http://www.ti.com
     8     *
     9     * Redistribution and use in source and binary forms, with or without
    10     * modification, are permitted provided that the following conditions
    11     * are met:
    12     *
    13     *   Redistributions of source code must retain the above copyright
    14     *   notice, this list of conditions and the following disclaimer.
    15     *
    16     *   Redistributions in binary form must reproduce the above copyright
    17     *   notice, this list of conditions and the following disclaimer in the
    18     *   documentation and/or other materials provided with the distribution.
    19     *
    20     *   Neither the name of Texas Instruments Incorporated nor the names of
    21     *   its contributors may be used to endorse or promote products derived
    22     *   from this software without specific prior written permission.
    23     *
    24     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    25     * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    26     * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    27     * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    28     * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    29     * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    30     * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    31     * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    32     * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    33     * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    34     * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    35     */
    36    /*
    37     *  ======== SysCBuf.xdc ========
    38     */
    39    
    40    /*!
    41     *  ======== SysCBuf ========
    42     *
    43     *  Implementation of `{@link ISystemSupport}` with circular buffer for
    44     *  output.
    45     *
    46     *  This implementation provides a fully functional implementation of
    47     *  all methods specified by `ISystemSupport`.
    48     *
    49     *  This module maintains a circular buffer where data is written on
    50     *  SysCBuf_putch(). When the buffer is full, data is overwritten, and
    51     *  SysCBuf internally keeps track of the number of characters lost
    52     *  due to overwrite. The output buffer can be statically configured
    53     *  or dynamically bound to a buffer using SysCBuf_bind().
    54     *
    55     *  When `System_flush()` is called the characters in the internal buffer
    56     *  are "output" using the user configuratble `{@link #outputFxn}`. There is
    57     *  also a user configurable "get" function that can be used to copy out a
    58     *  given amount from the circular buffer.
    59     *
    60     *  The difference between SysCBuf and the xdc.runtime.SysMin module, are
    61     *  the following additional features:
    62     *     - SysCBuf_bind() for dynamic binding of the circular output buffer.
    63     *     - SysCBuf_get() for copying a given amount of data from the output
    64     *       buffer to another buffer.
    65     *     - Maintaining the number of characters lost due to overrite, and the
    66     *       number of characters available for reading with SysCBuf_get().
    67     *
    68     *  As with all `ISystemSupport` modules, this module is the back-end for the
    69     *  `{@link System}` module; application code does not directly call these
    70     *  functions.
    71     */
    72    
    73    @Template("./SysCBuf.xdt")
    74    @ModuleStartup
    75    module SysCBuf inherits xdc.runtime.ISystemSupport {
    76    
    77        /*!
    78         *  ======== bufSize ========
    79         *  Size (in MAUs) of the output.
    80         *
    81         *  An internal buffer of this size is allocated. All output is stored
    82         *  in this internal buffer.
    83         *
    84         *  If 0 is specified for the size, no buffer is created.
    85         */
    86        config SizeT bufSize = 0;
    87    
    88        /*!
    89         *  ======== flushAtExit ========
    90         *  Flush the internal buffer during `{@link #exit}` or `{@link #abort}`.
    91         *
    92         *  If the application's target is a TI target, the internal buffer is
    93         *  flushed via the `HOSTwrite` function in the TI C Run Time Support
    94         *  (RTS) library.
    95         *
    96         *  If the application's target is not a TI target, the internal buffer
    97         *  is flushed to `stdout` via `fwrite(..., stdout)`.
    98         *
    99         *  Setting this parameter to `false` reduces the footprint of the
   100         *  application at the expense of not getting output when the application
   101         *  ends via a `System_exit()`, `System_abort()`, `exit()` or `abort()`.
   102         */
   103        config Bool flushAtExit = true;
   104    
   105        /*!
   106         *  ======== sectionName ========
   107         *  Section where the internal character output buffer is placed
   108         *
   109         *  The default is to have no explicit placement; i.e., the linker is
   110         *  free to place it anywhere in the memory map.
   111         */
   112        metaonly config String sectionName = null;
   113    
   114        /*!
   115         *  ======== OutputFxn ========
   116         *  Output characters in the specified buffer
   117         *
   118         *  The first parameter is a pointer to a buffer of characters to be
   119         *  output.  The second parameter is the number of characters in the
   120         *  buffer to output.
   121         *
   122         *  This function may be called with 0 as the second parameter.  In this
   123         *  case, the function should simply return.
   124         *
   125         */
   126        typedef Void (*OutputFxn)(Char *, UInt);
   127    
   128        /*!
   129         *  ======== outputFxn ========
   130         *  User suplied character output function
   131         *
   132         *  If this parameter is set to a non-`null` value, the specified
   133         *  function will be called by to output characters buffered within
   134         *  `SysCBuf`.
   135         *
   136         *  For example, if you define a function named `myOutputFxn`, the
   137         *  following configuration fragment will cause `SysCBuf` to call
   138         *  `myOutputFxn` whenever the character buffer is flushed.
   139         *  @p(code)
   140         *      var SysCBuf = xdc.useModule("xdc.runtime.SysCBuf");
   141         *      SysCBuf.outputFxn = "&myOutputFxn";
   142         *  @p
   143         *
   144         *  If this parameter is not set, a default function will be used which
   145         *  uses the ANSI C Standard Library function `fwrite()` (or `HOSTwrite`
   146         *  in the TI C Run Time Support library) to output
   147         *  accumulated output characters.
   148         *
   149         *  @see #OutputFxn
   150         */
   151        config OutputFxn outputFxn = null;
   152    
   153        /*!
   154         *  ======== abort ========
   155         *  Backend for `{@link System#abort()}`
   156         *
   157         *  This abort function writes the string to the internal
   158         *  output buffer and then gives all internal output to the
   159         *  `{@link #outputFxn}` function if the `{@link #flushAtExit}`
   160         *  configuration parameter is true.
   161         *
   162         *  @param(str)  message to output just prior to aborting
   163         *
   164         *      If non-`NULL`, this string should be output just prior to
   165         *      terminating.
   166         *
   167         *  @see ISystemSupport#abort
   168         */
   169        override Void abort(CString str);
   170    
   171        /*!
   172         *  ======== exit ========
   173         *  Backend for `{@link System#exit()}`
   174         *
   175         *  This exit function gives all internal output to the
   176         *  `{@link #outputFxn}` function if the `{@link #flushAtExit}`
   177         *  configuration parameter is true.
   178         *
   179         *  @see ISystemSupport#exit
   180         */
   181        override Void exit(Int stat);
   182    
   183        /*!
   184         *  ======== flush ========
   185         *  Backend for `{@link System#flush()}`
   186         *
   187         *  The `flush` writes the contents of the internal character buffer
   188         *  via the `{@link #outputFxn}` function.
   189         *
   190         *  @a(Warning)
   191         *  The `{@link System}` gate is used for thread safety during the
   192         *  entire flush operation, so care must be taken when flushing with
   193         *  this `ISystemSupport` module.  Depending on the nature of the
   194         *  `System` gate, your application's interrupt latency
   195         *  may become a function of the `bufSize` parameter!
   196         *
   197         *  @see ISystemSupport#flush
   198         */
   199        override Void flush();
   200    
   201        /*!
   202         *  ======== putch ========
   203         *  Backend for `{@link System#printf()}` and `{@link System#putch()}`
   204         *
   205         *  Places the character into an internal buffer. The `{@link #flush}`
   206         *  sends the internal buffer to the `{@link #outputFxn}` function.
   207         *  The internal buffer is also sent to the `SysCBuf_outputFxn`
   208         *  function by `{@link #exit}` and `{@link #abort}` if the
   209         *  `{@link #flushAtExit}` configuration parameter is true.
   210         *
   211         *  @see ISystemSupport#putch
   212         */
   213        override Void putch(Char ch);
   214    
   215        /*!
   216         *  ======== ready ========
   217         *  Test if character output can proceed
   218         *
   219         *  This function returns true if the internal buffer is non-zero.
   220         *
   221         *  @see ISystemSupport#ready
   222         */
   223        override Bool ready();
   224    
   225        /*!
   226         *  ======== bind ========
   227         *  Bind the buffer 'buf' of size 'size' bytes to the SysCBuf trace buffer.
   228         *
   229         *  Return 0 if successful, -1 otherwise.
   230         */
   231        Int bind(Char *buf, UInt32 size);
   232    
   233        /*!
   234         *  ======== get ========
   235         *  Copy contents of the trace buffer. Return the number of characters
   236         *  remaining in 'avail'. Return the number of characters lost due to
   237         *  wrapping in 'lost'.
   238         *
   239         *  Return the number of characters copied.
   240         *
   241         */
   242        UInt32 get(Char *buf, UInt32 size, UInt32 *avail, UInt32 *lost);
   243    
   244        /*!
   245         *  ======== getSize ========
   246         *  Return the size of the trace buffer.
   247         */
   248        UInt32 getSize();
   249    
   250    internal:
   251    
   252        /*
   253         * ======== output ========
   254         *  System_output__I is generated based on bufSize.
   255         *
   256         *  This function is generated so that the code does not contain a call to
   257         *  HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
   258         *  would optimize out the HOSTwrite function, leaving a 0-length symbol.
   259         *  If the a client later tried to pull in HOSTwrite, there would be a
   260         *  symbol error.
   261         *
   262         *  This generated function is accessed through an internal config so
   263         *  that it is an indirect call in the ROM case, but optimized to a direct
   264         *  call in the RAM case.
   265         */
   266        Void output(Char *buf, UInt size);
   267        readonly config OutputFxn outputFunc = '&ti_sdo_ce_utils_syscbuf_SysCBuf_output__I';
   268    
   269        struct Module_State {
   270            Char outbuf[];  /* the output buffer */
   271            UInt outidx;    /* index within outbuf to next Char to write */
   272            Bool wrapped;   /* has the index (outidx) wrapped */
   273            UInt32 bufSize; /* size of the trace buffer */
   274        }
   275    }
   276    /*
   277     *  @(#) ti.sdo.ce.utils.syscbuf; 1, 0, 0,3; 6-13-2013 00:19:47; /db/atree/library/trees/ce/ce-w08/src/ xlibrary
   278    
   279     */
   280