uart0.h : Interrupt-driven, ring buffered UART0 module
[/avr : Atmel AVR series]

Driver that initialises UART0 and allows buffered communication. More...

Functions
void	uart0_init (u32_t baud, u8_t data_bits, uart0_parity_t parity, u8_t stop_bits)
	Initialise UART0 peripheral, buffers and interrupt handlers.
void	uart0_change_baud (u32_t baud)
	Change to new BAUD rate.
bool_t	uart0_rx_buffer_empty (void)
	See if there is received data in the receive buffer.
bool_t	uart0_get_rx_byte (u8_t *data)
	See if received byte is available and store it in specified location.
u8_t	uart0_get_rx_data (u8_t *buffer, u8_t max_buf_size)
	Copy received data from ring buffer into specified buffer.
bool_t	uart0_tx_buffer_full (void)
	See if transmit ring buffer can accept more data.
bool_t	uart0_tx_buffer_empty (void)
	See if transmit ring buffer is empty.
bool_t	uart0_tx_finished (void)
	See if all transmission has finished, including last byte.
bool_t	uart0_tx_byte (u8_t data)
	Buffer one byte for transmission.
u8_t	uart0_tx_data (const u8_t *data, u8_t bytes_to_send)
	Buffer byte(s) for transmission.

---

Detailed Description

Files: avr\uart0.h & avr\uart0.c

This is a driver for the UART0 peripheral that provides buffered serial communication facilities. It uses two ring (circular) buffers for data to be sent and data received. If the receive buffer is full, extra received data is discarded. If more transmit data is specified than can be buffered, then only the number that can be buffered is accepted and the rest ignored.

The size of the receive and transmit buffer can be set separately, up to a maximum size of 256 bytes each. The default frame format is 8 data bits, no parity, 1 stop bit, but this can easily be changed in uart0_init().

Note:

The maximum number of bytes stored is one less than buffer size.

Example:

#include <avr/interrupt.h>

#include "uart0.h"

void uart0_test(void)
{
    u8_t data;
 
    // Initialise module
    uart0_init();

    // Enable global interrupts
    sei();
  
    for(;;)
    {
        // Wait until a byte is received
        if(uart0_get_rx_byte(&data))
        {
            // Send back received byte (loopback/echo mode)
            uart0_tx_byte(data);
        }
    }
}

---

Function Documentation

void uart0_init	(	u32_t	baud,
		u8_t	data_bits,
		uart0_parity_t	parity,
		u8_t	stop_bits
	)

Parameters:

	baud	Baud rate in bits/s
	data_bits	Data bits (5,6,7 or 8)
	parity	Parity(NONE, ODD or EVEN)
	stop_bits	Stop bits (1 or 2)

Definition at line 170 of file uart0.c.

References uart0_change_baud().

{
    u8_t ucsrc = 0x00;

    // Initialise variables
    uart0_rx_out           = 0;
    uart0_rx_in            = 0;
    uart0_tx_out           = 0;
    uart0_tx_in            = 0;
    uart0_tx_finished_flag = TRUE;

    switch(parity)
    {
    case UART0_ODD_PARITY :
        // Odd parity
        ucsrc |= (1<<UPM01) | (1<<UPM00);
        break;
    case UART0_EVEN_PARITY :
        // Even parity
        ucsrc |= (1<<UPM01) | (0<<UPM00);
        break;
    case UART0_NO_PARITY :
        // Fall through...
    default:
        // No parity
        ucsrc |= (0<<UPM01) | (0<<UPM00);
        break;
    }

    switch(data_bits)
    {
    case 5:
        // 5 data bits
        ucsrc |= (0<<UCSZ02) | (0<<UCSZ01) | (0<<UCSZ00);
        break;
    case 6:
        // 6 data bits
        ucsrc |= (0<<UCSZ02) | (0<<UCSZ01) | (1<<UCSZ00);
        break;
    case 7:
        // 7 data bits
        ucsrc |= (0<<UCSZ02) | (1<<UCSZ01) | (0<<UCSZ00);
        break;
    case 8:
        // Fall through...
    default:
        // 8 data bits
        ucsrc |= (0<<UCSZ02) | (1<<UCSZ01) | (1<<UCSZ00);
        break;
    }

    uart0_change_baud(baud);
}

void uart0_change_baud

(

u32_t

baud

)

Calculates and sets the new 16-bit UBBR register value. No check is performed that the actual BAUD rate is within tolerance of the specified BAUD rate.

UBBR = F_OSC / (16 * BAUD) - 1 (for Asynchronous Normal Mode; U2X flag = 0)

Parameters:

[in]

baud

New BAUD rate

Definition at line 227 of file uart0.c.

References U16_HI8, and U16_LO8.

Referenced by uart0_init().

{
    u16_t  ubrr;
    ldiv_t div;

    // Disable UART
    UCSR0B = 0;

    // Calculate new 16-bit UBBR register value
    baud <<= 4;
    div    = ldiv(F_CPU, baud);
    ubrr   = (u16_t)div.quot;
    baud >>= 1;
    if((u32_t)(div.rem) < baud)
    {
        ubrr--;
    }
    // Set BAUD rate by initalising 16-bit UBBR register
    UBRR0H = U16_HI8(ubrr);
    UBRR0L = U16_LO8(ubrr);

    // Enable RxD/TxD and receive interupt
    UCSR0B = (1<<RXCIE)|(1<<RXEN)|(1<<TXEN);
}

