1 | /* SPDX-License-Identifier: BSD-3-Clause */ |
2 | /* |
3 | usa26msg.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 USA28X |
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 | Third revision: USA28X version (aka USA26) |
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 | indicates 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 | |
95 | revision history: |
96 | |
97 | 1999feb10 add reportHskiaChanges to allow us to ignore them |
98 | 1999feb10 add txAckThreshold for fast+loose throughput enhancement |
99 | 1999mar30 beef up support for RX error reporting |
100 | 1999apr14 add resetDataToggle to control message |
101 | 2000jan04 merge with usa17msg.h |
102 | 2000jun01 add extended BSD-style copyright text |
103 | 2001jul05 change message format to improve OVERRUN case |
104 | |
105 | Note on shared names: |
106 | |
107 | In the case of fields which have been merged between the USA17 |
108 | and USA26 definitions, the USA26 definition is the first part |
109 | of the name and the USA17 definition is the second part of the |
110 | name; both meanings are described below. |
111 | */ |
112 | |
113 | #ifndef __USA26MSG__ |
114 | #define __USA26MSG__ |
115 | |
116 | |
117 | struct keyspan_usa26_portControlMessage |
118 | { |
119 | /* |
120 | there are three types of "commands" sent in the control message: |
121 | |
122 | 1. configuration changes which must be requested by setting |
123 | the corresponding "set" flag (and should only be requested |
124 | when necessary, to reduce overhead on the USA26): |
125 | */ |
126 | u8 setClocking, // BOTH: host requests baud rate be set |
127 | baudLo, // BOTH: host does baud divisor calculation |
128 | baudHi, // BOTH: baudHi is only used for first port (gives lower rates) |
129 | externalClock_txClocking, |
130 | // USA26: 0=internal, other=external |
131 | // USA17: 0=internal, other=external/RI |
132 | rxClocking, // USA17: 0=internal, 1=external/RI, other=external/DSR |
133 | |
134 | |
135 | setLcr, // BOTH: host requests lcr be set |
136 | lcr, // BOTH: use PARITY, STOPBITS, DATABITS below |
137 | |
138 | setFlowControl, // BOTH: host requests flow control be set |
139 | ctsFlowControl, // BOTH: 1=use CTS flow control, 0=don't |
140 | xonFlowControl, // BOTH: 1=use XON/XOFF flow control, 0=don't |
141 | xonChar, // BOTH: specified in current character format |
142 | xoffChar, // BOTH: specified in current character format |
143 | |
144 | setTxTriState_setRts, |
145 | // USA26: host requests TX tri-state be set |
146 | // USA17: host requests RTS output be set |
147 | txTriState_rts, // BOTH: 1=active (normal), 0=tristate (off) |
148 | |
149 | setHskoa_setDtr, |
150 | // USA26: host requests HSKOA output be set |
151 | // USA17: host requests DTR output be set |
152 | hskoa_dtr, // BOTH: 1=on, 0=off |
153 | |
154 | setPrescaler, // USA26: host requests prescalar be set (default: 13) |
155 | prescaler; // BOTH: specified as N/8; values 8-ff are valid |
156 | // must be set any time internal baud rate is set; |
157 | // must not be set when external clocking is used |
158 | // note: in USA17, prescaler is applied whenever |
159 | // setClocking is requested |
160 | |
161 | /* |
162 | 3. configuration data which is simply used as is (no overhead, |
163 | but must be specified correctly in every host message). |
164 | */ |
165 | u8 forwardingLength, // BOTH: forward when this number of chars available |
166 | reportHskiaChanges_dsrFlowControl, |
167 | // USA26: 1=normal; 0=ignore external clock |
168 | // USA17: 1=use DSR flow control, 0=don't |
169 | txAckThreshold, // BOTH: 0=not allowed, 1=normal, 2-255 deliver ACK faster |
170 | loopbackMode; // BOTH: 0=no loopback, 1=loopback enabled |
171 | |
172 | /* |
173 | 4. commands which are flags only; these are processed in order |
174 | (so that, e.g., if both _txOn and _txOff flags are set, the |
175 | port ends in a TX_OFF state); any non-zero value is respected |
176 | */ |
177 | u8 _txOn, // BOTH: enable transmitting (and continue if there's data) |
178 | _txOff, // BOTH: stop transmitting |
179 | txFlush, // BOTH: toss outbound data |
180 | txBreak, // BOTH: turn on break (cleared by _txOn) |
181 | rxOn, // BOTH: turn on receiver |
182 | rxOff, // BOTH: turn off receiver |
183 | rxFlush, // BOTH: toss inbound data |
184 | rxForward, // BOTH: forward all inbound data, NOW (as if fwdLen==1) |
185 | returnStatus, // BOTH: return current status (even if it hasn't changed) |
186 | resetDataToggle;// BOTH: reset data toggle state to DATA0 |
187 | |
188 | }; |
189 | |
190 | // defines for bits in lcr |
191 | #define USA_DATABITS_5 0x00 |
192 | #define USA_DATABITS_6 0x01 |
193 | #define USA_DATABITS_7 0x02 |
194 | #define USA_DATABITS_8 0x03 |
195 | #define STOPBITS_5678_1 0x00 // 1 stop bit for all byte sizes |
196 | #define STOPBITS_5_1p5 0x04 // 1.5 stop bits for 5-bit byte |
197 | #define STOPBITS_678_2 0x04 // 2 stop bits for 6/7/8-bit byte |
198 | #define USA_PARITY_NONE 0x00 |
199 | #define USA_PARITY_ODD 0x08 |
200 | #define USA_PARITY_EVEN 0x18 |
201 | #define PARITY_1 0x28 |
202 | #define PARITY_0 0x38 |
203 | |
204 | // all things called "StatusMessage" are sent on the status endpoint |
205 | |
206 | struct keyspan_usa26_portStatusMessage // one for each port |
207 | { |
208 | u8 port, // BOTH: 0=first, 1=second, other=see below |
209 | hskia_cts, // USA26: reports HSKIA pin |
210 | // USA17: reports CTS pin |
211 | gpia_dcd, // USA26: reports GPIA pin |
212 | // USA17: reports DCD pin |
213 | dsr, // USA17: reports DSR pin |
214 | ri, // USA17: reports RI pin |
215 | _txOff, // port has been disabled (by host) |
216 | _txXoff, // port is in XOFF state (either host or RX XOFF) |
217 | rxEnabled, // as configured by rxOn/rxOff 1=on, 0=off |
218 | controlResponse;// 1=a control message has been processed |
219 | }; |
220 | |
221 | // bits in RX data message when STAT byte is included |
222 | #define RXERROR_OVERRUN 0x02 |
223 | #define RXERROR_PARITY 0x04 |
224 | #define RXERROR_FRAMING 0x08 |
225 | #define RXERROR_BREAK 0x10 |
226 | |
227 | struct keyspan_usa26_globalControlMessage |
228 | { |
229 | u8 sendGlobalStatus, // 2=request for two status responses |
230 | resetStatusToggle, // 1=reset global status toggle |
231 | resetStatusCount; // a cycling value |
232 | }; |
233 | |
234 | struct keyspan_usa26_globalStatusMessage |
235 | { |
236 | u8 port, // 3 |
237 | sendGlobalStatus, // from request, decremented |
238 | resetStatusCount; // as in request |
239 | }; |
240 | |
241 | struct keyspan_usa26_globalDebugMessage |
242 | { |
243 | u8 port, // 2 |
244 | a, |
245 | b, |
246 | c, |
247 | d; |
248 | }; |
249 | |
250 | // ie: the maximum length of an EZUSB endpoint buffer |
251 | #define MAX_DATA_LEN 64 |
252 | |
253 | // update status approx. 60 times a second (16.6666 ms) |
254 | #define STATUS_UPDATE_INTERVAL 16 |
255 | |
256 | // status rationing tuning value (each port gets checked each n ms) |
257 | #define STATUS_RATION 10 |
258 | |
259 | #endif |
260 | |
261 | |
262 | |