1 2 3 4 5 6 7 8 9
10 11 12 13 14 15 16 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