USART Driver Frame
[USART Devices]

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

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



#define USART_RXHIWMARK   240
 Initial receive buffer size.
#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_RXHIWMARK   240

Initial receive buffer size.

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.

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

#define USART_MF_BLOCKREAD   0x0800

Block read enabled

Definition at line 257 of file usart.h.

Referenced by UnixDevIOCTL().

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


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 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 NutEnterCritical, NutEventWait(), NutExitCritical, and USART_MF_COOKEDMODE.

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 477 of file usart.c.

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 503 of file usart.c.

References CONST.

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 521 of file usart.c.

References free, and NUTFILE_EOF.

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:

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 554 of file usart.c.

References _O_BINARY, _O_RDONLY, _O_WRONLY, free, malloc, NUTFILE_EOF, USART_MF_COOKEDMODE, USART_RXHIWMARK, USART_RXLOWMARK, USART_TXBUFSIZ, USART_TXHIWMARK, and USART_TXLOWMARK.

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:

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 669 of file usart.c.

References NutEnterCritical, NutExitCritical, UART_GETCLOCKMODE, UART_GETCOOKEDMODE, UART_GETDATABITS, UART_GETFLOWCONTROL, 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_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, 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 866 of file usart.c.

References NutEnterCritical, and NutExitCritical.


© 2000-2007 by egnite Software GmbH - visit http://www.ethernut.de/