1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 34 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 193 194
195