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