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