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
#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_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.
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.

Definition at line 84 of file usart.h.

Referenced by UsartOpen().

#define USART_RXHIWMARK 240

Receiver's initial high water mark.

Disables receiver handshake.

Definition at line 93 of file usart.h.

Referenced by UsartOpen().

#define USART_RXLOWMARK 208

Receiver's initial low water mark.

Enables receiver handshake.

Definition at line 102 of file usart.h.

Referenced by UsartOpen().

#define USART_TXBUFSIZ 64

Initial transmit buffer size.

Definition at line 109 of file usart.h.

Referenced by UsartOpen().

#define USART_TXHIWMARK 56

Transmitter's initial high water mark.

Starts the transmitter.

Definition at line 118 of file usart.h.

Referenced by UsartOpen().

#define USART_TXLOWMARK 40

Transmitter's initial low water mark.

Wakes up transmitting threads.

Definition at line 127 of file usart.h.

Referenced by UsartOpen().

#define USART_INITSPEED 115200

Initial bit rate.

Definition at line 226 of file usart.h.

Referenced by UsartInit().

#define USART_MF_RTSCONTROL 0x0001

DTE output.

Definition at line 231 of file usart.h.

#define USART_MF_CTSSENSE 0x0002

DTE input.

Definition at line 232 of file usart.h.

#define USART_MF_DTRCONTROL 0x0004

DTE output.

Definition at line 233 of file usart.h.

#define USART_MF_DSRSENSE 0x0008

DTE input.

Definition at line 234 of file usart.h.

#define USART_MF_DCDSENSE 0x0010

DTE input.

Definition at line 235 of file usart.h.

#define USART_MF_SENSEMASK 0x001A

Handshake sense mask.

Definition at line 237 of file usart.h.

#define USART_MF_CONTROLMASK 0x0005

Handshake control mask.

Definition at line 238 of file usart.h.

#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.

Definition at line 247 of file usart.h.

Referenced by Sc16is752UsartGetFlowControl().

#define USART_MF_LOCALECHO 0x0040

Should be used in stream, not device.

Definition at line 249 of file usart.h.

Referenced by UsartIOCtl().

#define USART_MF_COOKEDMODE 0x0080

Should be used in stream, not device.

Definition at line 250 of file usart.h.

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

#define USART_MF_NOBUFFER 0x0100

No buffering.

Definition at line 252 of file usart.h.

#define USART_MF_LINEBUFFER 0x0200

Line buffered.

Definition at line 253 of file usart.h.

#define USART_MF_BUFFERMASK 0x0300

Masks buffering mode flags.

Definition at line 254 of file usart.h.

#define USART_MF_HALFDUPLEX 0x0400

Half duplex control.

Definition at line 256 of file usart.h.

Referenced by UsartIOCtl().

#define USART_MF_BLOCKREAD 0x0800

Block read enabled

Definition at line 257 of file usart.h.

#define USART_SF_RTSOFF 0x0001

Set if RTS line is off.

Definition at line 259 of file usart.h.

#define USART_SF_CTSOFF 0x0002

Set if CTS line is off.

Definition at line 260 of file usart.h.

#define USART_SF_DTROFF 0x0004

Set if DTR line is off.

Definition at line 261 of file usart.h.

#define USART_SF_DSROFF 0x0008

Set if DSR line is off.

Definition at line 262 of file usart.h.

#define USART_SF_DCDOFF 0x0010

Set if DCD line is off.

Definition at line 263 of file usart.h.

#define USART_SF_TXDISABLED 0x0040

Transmitter disabled.

Definition at line 265 of file usart.h.

#define USART_SF_RXDISABLED 0x0080

Receiver disabled.

Definition at line 266 of file usart.h.

Typedef Documentation

RINGBUF

Character device ring buffer type.

Definition at line 134 of file usart.h.

typedef struct _USARTDCB USARTDCB

USART device low level information type.

Definition at line 399 of file usart.h.

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.

Definition at line 111 of file usart.c.

References _USARTDCB::dcb_init, _USARTDCB::dcb_set_speed, _NUTDEVICE::dev_dcb, 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.

Definition at line 198 of file usart.c.

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_cnt, _RINGBUF::rbf_hwm, _RINGBUF::rbf_last, _RINGBUF::rbf_lwm, _RINGBUF::rbf_que, _RINGBUF::rbf_siz, _RINGBUF::rbf_start, _RINGBUF::rbf_tail, 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.

Definition at line 481 of file usart.c.

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.

Definition at line 507 of file usart.c.

References CONST, and _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.

Definition at line 525 of file usart.c.

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.

Definition at line 561 of file usart.c.

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.

Definition at line 678 of file usart.c.

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, 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_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_COOKEDMODE, USART_MF_HALFDUPLEX, and USART_MF_LOCALECHO.

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.

Definition at line 888 of file usart.c.

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