1 /* --COPYRIGHT--,BSD
2 * Copyright (c) $(CPYYEAR), Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * --/COPYRIGHT--*/
32 /*
33 * ======== IDriver.xdc ========
34 * Device Driver interface
35 *
36 *! Revision History
37 *! ================
38 *! 28-Apr-2008 nitya review update
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