drivers/usb/serial/keyspan_usa49msg.h

   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