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         *  @see #OutputFxn
   149         */
   150        /* REQ_TAG(SYSBIOS-914) */
   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 output buffer and
   158         *  then gives all internal output to the `{@link #outputFxn}` function if
   159         *  the `{@link #flushAtExit}` configuration parameter is true.
   160         *
   161         *  @param(str)  message to output just prior to aborting
   162         *
   163         *      If non-`NULL`, this string should be output just prior to
   164         *      terminating.
   165         *
   166         *  @see ISystemSupport#abort
   167         */
   168        /* REQ_TAG(SYSBIOS-915) */
   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 `{@link #outputFxn}`
   176         *  function if the `{@link #flushAtExit}` configuration parameter is true.
   177         *
   178         *  @see ISystemSupport#exit
   179         */
   180        /* REQ_TAG(SYSBIOS-916) */
   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        /* REQ_TAG(SYSBIOS-917) */
   220        override Void putch(Char ch);
   221    
   222        /*!
   223         *  ======== ready ========
   224         *  Test if character output can proceed
   225         *
   226         *  This function returns true if the internal buffer is non-zero.
   227         *
   228         *  @see ISystemSupport#ready
   229         */
   230        /* REQ_TAG(SYSBIOS-918) */
   231        override Bool ready();
   232    
   233    internal:
   234    
   235        /*
   236         * ======== output ======== 
   237         *  SysMin_output__I is generated based on bufSize.
   238         *
   239         *  This function is generated so that the code does not contain a call to
   240         *  HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
   241         *  would optimize out the HOSTwrite function, leaving a 0-length symbol.
   242         *  If the a client later tried to pull in HOSTwrite, there would be a
   243         *  symbol error.
   244         *
   245         *  This generated function is accessed through an internal config so
   246         *  that it is an indirect call in the ROM case, but optimized to a direct
   247         *  call in the RAM case.
   248         */
   249        Void output(Char *buf, UInt size);
   250        readonly config OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
   251    
   252        struct Module_State {
   253            Char outbuf[];  /* the output buffer */
   254            UInt outidx;    /* index within outbuf to next Char to write */
   255            Bool wrapped;   /* has the index (outidx) wrapped */  
   256        }
   257    }
   258    /*
   259     *  @(#) xdc.runtime; 2, 1, 0,0; 8-21-2019 13:22:47; /db/ztree/library/trees/xdc/xdc-H25/src/packages/
   260     */
   261