drivers/usb/serial/keyspan_usa49msg.h

   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