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