1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3	usa28msg.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 USA26X
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	Note: these message formats are common to USA18, USA19, and USA28;
40	(for USA28X, see usa26msg.h)
41
42	Buffer formats for RX/TX data messages are not defined by
43	a structure, but are described here:
44
45	USB OUT (host -> USA28, transmit) messages contain a
46	REQUEST_ACK indicator (set to 0xff to request an ACK at the
47	completion of transmit; 0x00 otherwise), followed by data.
48	If the port is configured for parity, the data will be an
49	alternating string of parity and data bytes, so the message
50	format will be:
51
52		RQSTACK PAR DAT PAR DAT ...
53
54	so the maximum length is 63 bytes (1 + 62, or 31 data bytes);
55	always an odd number for the total message length.
56
57	If there is no parity, the format is simply:
58
59		RQSTACK DAT DAT DAT ...
60
61	with a total data length of 63.
62
63	USB IN (USA28 -> host, receive) messages contain data and parity
64	if parity is configred, thusly:
65
66		DAT PAR DAT PAR DAT PAR ...
67
68	for a total of 32 data bytes;
69
70	If parity is not configured, the format is:
71
72		DAT DAT DAT ...
73
74	for a total of 64 data bytes.
75
76	In the TX messages (USB OUT), the 0x01 bit of the PARity byte is
77	the parity bit.  In the RX messages (USB IN), the PARity byte is
78	the content of the 8051's status register; the parity bit
79	(RX_PARITY_BIT) is the 0x04 bit.
80
81	revision history:
82
83	1999may06	add resetDataToggle to control message
84	2000mar21	add rs232invalid to status response message
85	2000apr04	add 230.4Kb definition to setBaudRate
86	2000apr13	add/remove loopbackMode switch
87	2000apr13	change definition of setBaudRate to cover 115.2Kb, too
88	2000jun01	add extended BSD-style copyright text
89*/
90
91#ifndef	__USA28MSG__
92#define	__USA28MSG__
93
94
95struct keyspan_usa28_portControlMessage
96{
97	/*
98		there are four types of "commands" sent in the control message:
99
100		1.	configuration changes which must be requested by setting
101			the corresponding "set" flag (and should only be requested
102			when necessary, to reduce overhead on the USA28):
103	*/
104	u8	setBaudRate,	// 0=don't set, 1=baudLo/Hi, 2=115.2K, 3=230.4K
105		baudLo,			// host does baud divisor calculation
106		baudHi;			// baudHi is only used for first port (gives lower rates)
107
108	/*
109		2.	configuration changes which are done every time (because it's
110			hardly more trouble to do them than to check whether to do them):
111	*/
112	u8	parity,			// 1=use parity, 0=don't
113		ctsFlowControl,	        // all except 19Q: 1=use CTS flow control, 0=don't
114					// 19Q: 0x08:CTSflowControl 0x10:DSRflowControl
115		xonFlowControl,	// 1=use XON/XOFF flow control, 0=don't
116		rts,			// 1=on, 0=off
117		dtr;			// 1=on, 0=off
118
119	/*
120		3.	configuration data which is simply used as is (no overhead,
121			but must be correct in every host message).
122	*/
123	u8	forwardingLength,  // forward when this number of chars available
124		forwardMs,		// forward this many ms after last rx data
125		breakThreshold,	// specified in ms, 1-255 (see note below)
126		xonChar,		// specified in current character format
127		xoffChar;		// specified in current character format
128
129	/*
130		4.	commands which are flags only; these are processed in order
131			(so that, e.g., if both _txOn and _txOff flags are set, the
132			port ends in a TX_OFF state); any non-zero value is respected
133	*/
134	u8	_txOn,			// enable transmitting (and continue if there's data)
135		_txOff,			// stop transmitting
136		txFlush,		// toss outbound data
137		txForceXoff,	// pretend we've received XOFF
138		txBreak,		// turn on break (leave on until txOn clears it)
139		rxOn,			// turn on receiver
140		rxOff,			// turn off receiver
141		rxFlush,		// toss inbound data
142		rxForward,		// forward all inbound data, NOW
143		returnStatus,	// return current status n times (1 or 2)
144		resetDataToggle;// reset data toggle state to DATA0
145
146};
147
148struct keyspan_usa28_portStatusMessage
149{
150	u8	port,			// 0=first, 1=second, 2=global (see below)
151		cts,
152		dsr,			// (not used in all products)
153		dcd,
154
155		ri,				// (not used in all products)
156		_txOff,			// port has been disabled (by host)
157		_txXoff,		// port is in XOFF state (either host or RX XOFF)
158		dataLost,		// count of lost chars; wraps; not guaranteed exact
159
160		rxEnabled,		// as configured by rxOn/rxOff 1=on, 0=off
161		rxBreak,		// 1=we're in break state
162		rs232invalid,	// 1=no valid signals on rs-232 inputs
163		controlResponse;// 1=a control messages has been processed
164};
165
166// bit defines in txState
167#define	TX_OFF			0x01	// requested by host txOff command
168#define	TX_XOFF			0x02	// either real, or simulated by host
169
170struct keyspan_usa28_globalControlMessage
171{
172	u8	sendGlobalStatus,	// 2=request for two status responses
173		resetStatusToggle,	// 1=reset global status toggle
174		resetStatusCount;	// a cycling value
175};
176
177struct keyspan_usa28_globalStatusMessage
178{
179	u8	port,				// 3
180		sendGlobalStatus,	// from request, decremented
181		resetStatusCount;	// as in request
182};
183
184struct keyspan_usa28_globalDebugMessage
185{
186	u8	port,				// 2
187		n,					// typically a count/status byte
188		b;					// typically a data byte
189};
190
191// ie: the maximum length of an EZUSB endpoint buffer
192#define	MAX_DATA_LEN			64
193
194// the parity bytes have only one significant bit
195#define	RX_PARITY_BIT			0x04
196#define	TX_PARITY_BIT			0x01
197
198// update status approx. 60 times a second (16.6666 ms)
199#define	STATUS_UPDATE_INTERVAL	16
200
201#endif
202
203