1 | /* SPDX-License-Identifier: BSD-3-Clause */ |
2 | /* |
3 | usa67msg.h |
4 | |
5 | Copyright (c) 1998-2007 InnoSys Incorporated. All Rights Reserved |
6 | This file is available under a BSD-style copyright |
7 | |
8 | Keyspan USB Async Firmware to run on Anchor FX1 |
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-2007 InnoSys Incorporated. All Rights Reserved |
20 | |
21 | This file is available under a BSD-style copyright |
22 | |
23 | 2. Redistributions in binary form must reproduce the above copyright |
24 | notice, this list of conditions and the following disclaimer in the |
25 | documentation and/or other materials provided with the distribution. |
26 | |
27 | 3. The name of InnoSys Incorprated may not be used to endorse or promote |
28 | products derived from this software without specific prior written |
29 | permission. |
30 | |
31 | THIS SOFTWARE IS PROVIDED BY INNOSYS CORP. ``AS IS'' AND ANY EXPRESS OR |
32 | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
33 | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN |
34 | NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, |
35 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
36 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR |
37 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER |
38 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
39 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
40 | OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
41 | SUCH DAMAGE. |
42 | |
43 | Fourth revision: This message format supports the USA28XG |
44 | |
45 | Buffer formats for RX/TX data messages are not defined by |
46 | a structure, but are described here: |
47 | |
48 | USB OUT (host -> USAxx, transmit) messages contain a |
49 | REQUEST_ACK indicator (set to 0xff to request an ACK at the |
50 | completion of transmit; 0x00 otherwise), followed by data: |
51 | |
52 | RQSTACK DAT DAT DAT ... |
53 | |
54 | with a total data length of up to 63. |
55 | |
56 | USB IN (USAxx -> host, receive) messages begin with a status |
57 | byte in which the 0x80 bit is either: |
58 | |
59 | (a) 0x80 bit clear |
60 | indicates that the bytes following it are all data |
61 | bytes: |
62 | |
63 | STAT DATA DATA DATA DATA DATA ... |
64 | |
65 | for a total of up to 63 DATA bytes, |
66 | |
67 | or: |
68 | |
69 | (b) 0x80 bit set |
70 | indiates that the bytes following alternate data and |
71 | status bytes: |
72 | |
73 | STAT DATA STAT DATA STAT DATA STAT DATA ... |
74 | |
75 | for a total of up to 32 DATA bytes. |
76 | |
77 | The valid bits in the STAT bytes are: |
78 | |
79 | OVERRUN 0x02 |
80 | PARITY 0x04 |
81 | FRAMING 0x08 |
82 | BREAK 0x10 |
83 | |
84 | Notes: |
85 | |
86 | (1) The OVERRUN bit can appear in either (a) or (b) format |
87 | messages, but the but the PARITY/FRAMING/BREAK bits |
88 | only appear in (b) format messages. |
89 | (2) For the host to determine the exact point at which the |
90 | overrun occurred (to identify the point in the data |
91 | stream at which the data was lost), it needs to count |
92 | 128 characters, starting at the first character of the |
93 | message in which OVERRUN was reported; the lost character(s) |
94 | would have been received between the 128th and 129th |
95 | characters. |
96 | (3) An RX data message in which the first byte has 0x80 clear |
97 | serves as a "break off" indicator. |
98 | |
99 | revision history: |
100 | |
101 | 1999feb10 add reportHskiaChanges to allow us to ignore them |
102 | 1999feb10 add txAckThreshold for fast+loose throughput enhancement |
103 | 1999mar30 beef up support for RX error reporting |
104 | 1999apr14 add resetDataToggle to control message |
105 | 2000jan04 merge with usa17msg.h |
106 | 2000jun01 add extended BSD-style copyright text |
107 | 2001jul05 change message format to improve OVERRUN case |
108 | 2002jun05 update copyright date, improve comments |
109 | 2006feb06 modify for FX1 chip |
110 | |
111 | */ |
112 | |
113 | #ifndef __USA67MSG__ |
114 | #define __USA67MSG__ |
115 | |
116 | |
117 | // all things called "ControlMessage" are sent on the 'control' endpoint |
118 | |
119 | typedef struct keyspan_usa67_portControlMessage |
120 | { |
121 | u8 port; // 0 or 1 (selects port) |
122 | /* |
123 | there are three types of "commands" sent in the control message: |
124 | |
125 | 1. configuration changes which must be requested by setting |
126 | the corresponding "set" flag (and should only be requested |
127 | when necessary, to reduce overhead on the device): |
128 | */ |
129 | u8 setClocking, // host requests baud rate be set |
130 | baudLo, // host does baud divisor calculation |
131 | baudHi, // baudHi is only used for first port (gives lower rates) |
132 | externalClock_txClocking, |
133 | // 0=internal, other=external |
134 | |
135 | setLcr, // host requests lcr be set |
136 | lcr, // use PARITY, STOPBITS, DATABITS below |
137 | |
138 | setFlowControl, // host requests flow control be set |
139 | ctsFlowControl, // 1=use CTS flow control, 0=don't |
140 | xonFlowControl, // 1=use XON/XOFF flow control, 0=don't |
141 | xonChar, // specified in current character format |
142 | xoffChar, // specified in current character format |
143 | |
144 | setTxTriState_setRts, |
145 | // host requests TX tri-state be set |
146 | txTriState_rts, // 1=active (normal), 0=tristate (off) |
147 | |
148 | setHskoa_setDtr, |
149 | // host requests HSKOA output be set |
150 | hskoa_dtr, // 1=on, 0=off |
151 | |
152 | setPrescaler, // host requests prescalar be set (default: 13) |
153 | prescaler; // specified as N/8; values 8-ff are valid |
154 | // must be set any time internal baud rate is set; |
155 | // must not be set when external clocking is used |
156 | |
157 | /* |
158 | 3. configuration data which is simply used as is (no overhead, |
159 | but must be specified correctly in every host message). |
160 | */ |
161 | u8 forwardingLength, // forward when this number of chars available |
162 | reportHskiaChanges_dsrFlowControl, |
163 | // 1=normal; 0=ignore external clock |
164 | // 1=use DSR flow control, 0=don't |
165 | txAckThreshold, // 0=not allowed, 1=normal, 2-255 deliver ACK faster |
166 | loopbackMode; // 0=no loopback, 1=loopback enabled |
167 | |
168 | /* |
169 | 4. commands which are flags only; these are processed in order |
170 | (so that, e.g., if both _txOn and _txOff flags are set, the |
171 | port ends in a TX_OFF state); any non-zero value is respected |
172 | */ |
173 | u8 _txOn, // enable transmitting (and continue if there's data) |
174 | _txOff, // stop transmitting |
175 | txFlush, // toss outbound data |
176 | txBreak, // turn on break (cleared by _txOn) |
177 | rxOn, // turn on receiver |
178 | rxOff, // turn off receiver |
179 | rxFlush, // toss inbound data |
180 | rxForward, // forward all inbound data, NOW (as if fwdLen==1) |
181 | returnStatus, // return current status (even if it hasn't changed) |
182 | resetDataToggle;// reset data toggle state to DATA0 |
183 | |
184 | } keyspan_usa67_portControlMessage; |
185 | |
186 | // defines for bits in lcr |
187 | #define USA_DATABITS_5 0x00 |
188 | #define USA_DATABITS_6 0x01 |
189 | #define USA_DATABITS_7 0x02 |
190 | #define USA_DATABITS_8 0x03 |
191 | #define STOPBITS_5678_1 0x00 // 1 stop bit for all byte sizes |
192 | #define STOPBITS_5_1p5 0x04 // 1.5 stop bits for 5-bit byte |
193 | #define STOPBITS_678_2 0x04 // 2 stop bits for 6/7/8-bit byte |
194 | #define USA_PARITY_NONE 0x00 |
195 | #define USA_PARITY_ODD 0x08 |
196 | #define USA_PARITY_EVEN 0x18 |
197 | #define PARITY_1 0x28 |
198 | #define PARITY_0 0x38 |
199 | |
200 | // all things called "StatusMessage" are sent on the status endpoint |
201 | |
202 | typedef struct keyspan_usa67_portStatusMessage // one for each port |
203 | { |
204 | u8 port, // 0=first, 1=second, other=see below |
205 | hskia_cts, // reports HSKIA pin |
206 | gpia_dcd, // reports GPIA pin |
207 | _txOff, // port has been disabled (by host) |
208 | _txXoff, // port is in XOFF state (either host or RX XOFF) |
209 | txAck, // indicates a TX message acknowledgement |
210 | rxEnabled, // as configured by rxOn/rxOff 1=on, 0=off |
211 | controlResponse;// 1=a control message has been processed |
212 | } keyspan_usa67_portStatusMessage; |
213 | |
214 | // bits in RX data message when STAT byte is included |
215 | #define RXERROR_OVERRUN 0x02 |
216 | #define RXERROR_PARITY 0x04 |
217 | #define RXERROR_FRAMING 0x08 |
218 | #define RXERROR_BREAK 0x10 |
219 | |
220 | typedef struct keyspan_usa67_globalControlMessage |
221 | { |
222 | u8 port, // 3 |
223 | sendGlobalStatus, // 2=request for two status responses |
224 | resetStatusToggle, // 1=reset global status toggle |
225 | resetStatusCount; // a cycling value |
226 | } keyspan_usa67_globalControlMessage; |
227 | |
228 | typedef struct keyspan_usa67_globalStatusMessage |
229 | { |
230 | u8 port, // 3 |
231 | sendGlobalStatus, // from request, decremented |
232 | resetStatusCount; // as in request |
233 | } keyspan_usa67_globalStatusMessage; |
234 | |
235 | typedef struct keyspan_usa67_globalDebugMessage |
236 | { |
237 | u8 port, // 2 |
238 | a, |
239 | b, |
240 | c, |
241 | d; |
242 | } keyspan_usa67_globalDebugMessage; |
243 | |
244 | // ie: the maximum length of an FX1 endpoint buffer |
245 | #define MAX_DATA_LEN 64 |
246 | |
247 | // update status approx. 60 times a second (16.6666 ms) |
248 | #define STATUS_UPDATE_INTERVAL 16 |
249 | |
250 | // status rationing tuning value (each port gets checked each n ms) |
251 | #define STATUS_RATION 10 |
252 | |
253 | #endif |
254 | |
255 | |
256 | |