1 /* --COPYRIGHT--,BSD
2 * Copyright (c) $(CPYYEAR), Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * --/COPYRIGHT--*/
32 /*
33 * ======== IConverter.xdc ========
34 *
35 *! Revision History
36 *! ================
37 *! 28-Apr-2008 nitya review update
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 }