Universal synchronous/asynchronous receiver/transmitter device driver. More...

Collaboration diagram for USART Driver Frame:

Data Structures
struct	_RINGBUF
	Character device ring buffer structure. More...
struct	_USARTDCB
	USART device low level information structure. More...
Modules
	UART I/O Control Functions
	UART _ioctl() commands.
Defines
#define	USART_MF_RTSCONTROL 0x0001
#define	USART_MF_CTSSENSE 0x0002
#define	USART_MF_DTRCONTROL 0x0004
#define	USART_MF_DSRSENSE 0x0008
#define	USART_MF_DCDSENSE 0x0010
#define	USART_MF_SENSEMASK 0x001A
#define	USART_MF_CONTROLMASK 0x0005
#define	USART_MF_XONXOFF 0x0020
	Software handshake.
#define	USART_MF_LOCALECHO 0x0040
	Echo configuration.
#define	USART_MF_COOKEDMODE 0x0080
#define	USART_MF_NOBUFFER 0x0100
#define	USART_MF_LINEBUFFER 0x0200
#define	USART_MF_BUFFERMASK 0x0300
#define	USART_MF_HALFDUPLEX 0x0400
#define	USART_MF_BLOCKREAD 0x0800
#define	USART_MF_BLOCKWRITE 0x1000
#define	USART_MF_FLOWMASK (USART_MF_XONXOFF\| USART_MF_HALFDUPLEX\|USART_MF_LOCALECHO\|USART_MF_BLOCKREAD\|USART_MF_BLOCKWRITE)
#define	USART_SF_RTSOFF 0x0001
#define	USART_SF_CTSOFF 0x0002
#define	USART_SF_DTROFF 0x0004
#define	USART_SF_DSROFF 0x0008
#define	USART_SF_DCDOFF 0x0010
#define	USART_SF_TXDISABLED 0x0040
#define	USART_SF_RXDISABLED 0x0080
Typedefs
typedef struct _USARTDCB	USARTDCB
Functions
int	UsartInit (NUTDEVICE *dev)
	Initialize the USART device.
int	UsartRead (NUTFILE fp, void buffer, int size)
	Read from device.
int	UsartWrite (NUTFILE fp, const void buffer, int len)
	Write a device or file.
int	UsartWrite_P (NUTFILE *fp, PGM_P buffer, int len)
	Write a device or file.
int	UsartClose (NUTFILE *fp)
	Close an USART device.
NUTFILE *	UsartOpen (NUTDEVICE dev, const char name, int mode, int acc)
	Open an USART device.
int	UsartIOCtl (NUTDEVICE dev, int req, void conf)
	Perform USART control functions.
long	UsartSize (NUTFILE *fp)
	Retrieves the number of characters in input buffer.
Ring Buffer
typedef struct _RINGBUF	RINGBUF
	Character device ring buffer type.
#define	USART_RXBUFSIZ 256
	Initial receive buffer size.
#define	USART_RXHIWMARK 240
	Receiver's initial high water mark.
#define	USART_RXLOWMARK 208
	Receiver's initial low water mark.
#define	USART_TXBUFSIZ 64
	Initial transmit buffer size.
#define	USART_TXHIWMARK 56
	Transmitter's initial high water mark.
#define	USART_TXLOWMARK 40
	Transmitter's initial low water mark.
#define	ENABLE 1
#define	DISABLE 0
Initial UART Configuration
#define	USART_INITSPEED 115200
	Initial bit rate.

Detailed Description

Universal synchronous/asynchronous receiver/transmitter device driver.

The USART device driver implements buffered, interrupt controlled serial communication. It supports software and hardware handshake, 9-bit communication, half duplex and synchronous operation.

The driver's code is devided into a general part and a hardware dependant part, which simplifies porting it to different USART chips. The AVR USART Devices provide support for the ATmega128/103 on-chip USARTs.

Define Documentation

#define USART_RXBUFSIZ 256

Initial receive buffer size.

Referenced by UsartOpen().

#define USART_RXHIWMARK 240

Receiver's initial high water mark.

Disables receiver handshake.

Referenced by UsartOpen().

#define USART_RXLOWMARK 208

Receiver's initial low water mark.

Enables receiver handshake.

Referenced by UsartOpen().

#define USART_TXBUFSIZ 64

Initial transmit buffer size.

Referenced by UsartOpen().

#define USART_TXHIWMARK 56

Transmitter's initial high water mark.

Starts the transmitter.

Referenced by UsartOpen().

#define USART_TXLOWMARK 40

Transmitter's initial low water mark.

Wakes up transmitting threads.

Referenced by UsartOpen().

#define ENABLE 1

Referenced by EmacInit(), scif_dfll0_closedloop_start(), scif_dfll0_openloop_start(), scif_dfll0_ssg_enable(), scif_enable_osc(), scif_start_osc(), scif_start_osc32(), SetPllClockSource(), SetSysClockSource(), Stm32CanHw1Init(), Stm32CanHw2Init(), Stm32I2cBus1Init(), Stm32I2cBus2Init(), TIM_DeInit(), and USART_DeInit().

#define DISABLE 0

Referenced by FLASH_ITConfig(), GPIO_PinRemapConfig(), RCC_AHB1PeriphClockCmd(), RCC_AHB1PeriphClockLPModeCmd(), RCC_AHB1PeriphResetCmd(), RCC_AHB2PeriphClockCmd(), RCC_AHB2PeriphClockLPModeCmd(), RCC_AHB2PeriphResetCmd(), RCC_AHB3PeriphClockCmd(), RCC_AHB3PeriphClockLPModeCmd(), RCC_AHB3PeriphResetCmd(), RCC_AHBPeriphClockCmd(), RCC_AHBPeriphClockLPModeCmd(), RCC_AHBPeriphResetCmd(), RCC_APB1PeriphClockCmd(), RCC_APB1PeriphClockLPModeCmd(), RCC_APB1PeriphResetCmd(), RCC_APB2PeriphClockCmd(), RCC_APB2PeriphClockLPModeCmd(), RCC_APB2PeriphResetCmd(), RCC_ITConfig(), Stm32I2cBus1Init(), Stm32I2cBus2Init(), TIM_ARRPreloadConfig(), TIM_CCPreloadControl(), TIM_Cmd(), TIM_CtrlPWMOutputs(), TIM_DeInit(), TIM_DMACmd(), TIM_ITConfig(), TIM_SelectCCDMA(), TIM_SelectCOM(), TIM_SelectHallSensor(), TIM_UpdateDisableConfig(), USART_Cmd(), USART_DeInit(), USART_DMACmd(), USART_HalfDuplexCmd(), USART_IrDACmd(), USART_ITConfig(), USART_LINCmd(), USART_OneBitMethodCmd(), USART_OverSampling8Cmd(), USART_ReceiverWakeUpCmd(), USART_SmartCardCmd(), USART_SmartCardNACKCmd(), and USB_Cable_Config().

#define USART_INITSPEED 115200

Initial bit rate.

Referenced by UsartInit().

#define USART_MF_RTSCONTROL 0x0001

DTE output.

#define USART_MF_CTSSENSE 0x0002

DTE input.

#define USART_MF_DTRCONTROL 0x0004

DTE output.

#define USART_MF_DSRSENSE 0x0008

DTE input.

#define USART_MF_DCDSENSE 0x0010

DTE input.

#define USART_MF_SENSEMASK 0x001A

Handshake sense mask.

#define USART_MF_CONTROLMASK 0x0005

Handshake control mask.

#define USART_MF_XONXOFF 0x0020

Software handshake.

It is recommended to set a proper read timeout with software handshake. In this case a timeout may occur, if the communication peer lost our last XON character. The application may then use ioctl() to disable the receiver and do the read again. This will send out another XON.

Referenced by Sc16is752UsartGetFlowControl(), and UsartIOCtl().

#define USART_MF_LOCALECHO 0x0040

Echo configuration.

For RS232 mode it defines if any received character is echoed back to the sender. For 485 mode it defines if on switch to transmitting mode the receiver is left enabled. Should be used in stream, not device.

Referenced by UsartIOCtl().

#define USART_MF_COOKEDMODE 0x0080

Should be used in stream, not device.

Referenced by UsartIOCtl(), UsartOpen(), and UsartRead().

#define USART_MF_NOBUFFER 0x0100

No buffering.

#define USART_MF_LINEBUFFER 0x0200

Line buffered.

#define USART_MF_BUFFERMASK 0x0300

Masks buffering mode flags.

#define USART_MF_HALFDUPLEX 0x0400

Half duplex control.

Referenced by UsartIOCtl().

#define USART_MF_BLOCKREAD 0x0800

Block read mode enabled

Referenced by UnixDevIOCTL(), UsartIOCtl(), and UsartRead().

#define USART_MF_BLOCKWRITE 0x1000

Block write mode enabled

Referenced by UsartIOCtl().

#define USART_MF_FLOWMASK (USART_MF_XONXOFF| USART_MF_HALFDUPLEX|USART_MF_LOCALECHO|USART_MF_BLOCKREAD|USART_MF_BLOCKWRITE)

#define USART_SF_RTSOFF 0x0001

Set if RTS line is off.

#define USART_SF_CTSOFF 0x0002

Set if CTS line is off.

#define USART_SF_DTROFF 0x0004

Set if DTR line is off.

#define USART_SF_DSROFF 0x0008

Set if DSR line is off.

#define USART_SF_DCDOFF 0x0010

Set if DCD line is off.

#define USART_SF_TXDISABLED 0x0040

Transmitter disabled.

#define USART_SF_RXDISABLED 0x0080

Receiver disabled.

Typedef Documentation

RINGBUF

Character device ring buffer type.

typedef struct _USARTDCB USARTDCB

USART device low level information type.

Function Documentation

int UsartInit ( NUTDEVICE * dev )

Initialize the USART device.

This function is called by NutRegisterDevice(), using the _NUTDEVICE::dev_init entry. It will call the low level driver's _USARTDCB::dcb_init routine to initialize the hardware.

Parameters:

dev	Identifies the device to initialize.

Returns:: 0 on success, -1 otherwise.

Todo:: Read initial settings from EEPROM.

References _USARTDCB::dcb_init, _USARTDCB::dcb_set_speed, _NUTDEVICE::dev_dcb, rc, and USART_INITSPEED.

int UsartRead	(	NUTFILE *	fp,
		void *	buffer,
		int	size
	)

Read from device.

This function is called by the low level input routines of the C runtime library, using the _NUTDEVICE::dev_read entry.

The function may block the calling thread until at least one character has been received or a timeout occurs.

It is recommended to set a proper read timeout with software handshake. In this case a timeout may occur, if the communication peer lost our last XON character. The application may then use ioctl() to disable the receiver and do the read again. This will send out another XON.

Parameters:

fp	Pointer to a _NUTFILE structure, obtained by a previous call to UsartOpen().
buffer	Pointer to the buffer that receives the data. If zero, then all characters in the input buffer will be removed.
size	Maximum number of bytes to read.

Returns:: The number of bytes read, which may be less than the number of bytes specified. A return value of -1 indicates an error, while zero is returned in case of a timeout.

References _USARTDCB::dcb_last_eol, _USARTDCB::dcb_modeflags, _USARTDCB::dcb_rtimeout, _USARTDCB::dcb_rx_rbf, _USARTDCB::dcb_rx_start, _NUTDEVICE::dev_dcb, _NUTFILE::nf_dev, NutEnterCritical, NutEventWait(), NutExitCritical, _RINGBUF::rbf_blockcnt, _RINGBUF::rbf_blockptr, _RINGBUF::rbf_cnt, _RINGBUF::rbf_hwm, _RINGBUF::rbf_last, _RINGBUF::rbf_lwm, _RINGBUF::rbf_que, _RINGBUF::rbf_siz, _RINGBUF::rbf_start, _RINGBUF::rbf_tail, rc, USART_MF_BLOCKREAD, and USART_MF_COOKEDMODE.

Here is the call graph for this function:

int UsartWrite	(	NUTFILE *	fp,
		const void *	buffer,
		int	len
	)

Write a device or file.

This function is called by the low level output routines of the C runtime library, using the _NUTDEVICE::dev_write entry.

The function may block the calling thread.

Parameters:

fp	Pointer to a _NUTFILE structure, obtained by a previous call to UsartOpen().
buffer	Pointer to the data to be written. If zero, then the output buffer will be flushed.
len	Number of bytes to write.

Returns:: The number of bytes written, which may be less than the number of bytes specified if a timeout occured. A return value of -1 indicates an error.

References _NUTFILE::nf_dev.

int UsartWrite_P	(	NUTFILE *	fp,
		PGM_P	buffer,
		int	len
	)

Write a device or file.

Similar to UsartWrite() except that the data is located in program memory.

This function is called by the low level output routines of the C runtime library, using the _NUTDEVICE::dev_write_P entry.

The function may block the calling thread.

Parameters:

fp	Pointer to a NUTFILE structure, obtained by a previous call to UsartOpen().
buffer	Pointer to the data in program space to be written.
len	Number of bytes to write.

Returns:: The number of bytes written, which may be less than the number of bytes specified if a timeout occured. A return value of -1 indicates an error.

References _NUTFILE::nf_dev.

int UsartClose ( NUTFILE * fp )

Close an USART device.

This function is called by the low level close routine of the C runtime library, using the _NUTDEVICE::dev_close entry.

Parameters:

fp	Pointer to a _NUTFILE structure, obtained by a previous call to UsartOpen().

Returns:: 0 on success or -1 otherwise.

Todo:: We may support shared open and use dev_irq as an open counter.

References _USARTDCB::dcb_rx_rbf, _USARTDCB::dcb_set_status, _USARTDCB::dcb_tx_rbf, _NUTDEVICE::dev_dcb, free(), _NUTFILE::nf_dev, NutEventBroadcast(), NUTFILE_EOF, _RINGBUF::rbf_que, and UART_RTSDISABLED.

Here is the call graph for this function:

NUTFILE* UsartOpen	(	NUTDEVICE *	dev,
		const char *	name,
		int	mode,
		int	acc
	)

Open an USART device.

This function is called by the low level open routine of the C runtime library, using the _NUTDEVICE::dev_open entry.

Parameters:

dev	Pointer to the NUTDEVICE structure.
name	Ignored, should point to an empty string.
mode	Operation mode. Any of the following values may be or-ed: _O_BINARY _O_RDONLY _O_WRONLY
acc	Ignored, should be zero.

Returns:: Pointer to a NUTFILE structure if successful or NUTFILE_EOF otherwise.

Todo:: We may support shared open and use dev_irq as an open counter.

References _O_BINARY, _O_RDONLY, _O_WRONLY, _USARTDCB::dcb_modeflags, _USARTDCB::dcb_rx_rbf, _USARTDCB::dcb_rx_start, _USARTDCB::dcb_tx_rbf, _NUTDEVICE::dev_dcb, free(), malloc(), _NUTFILE::nf_dev, _NUTFILE::nf_fcb, _NUTFILE::nf_next, NUTFILE_EOF, _RINGBUF::rbf_start, USART_MF_COOKEDMODE, USART_RXBUFSIZ, USART_RXHIWMARK, USART_RXLOWMARK, USART_TXBUFSIZ, USART_TXHIWMARK, and USART_TXLOWMARK.

Here is the call graph for this function:

int UsartIOCtl	(	NUTDEVICE *	dev,
		int	req,
		void *	conf
	)

Perform USART control functions.

This function is called by the ioctl() function of the C runtime library.

Parameters:

dev	Identifies the device that receives the device-control function.
req	Requested control function. May be set to one of the following constants: UART_SETSPEED UART_GETSPEED UART_SETDATABITS UART_GETDATABITS UART_SETPARITY UART_GETPARITY UART_SETSTOPBITS UART_GETSTOPBITS UART_SETSTATUS UART_GETSTATUS UART_SETREADTIMEOUT UART_GETREADTIMEOUT UART_SETWRITETIMEOUT UART_GETWRITETIMEOUT UART_SETLOCALECHO UART_GETLOCALECHO UART_SETFLOWCONTROL UART_GETFLOWCONTROL UART_SETCOOKEDMODE UART_GETCOOKEDMODE UART_SETHDPXMODE UART_GETHDPXMODE UART_SETCLOCKMODE UART_GETCLOCKMODE UART_SETTXBUFSIZ UART_GETTXBUFSIZ UART_SETRXBUFSIZ UART_GETRXBUFSIZ UART_SETTXBUFLWMARK UART_GETTXBUFLWMARK UART_SETTXBUFHWMARK UART_GETTXBUFHWMARK UART_SETRXBUFLWMARK UART_GETRXBUFLWMARK UART_SETRXBUFHWMARK UART_GETRXBUFHWMARK
conf	Points to a buffer that contains any data required for the given control function or receives data from that function.

