1    /* 
     2     *  Copyright (c) 2008-2019 Texas Instruments Incorporated
     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        /* REQ_TAG(SYSBIOS-913), REQ_TAG(SYSBIOS-919) */
    85        config SizeT bufSize = 1024;
    86    
    87        /*!
    88         *  ======== flushAtExit ========
    89         *  Flush the internal buffer during `{@link #exit}` or `{@link #abort}`.
    90         *
    91         *  If the application's target is a TI target, the internal buffer is
    92         *  flushed via the `HOSTwrite` function in the TI C Run Time Support
    93         *  (RTS) library.
    94         *
    95         *  If the application's target is not a TI target, the internal buffer
    96         *  is flushed to `stdout` via `fwrite(..., stdout)`.
    97         *
    98         *  Setting this parameter to `false` reduces the footprint of the
    99         *  application at the expense of not getting output when the application
   100         *  ends via a `System_exit()`, `System_abort()`, `exit()` or `abort()`.
   101         */
   102        /* REQ_TAG(SYSBIOS-920) */
   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 uses
   145         *  the ANSI C Standard Library function `fwrite()` (or `HOSTwrite` in the
   146         *  TI C Run Time Support library) to output accumulated output characters.
   147         *
   148         *  @a(Note)
   149         *  The default implementation of `outputFxn` can block, and that might be
   150         *  the case for other implementations. Therefore, this function must not be
   151         *  called by an interrupt service routine (ISR) unless a non-blocking
   152         *  implementation of `outputFxn` is used. If `{@link #flushAtExit}`
   153         *  configuration parameter is true, `{@link #exit}` and `{@link #abort}`
   154         *  will call this function, and the above limitation holds true for them
   155         *  too.
   156         *
   157         *  @see #OutputFxn
   158         */
   159        /* REQ_TAG(SYSBIOS-914) */
   160        config OutputFxn outputFxn = null;
   161    
   162        /*!
   163         *  ======== abort ========
   164         *  Backend for `{@link System#abort()}`
   165         *
   166         *  This abort function writes the string to the internal output buffer and
   167         *  then gives all internal output to the `{@link #outputFxn}` function if
   168         *  the `{@link #flushAtExit}` configuration parameter is true.
   169         *
   170         *  @param(str)  message to output just prior to aborting
   171         *
   172         *      If non-`NULL`, this string should be output just prior to
   173         *      terminating.
   174         *
   175         *  @see ISystemSupport#abort
   176         */
   177        /* REQ_TAG(SYSBIOS-915) */
   178        override Void abort(CString str);
   179    
   180        /*!
   181         *  ======== exit ========
   182         *  Backend for `{@link System#exit()}`
   183         *
   184         *  This exit function gives all internal output to the `{@link #outputFxn}`
   185         *  function if the `{@link #flushAtExit}` configuration parameter is true.
   186         *
   187         *  @see ISystemSupport#exit
   188         */
   189        /* REQ_TAG(SYSBIOS-916) */
   190        override Void exit(Int stat);
   191    
   192        /*!
   193         *  ======== flush ========
   194         *  Backend for `{@link System#flush()}`
   195         *
   196         *  The `flush` writes the contents of the internal character buffer
   197         *  via the `{@link #outputFxn}` function.
   198         *
   199         *  @a(Warning)
   200         *  The `{@link System}` gate is used for thread safety during the
   201         *  entire flush operation, so care must be taken when flushing with
   202         *  this `ISystemSupport` module.  Depending on the nature of the
   203         *  `System` gate, your application's interrupt latency
   204         *  may become a function of the `bufSize` parameter!
   205         *
   206         *  @see ISystemSupport#flush
   207         */
   208        override Void flush();
   209    
   210        /*!
   211         *  ======== putch ========
   212         *  Backend for `{@link System#printf()}` and `{@link System#putch()}`
   213         *
   214         *  This function appends the character to an internal circular buffer.
   215         *  In the event that this buffer is not "flushed" (via `{@link #flush}`)
   216         *  before the output pointer wraps, the oldest previously put character
   217         *  will be overwritten.
   218         *
   219         *  `SysMin_flush` passes the internal buffer to the
   220         *  `{@link #outputFxn}` function and resets the internal buffer.
   221         *
   222         *  If the `{@link #flushAtExit}` configuration parameter is true,
   223         *  `SysMin_flush` is implicitly called by `{@link #exit}` and
   224         *  `{@link #abort}`.
   225         *
   226         *  @see ISystemSupport#putch
   227         */
   228        /* REQ_TAG(SYSBIOS-917) */
   229        override Void putch(Char ch);
   230    
   231        /*!
   232         *  ======== ready ========
   233         *  Test if character output can proceed
   234         *
   235         *  This function returns true if the internal buffer is non-zero.
   236         *
   237         *  @see ISystemSupport#ready
   238         */
   239        /* REQ_TAG(SYSBIOS-918) */
   240        override Bool ready();
   241    
   242    internal:
   243    
   244        /*
   245         * ======== output ======== 
   246         *  SysMin_output__I is generated based on bufSize.
   247         *
   248         *  This function is generated so that the code does not contain a call to
   249         *  HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
   250         *  would optimize out the HOSTwrite function, leaving a 0-length symbol.
   251         *  If the a client later tried to pull in HOSTwrite, there would be a
   252         *  symbol error.
   253         *
   254         *  This generated function is accessed through an internal config so
   255         *  that it is an indirect call in the ROM case, but optimized to a direct
   256         *  call in the RAM case.
   257         */
   258        Void output(Char *buf, UInt size);
   259        readonly config OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
   260    
   261        struct Module_State {
   262            Char outbuf[];  /* the output buffer */
   263            UInt outidx;    /* index within outbuf to next Char to write */
   264            Bool wrapped;   /* has the index (outidx) wrapped */  
   265        }
   266    }
   267    /*
   268     *  @(#) xdc.runtime; 2, 1, 0,0; 10-3-2020 15:24:56; /db/ztree/library/trees/xdc/xdc-K04/src/packages/
   269     */
   270