proconX: Protocol Converter & Gateways

Programmable Gateways
Smart Industrial Communication and Embeddeded Ethernet Solutions
 Login 
Overview
Power Industry
Serial Device Server
Programmable Gateways
Serial/Ethernet Gateway XNUT-100
CAN/Ethernet Gateway XNUT-105
Ethernet CPU Boards
Shop
Information and Support
We accept VISA, MasterCard, PayPal

World Wide Shipping

Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages | Examples

USART Device Driver
[Serial communication devices.]

Collaboration diagram for USART Device Driver:

Detailed Description

Universal synchronous/asynchronous receiver/transmitter device driver.

The USART device driver implements buffered, interrupt controlled serial communication. In opposite to the AVR UART Device Driver 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.


Modules

 AVR USART Devices
 AVR USART hardware dependant implementation.

Data Structures

struct  _RINGBUF
 Character device ring buffer structure. More...
struct  _USARTDCB
 USART device low level information structure. More...
struct  _RINGBUF
 Character device ring buffer structure. More...
struct  _USARTDCB
 USART device low level information structure. More...

Ring Buffer

#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.
typedef _RINGBUF RINGBUF
 Character device ring buffer type.

Initial UART Configuration

#define USART_INITSPEED   115200
 Initial bit rate.

Defines

#define USART_MF_RTSCONTROL
#define USART_MF_CTSSENSE
#define USART_MF_DTRCONTROL
#define USART_MF_DSRSENSE
#define USART_MF_DCDSENSE
#define USART_MF_SENSEMASK
#define USART_MF_CONTROLMASK
#define USART_MF_XONXOFF
 Software handshake.
#define USART_MF_LOCALECHO
#define USART_MF_COOKEDMODE
#define USART_MF_NOBUFFER
#define USART_MF_LINEBUFFER
#define USART_MF_BUFFERMASK
#define USART_MF_HALFDUPLEX
#define USART_MF_BLOCKREAD
#define USART_SF_RTSOFF
#define USART_SF_CTSOFF
#define USART_SF_DTROFF
#define USART_SF_DSROFF
#define USART_SF_DCDOFF
#define USART_SF_TXDISABLED
#define USART_SF_RXDISABLED

Typedefs

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

Define Documentation

#define USART_MF_BLOCKREAD
 

Block read enabled

#define USART_MF_BUFFERMASK
 

Masks buffering mode flags.

#define USART_MF_CONTROLMASK
 

Handshake control mask.

#define USART_MF_COOKEDMODE
 

Should be used in stream, not device.

#define USART_MF_CTSSENSE
 

DTE input.

#define USART_MF_DCDSENSE
 

DTE input.

#define USART_MF_DSRSENSE
 

DTE input.

#define USART_MF_DTRCONTROL
 

DTE output.

#define USART_MF_HALFDUPLEX
 

Half duplex control.

#define USART_MF_LINEBUFFER
 

Line buffered.

#define USART_MF_LOCALECHO
 

Should be used in stream, not device.

#define USART_MF_NOBUFFER
 

No buffering.

#define USART_MF_RTSCONTROL
 

DTE output.

#define USART_MF_SENSEMASK
 

Handshake sense mask.

#define USART_MF_XONXOFF
 

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.

#define USART_RXHIWMARK   240
 

Receiver's initial high water mark.

Disables receiver handshake.

#define USART_RXLOWMARK   208
 

Receiver's initial low water mark.

Enables receiver handshake.

#define USART_SF_CTSOFF
 

Set if CTS line is off.

#define USART_SF_DCDOFF
 

Set if DCD line is off.

#define USART_SF_DSROFF
 

Set if DSR line is off.

#define USART_SF_DTROFF
 

Set if DTR line is off.

#define USART_SF_RTSOFF
 

Set if RTS line is off.

#define USART_SF_RXDISABLED
 

Receiver disabled.

#define USART_SF_TXDISABLED
 

Transmitter disabled.

#define USART_TXHIWMARK   56
 

Transmitter's initial high water mark.

Starts the transmitter.

#define USART_TXLOWMARK   40
 

Transmitter's initial low water mark.

Wakes up transmitting threads.

Typedef Documentation

typedef struct _USARTDCB USARTDCB
 

USART device low level information type.

Function Documentation

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.

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.

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

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.

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.

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.

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.

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.