iPXE
Data Structures | Defines | Enumerations | Functions
uart.h File Reference

16550-compatible UART More...

#include <stdint.h>
#include <bits/uart.h>

Go to the source code of this file.

Data Structures

struct  uart
 A 16550-compatible UART. More...

Defines

#define UART_THR   0x00
 Transmitter holding register.
#define UART_RBR   0x00
 Receiver buffer register.
#define UART_IER   0x01
 Interrupt enable register.
#define UART_FCR   0x02
 FIFO control register.
#define UART_FCR_FE   0x01
 FIFO enable.
#define UART_LCR   0x03
 Line control register.
#define UART_LCR_WLS0   0x01
 Word length select bit 0.
#define UART_LCR_WLS1   0x02
 Word length select bit 1.
#define UART_LCR_STB   0x04
 Number of stop bits.
#define UART_LCR_PEN   0x08
 Parity enable.
#define UART_LCR_EPS   0x10
 Even parity select.
#define UART_LCR_DLAB   0x80
 Divisor latch access bit.
#define UART_LCR_WORD_LEN(x)   ( ( (x) - 5 ) << 0 )
 Word length.
#define UART_LCR_STOP_BITS(x)   ( ( (x) - 1 ) << 2 )
 Stop bits.
#define UART_LCR_PARITY(x)   ( ( (x) - 0 ) << 3 )
 Parity.
#define UART_LCR_WPS(word_len, parity, stop_bits)
 Calculate line control register value.
#define UART_LCR_8N1   UART_LCR_WPS ( 8, 0, 1 )
 Default LCR value: 8 data bits, no parity, one stop bit.
#define UART_MCR   0x04
 Modem control register.
#define UART_MCR_DTR   0x01
 Data terminal ready.
#define UART_MCR_RTS   0x02
 Request to send.
#define UART_LSR   0x05
 Line status register.
#define UART_LSR_DR   0x01
 Data ready.
#define UART_LSR_THRE   0x20
 Transmitter holding register empty.
#define UART_LSR_TEMT   0x40
 Transmitter empty.
#define UART_SCR   0x07
 Scratch register.
#define UART_DLL   0x00
 Divisor latch (least significant byte)
#define UART_DLM   0x01
 Divisor latch (most significant byte)
#define UART_MAX_BAUD   115200
 Maximum baud rate.

Enumerations

enum  uart_port { COM1 = 1, COM2 = 2, COM3 = 3, COM4 = 4 }
 Symbolic names for port indexes. More...

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
void uart_write (struct uart *uart, unsigned int addr, uint8_t data)
uint8_t uart_read (struct uart *uart, unsigned int addr)
int uart_select (struct uart *uart, unsigned int port)
 Select UART port.
static int uart_data_ready (struct uart *uart)
 Check if received data is ready.
static uint8_t uart_receive (struct uart *uart)
 Receive data.
void uart_transmit (struct uart *uart, uint8_t data)
 Transmit data.
void uart_flush (struct uart *uart)
 Flush data.
int uart_exists (struct uart *uart)
 Check for existence of UART.
int uart_init (struct uart *uart, unsigned int baud, uint8_t lcr)
 Initialise UART.

Detailed Description

16550-compatible UART

Definition in file uart.h.


Define Documentation

#define UART_THR   0x00

Transmitter holding register.

Definition at line 15 of file uart.h.

Referenced by uart_transmit().

#define UART_RBR   0x00

Receiver buffer register.

Definition at line 18 of file uart.h.

Referenced by uart_flush(), and uart_receive().

#define UART_IER   0x01

Interrupt enable register.

Definition at line 21 of file uart.h.

Referenced by uart_init().

#define UART_FCR   0x02

FIFO control register.

Definition at line 24 of file uart.h.

Referenced by uart_init().

#define UART_FCR_FE   0x01

FIFO enable.

Definition at line 25 of file uart.h.

Referenced by uart_init().

#define UART_LCR   0x03

Line control register.

Definition at line 28 of file uart.h.

Referenced by uart_init().

#define UART_LCR_WLS0   0x01

Word length select bit 0.

Definition at line 29 of file uart.h.

#define UART_LCR_WLS1   0x02

Word length select bit 1.

Definition at line 30 of file uart.h.

#define UART_LCR_STB   0x04

Number of stop bits.

Definition at line 31 of file uart.h.

#define UART_LCR_PEN   0x08

Parity enable.

Definition at line 32 of file uart.h.

#define UART_LCR_EPS   0x10

Even parity select.

Definition at line 33 of file uart.h.

#define UART_LCR_DLAB   0x80

Divisor latch access bit.

Definition at line 34 of file uart.h.

Referenced by uart_init().

#define UART_LCR_WORD_LEN (   x)    ( ( (x) - 5 ) << 0 )

