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 ... ]
XDCspec summary sourced in ti/sdo/io/IDriver.xdc
interface IDriver {  ...
// inherits xdc.runtime.IModule
instance:  ...
XDCspec declarations sourced in ti/sdo/io/IDriver.xdc
package ti.sdo.io;
 
interface IDriver {
module-wide config parameters
 
 
instance:
per-instance functions
    Ptr open// Open a channel(String name, UInt mode, UArg chanParams, DriverTypes.DoneFxn cbFxn, UArg cbArg, Error.Block *eb);
}
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

XDCspec declarations sourced in ti/sdo/io/IDriver.xdc
metaonly config Types.Common$ common$;
 
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

XDCspec declarations sourced in ti/sdo/io/IDriver.xdc
Void close(Ptr chanHandle, Error.Block *eb);
 
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

XDCspec declarations sourced in ti/sdo/io/IDriver.xdc
Void control(Ptr chanHandle, DriverTypes.ControlCmd cmd, UArg cmdArgs, Error.Block *eb);
 
ARGUMENTS
chanHandle — opaque channel handle
cmd — control command
cmdArgs — command argument
eb — error block
 
IDriver.open()  // instance

Open a channel

XDCspec declarations sourced in ti/sdo/io/IDriver.xdc
Ptr open(String name, UInt mode, UArg chanParams, DriverTypes.DoneFxn cbFxn, UArg cbArg, Error.Block *eb);
 
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

XDCspec declarations sourced in ti/sdo/io/IDriver.xdc
UInt submit(Ptr chanHandle, DriverTypes.Packet *packet, Error.Block *eb);
 
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 Sat, 11 Feb 2012 00:37:45 GMT