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