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
39 /*!
40 * Interface defining an IConverter
41 *
42 * This interfaces allows applications to "stack" functionality on top
43 * of a driver. Modules that implement this interface can manipulate data
44 * coming to and from a driver. Simple scaling, fixed to float or float to
45 * fixed transformations can be done using IConverters without major changes
46 * in the application.
47 *
48 * IConverters can only be used along with the {@link Stream} module.
49 *
50 * Stream maintains a name table of {@link IConverter} handles.
51 * This table is used by Stream to create an IO stack. The name passed to
52 * {@link Stream#create} is usually of the form "/scale/uart". This name may
53 * correspond to the following IO stack.
54 *
55 * Stream Instance
56 *
57 * |
58
59 * V
60 *
61 * IConverter Instance (/scale)
62 *
63 * |
64 *
65 * V
66 *
67 * IDriver Instance (/uart)
68 *
69 * In this case the Stream requires "/scale" to be in its IConverter table
70 * and "/uart" to be in {@link DriverTable}. The IConverter table associates
71 * a name with an IConverter Handle. Note that these names have to be of the
72 * form "/name1".
73 *
74 * There may be several other IConverters such as a
75 * {@link ti.sdo.io.converters.Transformer} instance in the stack.
76 *
77 * IConverter implementation follows a simple asynchronous issue/reclaim
78 * model. Once an instance of an IConverter is created it accepts IO
79 * packets through the {@link #issue} function. Issue ALWAYS results in a
80 * callback when IO completes or an error occurs.
81 *
82 * The IConverter device above it in the stack or the {@link Stream}
83 * module will call {@link #reclaim} to get the packet back.
84 *
85 * {@link ti.sdo.io.DriverTypes#ControlCmd} are sent to the IConverters or the
86 * underlying drivers using {@link #control} function.
87 *
88 * Only packets with {@link ti.sdo.io.DriverTypes#READ} and
89 * {@link ti.sdo.io.DriverTypes#WRITE} are operated on by IConverter. Other
90 * commands are passed down.
91 */
92
93
94 interface IConverter
95 {
96 /*!
97 * ======== Q_TERMINATING ========
98 * Terminating quality.
99 *
100 * Implementations with this "quality" can be at the bottom of the IO
101 * stack
102 */
103 const Int Q_TERMINATING = 1;
104
105 /*!
106 * Typedef for callback function.
107 *
108 * The IConverter instance lower in the stack will invoke this callback
109 * whenever an I/O operation completes.
110 */
111 typedef Void (*DoneFxn)(UArg);
112
113 instance:
114
115 /*! ======== open ========
116 * Opens the IConverter Instance.
117 *
118 * This is called at runtime after the IConverter instance has been
119 * created. This function opens the IConverter instance lower in the
120 * stack and gives its callback function and arg.
121 *
122 * @param(name) remaining name
123 * @param(mode) DriverTypes_INPUT/OUTPUT
124 * @param(chanParams) channel params for driver at the bottom of stack
125 * @param(cbFxn) callback function
126 * @param(cbArg) callback function arg
127 * @param(eb) error block
128 */
129 Void open(String name, UInt mode, UArg chanParams,
130 DoneFxn cbFxn, UArg cbArg, Error.Block *eb);
131
132 /*! ======== close ========
133 * Close an IConverter Instance.
134 *
135 * @param(eb) error block
136 */
137 Void close( Error.Block *eb);
138
139 /*! ======== issue ========
140 * Issue a packet for IO.
141 *
142 * The IConverter might work on the buffer of data if the mode is
143 * {@link ti.sdo.io.DriverTypes#OUTPUT} and call the issue function for the
144 * IConverter lower in the stack. Some IConverters may be the last in
145 * the IO stack. issue() always results in a callback.
146 *
147 * @param(packet) IO packet
148 * @param(eb) Error Block
149 */
150 Void issue(DriverTypes.Packet *packet, Error.Block *eb);
151
152 /*! ======== reclaim ========
153 * Reclaim a previously issued packet.
154 *
155 * The IConverter will call the reclaim function for the
156 * IConverter lower in the stack. It may work on the buffer of data
157 * returned if the mode is {@link ti.sdo.io.DriverTypes#INPUT}.
158 *
159 * @param(packetp) pointer to returned packet
160 * @param(eb) Error Block
161 */
162 Void reclaim(DriverTypes.Packet **packetp, Error.Block *eb);
163
164 /*! ======== control ========
165 * Send a control command.
166 *
167 * The IConverter will respond to command meant for it and pass down all
168 * others.
169 *
170 * @param(cmd) control cmd
171 * @param(cmdArg) control cmd arg
172 * @param(eb) error block
173 */
174 Void control(DriverTypes.ControlCmd cmd, UArg cmdArg, Error.Block *eb);
175
176 /*!
177 * ======== query ========
178 * Query for qualities supported.
179 *
180 * @param(qual) quality to be tested
181 */
182 Bool query(Int qual);
183 }
184 185 186
187