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