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