Chrysler SCI (and generic UART) Gryphon driver information

Apologies for the crazy mix of HTML and preformated text in this page.

This page was deliberately written with a distinct bias towards users wishing to support Chrysler SCI protocols. It is however currently my best documentation available for generic UART applications, and maybe for quite sometime as I'm not likely to start maintaining two documents very soon. If you've no particular interest in Chrysler SCI protocols, please don't be put off by the constant references throughout.

Please read this background information, which explains issues such as 'message based SCI' verses 'byte based SCI', and 'generic UART driver' verses 'Chrysler SCI driver'.

Basic ioctls

#define GUARTGETBAUDBASE        0x11a00003      /* 4 */

Arguments:	4 bytes representing the baud base frequency as a
		32 bit unsigned integer.  For example, if the UART
		is running from a 18.432 MHz clock frequency, the
		16550 first divides this by 16 to produce a baud
		base frequency of 1,152,000 Hz.

#define GUARTGETDIV		0x11a00001	/* 4 */
#define GUARTSETDIV		0x11a00002	/* 4 vsoni */

Arguments:	4 bytes representing the divisor as a 32 bit unsigned
		integer.  The network baud rate corresponds to the
		baud base frequency (see above) divided by the divisor.
		GUARTSETDIV needs to be followed by a hard initialisation
		of the channel (i.e. with GINIT or CMD_INIT) for the
		change in bus speed to take affect.  16550 type devices
		support any divisor from 1 to 0xffff and thus the ioctl
		will fail if the value is greater than 0xffff (setting
		zero is currently permitted by the driver but not
		recommended by National Semiconductor and other UART
		manufacturers.  A zero divisor will also make the
		GGETBITRATE ioctl fail / return error.).  Future UART
		devices may support more or less values.

#define GUARTGETRXMODE		0x11a00009	/* 1 */
#define GUARTSETRXMODE		0x11a0000a	/* 1 vsoni */
#define GUARTGETTXMODE		0x11a0000b	/* 1 */
#define GUARTSETTXMODE		0x11a0000c	/* 1 vsoni */

Arguments:	1 byte which currently can be one of the following values:

#define		GUARTMODETIME		0x01

These ioctls get and set the drivers behavior such as the mode of message
delimitation mode.  If the 'TX mode' is set to GUARTMODECHRYSLERMSCI the
driver will automatically mark the beginning and end of the frame with
'0x7e' as required by message based Chrysler SCI protocol.  Also, should
'0x7e' occur in the message data given by the user, the driver automatically
translates this to '0x7d 0x5e' as required by the protocol.  Similarly
'0x7d' is automatically translated to '0x7d 0x5d'. 

If the 'RX mode' is set to GUARTMODECHRYSLERMSCI, the driver uses 0x7e
values to delimit received bytes into messages.  '0x7d 0x5e' is translated
back to '0x7e' and '0x7d 0x5d' is translated back into '0x7d'.

(Note: the message based Chrysler SCI spec forbids messages with protocol
IDs of 0x7d and 0x7e.  The driver does not enforce this restriction, and
shouldn't have any problem transmitting and receiving such messages should
the user deliberately wish to use gryphon to send these forbidden messages
for the purposes of testing or validation.)

By default, the 'hdrlen's of received messages are set to 1 and 'hdrbits'
set to 8, when the 'RX mode' is set to GUARTMODECHRYSLERMSCI.

GUARTMODETIME mode uses time alone to delimit received bytes into messages
and performs no translation on data between user and network.  Please see
the 'RXINTERMSG' ioctls below for further information.  Note that currently
the device transmits data as fast as possible and as soon as its given it,
although specific transmit byte timing could be achieved by using the
critical scheduler with a list of one network byte long gryphon messages.

By default, the 'hdrlen's and 'hdrbits's of received messages are set to
0 when the 'RX mode' is set GUARTMODETIME.

Channel needs to be hard initialised before GUARTSETRXMODE or GUARTSETTXMODE
take effect.

#define GUARTGETRXINTERMSG	0x11a00005	/* 4 */
#define GUARTSETRXINTERMSG	0x11a00006	/* 4 */

