Merge branch 'upstream' of git://ftp.linux-mips.org/pub/scm/upstream-linus
[linux-2.6] / 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