1    /* --COPYRIGHT--,TI
     2     * Copyright (c) $(CPYYEAR)
     3     * Texas Instruments
     4     *
     5     *  All rights reserved.  Property of Texas Instruments
     6     *  Restricted rights to use, duplicate or disclose this code are
     7     *  granted through contract.
     8     * 
     9     * --/COPYRIGHT--*/
    10    /*
    11     *  ======== Transformer.xdc ========
    12     */
    13     
    14    import xdc.rov.ViewInfo;
    15    
    16    import xdc.runtime.Error;
    17    import ti.sdo.io.IConverter;
    18    
    19    /*! 
    20     *  Transformer module
    21     *
    22     *  This module allows the user to create instances which modify a data stream 
    23     *  by applying a function to each point produced or consumed by an underlying 
    24     *  driver. The number of transformer instances in the system is limited only 
    25     *  by the availability of memory; 
    26     *  
    27     *  This module implements {@link ti.sdo.io.IConverter} interface and as such is
    28     *  only usable with {@link ti.sdo.io.Stream}. IConverter instances are added to
    29     *  a table within Stream and they can be linked together to form an IO 
    30     *  stack/chain.
    31     *
    32     *  For example, is "/scale" is a Transformer instance in the stream table
    33     *  and "/adc" is a driver in {@link ti.sdo.io.DriverTable} then the name
    34     *  "/scale/adc" can be used to create a Stream instance.
    35     *
    36     *  For every Transformer instance the user can supply a tranfer function.
    37     *  Transformer provides three of these functions - {@link #multiply},
    38     *  {@link #fix2flt} and {@link #flt2fix}.
    39     */
    40    
    41    module Transformer inherits IConverter
    42    {
    43        /*! typedefs for transformer function
    44         *
    45         *  Functions of this type get passed the buffer, buffer size and a 
    46         *  function specific argument. The function should NOT act on the buffer 
    47         *  if buffer is NULL or buffer size is zero.
    48         */
    49        typedef Void (*TransFunc)(Ptr, SizeT, UArg);    
    50       
    51        metaonly struct BasicView {
    52            String              label;
    53            Ptr                 lowerConverter;
    54            String              mode;   
    55            String              callbackFxn[];
    56            UArg                callbackArg;
    57            String              transformFxn[];
    58            UArg                transformArg;
    59        }
    60        
    61        @Facet
    62        metaonly config ViewInfo.Instance rovViewInfo = 
    63            ViewInfo.create({
    64                viewMap: [
    65                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
    66                ]
    67            });
    68        
    69        /*! 
    70         *  ======== multiply ========
    71         *  multiply function mutiples each data point with a scale value 
    72         * 
    73         *  This function casts the scaleFactor to a UInt before using it.
    74         *  If arg is NULL a scaleFactor of 1 is used.
    75         */
    76        Void multiply(Ptr addr, SizeT size, UArg scaleFactor);
    77        
    78        /*! 
    79         *  ======== fix2flt ========
    80         *  fix2flt converts each data point from fixed point to floating point 
    81         *
    82         *  This function ignores the scaleFactor.
    83         */
    84        Void fix2flt(Ptr addr, SizeT size, UArg scaleFactor);
    85    
    86        /*! 
    87         *  ======== flt2fix ========
    88         *  flt2fix converts each data point from floating point to fixed point 
    89         *
    90         *  This function ignores the scaleFactor.
    91         */
    92        Void flt2fix(Ptr addr, SizeT size, UArg scalePtr);
    93       
    94    instance:
    95        /*! 
    96         *  Function can be {@link #multiply}, {@link #fix2flt}
    97         *  or {@link #flt2fix} or a user specific function.
    98         */
    99        config TransFunc fxn = null;
   100    
   101        /*! 
   102         * Arg to be used with transform functions. 
   103         */
   104        config UArg arg = null;
   105    
   106    internal:
   107        
   108        /*!
   109         *  ======== callback ========
   110         *  @_nodoc
   111         *  callback function for lower IConverter instance.
   112         *
   113         *  @param(cbArg)   callback argument 
   114         */
   115        Void callback(UArg cbArg);
   116         
   117        // -------- Internal Structures --------
   118        struct Instance_State {
   119            IConverter.Handle   convHandle;     /* handle for IConverter */
   120            Bool                drvAdapHdl;     /* created DriverAdapter */
   121            UInt                mode;   
   122            IConverter.DoneFxn  cbFxn;
   123            UArg                cbArg;
   124            TransFunc           fxn;            /* transform function */
   125            UArg                arg;            /* transform func arg */
   126        };
   127    }