1    /* 
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SysMin.xdc ========
    15     */
    16    
    17    /*!
    18     *  ======== SysMin ========
    19     *
    20     *  Minimal implementation of `{@link ISystemSupport}`
    21     *
    22     *  This implementation provides a fully functional implementation of
    23     *  all methods specified by `ISystemSupport`. 
    24     *
    25     *  The module maintains an internal buffer (with a configurable size)
    26     *  that stores on the "output". When full, the data is over-written.  When
    27     *  `System_flush()` is called the characters in the internal buffer are
    28     *  "output" using the user configurable `{@link #outputFxn}`.
    29     *
    30     *  As with all `ISystemSupport` modules, this module is the back-end for the
    31     *  `{@link System}` module; application code does not directly call these
    32     *  functions.
    33     */
    34    
    35    @Template("./SysMin.xdt")
    36    @ModuleStartup
    37    @RomConsts
    38    
    39    module SysMin inherits xdc.runtime.ISystemSupport {
    40    
    41        metaonly struct ModuleView {
    42            Ptr outBuf;
    43            UInt outBufIndex;
    44            Bool wrapped;    /* has the buffer wrapped */
    45        };
    46    
    47        metaonly struct BufferEntryView {
    48            String entry;
    49        }
    50    
    51        /*!
    52         *  ======== rovViewInfo ========
    53         *  @_nodoc
    54         */
    55        @Facet
    56        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo = 
    57            xdc.rov.ViewInfo.create({
    58                viewMap: [
    59                    ['Module',
    60                        {
    61                            type: xdc.rov.ViewInfo.MODULE,
    62                            viewInitFxn: 'viewInitModule',
    63                            structName: 'ModuleView'
    64                        }
    65                    ],
    66                    ['OutputBuffer',
    67                        {
    68                            type: xdc.rov.ViewInfo.MODULE_DATA,
    69                            viewInitFxn: 'viewInitOutputBuffer',
    70                            structName: 'BufferEntryView'
    71                        }
    72                    ]
    73                ]
    74            });
    75    
    76        /*!
    77         *  ======== bufSize ========
    78         *  Size (in MAUs) of the output.
    79         *
    80         *  An internal buffer of this size is allocated. All output is stored 
    81         *  in this internal buffer. 
    82         *
    83         *  If 0 is specified for the size, no buffer is created, all output
    84         *  is dropped, and `{@link SysMin#ready()}` always returns `FALSE`.
    85         */
    86        config SizeT bufSize = 1024;
    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 supplied character output function
   131         *
   132         *  If this parameter is set to a non-`null` value, the specified
   133         *  function will be called by `{@link System#flush()}` to output
   134         *  any characters buffered within `SysMin`.
   135         *
   136         *  For example, if you define a function named `myOutputFxn`, the
   137         *  following configuration fragment will cause `SysMin` to call
   138         *  `myOutputFxn` whenever the character buffer is flushed.
   139         *  @p(code)
   140         *      var SysMin = xdc.useModule("xdc.runtime.SysMin");
   141         *      SysMin.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         *  This function appends the character to an internal circular buffer.
   206         *  In the event that this buffer is not "flushed" (via `{@link #flush}`)
   207         *  before the output pointer wraps, the oldest previously put character
   208         *  will be overwritten.
   209         *
   210         *  `SysMin_flush` passes the internal buffer to the
   211         *  `{@link #outputFxn}` function and resets the internal buffer.
   212         *
   213         *  If the `{@link #flushAtExit}` configuration parameter is true, 
   214         *  `SysMin_flush` is implicitly called by `{@link #exit}` and
   215         *  `{@link #abort}`.
   216         *
   217         *  @see ISystemSupport#putch
   218         */
   219        override Void putch(Char ch);
   220    
   221        /*!
   222         *  ======== ready ========
   223         *  Test if character output can proceed
   224         *
   225         *  This function returns true if the internal buffer is non-zero.
   226         *
   227         *  @see ISystemSupport#ready
   228         */
   229        override Bool ready();
   230    
   231    internal:
   232    
   233        /*
   234         * ======== output ======== 
   235         *  SysMin_output__I is generated based on bufSize.
   236         *
   237         *  This function is generated so that the code does not contain a call to
   238         *  HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
   239         *  would optimize out the HOSTwrite function, leaving a 0-length symbol.
   240         *  If the a client later tried to pull in HOSTwrite, there would be a
   241         *  symbol error.
   242         *
   243         *  This generated function is accessed through an internal config so
   244         *  that it is an indirect call in the ROM case, but optimized to a direct
   245         *  call in the RAM case.
   246         */
   247        Void output(Char *buf, UInt size);
   248        readonly config OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
   249    
   250        struct Module_State {
   251            Char outbuf[];  /* the output buffer */
   252            UInt outidx;    /* index within outbuf to next Char to write */
   253            Bool wrapped;   /* has the index (outidx) wrapped */  
   254        }
   255    }
   256    /*
   257     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:16; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   258     */
   259