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     *  ======== IConverter.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     *! 28-Apr-2008 nitya   review update
    16     */
    17    
    18    import xdc.runtime.Error;
    19     
    20    /*!
    21     *  Interface defining an IConverter
    22     *
    23     *  This interfaces allows applications to "stack" functionality on top
    24     *  of a driver. Modules that implement this interface can manipulate data
    25     *  coming to and from a driver. Simple scaling, fixed to float or float to
    26     *  fixed transformations can be done using IConverters without major changes
    27     *  in the application.
    28     *
    29     *  IConverters can only be used along with the {@link Stream} module.
    30     *  
    31     *  Stream maintains a name table of {@link IConverter} handles. 
    32     *  This table is used by Stream to create an IO stack. The name passed to
    33     *  {@link Stream#create} is usually of the form "/scale/uart". This name may
    34     *  correspond to the following IO stack.
    35     *
    36     *         Stream Instance
    37     *
    38     *                 |
    39    
    40     *                 V
    41     *
    42     *         IConverter Instance (/scale)
    43     *
    44     *                 |
    45     *
    46     *                 V
    47     *
    48     *         IDriver Instance (/uart)
    49     *
    50     *  In this case the Stream requires "/scale" to be in its IConverter table 
    51     *  and "/uart" to be in {@link DriverTable}. The IConverter table associates
    52     *  a name with an IConverter Handle. Note that these names have to be of the
    53     *  form "/name1".
    54     *
    55     *  There may be several other IConverters such as a 
    56     *  {@link ti.sdo.io.converters.Transformer} instance in the stack.
    57     *
    58     *  IConverter implementation follows a simple asynchronous issue/reclaim
    59     *  model. Once an instance of an IConverter is created it accepts IO
    60     *  packets through the {@link #issue} function. Issue ALWAYS results in a 
    61     *  callback when IO completes or an error occurs.
    62     *
    63     *  The IConverter device above it in the stack or the {@link Stream} 
    64     *  module will call {@link #reclaim} to get the packet back.
    65     *
    66     *  {@link ti.sdo.io.DriverTypes#ControlCmd} are sent to the IConverters or the 
    67     *  underlying drivers using {@link #control} function.
    68     *
    69     *  Only  packets with {@link ti.sdo.io.DriverTypes#READ} and 
    70     *  {@link ti.sdo.io.DriverTypes#WRITE} are operated on by IConverter. Other 
    71     *  commands are passed down.
    72     */
    73    
    74     
    75    interface IConverter
    76    {
    77        /*!
    78         *  ======== Q_TERMINATING ========
    79         *  Terminating quality.
    80         *
    81         *  Implementations with this "quality" can be at the bottom of the IO
    82         *  stack
    83         */
    84        const Int Q_TERMINATING = 1;
    85        
    86        /*!
    87         *  Typedef for callback function.
    88         *
    89         *  The IConverter instance lower in the stack will invoke this callback 
    90         *  whenever an I/O operation completes.
    91         */
    92        typedef Void (*DoneFxn)(UArg);
    93    
    94    instance:
    95        
    96        /*! ======== open ========
    97         *  Opens the IConverter Instance.
    98         *
    99         *  This is called at runtime after the IConverter instance has been
   100         *  created. This function opens the IConverter instance lower in the
   101         *  stack and gives its callback function and arg.
   102         *
   103         *  @param(name)        remaining name
   104         *  @param(mode)        DriverTypes_INPUT/OUTPUT
   105         *  @param(chanParams)  channel params for driver at the bottom of stack
   106         *  @param(cbFxn)       callback function
   107         *  @param(cbArg)       callback function arg
   108         *  @param(eb)          error block
   109         */
   110        Void open(String name, UInt mode, UArg chanParams, 
   111            DoneFxn cbFxn, UArg cbArg, Error.Block *eb);
   112    
   113        /*! ======== close ========
   114         *  Close an IConverter Instance.
   115         *
   116         *  @param(eb)       error block
   117         */
   118        Void close( Error.Block *eb);
   119               
   120        /*! ======== issue ========
   121         *  Issue a packet for IO.
   122         *
   123         *  The IConverter might work on the buffer of data if the mode is
   124         *  {@link ti.sdo.io.DriverTypes#OUTPUT} and call the issue function for the
   125         *  IConverter lower in the stack. Some IConverters may be the last in
   126         *  the IO stack. issue() always results in a callback.
   127         *
   128         *  @param(packet)      IO packet
   129         *  @param(eb)          Error Block
   130         */
   131        Void issue(DriverTypes.Packet *packet, Error.Block *eb);
   132    
   133        /*! ======== reclaim ========
   134         *  Reclaim a previously issued packet.
   135         *
   136         *  The IConverter will call the reclaim function for the
   137         *  IConverter lower in the stack. It may work on the buffer of data 
   138         *  returned if the mode is {@link ti.sdo.io.DriverTypes#INPUT}.
   139         *
   140         *  @param(packetp)   pointer to returned packet
   141         *  @param(eb)        Error Block
   142         */
   143        Void reclaim(DriverTypes.Packet **packetp, Error.Block *eb);
   144    
   145        /*! ======== control ========
   146         *  Send a control command.
   147         *
   148         *  The IConverter will respond to command meant for it and pass down all
   149         *  others.
   150         *
   151         *  @param(cmd)    control cmd
   152         *  @param(cmdArg) control cmd arg
   153         *  @param(eb)     error block
   154         */
   155        Void control(DriverTypes.ControlCmd cmd, UArg cmdArg, Error.Block *eb);
   156        
   157        /*!
   158         * ======== query ========
   159         * Query for qualities supported.
   160         *
   161         *  @param(qual)    quality to be tested     
   162         */
   163        Bool query(Int qual);
   164    }