Word length.

Definition at line 36 of file uart.h.

#define UART_LCR_STOP_BITS (   x)    ( ( (x) - 1 ) << 2 )

Stop bits.

Definition at line 37 of file uart.h.

#define UART_LCR_PARITY (   x)    ( ( (x) - 0 ) << 3 )

Parity.

Definition at line 38 of file uart.h.

#define UART_LCR_WPS (   word_len,
  parity,
  stop_bits 
)
Value:
( UART_LCR_WORD_LEN ( (word_len) ) |            \
          UART_LCR_PARITY ( (parity) ) |                \
          UART_LCR_STOP_BITS ( (stop_bits) ) )

Calculate line control register value.

Parameters:
word_lenWord length (5-8)
parityParity (0=none, 1=odd, 3=even)
stop_bitsStop bits (1-2)
Return values:
lcrLine control register value

Definition at line 48 of file uart.h.

#define UART_LCR_8N1   UART_LCR_WPS ( 8, 0, 1 )

Default LCR value: 8 data bits, no parity, one stop bit.

Definition at line 54 of file uart.h.

#define UART_MCR   0x04

Modem control register.

Definition at line 57 of file uart.h.

Referenced by uart_init().

#define UART_MCR_DTR   0x01

Data terminal ready.

Definition at line 58 of file uart.h.

Referenced by uart_init().

#define UART_MCR_RTS   0x02

Request to send.

Definition at line 59 of file uart.h.

Referenced by uart_init().

#define UART_LSR   0x05

Line status register.

Definition at line 62 of file uart.h.

Referenced by uart_data_ready(), uart_flush(), and uart_transmit().

#define UART_LSR_DR   0x01

Data ready.

Definition at line 63 of file uart.h.

Referenced by uart_data_ready(), and uart_flush().

#define UART_LSR_THRE   0x20

Transmitter holding register empty.

Definition at line 64 of file uart.h.

Referenced by uart_transmit().

#define UART_LSR_TEMT   0x40

Transmitter empty.

Definition at line 65 of file uart.h.

Referenced by uart_flush().

#define UART_SCR   0x07

Scratch register.

Definition at line 68 of file uart.h.

Referenced by uart_exists().

#define UART_DLL   0x00

Divisor latch (least significant byte)

Definition at line 71 of file uart.h.

Referenced by uart_init().

#define UART_DLM   0x01

Divisor latch (most significant byte)

Definition at line 74 of file uart.h.

Referenced by uart_init().

#define UART_MAX_BAUD   115200

Maximum baud rate.

Definition at line 77 of file uart.h.

Referenced by uart_init().


Enumeration Type Documentation

enum uart_port

Symbolic names for port indexes.

Enumerator:
COM1 
COM2 
COM3 
COM4 

Definition at line 90 of file uart.h.

               {
        COM1 = 1,
        COM2 = 2,
        COM3 = 3,
        COM4 = 4,
};

Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )
void uart_write ( struct uart uart,
unsigned int  addr,
uint8_t  data 
)
uint8_t uart_read ( struct uart uart,
unsigned int  addr 
)
int uart_select ( struct uart uart,
unsigned int  port 
)

Select UART port.

Parameters:
uartUART
portPort number, or 0 to disable
Return values:
rcReturn status code

Definition at line 50 of file x86_uart.c.

References uart::base, ENODEV, NULL, port, rc, uart_base, and uart_exists().

Referenced by gdbserial_configure(), and serial_init().

                                                         {
        int rc;

        /* Set new UART base */
        if ( port >= ( sizeof ( uart_base ) / sizeof ( uart_base[0] ) ) ) {
                rc = -ENODEV;
                goto err;
        }
        uart->base = ( ( void * ) ( intptr_t ) uart_base[port] );

        /* Check that UART exists */
        if ( ( rc = uart_exists ( uart ) ) != 0 )
                goto err;

        return 0;

 err:
        uart->base = NULL;
        return rc;
}
static int uart_data_ready ( struct uart uart) [inline, static]

Check if received data is ready.

Parameters:
uartUART
Return values:
readyData is ready

Definition at line 109 of file uart.h.

References UART_LSR, UART_LSR_DR, and uart_read().

Referenced by gdbserial_recv(), serial_getchar(), and serial_iskey().

                                                        {
        uint8_t lsr;

        lsr = uart_read ( uart, UART_LSR );
        return ( lsr & UART_LSR_DR );
}
static uint8_t uart_receive ( struct uart uart) [inline, static]

Receive data.

Parameters:
uartUART
Return values:
dataData

Definition at line 122 of file uart.h.

References UART_RBR, and uart_read().

