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     *  ======== IDriver.xdc ========
    12     *  Device Driver interface 
    13     *
    14     *! Revision History
    15     *! ================
    16     *! 28-Apr-2008 nitya   review update
    17     */
    18    
    19    import xdc.runtime.Error;
    20    
    21    /*!
    22     *  Interface for IO drivers.
    23     *
    24     *  An IO Driver manages a peripheral(s) that provide channels for input and
    25     *  output. All peripherals of the same type are ideally managed by a single 
    26     *  driver. For example all uarts on a platform are managed by a single uart 
    27     *  driver.
    28     *
    29     *  The user will call the driver specific create function to instantiate a
    30     *  driver (e.g. a uart instance). The driver specific create function will 
    31     *  take device specific parameters. The create function will also take a 
    32     *  device ID to allow the client to specify a particular device.
    33     *  This allows users to select devices to be managed by the driver. It also
    34     *  allows the driver to manage resources and mark devices in use.
    35     *  
    36     *  The user calls {@link #open} at runtime using the handle returned by create
    37     *  to open a channel for use. The user passes a name, mode, chanParams,
    38     *  callback function and callback arg and an {@link xdc.runtime.Error#Block}. 
    39     *  open() could fail (e.g. channel is in use). When successful, the driver 
    40     *  returns an opaque channel handle, usually a pointer to the channel object.
    41     *
    42     *  The user uses {@link #close} to close the channel. {@link #close} raises an 
    43     *  error in case of failure. e.g. Trying to close a channel not is use.
    44     *
    45     *  The user calls {@link #submit} with the channel handle and an 
    46     *  {@link ti.sdo.io.DriverTypes#Packet} to initiate IO. 
    47     *  It may be possible for the driver to complete the IO 
    48     *  without the use of an asynchronous interrupt. e.g enough room in peripheral
    49     *  buffer, polling mode used, etc. In such cases the driver will return
    50     *  {@link ti.sdo.io.DriverTypes#COMPLETED} status and there is no callback.
    51     * 
    52     *  {@link ti.sdo.io.DriverTypes#ERROR} is returned by submit() if there is an error.
    53     *
    54     *  When the driver requires an asynchronous event like an interrupt to 
    55     *  complete the IO submit() will return {@link ti.sdo.io.DriverTypes#PENDING} status. 
    56     *  In such cases the asynchronous event will result in a callback. In the 
    57     *  callback the user should check for errors in the IO packet. The error in
    58     *  the packet could be driver specific. In case of success the 
    59     *  {@link xdc.runtime.Error#Id} in the packet will be null.
    60     *  The driver needs to update the size field to reflect the actual size of IO. 
    61     *
    62     *  In all cases the driver is responsible for raising errors except in the
    63     *  case when submit returns {@link ti.sdo.io.DriverTypes#PENDING}. In this case the 
    64     *  driver fills the {@link xdc.runtime.Error#Id} in the IO Packet. 
    65     *
    66     *  The driver is expected to queue up IO packets for transfer if necessary and
    67     *  must not error when given more than one packet.
    68     *
    69     *  The driver is non-blocking. e.g cannot call APIs that block as it is 
    70     *  expected that the higher layer will wait for IO to be completed and take 
    71     *  action in case of timeout.
    72     *
    73     *  The user will use {@link #control} with channel handle, command and argument
    74     *  to change channel parameters (e.g baud rate of uart). An error status is
    75     *  returned in case of failure. The control commands are used to specify
    76     *  channel parameters. Drivers can define their own control commands. See
    77     *  {@link ti.sdo.io.DriverTypes}
    78     *
    79     *  The command and command argument within the IO packet is used to control 
    80     *  the IO operation. Drivers can also define their own packet commands.
    81     *  See {@link ti.sdo.io.DriverTypes}.
    82     *
    83     *  A control command {@link ti.sdo.io.DriverTypes#CHAN_ABORT} is used to 
    84     *  abort/discard all packets queued up for a channel. Note that when the driver
    85     *  receives the abort control cmd, it must abort ALL packets and call the 
    86     *  callback for very packet. If a packet is currently in progress, the driver
    87     *  must attempt to shut down dma etc and return the packet. Aborted packets
    88     *  need to be updated with error filed set to {@link ti.sdo.io.DriverTypes#E_Aborted}.
    89     * 
    90     */
    91    interface IDriver
    92    {
    93        
    94    instance:
    95        
    96        /*!
    97         *  ======== open ========
    98         *  Open a channel
    99         *
   100         *  Use this function to open a channel. The name parameter allows for
   101         *  driver specific configuration. e.g when a channel id is required. The
   102         *  name will be null for most drivers. The mode is either 
   103         *  {@link ti.sdo.io.DriverTypes#INPUT} or {@link ti.sdo.io.DriverTypes#OUTPUT}.
   104         *  chanParams are driver specific. When chanparams is null driver will use
   105         *  default params which were statically configured. The callback function
   106         *  and arg are used to indicate completion of IO after an async 
   107         *  {@link #submit} call. The driver will raise an error when open fails and
   108         *  the error block will contain a driver specific error or a generic error
   109         *  defined by {@link ti.sdo.io.DriverTypes}.
   110         *  open returns a driver specific opaque channel handle.
   111         *  Note that open() can be called at Startup time and the driver
   112         *  has to ensure that open() returns the channel pointer even though the
   113         *  driver startup has not been called. 
   114         *
   115         *  @param(name)            name string
   116         *  @param(mode)            open mode for channel
   117         *  @param(chanParams)      driver specific channel parameters
   118         *  @param(cbFxn)           callback function
   119         *  @param(cbArg)           callback function arg
   120         *  @param(eb)              error block
   121         *  @b(returns)             opaque channel handle
   122         */
   123        Ptr open(String name, UInt mode, UArg chanParams, DriverTypes.DoneFxn cbFxn,
   124             UArg cbArg, Error.Block *eb);
   125        
   126        /*!
   127         *  ======== close ========
   128         *  Close a channel. Raises an error upon failure. 
   129         *
   130         *  For example, trying to close a channel which is NOT in use could raise 
   131         *  an error. The error could be driver specific or generic errors defined
   132         *  by {@link ti.sdo.io.DriverTypes}
   133         *  
   134         *
   135         *  @param(chanHandle)      opaque channel handle
   136         *  @param(eb)              error block
   137         */
   138        Void close(Ptr chanHandle, Error.Block *eb);
   139    
   140        /*!
   141         *  ======== submit ========
   142         *  Submit io packet to a channel. This may result in a callback.  
   143         *
   144         *  The driver may be able to complete the IO immediately and will return
   145         *  {@link ti.sdo.io.DriverTypes#COMPLETED} status. If the driver requires an async
   146         *  callback then, it will return {@link ti.sdo.io.DriverTypes#PENDING}. When the
   147         *  driver raises an error, it will return {@link ti.sdo.io.DriverTypes#ERROR} and the
   148         *  caller need to check the error block.
   149         *  In case the return value is {@link ti.sdo.io.DriverTypes#PENDING}, the driver will
   150         *  call the function specified during {@link #open} with the IO packet.
   151         *
   152         *  @param(chanHandle)      opaque channel handle
   153         *  @param(packet)          io packet
   154         *  @param(eb)              error block
   155         *  @b(returns)             status (DriverTypes_COMPLETED/PENDING/ERROR)
   156         */
   157        UInt submit(Ptr chanHandle, DriverTypes.Packet *packet, Error.Block *eb);
   158        
   159        /*!
   160         *  ======== control ========
   161         *  Send driver specific command to channel or associated device.
   162         *
   163         *  @param(chanHandle)      opaque channel handle
   164         *  @param(cmd)             control command
   165         *  @param(cmdArgs)         command argument
   166         *  @param(eb)              error block
   167         */
   168        Void control(Ptr chanHandle, DriverTypes.ControlCmd cmd, UArg cmdArgs, Error.Block *eb);
   169    
   170    }
   171