VxWorks Reference Manual : Libraries
ambaSio - ARM AMBA UART tty driver
ambaDevInit( ) - initialise an AMBA channel
ambaIntTx( ) - handle a transmitter interrupt
ambaIntRx( ) - handle a receiver interrupt
This is the device driver for the Advanced RISC Machines (ARM) AMBA UART. This is a generic design of UART used within a number of chips containing (or for use with) ARM CPUs such as in the Digital Semiconductor 21285 chip as used in the EBSA-285 BSP.
This design contains a universal asynchronous receiver/transmitter, a baud-rate generator, and an InfraRed Data Association (IrDa) Serial InfraRed (SiR) protocol encoder. The Sir encoder is not supported by this driver. The UART contains two 16-entry deep FIFOs for receive and transmit: if a framing, overrun or parity error occurs during reception, the appropriate error bits are stored in the receive FIFO along with the received data. The FIFOs can be programmed to be one byte deep only, like a conventional UART with double buffering, but the only mode of operation supported is with the FIFOs enabled.
The UART design does not support the modem control output signals: DTR, RI and RTS. Moreover, the implementation in the 21285 chip does not support the modem control inputs: DCD, CTS and DSR.
The UART design can generate four interrupts: Rx, Tx, modem status change and a UART disabled interrupt (which is asserted when a start bit is detected on the receive line when the UART is disabled). The implementation in the 21285 chip has only two interrupts: Rx and Tx, but the Rx interrupt is a combination of the normal Rx interrupt status and the UART disabled interrupt status.
Only asynchronous serial operation is supported by the UART which supports 5 to 8 bit bit word lengths with or without parity and with one or two stop bits. The only serial word format supported by the driver is 8 data bits, 1 stop bit, no parity, The default baud rate is determined by the BSP by filling in the AMBA_CHAN structure before calling ambaDevInit( ).
The exact baud rates supported by this driver will depend on the crystal fitted (and consequently the input clock to the baud-rate generator), but in general, baud rates from about 300 to about 115200 are possible.
In theory, any number of UART channels could be implemented within a chip. This driver has been designed to cope with an arbitrary number of channels, but at the time of writing, has only ever been tested with one channel.
An AMBA_CHAN data structure is used to describe each channel, this structure is described in h/drv/sio/ambaSio.h.
Servicing a "transmitter ready" interrupt involves making a callback to a higher level library in order to get a character to transmit. By default, this driver installs dummy callback routines which do nothing. A higher layer library that wants to use this driver (e.g. ttyDrv) will install its own callback routine using the SIO_INSTALL_CALLBACK ioctl command. Likewise, a receiver interrupt handler makes a callback to pass the character to the higher layer library.
This driver supports both polled and interrupt modes.
The driver is typically only called by the BSP. The directly callable routines in this modules are ambaDevInit( ), ambaIntTx( ) and ambaIntRx( ).
The BSP's sysHwInit( ) routine typically calls sysSerialHwInit( ), which initialises the hardware-specific fields in the AMBA_CHAN structure (e.g. register I/O addresses etc) before calling ambaDevInit( ) which resets the device and installs the driver function pointers. After this the UART will be enabled and ready to generate interrupts, but those interrupts will be disabled in the interrupt controller.
The following example shows the first parts of the initialisation:
#include "drv/sio/ambaSio.h" LOCAL AMBA_CHAN ambaChan[N_AMBA_UART_CHANS]; void sysSerialHwInit (void) { int i; for (i = 0; i < N_AMBA_UART_CHANS; i++) { ambaChan[i].regs = devParas[i].baseAdrs; ambaChan[i].baudRate = CONSOLE_BAUD_RATE; ambaChan[i].xtal = UART_XTAL_FREQ; ambaChan[i].levelRx = devParas[i].intLevelRx; ambaChan[i].levelTx = devParas[i].intLevelTx; /* * Initialise driver functions, getTxChar, putRcvChar and * channelMode, then initialise UART */ ambaDevInit(&ambaChan[i]); } }The BSP's sysHwInit2( ) routine typically calls sysSerialHwInit2( ), which connects the chips interrupts via intConnect( ) (the two interrupts ambaIntTx and ambaIntRx) and enables those interrupts, as shown in the following example:
void sysSerialHwInit2 (void) { /* connect and enable Rx interrupt */ (void) intConnect (INUM_TO_IVEC(devParas[0].vectorRx), ambaIntRx, (int) &ambaChan[0]); intEnable (devParas[0].intLevelRx); /* connect Tx interrupt */ (void) intConnect (INUM_TO_IVEC(devParas[0].vectorTx), ambaIntTx, (int) &ambaChan[0]); /* * There is no point in enabling the Tx interrupt, as it will * interrupt immediately and then be disabled. */ }
By convention all the BSP-specific serial initialisation is performed in a file called sysSerial.c, which is #include'ed by sysLib.c. sysSerial.c implements at least four functions, sysSerialHwInit( ) sysSerialHwInit2( ), sysSerialChanGet( ), and sysSerialReset( ). The first two have been described above, the others work as follows:
sysSerialChanGet is called by usrRoot to get the serial channel descriptor associated with a serial channel number. The routine takes a single parameter which is a channel number ranging between zero and NUM_TTY. It returns a pointer to the corresponding channel descriptor, SIO_CHAN *, which is just the address of the AMBA_CHAN structure.
sysSerialReset is called from sysToMonitor( ) and should reset the serial devices to an inactive state (prevent them from generating any interrupts).
drv/sio/ambaSio.h sioLib.h
ambaSio, Advanced RISC Machines AMBA UART (AP13) Data Sheet, Digital Semiconductor 21285 Core Logic for SA-110 Microprocessor Data Sheet, " Digital Semiconductor EBSA-285 Evaluation Board Reference Manual.
ambaDevInit( ) - initialise an AMBA channel
void ambaDevInit ( AMBA_CHAN * pChan /* ptr to AMBA_CHAN describing this channel */ )
This routine initialises some SIO_CHAN function pointers and then resets the chip to a quiescent state. Before this routine is called, the BSP must already have initialised all the device addresses, etc. in the AMBA_CHAN structure.
N/A
ambaIntTx( ) - handle a transmitter interrupt
void ambaIntTx ( AMBA_CHAN * pChan /* ptr to AMBA_CHAN describing this channel */ )
This routine handles write interrupts from the UART.
N/A
ambaIntRx( ) - handle a receiver interrupt
void ambaIntRx ( AMBA_CHAN * pChan /* ptr to AMBA_CHAN describing this channel */ )
This routine handles read interrupts from the UART.
N/A