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