bool_t uart0_rx_buffer_empty

(

void

)

Return values:

	TRUE	There is received data in the receive buffer
	FALSE	The receive buffer is empty

Definition at line 252 of file uart0.c.

{
    // See if there is data in the buffer
    if(uart0_rx_out == uart0_rx_in)
    {
        return FALSE;
    }
    else
    {
        return TRUE;
    }
}

bool_t uart0_get_rx_byte

(

u8_t *

data

)

Parameters:

[out]

data

Pointer to location where data byte must be stored

Return values:

	TRUE	Received byte is stored in specified location
	FALSE	No received data available (receive buffer empty)

Definition at line 266 of file uart0.c.

{
    // See if there is data in the buffer
    if(uart0_rx_out == uart0_rx_in)
    {
        return FALSE;
    }
    // Fetch data
    *data = uart0_rx_buffer[uart0_rx_out];

    // Advance pointer
    UART0_NEXT_INDEX(uart0_rx_out, UART0_RX_BUFFER_SIZE);

    return TRUE;
}

u8_t uart0_get_rx_data	(	u8_t *	buffer,
		u8_t	max_buf_size
	)

Parameters:

[out]	buffer	Buffer to copy received data into
[in]	max_buf_size	Maximum number of received bytes to copy into buffer

Returns:

u8_t Number of received bytes copied into buffer

Definition at line 282 of file uart0.c.

{
    u8_t data_received = 0;

    while(max_buf_size)
    {
        // See if there is data in the buffer
        if(uart0_rx_out == uart0_rx_in)
        {
            break;
        }
        // Fetch data
        *buffer++ = uart0_rx_buffer[uart0_rx_out];

        // Advance pointer
        UART0_NEXT_INDEX(uart0_rx_out, UART0_RX_BUFFER_SIZE);

        // Next byte
        data_received++;
        max_buf_size--;
    }

    return data_received;
}

bool_t uart0_tx_buffer_full

(

void

)

Return values:

	TRUE	Transmit ring buffer is full
	FALSE	Transmit ring buffer has space for at least one byte

Definition at line 307 of file uart0.c.

{
    u8_t index = uart0_tx_in;
    
    // Calculate next pointer position
    UART0_NEXT_INDEX(index, UART0_TX_BUFFER_SIZE);

    if(index == uart0_tx_out)
    {
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}

bool_t uart0_tx_buffer_empty

(

void

)

Note:

Buffer may be empty, but UART peripheral may still be busy with the transmission of the last byte in the buffer.

See also:

uart0_tx_finished.

Return values:

	TRUE	Transmit ring buffer is empty
	FALSE	Transmit ring buffer has space for at least one byte

Definition at line 324 of file uart0.c.

{
    if(uart0_tx_out == uart0_tx_in)
    {
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}

bool_t uart0_tx_finished

(

void

)

This functions is usefull for communication standards like RS-485 where the mode must be changed manually from TX to RX after transmission.

Return values:

	TRUE	Transmision completely finished
	FALSE	Busy with transmission

Definition at line 336 of file uart0.c.

{
    if(uart0_tx_out != uart0_tx_in)
    {
        return FALSE;
    }
    return uart0_tx_finished_flag;
}

bool_t uart0_tx_byte

(

u8_t

data

)

Parameters:

[in]

data

Byte to be transmitted

Return values:

	TRUE	Byte has been buffered
	FALSE	Byte has not been buffered, because transmit buffer is full

Definition at line 345 of file uart0.c.

References BIT_SET_HI.

{
    u8_t index = uart0_tx_in;
    
    // Calculate next pointer position
    UART0_NEXT_INDEX(index, UART0_TX_BUFFER_SIZE);

    // Make sure there is space available in buffer
    if(index == uart0_tx_out)
    {
        return FALSE;
    }

    // Insert data into buffer
    uart0_tx_buffer[uart0_tx_in] = data;

    // Advance pointer
    uart0_tx_in = index;

    // Make sure transmit process is started by enabling interrupt
    BIT_SET_HI(UCSR0B, UDRIE);

    return TRUE;
}

u8_t uart0_tx_data	(	const u8_t *	data,
		u8_t	bytes_to_send
	)

Note:

The transmit ring buffer may not be able to hold all of the specified data.

Parameters:

[in]	data	Buffer containing data for transmission
[in]	bytes_to_send	Number of bytes in buffer to be transmitted

Returns:

u8_t The actual number of bytes buffered for transmission.

Definition at line 370 of file uart0.c.

References BIT_SET_HI.

{
    u8_t bytes_buffered = 0;
    u8_t index;

    while(bytes_to_send)
    {
        // Calculate next pointer position
        index = uart0_tx_in;
        UART0_NEXT_INDEX(index, UART0_TX_BUFFER_SIZE);

        // Make sure there is space available in buffer
        if(index == uart0_tx_out)
        {
            break;
        }

        // Insert data into buffer
        uart0_tx_buffer[uart0_tx_in] = *data++;

        // Advance pointer
        uart0_tx_in = index;

        // Next byte
        bytes_buffered++;
        bytes_to_send--;
    }

    // Make sure transmit process is started by enabling interrupt
    BIT_SET_HI(UCSR0B, UDRIE);

    return bytes_buffered;
}