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