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    module SysMin inherits xdc.runtime.ISystemSupport {
    38     
    39        metaonly struct ModuleView {
    40            Ptr outBuf;
    41            UInt outBufIndex;
    42            Bool wrapped;    /* has the buffer wrapped */
    43        };
    44        
    45        metaonly struct BufferEntryView {
    46            String entry;
    47        }
    48    
    49        /*!
    50         *  ======== rovViewInfo ========
    51         *  @_nodoc
    52         */
    53        @Facet
    54        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo = 
    55            xdc.rov.ViewInfo.create({
    56                viewMap: [
    57                    ['Module',
    58                        {
    59                            type: xdc.rov.ViewInfo.MODULE,
    60                            viewInitFxn: 'viewInitModule',
    61                            structName: 'ModuleView'
    62                        }
    63                    ],
    64                    ['OutputBuffer',
    65                        {
    66                            type: xdc.rov.ViewInfo.MODULE_DATA,
    67                            viewInitFxn: 'viewInitOutputBuffer',
    68                            structName: 'BufferEntryView'
    69                        }
    70                    ]
    71                ]
    72            });
    73        
    74        /*!
    75         *  ======== bufSize ========
    76         *  Size (in MAUs) of the output.
    77         *
    78         *  An internal buffer of this size is allocated. All output is stored 
    79         *  in this internal buffer. 
    80         *
    81         *  If 0 is specified for the size, no buffer is created, all output
    82         *  is dropped, and `{@link SysMin#ready()}` always returns `FALSE`.
    83         */
    84        config SizeT bufSize = 1024;
    85    
    86        /*!
    87         *  ======== flushAtExit ========
    88         *  Flush the internal buffer during `{@link #exit}` or `{@link #abort}`.
    89         *
    90         *  If the application's target is a TI target, the internal buffer is
    91         *  flushed via the `HOSTwrite` function in the TI C Run Time Support
    92         *  (RTS) library.
    93         *
    94         *  If the application's target is not a TI target, the internal buffer
    95         *  is flushed to `stdout` via `fwrite(..., stdout)`.
    96         *
    97         *  Setting this parameter to `false` reduces the footprint of the 
    98         *  application at the expense of not getting output when the application
    99         *  ends via a `System_exit()`, `System_abort()`, `exit()` or `abort()`.  
   100         */
   101        config Bool flushAtExit = true;
   102     
   103        /*!
   104         *  ======== sectionName ========
   105         *  Section where the internal character output buffer is placed
   106         *
   107         *  The default is to have no explicit placement; i.e., the linker is
   108         *  free to place it anywhere in the memory map.
   109         */
   110        metaonly config String sectionName = null;
   111       
   112        /*!
   113         *  ======== OutputFxn ========
   114         *  Output characters in the specified buffer
   115         *
   116         *  The first parameter is a pointer to a buffer of characters to be
   117         *  output.  The second parameter is the number of characters in the
   118         *  buffer to output.
   119         *
   120         *  This function may be called with 0 as the second parameter.  In this
   121         *  case, the function should simply return.
   122         *  
   123         */
   124        typedef Void (*OutputFxn)(Char *, UInt);
   125    
   126        /*!
   127         *  ======== outputFxn ========
   128         *  User supplied character output function
   129         *
   130         *  If this parameter is set to a non-`null` value, the specified
   131         *  function will be called by `{@link System#flush()}` to output
   132         *  any characters buffered within `SysMin`.
   133         *
   134         *  For example, if you define a function named `myOutputFxn`, the
   135         *  following configuration fragment will cause `SysMin` to call
   136         *  `myOutputFxn` whenever the character buffer is flushed.
   137         *  @p(code)
   138         *      var SysMin = xdc.useModule("xdc.runtime.SysMin");
   139         *      SysMin.outputFxn = "&myOutputFxn";
   140         *  @p
   141         *
   142         *  If this parameter is not set, a default function will be used which
   143         *  uses the ANSI C Standard Library function `fwrite()` (or `HOSTwrite` 
   144         *  in the TI C Run Time Support library) to output
   145         *  accumulated output characters.
   146         *
   147         *  @see #OutputFxn
   148         */
   149        config OutputFxn outputFxn = null;
   150        
   151        /*!
   152         *  ======== abort ========
   153         *  Backend for `{@link System#abort()}`
   154         *
   155         *  This abort function writes the string to the internal
   156         *  output buffer and then gives all internal output to the 
   157         *  `{@link #outputFxn}` function if the `{@link #flushAtExit}` 
   158         *  configuration parameter is true.
   159         *
   160         *  @param(str)  message to output just prior to aborting
   161         *
   162         *      If non-`NULL`, this string should be output just prior to
   163         *      terminating. 
   164         *
   165         *  @see ISystemSupport#abort
   166         */
   167        override Void abort(CString str);
   168        
   169        /*!
   170         *  ======== exit ========
   171         *  Backend for `{@link System#exit()}`
   172         *
   173         *  This exit function gives all internal output to the 
   174         *  `{@link #outputFxn}` function if the `{@link #flushAtExit}` 
   175         *  configuration parameter is true.
   176         *
   177         *  @see ISystemSupport#exit
   178         */
   179        override Void exit(Int stat);
   180        
   181        /*!
   182         *  ======== flush ========
   183         *  Backend for `{@link System#flush()}`
   184         *
   185         *  The `flush` writes the contents of the internal character buffer
   186         *  via the `{@link #outputFxn}` function.
   187         *
   188         *  @a(Warning)
   189         *  The `{@link System}` gate is used for thread safety during the
   190         *  entire flush operation, so care must be taken when flushing with
   191         *  this `ISystemSupport` module.  Depending on the nature of the
   192         *  `System` gate, your application's interrupt latency
   193         *  may become a function of the `bufSize` parameter!
   194         *
   195         *  @see ISystemSupport#flush
   196         */
   197        override Void flush();
   198        
   199        /*!
   200         *  ======== putch ========
   201         *  Backend for `{@link System#printf()}` and `{@link System#putch()}`
   202         *
   203         *  Places the character into an internal buffer. The `{@link #flush}` 
   204         *  sends the internal buffer to the `{@link #outputFxn}` function.
   205         *  The internal buffer is also sent to the `SysMin_outputFxn` 
   206         *  function by `{@link #exit}` and `{@link #abort}` if the 
   207         *  `{@link #flushAtExit}` configuration parameter is true.
   208         *
   209         *  @see ISystemSupport#putch
   210         */
   211        override Void putch(Char ch);
   212        
   213        /*!
   214         *  ======== ready ========
   215         *  Test if character output can proceed
   216         *
   217         *  This function returns true if the internal buffer is non-zero.
   218         *
   219         *  @see ISystemSupport#ready
   220         */
   221        override Bool ready();
   222        
   223    internal:
   224        
   225        /*
   226         * ======== output ======== 
   227         *  SysMin_output__I is generated based on bufSize.
   228         *
   229         *  This function is generated so that the code does not contain a call to
   230         *  HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
   231         *  would optimize out the HOSTwrite function, leaving a 0-length symbol.
   232         *  If the a client later tried to pull in HOSTwrite, there would be a
   233         *  symbol error.
   234         *
   235         *  This generated function is accessed through an internal config so
   236         *  that it is an indirect call in the ROM case, but optimized to a direct
   237         *  call in the RAM case.
   238         */
   239        Void output(Char *buf, UInt size);
   240        readonly config OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
   241    
   242        struct Module_State {
   243            Char outbuf[];  /* the output buffer */
   244            UInt outidx;    /* index within outbuf to next Char to write */
   245            Bool wrapped;   /* has the index (outidx) wrapped */  
   246        }
   247    }
   248    /*
   249     *  @(#) xdc.runtime; 2, 1, 0,0; 4-24-2015 12:34:13; /db/ztree/library/trees/xdc/xdc-A71/src/packages/
   250     */
   251