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'.
#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 #define GUARTMODECHRYSLERMSCI 0x02 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 elapsed.
#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 */ Arguments: 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 returned by GUARTGETRXFIFOSTATS24). #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.
#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 data. #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 microseconds). #define GSCIESCERR 0x71 Invalid message based SCI escape sequence seen on bus whilst in GUARTMODECHRYSLERMSCI 'RXMODE'. This occurs 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.
#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).
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.)