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