Arguments:	4 bytes representing the time the driver should use when
		delimiting messages in GUARTMODETIME 'RX mode'.  I.E.  If
		a byte occurs on the bus at a time greater than this value
		after the previous byte, it is considered the beginning of
		a new message.  The parameter is an unsigned 32 bit integer
		in units of 10 microseconds.  If the parameter is set to
		zero the driver will pass each received byte to the user in
		an individual gryphon data frame  (this may be appropriate
		for Chrysler byte based protocols, or for applications
		that require per byte timestamps).  Obviously this
		parameter affects message receive latency, as the driver
		has to hold onto message data at least until the time has

More ioctls, some of which might not be needed by most users

#define GUARTGETRXFIFOSIZE	0x11a0000d	/* 2 */
#define GUARTGETTXFIFOSIZE	0x11a0000f	/* 2 */

Arguments:	2 bytes representing the size of FIFOs on the UART as
		a 16 bit unsigned integer.  For the 16550 this parameter
		will have the value 16, but future devices (e.g. the
		16850) may have bigger FIFOs.

#define GUARTGETRXFIFOTRIG	0x11a00017	/* 2 */
#define GUARTSETRXFIFOTRIG	0x11a00018	/* 2 vsoni */

Arguments:	2 bytes representing the UART receive FIFO trigger
		level as a 16 bit unsigned integer.  Please see the
		appropriate UART chip datasheet for more information.
		Only values 1, 4, 8 and 14 are supported by 16550
		and thus the GUARTSETRXFIFOTRIG ioctl will currently
		fail if called with other values (the 16850 offers
		a wider choice).  Higher values may improve efficiency
		of the device drivers, but any value other than 1 will
		affect the accuracy of timestamps and possibly the
		operation of time based message delimitation.

#define GUARTGETRXFIFOSTATS24	0x11a00013	/* 112 */


offset          length          description
------          ------          -----------

0		4		number of FIFO timeouts (see UART
				semiconductor datasheet for definition
				of a FIFO timeout.)  As might be expected,
				the parameter set by GUARTSETRXFIFOTRIG
				will affect the number of FIFO timeouts.

4		12		reserved for possible future use

16		4		number of interrupt service routine calls
				where only 1 byte was obtained from UART
				receive FIFO.

20		4		number of interrupt service routine calls
				where exactly 2 bytes were obtained from
				UART receive FIFO.

24		4		number of interrupt service routine calls
				where exactly 3 bytes were obtained from
				UART receive FIFO.

28		4		number of interrupt service routine calls
				where exactly 4 bytes were obtained from
				UART receive FIFO.

and so on...........

104		4		number of interrupt service routine calls
				where exactly 23 bytes were obtained from
				UART receive FIFO.

108		4		number of interrupt service routine calls
				where 24 bytes or more were obtained from
				UART receive FIFO.

(all numbers are in the form of 32 bit unsigned integers)

This ioctl is mainly for developmental purposes to indicate how
comfortably the Gryphon SCI/UART driver is coping with UART bus
traffic at very high baud-rates, or perhaps even to indicate how
demanding a particular protocol is at a particular bitrate /
busload etc by assuming the gryphon device to be a yardstick.

Actual size of the UART's FIFO should be borne in mind, if the
counter for 'the number of times 16 bytes were retrieved at once
from the FIFO' is incrementing and the UART device only has 16 bytes
of FIFO, its reasonable to suspect that bytes are getting lost
(see also the GUARTRXOVER event).  Just because the size of the
array in this ioctl is 24, doesn't mean the hardware actually has
a 24 byte receive FIFO.

(note: these counters in the driver may wrap back round to zero,
but bear in mind that at one increment per network byte on a
100 Kbaud bus, it would still take over 4 days of continuous traffic
for a counter to wrap.).

#define GUARTRESETRXFIFOSTATS	0x11a00012	/* 0 */

