interface ti.sdo.io.IDriver |
|
|
|
Interface for IO drivers
An IO Driver manages a peripheral(s) that provide channels for input and
output. All peripherals of the same type are ideally managed by a single
driver. For example all uarts on a platform are managed by a single uart
driver.
[
more ... ]
interface IDriver { ...
instance: ...
interface IDriver {
module-wide config parameters
instance:
per-instance functions
}
DETAILS
An IO Driver manages a peripheral(s) that provide channels for input and
output. All peripherals of the same type are ideally managed by a single
driver. For example all uarts on a platform are managed by a single uart
driver.
The user will call the driver specific create function to instantiate a
driver (e.g. a uart instance). The driver specific create function will
take device specific parameters. The create function will also take a
device ID to allow the client to specify a particular device.
This allows users to select devices to be managed by the driver. It also
allows the driver to manage resources and mark devices in use.
The user calls
open at runtime using the handle returned by create
to open a channel for use. The user passes a name, mode, chanParams,
callback function and callback arg and an
xdc.runtime.Error.Block.
open() could fail (e.g. channel is in use). When successful, the driver
returns an opaque channel handle, usually a pointer to the channel object.
The user uses
close to close the channel.
close raises an
error in case of failure. e.g. Trying to close a channel not is use.
The user calls
submit with the channel handle and an
ti.sdo.io.DriverTypes.Packet to initiate IO.
It may be possible for the driver to complete the IO
without the use of an asynchronous interrupt. e.g enough room in peripheral
buffer, polling mode used, etc. In such cases the driver will return
ti.sdo.io.DriverTypes.COMPLETED status and there is no callback.
ti.sdo.io.DriverTypes.ERROR is returned by submit() if there is an error.
When the driver requires an asynchronous event like an interrupt to
complete the IO submit() will return
ti.sdo.io.DriverTypes.PENDING status.
In such cases the asynchronous event will result in a callback. In the
callback the user should check for errors in the IO packet. The error in
the packet could be driver specific. In case of success the
xdc.runtime.Error.Id in the packet will be null.
The driver needs to update the size field to reflect the actual size of IO.
In all cases the driver is responsible for raising errors except in the
case when submit returns
ti.sdo.io.DriverTypes.PENDING. In this case the
driver fills the
xdc.runtime.Error.Id in the IO Packet.
The driver is expected to queue up IO packets for transfer if necessary and
must not error when given more than one packet.
The driver is non-blocking. e.g cannot call APIs that block as it is
expected that the higher layer will wait for IO to be completed and take
action in case of timeout.
The user will use
control with channel handle, command and argument
to change channel parameters (e.g baud rate of uart). An error status is
returned in case of failure. The control commands are used to specify
channel parameters. Drivers can define their own control commands. See
ti.sdo.io.DriverTypes
The command and command argument within the IO packet is used to control
the IO operation. Drivers can also define their own packet commands.
See
ti.sdo.io.DriverTypes.
A control command
ti.sdo.io.DriverTypes.CHAN_ABORT is used to
abort/discard all packets queued up for a channel. Note that when the driver
receives the abort control cmd, it must abort ALL packets and call the
callback for very packet. If a packet is currently in progress, the driver
must attempt to shut down dma etc and return the packet. Aborted packets
need to be updated with error filed set to
ti.sdo.io.DriverTypes.E_Aborted.
metaonly config IDriver.common$ // module-wide |
|
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
IDriver.close() // instance |
|
Close a channel. Raises an error upon failure
ARGUMENTS
chanHandle
opaque channel handle
eb
error block
DETAILS
For example, trying to close a channel which is NOT in use could raise
an error. The error could be driver specific or generic errors defined
by
ti.sdo.io.DriverTypes
IDriver.control() // instance |
|
Send driver specific command to channel or associated device
ARGUMENTS
chanHandle
opaque channel handle
cmd
control command
cmdArgs
command argument
eb
error block
IDriver.open() // instance |
|
Open a channel
ARGUMENTS
name
name string
mode
open mode for channel
chanParams
driver specific channel parameters
cbFxn
callback function
cbArg
callback function arg
eb
error block
RETURNS
opaque channel handle
DETAILS
Use this function to open a channel. The name parameter allows for
driver specific configuration. e.g when a channel id is required. The
name will be null for most drivers. The mode is either
ti.sdo.io.DriverTypes.INPUT or
ti.sdo.io.DriverTypes.OUTPUT.
chanParams are driver specific. When chanparams is null driver will use
default params which were statically configured. The callback function
and arg are used to indicate completion of IO after an async
submit call. The driver will raise an error when open fails and
the error block will contain a driver specific error or a generic error
defined by
ti.sdo.io.DriverTypes.
open returns a driver specific opaque channel handle.
Note that open() can be called at Startup time and the driver
has to ensure that open() returns the channel pointer even though the
driver startup has not been called.
IDriver.submit() // instance |
|
Submit io packet to a channel. This may result in a callback
ARGUMENTS
chanHandle
opaque channel handle
packet
io packet
eb
error block
RETURNS
status (DriverTypes_COMPLETED/PENDING/ERROR)
DETAILS
The driver may be able to complete the IO immediately and will return
ti.sdo.io.DriverTypes.COMPLETED status. If the driver requires an async
callback then, it will return
ti.sdo.io.DriverTypes.PENDING. When the
driver raises an error, it will return
ti.sdo.io.DriverTypes.ERROR and the
caller need to check the error block.
In case the return value is
ti.sdo.io.DriverTypes.PENDING, the driver will
call the function specified during
open with the IO packet.
generated on Wed, 23 Mar 2011 16:23:26 GMT