1 | /* SPDX-License-Identifier: BSD-3-Clause */ |
2 | /* |
3 | usa49msg.h |
4 | |
5 | Copyright (C) 1998-2000 InnoSys Incorporated. All Rights Reserved |
6 | This file is available under a BSD-style copyright |
7 | |
8 | Keyspan USB Async Message Formats for the USA49W |
9 | |
10 | Redistribution and use in source and binary forms, with or without |
11 | modification, are permitted provided that the following conditions are |
12 | met: |
13 | |
14 | 1. Redistributions of source code must retain this licence text |
15 | without modification, this list of conditions, and the following |
16 | disclaimer. The following copyright notice must appear immediately at |
17 | the beginning of all source files: |
18 | |
19 | Copyright (C) 1998-2000 InnoSys Incorporated. All Rights Reserved |
20 | |
21 | This file is available under a BSD-style copyright |
22 | |
23 | 2. The name of InnoSys Incorporated may not be used to endorse or promote |
24 | products derived from this software without specific prior written |
25 | permission. |
26 | |
27 | THIS SOFTWARE IS PROVIDED BY INNOSYS CORP. ``AS IS'' AND ANY EXPRESS OR |
28 | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
29 | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN |
30 | NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, |
31 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
32 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR |
33 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER |
34 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
35 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
36 | OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
37 | SUCH DAMAGE. |
38 | |
39 | 4th revision: USA49W version |
40 | |
41 | Buffer formats for RX/TX data messages are not defined by |
42 | a structure, but are described here: |
43 | |
44 | USB OUT (host -> USAxx, transmit) messages contain a |
45 | REQUEST_ACK indicator (set to 0xff to request an ACK at the |
46 | completion of transmit; 0x00 otherwise), followed by data: |
47 | |
48 | RQSTACK DAT DAT DAT ... |
49 | |
50 | with a total data length of 63. |
51 | |
52 | USB IN (USAxx -> host, receive) messages begin with a status |
53 | byte in which the 0x80 bit is either: |
54 | |
55 | (a) 0x80 bit clear |
56 | indicates that the bytes following it are all data |
57 | bytes: |
58 | |
59 | STAT DATA DATA DATA DATA DATA ... |
60 | |
61 | for a total of up to 63 DATA bytes, |
62 | |
63 | or: |
64 | |
65 | (b) 0x80 bit set |
66 | indiates that the bytes following alternate data and |
67 | status bytes: |
68 | |
69 | STAT DATA STAT DATA STAT DATA STAT DATA ... |
70 | |
71 | for a total of up to 32 DATA bytes. |
72 | |
73 | The valid bits in the STAT bytes are: |
74 | |
75 | OVERRUN 0x02 |
76 | PARITY 0x04 |
77 | FRAMING 0x08 |
78 | BREAK 0x10 |
79 | |
80 | Notes: |
81 | |
82 | (1) The OVERRUN bit can appear in either (a) or (b) format |
83 | messages, but the but the PARITY/FRAMING/BREAK bits |
84 | only appear in (b) format messages. |
85 | (2) For the host to determine the exact point at which the |
86 | overrun occurred (to identify the point in the data |
87 | stream at which the data was lost), it needs to count |
88 | 128 characters, starting at the first character of the |
89 | message in which OVERRUN was reported; the lost character(s) |
90 | would have been received between the 128th and 129th |
91 | characters. |
92 | (3) An RX data message in which the first byte has 0x80 clear |
93 | serves as a "break off" indicator. |
94 | (4) a control message specifying disablePort will be answered |
95 | with a status message, but no further status will be sent |
96 | until a control messages with enablePort is sent |
97 | |
98 | revision history: |
99 | |
100 | 1999feb10 add reportHskiaChanges to allow us to ignore them |
101 | 1999feb10 add txAckThreshold for fast+loose throughput enhancement |
102 | 1999mar30 beef up support for RX error reporting |
103 | 1999apr14 add resetDataToggle to control message |
104 | 2000jan04 merge with usa17msg.h |
105 | 2000mar08 clone from usa26msg.h -> usa49msg.h |
106 | 2000mar09 change to support 4 ports |
107 | 2000may03 change external clocking to match USA-49W hardware |
108 | 2000jun01 add extended BSD-style copyright text |
109 | 2001jul05 change message format to improve OVERRUN case |
110 | */ |
111 | |
112 | #ifndef __USA49MSG__ |
113 | #define __USA49MSG__ |
114 | |
115 | |
116 | /* |
117 | Host->device messages sent on the global control endpoint: |
118 | |
119 | portNumber message |
120 | ---------- -------------------- |
121 | 0,1,2,3 portControlMessage |
122 | 0x80 globalControlMessage |
123 | */ |
124 | |
125 | struct keyspan_usa49_portControlMessage |
126 | { |
127 | /* |
128 | 0. 0/1/2/3 port control message follows |
129 | 0x80 set non-port control message follows |
130 | */ |
131 | u8 portNumber, |
132 | |
133 | /* |
134 | there are three types of "commands" sent in the control message: |
135 | |
136 | 1. configuration changes which must be requested by setting |
137 | the corresponding "set" flag (and should only be requested |
138 | when necessary, to reduce overhead on the USA26): |
139 | */ |
140 | setClocking, // host requests baud rate be set |
141 | baudLo, // host does baud divisor calculation |
142 | baudHi, // baudHi is only used for first port (gives lower rates) |
143 | prescaler, // specified as N/8; values 8-ff are valid |
144 | // must be set any time internal baud rate is set; |
145 | txClocking, // 0=internal, 1=external/DSR |
146 | rxClocking, // 0=internal, 1=external/DSR |
147 | |
148 | setLcr, // host requests lcr be set |
149 | lcr, // use PARITY, STOPBITS, DATABITS below |
150 | |
151 | setFlowControl, // host requests flow control be set |
152 | ctsFlowControl, // 1=use CTS flow control, 0=don't |
153 | xonFlowControl, // 1=use XON/XOFF flow control, 0=don't |
154 | xonChar, // specified in current character format |
155 | xoffChar, // specified in current character format |
156 | |
157 | setRts, // host requests RTS output be set |
158 | rts, // 1=active, 0=inactive |
159 | |
160 | setDtr, // host requests DTR output be set |
161 | dtr; // 1=on, 0=off |
162 | |
163 | |
164 | /* |
165 | 3. configuration data which is simply used as is (no overhead, |
166 | but must be specified correctly in every host message). |
167 | */ |
168 | u8 forwardingLength, // forward when this number of chars available |
169 | dsrFlowControl, // 1=use DSR flow control, 0=don't |
170 | txAckThreshold, // 0=not allowed, 1=normal, 2-255 deliver ACK faster |
171 | loopbackMode; // 0=no loopback, 1=loopback enabled |
172 | |
173 | /* |
174 | 4. commands which are flags only; these are processed in order |
175 | (so that, e.g., if both _txOn and _txOff flags are set, the |
176 | port ends in a TX_OFF state); any non-zero value is respected |
177 | */ |
178 | u8 _txOn, // enable transmitting (and continue if there's data) |
179 | _txOff, // stop transmitting |
180 | txFlush, // toss outbound data |
181 | txBreak, // turn on break (cleared by _txOn) |
182 | rxOn, // turn on receiver |
183 | rxOff, // turn off receiver |
184 | rxFlush, // toss inbound data |
185 | rxForward, // forward all inbound data, NOW (as if fwdLen==1) |
186 | returnStatus, // return current status (even if it hasn't changed) |
187 | resetDataToggle,// reset data toggle state to DATA0 |
188 | enablePort, // start servicing port (move data, check status) |
189 | disablePort; // stop servicing port (does implicit tx/rx flush/off) |
190 | |
191 | }; |
192 | |
193 | // defines for bits in lcr |
194 | #define USA_DATABITS_5 0x00 |
195 | #define USA_DATABITS_6 0x01 |
196 | #define USA_DATABITS_7 0x02 |
197 | #define USA_DATABITS_8 0x03 |
198 | #define STOPBITS_5678_1 0x00 // 1 stop bit for all byte sizes |
199 | #define STOPBITS_5_1p5 0x04 // 1.5 stop bits for 5-bit byte |
200 | #define STOPBITS_678_2 0x04 // 2 stop bits for 6/7/8-bit byte |
201 | #define USA_PARITY_NONE 0x00 |
202 | #define USA_PARITY_ODD 0x08 |
203 | #define USA_PARITY_EVEN 0x18 |
204 | #define PARITY_1 0x28 |
205 | #define PARITY_0 0x38 |
206 | |
207 | /* |
208 | during normal operation, status messages are returned |
209 | to the host whenever the board detects changes. In some |
210 | circumstances (e.g. Windows), status messages from the |
211 | device cause problems; to shut them off, the host issues |
212 | a control message with the disableStatusMessages flags |
213 | set (to any non-zero value). The device will respond to |
214 | this message, and then suppress further status messages; |
215 | it will resume sending status messages any time the host |
216 | sends any control message (either global or port-specific). |
217 | */ |
218 | |
219 | struct keyspan_usa49_globalControlMessage |
220 | { |
221 | u8 portNumber, // 0x80 |
222 | sendGlobalStatus, // 1/2=number of status responses requested |
223 | resetStatusToggle, // 1=reset global status toggle |
224 | resetStatusCount, // a cycling value |
225 | remoteWakeupEnable, // 0x10=P1, 0x20=P2, 0x40=P3, 0x80=P4 |
226 | disableStatusMessages; // 1=send no status until host talks |
227 | }; |
228 | |
229 | /* |
230 | Device->host messages send on the global status endpoint |
231 | |
232 | portNumber message |
233 | ---------- -------------------- |
234 | 0x00,0x01,0x02,0x03 portStatusMessage |
235 | 0x80 globalStatusMessage |
236 | 0x81 globalDebugMessage |
237 | */ |
238 | |
239 | struct keyspan_usa49_portStatusMessage // one for each port |
240 | { |
241 | u8 portNumber, // 0,1,2,3 |
242 | cts, // reports CTS pin |
243 | dcd, // reports DCD pin |
244 | dsr, // reports DSR pin |
245 | ri, // reports RI pin |
246 | _txOff, // transmit has been disabled (by host) |
247 | _txXoff, // transmit is in XOFF state (either host or RX XOFF) |
248 | rxEnabled, // as configured by rxOn/rxOff 1=on, 0=off |
249 | controlResponse,// 1=a control message has been processed |
250 | txAck, // ACK (data TX complete) |
251 | rs232valid; // RS-232 signal valid |
252 | }; |
253 | |
254 | // bits in RX data message when STAT byte is included |
255 | #define RXERROR_OVERRUN 0x02 |
256 | #define RXERROR_PARITY 0x04 |
257 | #define RXERROR_FRAMING 0x08 |
258 | #define RXERROR_BREAK 0x10 |
259 | |
260 | struct keyspan_usa49_globalStatusMessage |
261 | { |
262 | u8 portNumber, // 0x80=globalStatusMessage |
263 | sendGlobalStatus, // from request, decremented |
264 | resetStatusCount; // as in request |
265 | }; |
266 | |
267 | struct keyspan_usa49_globalDebugMessage |
268 | { |
269 | u8 portNumber, // 0x81=globalDebugMessage |
270 | n, // typically a count/status byte |
271 | b; // typically a data byte |
272 | }; |
273 | |
274 | // ie: the maximum length of an EZUSB endpoint buffer |
275 | #define MAX_DATA_LEN 64 |
276 | |
277 | // update status approx. 60 times a second (16.6666 ms) |
278 | #define STATUS_UPDATE_INTERVAL 16 |
279 | |
280 | // status rationing tuning value (each port gets checked each n ms) |
281 | #define STATUS_RATION 10 |
282 | |
283 | #endif |
284 | |