No arguments.   Resets all the FIFO statistics to zero (e.g. everything

#define GUARTGETMCR		0x11a00007	/* 1 */
#define GUARTSETMCR		0x11a00008	/* 1 */

Arguments:	one byte.  These set and get the 16550s modem control
		register.  The modem control register controls a selection
		of general purpose output ports on the 16550, please see
		the exact semiconductor datasheet of the exact UART you are
		using for more information if for some reason you wish to
		know more (also see the warnings in the gryphon UART device
		include file).  These two ioctls are of no use to the user
		on the current DCX card and should not be used.

Currently supported generic ioctls

In addition the following GET/SET counter ioctls are also supported:


#define GUARTRXOVER	0x41

	Receive buffer overrun (driver didn't manage to service interrupt
	requests quick enough).  No event data.

#define GUARTPARITY	0x42

	Parity error (for protocols that don't use parity bits you shouldn't
	see this event).  No event data.

#define GUARTFRAME	0x43

	Frame error (i.e. valid logic 1 stop bit wasn't seen).  No event

#define GUARTBREAK	0x44

	Break seen on the bus.  According to the 16550 datasheet, a
	break is a logic 0 on the bus for longer than a full word
	transmission time (e.g. 10 bit times in the case of 1 start,
	8 data and 1 stop bits).  Note that the UART may also receive
	a data byte of value zero in this case.  No event data.

#define GUARTGTIME	0x50

	Error with gryphon's time (e.g. time went backwards).
	You shouldn't normally see this event, but for example one
	cause might be the user setting the clock on gryphon at an
	inopportune moment whilst the UART driver is receiving a
	message in time based message delimitation mode.
	8 bytes of event data, the first 4 bytes is the time 'now',
	next/last 4 bytes is the time recorded when the last byte
	was received (both 32 bit unsigned integers in units of 10

#define GSCIESCERR	0x71

	Invalid message based SCI escape sequence seen on bus
	if something other than 0x5d or 0x5e is seen on the
	bus after a 0x7d byte has been received.  1 byte of
	event data: the byte received after the 0x7d.

Stat field

#define GUARTSTAT_ERROR	0x01

	An error occurred whilst receiving this message.  A bit of a
	warning that message data may be suspect.  Commonly this
	might indicate a message has been split into two by one of
	the errors listed under 'error events' occurring in the
	middle of the message.  Note this feature was primarily
	intended to give extra information, this stat field bit not
	being set shouldn't be treated as a guarantee that everything
	is ok, and error events should still be used to indicate
	something went wrong and imply the preceding and following
	messages may possibly be suspect (not to mention any checksums,
	CRC checks, or implied length information there may be in the
	protocol being received).

Gryphon data frame format


hdrlen, datalen, extralen can be anything you like as long as they total more than zero and less than or equal to MAXUARTMSG (currently == 64). Bytes are transmitted on the bus as soon as possible. Bytes in one message should be transmitted altogether with no interbyte time between them (subject to performance).

If interbyte timing is desired, use of the critical scheduler is suggested (o.k. slow and ugly, but it should work for basic applications such as ISO 9141 protocols where byte timings are normally expressed in milliseconds rather than in bit-times). Note that the critical scheduler should queue jump on a per gryphon message basis, not a per byte basis, so placing a sequence of bytes in a single message instead of a sequence of several messages is a way to ensure they don't get split up by a critical transmit.

(Slightly obscure issue you probably don't need to worry about, but I'll mention it just in case: It is expected timing values used in the critical scheduler should either be zero, or at least a bit bigger than a character time. Otherwise, if you use the critical scheduler to give the 16550 characters one at a time just a little bit slower than it can transmit them, you may run into a feature of the chip that deliberately tries to make the host computer (in this case gryphon) make proper use of the transmit FIFO and byte timings may not be as regular as you had expected. This is more an issue that might be noticed at slow baud rates where character times could be as much as several milliseconds. At normal baud rates such as 9600 baud, interrupt latency means timings wont always be reliably accurate to the sub-character-time level anyway. If anyone happens to have an application such as some 1200 baud network where this is an issue, if they let me know I could always add an ioctl to disable the FIFOs, otherwise I don't see the need.)

Receive whilst in GUARTMODETIME:

Bytes received from the bus are packed into messages on the basis of the time set by GUARTSETRXINTERMSG. Timestamp reflects the time which the last byte of the message was received. Those interested in per byte timestamps may set 'RXINTERMSG' to zero and thus every byte received should be instantly passed in its own gryphon data frame with its own timestamp. hdrlen and extralen are set to zero, datalen reflects the number of bytes in the message. The max number of bytes in a message is MAXUARTMSG (currently 64) and currently any bytes received after this are thrown away until 'RXINTERMSG' is exceeded. This is probably the wrong thing to do and I will probably change this soon.


hdrlen == 1, hdrbits == 8, extralen == 0. Timestamp is the time when the terminating 0x7e was received. Note the 0x7e bytes which occur on the bus marking the beginning and end of messages aren't passed to the user by the driver.

Current state of development at Mon Aug 6 22:32:54 BST 2001

Stuff that might currently work:

Stuff to do: