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 * ======== DriverTypes.xdc ========
34 *
35 *! Revision History
36 *! ================
37 *! 28-Apr-2008 nitya review update
38 */
39
40 import xdc.runtime.Error;
41 import xdc.runtime.Log;
42 import xdc.runtime.Diags;
43 import ti.sdo.utils.List;
44
45 /*!
46 * DriverTypes module
47 *
48 * This module defines several types required by modules implementing the
49 * IDriver interface.
50 *
51 * This modules defines two Encoded types PacketCmd and ControlCmd.
52 * The @Encoded keyword is used here to allow us to have different
53 * representations for PacketCmd and ControlCmd in the meta
54 * domain and in the target domain. Here these datatypes are Bits32 in
55 * the target domain. In the meta domain they are represented as
56 * structures whose contents decide the value in the target domain.
57 * The purpose is to assign unique values to all PacketCmds in the
58 * application. Similarly all config parameters of type ControlCmds
59 * get assigned unique values at configuration time.
60 * The encoding scheme used is (moduleId << 16) | unique number.
61 *
62 * Modules that implement IDriver can define their own ControlCmds and
63 * PacketCmds as follows
64 *
65 * readonly config ControlCmd MYCMD;
66 *
67 * readonly config PacketCmd MYPKTCMD;
68 *
69 * This module also defines the IO packet used to send buffers to a driver.
70 * Common cmds and errors useful to all IDriver modules are also defined here.
71 */
72
73 @CustomHeader
74
75 module DriverTypes {
76
77 /*! @_nodoc */
78 metaonlystruct PacketCmdDesc { Bits32 val; };
79 @Encoded typedef PacketCmdDesc PacketCmd; /*! Packet command type */
80
81 /*! @_nodoc */
82 metaonlystruct ControlCmdDesc { Bits32 val; };
83 @Encoded typedef ControlCmdDesc ControlCmd; /*! Control command type */
84
85
86 /*!
87 * IO packet
88 *
89 * Packets are the basis for all I/O operations. Packets are sent
90 * to the driver using {@link IDriver#submit} function.
91 *
92 * @field(link) field can be used by driver to queue up IO packets.
93 *
94 * @field(addr) field points to buffer of data.
95 * The driver preserves this field.
96 *
97 * @field(origSize) is the size of data buffer.
98 * The driver preserves this field.
99 *
100 * @field(size) is actual size of data written or read.
101 * Driver updates this field.
102 *
103 * @field(arg) is used by end application. The driver preserves
104 * this field.
105 *
106 * @field(cmd) is the Packet command. Driver preserves this field.
107 *
108 * @field(error) is filled in by the mini-driver and contains status
109 * of IO.
110 *
111 * @field(misc) is used by {@link Stream}. The driver preserves
112 * this field.
113 *
114 * @field(status) is reserved for use by iom adapters.
115 *
116 * @field(drvArg) is reserved for use by drivers. Only drivers can use
117 * this field.
118 *
119 */
120 struct Packet {
121 List.Elem link; /*! queue link */
122 Ptr addr; /*! buffer address */
123 SizeT origSize; /*! size requested */
124 SizeT size; /*! processed size */
125 UArg arg; /*! arg to be used by end app */
126 PacketCmd cmd; /*! command for mini-driver */
127 Error.Id error; /*! error id */
128 UArg misc; /*! reserved */
129 Int status; /*! reserved for legacy IOM support */
130 UArg drvArg; /*! reserved for use by driver */
131 };
132
133 /*!
134 * Typedef for driver's callback function.
135 *
136 * The driver will call a function of this type whenever an I/O
137 * operation completes after an async submit() call.
138 *
139 * The UArg is the callback function arg specified during
140 * {@link IDriver#open}.
141 * The Packet* points to packet used during {@link IDriver#submit} call.
142 */
143 typedef Void (*DoneFxn)(UArg, Packet *);
144
145 const UInt COMPLETED = 0x0; /*! completed status {@link IDriver#submit}*/
146 const UInt PENDING = 0x1; /*! async callback {@link IDriver#submit}*/
147 const UInt ERROR = 0x2; /*! error status {@link IDriver#submit}*/
148
149 enum IOMode {
150 INPUT, /*! open channel for input */
151 OUTPUT, /*! open channel for output */
152 INOUT /*! simultaneous input/output */
153 };
154
155 /*
156 * Common Command and Packet commands.
157 */
158
159 readonlyconfig PacketCmd READ; /*! READ IO operation */
160 readonlyconfig PacketCmd WRITE; /*! WRITE IO operation */
161
162 /*!
163 * Abort channel
164 *
165 * This is a control command that all drivers must attempt
166 * to support. This control command will abort ALL the packets
167 * queued up in the driver and return the packets by calling the
168 * {@link #DoneFxn} for each packet. Aborted packets are marked
169 * with {@link #E_Aborted}. This control command arg is an (UInt *).
170 * The driver returns number of packets aborted in the cmdArg.
171 */
172 readonlyconfig ControlCmd CHAN_ABORT;
173
174 readonlyconfig ControlCmd CHAN_RESET; /*! Reset channel */
175 readonlyconfig ControlCmd DEVICE_RESET; /*! Reset device */
176
177 /*
178 * Note that the errors below are very generic and it is preferable to
179 * avoid using these errors. The drivers should define their own errors.
180 */
181 config Error.Id EBADIO = {msg: "Generic Failure"};
182 config Error.Id EBADMODE = {msg: "Illegal Mode"};
183 config Error.Id ENOTIMPL = {msg: "Not implemented"};
184 config Error.Id EBADARGS = {msg: "Bad args"};
185 config Error.Id EINUSE = {msg: "Channel in use"};
186 config Error.Id EINVALIDDEV = {msg: "Invalid devNum"};
187
188 /*! used in {@link #Packet} when io completes without an error */
189 const UInt NOERROR = 0;
190 /*!
191 * Error within aborted packet
192 *
193 * This is a special error that all drivers will return in the IO packet
194 * in case {@link #ABORT} control cmd is received.
195 */
196 config Error.Id EABORTED = {msg: "Aborted Packet"};
197
198 /*! Logged just prior to submitting IO packet to driver */
199 config Log.Event LM_startIO = {
200 mask: Diags.USER1 | Diags.USER2,
201 msg: "LM_startIO: buf: 0x%x, size: 0x%x, arg: 0x%x"
202 };
203
204 /*! Logged when io is completed */
205 config Log.Event LM_ioComplete = {
206 mask: Diags.USER1 | Diags.USER2,
207 msg: "LM_ioComplete: buf: 0x%x, size: 0x%x, arg: 0x%x"
208 };
209 }