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