1    /* --COPYRIGHT--,BSD
     2     * Copyright (c) $(CPYYEAR), Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * --/COPYRIGHT--*/
    32    /*
    33     *  ======== IConverter.xdc ========
    34     *
    35     *! Revision History
    36     *! ================
    37     *! 28-Apr-2008 nitya   review update
    38     */
    39    
    40    import xdc.runtime.Error;
    41     
    42    /*!
    43     *  Interface defining an IConverter
    44     *
    45     *  This interfaces allows applications to "stack" functionality on top
    46     *  of a driver. Modules that implement this interface can manipulate data
    47     *  coming to and from a driver. Simple scaling, fixed to float or float to
    48     *  fixed transformations can be done using IConverters without major changes
    49     *  in the application.
    50     *
    51     *  IConverters can only be used along with the {@link Stream} module.
    52     *  
    53     *  Stream maintains a name table of {@link IConverter} handles. 
    54     *  This table is used by Stream to create an IO stack. The name passed to
    55     *  {@link Stream#create} is usually of the form "/scale/uart". This name may
    56     *  correspond to the following IO stack.
    57     *
    58     *         Stream Instance
    59     *
    60     *                 |
    61    
    62     *                 V
    63     *
    64     *         IConverter Instance (/scale)
    65     *
    66     *                 |
    67     *
    68     *                 V
    69     *
    70     *         IDriver Instance (/uart)
    71     *
    72     *  In this case the Stream requires "/scale" to be in its IConverter table 
    73     *  and "/uart" to be in {@link DriverTable}. The IConverter table associates
    74     *  a name with an IConverter Handle. Note that these names have to be of the
    75     *  form "/name1".
    76     *
    77     *  There may be several other IConverters such as a 
    78     *  {@link ti.sdo.io.converters.Transformer} instance in the stack.
    79     *
    80     *  IConverter implementation follows a simple asynchronous issue/reclaim
    81     *  model. Once an instance of an IConverter is created it accepts IO
    82     *  packets through the {@link #issue} function. Issue ALWAYS results in a 
    83     *  callback when IO completes or an error occurs.
    84     *
    85     *  The IConverter device above it in the stack or the {@link Stream} 
    86     *  module will call {@link #reclaim} to get the packet back.
    87     *
    88     *  {@link ti.sdo.io.DriverTypes#ControlCmd} are sent to the IConverters or the 
    89     *  underlying drivers using {@link #control} function.
    90     *
    91     *  Only  packets with {@link ti.sdo.io.DriverTypes#READ} and 
    92     *  {@link ti.sdo.io.DriverTypes#WRITE} are operated on by IConverter. Other 
    93     *  commands are passed down.
    94     */
    95    
    96     
    97    interface IConverter
    98    {
    99        /*!
   100         *  ======== Q_TERMINATING ========
   101         *  Terminating quality.
   102         *
   103         *  Implementations with this "quality" can be at the bottom of the IO
   104         *  stack
   105         */
   106        const Int Q_TERMINATING = 1;
   107        
   108        /*!
   109         *  Typedef for callback function.
   110         *
   111         *  The IConverter instance lower in the stack will invoke this callback 
   112         *  whenever an I/O operation completes.
   113         */
   114        typedef Void (*DoneFxn)(UArg);
   115    
   116    instance:
   117        
   118        /*! ======== open ========
   119         *  Opens the IConverter Instance.
   120         *
   121         *  This is called at runtime after the IConverter instance has been
   122         *  created. This function opens the IConverter instance lower in the
   123         *  stack and gives its callback function and arg.
   124         *
   125         *  @param(name)        remaining name
   126         *  @param(mode)        DriverTypes_INPUT/OUTPUT
   127         *  @param(chanParams)  channel params for driver at the bottom of stack
   128         *  @param(cbFxn)       callback function
   129         *  @param(cbArg)       callback function arg
   130         *  @param(eb)          error block
   131         */
   132        Void open(String name, UInt mode, UArg chanParams, 
   133            DoneFxn cbFxn, UArg cbArg, Error.Block *eb);
   134    
   135        /*! ======== close ========
   136         *  Close an IConverter Instance.
   137         *
   138         *  @param(eb)       error block
   139         */
   140        Void close( Error.Block *eb);
   141               
   142        /*! ======== issue ========
   143         *  Issue a packet for IO.
   144         *
   145         *  The IConverter might work on the buffer of data if the mode is
   146         *  {@link ti.sdo.io.DriverTypes#OUTPUT} and call the issue function for the
   147         *  IConverter lower in the stack. Some IConverters may be the last in
   148         *  the IO stack. issue() always results in a callback.
   149         *
   150         *  @param(packet)      IO packet
   151         *  @param(eb)          Error Block
   152         */
   153        Void issue(DriverTypes.Packet *packet, Error.Block *eb);
   154    
   155        /*! ======== reclaim ========
   156         *  Reclaim a previously issued packet.
   157         *
   158         *  The IConverter will call the reclaim function for the
   159         *  IConverter lower in the stack. It may work on the buffer of data 
   160         *  returned if the mode is {@link ti.sdo.io.DriverTypes#INPUT}.
   161         *
   162         *  @param(packetp)   pointer to returned packet
   163         *  @param(eb)        Error Block
   164         */
   165        Void reclaim(DriverTypes.Packet **packetp, Error.Block *eb);
   166    
   167        /*! ======== control ========
   168         *  Send a control command.
   169         *
   170         *  The IConverter will respond to command meant for it and pass down all
   171         *  others.
   172         *
   173         *  @param(cmd)    control cmd
   174         *  @param(cmdArg) control cmd arg
   175         *  @param(eb)     error block
   176         */
   177        Void control(DriverTypes.ControlCmd cmd, UArg cmdArg, Error.Block *eb);
   178        
   179        /*!
   180         * ======== query ========
   181         * Query for qualities supported.
   182         *
   183         *  @param(qual)    quality to be tested     
   184         */
   185        Bool query(Int qual);
   186    }