Referenced by gdbserial_recv(), and serial_getchar().

                                                         {

        return uart_read ( uart, UART_RBR );
}
void uart_transmit ( struct uart uart,
uint8_t  data 
)

Transmit data.

Parameters:
uartUART
dataData

Definition at line 48 of file uart.c.

References mdelay(), UART_LSR, UART_LSR_THRE, uart_read(), UART_THR, UART_THRE_TIMEOUT_MS, and uart_write().

Referenced by gdbserial_send(), int21(), and serial_putchar().

                                                       {
        unsigned int i;
        uint8_t lsr;

        /* Wait for transmitter holding register to become empty */
        for ( i = 0 ; i < UART_THRE_TIMEOUT_MS ; i++ ) {
                lsr = uart_read ( uart, UART_LSR );
                if ( lsr & UART_LSR_THRE )
                        break;
                mdelay ( 1 );
        }

        /* Transmit data (even if we timed out) */
        uart_write ( uart, UART_THR, data );
}
void uart_flush ( struct uart uart)

Flush data.

Parameters:
uartUART

Definition at line 69 of file uart.c.

References UART_LSR, UART_LSR_DR, UART_LSR_TEMT, UART_RBR, uart_read(), and UART_TEMT_TIMEOUT_MS.

Referenced by serial_shutdown(), and uart_init().

                                      {
        unsigned int i;
        uint8_t lsr;

        /* Wait for transmitter and receiver to become empty */
        for ( i = 0 ; i < UART_TEMT_TIMEOUT_MS ; i++ ) {
                uart_read ( uart, UART_RBR );
                lsr = uart_read ( uart, UART_LSR );
                if ( ( lsr & UART_LSR_TEMT ) && ! ( lsr & UART_LSR_DR ) )
                        break;
        }
}
int uart_exists ( struct uart uart)

Check for existence of UART.

Parameters:
uartUART
Return values:
rcReturn status code

Definition at line 88 of file uart.c.

References uart::base, ENODEV, uart_read(), UART_SCR, and uart_write().

Referenced by uart_init(), and uart_select().

                                      {

        /* Fail if no UART port is defined */
        if ( ! uart->base )
                return -ENODEV;

        /* Fail if UART scratch register seems not to be present */
        uart_write ( uart, UART_SCR, 0x18 );
        if ( uart_read ( uart, UART_SCR ) != 0x18 )
                return -ENODEV;
        uart_write ( uart, UART_SCR, 0xae );
        if ( uart_read ( uart, UART_SCR ) != 0xae )
                return -ENODEV;

        return 0;
}
int uart_init ( struct uart uart,
unsigned int  baud,
uint8_t  lcr 
)

Initialise UART.

Parameters:
uartUART
baudBaud rate, or zero to leave unchanged
lcrLine control register value, or zero to leave unchanged
Return values:
rcReturn status code

Definition at line 113 of file uart.c.

References uart::divisor, uart::lcr, rc, UART_DLL, UART_DLM, uart_exists(), UART_FCR, UART_FCR_FE, uart_flush(), UART_IER, UART_LCR, UART_LCR_DLAB, UART_MAX_BAUD, UART_MCR, UART_MCR_DTR, UART_MCR_RTS, uart_read(), and uart_write().

Referenced by gdbserial_configure(), and serial_init().

                                                                    {
        uint8_t dlm;
        uint8_t dll;
        int rc;

        /* Check for existence of UART */
        if ( ( rc = uart_exists ( uart ) ) != 0 )
                return rc;

        /* Configure divisor and line control register, if applicable */
        if ( ! lcr )
                lcr = uart_read ( uart, UART_LCR );
        uart->lcr = lcr;
        uart_write ( uart, UART_LCR, ( lcr | UART_LCR_DLAB ) );
        if ( baud ) {
                uart->divisor = ( UART_MAX_BAUD / baud );
                dlm = ( ( uart->divisor >> 8 ) & 0xff );
                dll = ( ( uart->divisor >> 0 ) & 0xff );
                uart_write ( uart, UART_DLM, dlm );
                uart_write ( uart, UART_DLL, dll );
        } else {
                dlm = uart_read ( uart, UART_DLM );
                dll = uart_read ( uart, UART_DLL );
                uart->divisor = ( ( dlm << 8 ) | dll );
        }
        uart_write ( uart, UART_LCR, ( lcr & ~UART_LCR_DLAB ) );

        /* Disable interrupts */
        uart_write ( uart, UART_IER, 0 );

        /* Enable FIFOs */
        uart_write ( uart, UART_FCR, UART_FCR_FE );

        /* Assert DTR and RTS */
        uart_write ( uart, UART_MCR, ( UART_MCR_DTR | UART_MCR_RTS ) );

        /* Flush any stale data */
        uart_flush ( uart );

        return 0;
}