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