Returns:: 0 on success, -1 otherwise.

Note:: Not all control functions may be supported on all platforms. In any case applications should check the returned result.

Todo:: Hardware handshake is not available with AT91 targets.

Warning:: Timeout values are given in milliseconds and are limited to the granularity of the system timer. To disable timeout, set the parameter to NUT_WAIT_INFINITE.

References _USARTDCB::dcb_get_clock_mode, _USARTDCB::dcb_get_data_bits, _USARTDCB::dcb_get_flow_control, _USARTDCB::dcb_get_parity, _USARTDCB::dcb_get_speed, _USARTDCB::dcb_get_status, _USARTDCB::dcb_get_stop_bits, _USARTDCB::dcb_modeflags, _USARTDCB::dcb_rtimeout, _USARTDCB::dcb_rx_rbf, _USARTDCB::dcb_rx_start, _USARTDCB::dcb_set_clock_mode, _USARTDCB::dcb_set_data_bits, _USARTDCB::dcb_set_flow_control, _USARTDCB::dcb_set_parity, _USARTDCB::dcb_set_speed, _USARTDCB::dcb_set_status, _USARTDCB::dcb_set_stop_bits, _USARTDCB::dcb_tx_rbf, _USARTDCB::dcb_wtimeout, _NUTDEVICE::dev_dcb, NutEnterCritical, NutExitCritical, _RINGBUF::rbf_cnt, _RINGBUF::rbf_hwm, _RINGBUF::rbf_lwm, _RINGBUF::rbf_siz, rc, UART_GETBLOCKREAD, UART_GETBLOCKWRITE, UART_GETCLOCKMODE, UART_GETCOOKEDMODE, UART_GETDATABITS, UART_GETFLOWCONTROL, UART_GETHDPXMODE, UART_GETLOCALECHO, UART_GETPARITY, UART_GETREADTIMEOUT, UART_GETRXBUFHWMARK, UART_GETRXBUFLWMARK, UART_GETRXBUFSIZ, UART_GETSPEED, UART_GETSTATUS, UART_GETSTOPBITS, UART_GETTXBUFHWMARK, UART_GETTXBUFLWMARK, UART_GETTXBUFSIZ, UART_GETWRITETIMEOUT, UART_RXBUFFEREMPTY, UART_SETBLOCKREAD, UART_SETBLOCKWRITE, UART_SETCLOCKMODE, UART_SETCOOKEDMODE, UART_SETDATABITS, UART_SETFLOWCONTROL, UART_SETHDPXMODE, UART_SETLOCALECHO, UART_SETPARITY, UART_SETREADTIMEOUT, UART_SETRXBUFHWMARK, UART_SETRXBUFLWMARK, UART_SETRXBUFSIZ, UART_SETSPEED, UART_SETSTATUS, UART_SETSTOPBITS, UART_SETTXBUFHWMARK, UART_SETTXBUFLWMARK, UART_SETTXBUFSIZ, UART_SETWRITETIMEOUT, UART_TXBUFFEREMPTY, USART_MF_BLOCKREAD, USART_MF_BLOCKWRITE, USART_MF_COOKEDMODE, USART_MF_HALFDUPLEX, USART_MF_LOCALECHO, and USART_MF_XONXOFF.

long UsartSize ( NUTFILE * fp )

Retrieves the number of characters in input buffer.

This function is called by the low level size routine of the C runtime library, using the _NUTDEVICE::dev_size entry.

Parameters:

fp	Pointer to a _NUTFILE structure, obtained by a previous call to UsartOpen().

Returns:: The number of bytes currently stored in input buffer.

References _USARTDCB::dcb_rx_rbf, _NUTDEVICE::dev_dcb, _NUTFILE::nf_dev, NutEnterCritical, NutExitCritical, and _RINGBUF::rbf_cnt.

Data Structures

Modules

Defines

Typedefs

Functions

Ring Buffer

Initial UART Configuration

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation