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