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     *  ======== DriverTypes.xdc ========
    34     *
    35     */
    36    
    37    import xdc.runtime.Error;
    38    import xdc.runtime.Log;
    39    import xdc.runtime.Diags;
    40    import ti.sdo.utils.List;
    41    
    42    /*! 
    43     *  DriverTypes module
    44     *
    45     *  This module defines several types required by modules implementing the
    46     *  IDriver interface.
    47     *
    48     *  This modules defines two Encoded types PacketCmd and ControlCmd.
    49     *  The @Encoded keyword is used here to allow us to have different
    50     *  representations for PacketCmd and ControlCmd in the meta
    51     *  domain and in the target domain. Here these datatypes are Bits32 in
    52     *  the target domain. In the meta domain they are represented as
    53     *  structures whose contents decide the value in the target domain.
    54     *  The purpose is to assign unique values to all PacketCmds in the
    55     *  application. Similarly all config parameters of type ControlCmds
    56     *  get assigned unique values at configuration time.
    57     *  The encoding scheme used is (moduleId << 16) | unique number.
    58     * 
    59     *  Modules that implement IDriver can define their own ControlCmds and
    60     *  PacketCmds as follows
    61     *
    62     *      readonly config ControlCmd MYCMD;
    63     *
    64     *      readonly config PacketCmd MYPKTCMD;
    65     *
    66     *  This module also defines the IO packet used to send buffers to a driver. 
    67     *  Common cmds and errors useful to all IDriver modules are also defined here.
    68     */
    69    
    70    @CustomHeader
    71    
    72    module DriverTypes {
    73    
    74        /*! @_nodoc */
    75        metaonly struct PacketCmdDesc { Bits32 val; };
    76        @Encoded typedef PacketCmdDesc PacketCmd;       /*! Packet command type */
    77    
    78        /*! @_nodoc */
    79        metaonly struct ControlCmdDesc { Bits32 val; };
    80        @Encoded typedef ControlCmdDesc ControlCmd;     /*! Control command type */
    81    
    82    
    83        /*!
    84         * IO packet 
    85         *
    86         * Packets are the basis for all I/O operations. Packets are sent
    87         * to the driver using {@link IDriver#submit} function.
    88         *
    89         * @field(link)     field can be used by driver to queue up IO packets.
    90         *
    91         * @field(addr)     field points to buffer of data. 
    92         *                  The driver preserves this field.
    93         *
    94         * @field(origSize) is the size of data buffer. 
    95         *                  The driver preserves this field.
    96         *
    97         * @field(size)     is actual size of data written or read. 
    98         *                  Driver updates this field.
    99         *
   100         * @field(arg)      is used by end application. The driver preserves 
   101         *                  this field.
   102         *
   103         * @field(cmd)      is the Packet command. Driver preserves this field.
   104         *
   105         * @field(error)    is filled in by the mini-driver and contains status 
   106         *                  of IO. 
   107         *
   108         * @field(misc)     is used by {@link Stream}. The driver preserves 
   109         *                  this field.
   110         *
   111         * @field(status)   is reserved for use by iom adapters.
   112         *
   113         * @field(drvArg)   is reserved for use by drivers. Only drivers can use
   114         *                  this field.
   115         *
   116         */
   117        struct Packet {     
   118            List.Elem       link;       /*! queue link */
   119            Ptr             addr;       /*! buffer address */
   120            SizeT           origSize;   /*! size requested */
   121            SizeT           size;       /*! processed size */
   122            UArg            arg;        /*! arg to be used by end app */
   123            PacketCmd       cmd;        /*! command for mini-driver */
   124            Error.Id        error;      /*! error id */
   125            UArg            misc;       /*! reserved */
   126            Int             status;     /*! reserved for legacy IOM support */    
   127            UArg            drvArg;     /*! reserved for use by driver */
   128        };
   129    
   130        /*!
   131         *  Typedef for driver's callback function.
   132         *
   133         *  The driver will call a function of this type whenever an I/O
   134         *  operation completes after an async submit() call.
   135         *
   136         *  The UArg is the callback function arg specified during 
   137         *  {@link IDriver#open}.
   138         *  The Packet* points to packet used during {@link IDriver#submit} call.
   139         */
   140        typedef Void (*DoneFxn)(UArg, Packet *);
   141     
   142        const UInt COMPLETED = 0x0;    /*! completed status {@link IDriver#submit}*/
   143        const UInt PENDING   = 0x1;    /*! async callback {@link IDriver#submit}*/
   144        const UInt ERROR     = 0x2;    /*! error status {@link IDriver#submit}*/
   145          
   146        enum IOMode {
   147            INPUT,          /*! open channel for input */
   148            OUTPUT,         /*! open channel for output */
   149            INOUT           /*! simultaneous input/output */
   150        };
   151    
   152        /*
   153         *  Common Command and Packet commands.
   154         */
   155    
   156        readonly config PacketCmd READ;     /*! READ IO operation */
   157        readonly config PacketCmd WRITE;    /*! WRITE IO operation */
   158    
   159         /*! 
   160          *  Abort channel 
   161          *
   162          *  This is a control command that all drivers must attempt
   163          *  to support. This control command will abort ALL the packets
   164          *  queued up in the driver and return the packets by calling the
   165          *  {@link #DoneFxn} for each packet. Aborted packets are marked
   166          *  with {@link #E_Aborted}. This control command arg is an (UInt *).
   167          *  The driver returns number of packets aborted in the cmdArg.
   168          */
   169         readonly config ControlCmd CHAN_ABORT;
   170    
   171         readonly config ControlCmd CHAN_RESET;     /*! Reset channel */
   172         readonly config ControlCmd DEVICE_RESET;   /*! Reset device */ 
   173    
   174         /*
   175          *  Note that the errors below are very generic and it is preferable to
   176          *  avoid using these errors. The drivers should define their own errors.
   177          */
   178         config Error.Id EBADIO = {msg: "Generic Failure"};
   179         config Error.Id EBADMODE = {msg: "Illegal Mode"};
   180         config Error.Id ENOTIMPL = {msg: "Not implemented"};
   181         config Error.Id EBADARGS = {msg: "Bad args"};
   182         config Error.Id EINUSE = {msg: "Channel in use"};
   183         config Error.Id EINVALIDDEV = {msg: "Invalid devNum"};
   184         
   185         /*! used in {@link #Packet} when io completes without an error */
   186         const  UInt NOERROR = 0;          
   187         /*! 
   188          *  Error within aborted packet  
   189          *
   190          *  This is a special error that all drivers will return in the IO packet
   191          *  in case {@link #ABORT} control cmd is received.
   192          */
   193         config Error.Id EABORTED = {msg: "Aborted Packet"};
   194         
   195        /*! Logged just prior to submitting IO packet to driver */
   196        config Log.Event LM_startIO = {
   197            mask: Diags.USER1 | Diags.USER2,
   198            msg: "LM_startIO: buf: 0x%x, size: 0x%x, arg: 0x%x"
   199        };
   200        
   201        /*! Logged when io is completed */
   202        config Log.Event LM_ioComplete = {
   203            mask: Diags.USER1 | Diags.USER2,
   204            msg: "LM_ioComplete: buf: 0x%x, size: 0x%x, arg: 0x%x"
   205        };
   206    }
   207    /*
   208     *  @(#) ti.sdo.io; 1, 0, 0, 0,348; 8-10-2010 17:48:24; /db/vtree/library/trees/ipc/ipc-e23x/src/
   209     */
   210