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