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