Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
UART

UART peripheral driver. More...

Data Structures

struct  qm_uart_config_t
 UART configuration structure type. More...
 
struct  qm_uart_transfer_t
 UART asynchronous transfer structure. More...
 

Enumerations

enum  qm_uart_lc_t {
  QM_UART_LC_5N1 = 0x00, QM_UART_LC_5N1_5 = 0x04, QM_UART_LC_5E1 = 0x18, QM_UART_LC_5E1_5 = 0x1c,
  QM_UART_LC_5O1 = 0x08, QM_UART_LC_5O1_5 = 0x0c, QM_UART_LC_6N1 = 0x01, QM_UART_LC_6N2 = 0x05,
  QM_UART_LC_6E1 = 0x19, QM_UART_LC_6E2 = 0x1d, QM_UART_LC_6O1 = 0x09, QM_UART_LC_6O2 = 0x0d,
  QM_UART_LC_7N1 = 0x02, QM_UART_LC_7N2 = 0x06, QM_UART_LC_7E1 = 0x1a, QM_UART_LC_7E2 = 0x1e,
  QM_UART_LC_7O1 = 0x0a, QM_UART_LC_7O2 = 0x0e, QM_UART_LC_8N1 = 0x03, QM_UART_LC_8N2 = 0x07,
  QM_UART_LC_8E1 = 0x1b, QM_UART_LC_8E2 = 0x1f, QM_UART_LC_8O1 = 0x0b, QM_UART_LC_8O2 = 0x0f
}
 UART Line control. More...
 
enum  qm_uart_status_t {
  QM_UART_IDLE = 0, QM_UART_RX_OE = BIT(1), QM_UART_RX_PE = BIT(2), QM_UART_RX_FE = BIT(3),
  QM_UART_RX_BI = BIT(4), QM_UART_TX_BUSY = BIT(5), QM_UART_RX_BUSY = BIT(6), QM_UART_TX_NFULL = BIT(7),
  QM_UART_RX_NEMPTY = BIT(8)
}
 UART Status type. More...
 

Functions

int qm_uart_set_config (const qm_uart_t uart, const qm_uart_config_t *const cfg)
 Set UART configuration. More...
 
int qm_uart_get_status (const qm_uart_t uart, qm_uart_status_t *const status)
 Get UART bus status. More...
 
int qm_uart_write (const qm_uart_t uart, const uint8_t data)
 UART character data write. More...
 
int qm_uart_read (const qm_uart_t uart, uint8_t *const data, qm_uart_status_t *const status)
 UART character data read. More...
 
int qm_uart_write_non_block (const qm_uart_t uart, const uint8_t data)
 UART character data write. More...
 
int qm_uart_read_non_block (const qm_uart_t uart, uint8_t *const data)
 UART character data read. More...
 
int qm_uart_write_buffer (const qm_uart_t uart, const uint8_t *const data, const uint32_t len)
 UART multi-byte data write. More...
 
int qm_uart_irq_write (const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
 Interrupt based TX on UART. More...
 
int qm_uart_irq_read (const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
 Interrupt based RX on UART. More...
 
int qm_uart_irq_write_terminate (const qm_uart_t uart)
 Terminate UART IRQ TX transfer. More...
 
int qm_uart_irq_read_terminate (const qm_uart_t uart)
 Terminate UART IRQ RX transfer. More...
 
int qm_uart_dma_channel_config (const qm_uart_t uart, const qm_dma_t dma_ctrl_id, const qm_dma_channel_id_t dma_channel_id, const qm_dma_channel_direction_t dma_channel_direction)
 Configure a DMA channel with a specific transfer direction. More...
 
int qm_uart_dma_write (const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
 Perform a DMA-based TX transfer on the UART bus. More...
 
int qm_uart_dma_read (const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
 Perform a DMA-based RX transfer on the UART bus. More...
 
int qm_uart_dma_write_terminate (const qm_uart_t uart)
 Terminate the current DMA TX transfer on the UART bus. More...
 
int qm_uart_dma_read_terminate (const qm_uart_t uart)
 Terminate the current DMA RX transfer on the UART bus. More...
 
int qm_uart_save_context (const qm_uart_t uart, qm_uart_context_t *const ctx)
 Save UART context. More...
 
int qm_uart_restore_context (const qm_uart_t uart, const qm_uart_context_t *const ctx)
 Restore UART context. More...
 

Detailed Description

UART peripheral driver.

Enumeration Type Documentation

UART Line control.

Enumerator
QM_UART_LC_5N1 

5 data bits, no parity, 1 stop bit.

QM_UART_LC_5N1_5 

5 data bits, no parity, 1.5 stop bits.

QM_UART_LC_5E1 

5 data bits, even parity, 1 stop bit.

QM_UART_LC_5E1_5 

5 data bits, even par., 1.5 stop bits.

QM_UART_LC_5O1 

5 data bits, odd parity, 1 stop bit.

QM_UART_LC_5O1_5 

5 data bits, odd parity, 1.5 stop bits.

QM_UART_LC_6N1 

6 data bits, no parity, 1 stop bit.

QM_UART_LC_6N2 

6 data bits, no parity, 2 stop bits.

QM_UART_LC_6E1 

6 data bits, even parity, 1 stop bit.

QM_UART_LC_6E2 

6 data bits, even parity, 2 stop bits.

QM_UART_LC_6O1 

6 data bits, odd parity, 1 stop bit.

QM_UART_LC_6O2 

6 data bits, odd parity, 2 stop bits.

QM_UART_LC_7N1 

7 data bits, no parity, 1 stop bit.

QM_UART_LC_7N2 

7 data bits, no parity, 2 stop bits.

QM_UART_LC_7E1 

7 data bits, even parity, 1 stop bit.

QM_UART_LC_7E2 

7 data bits, even parity, 2 stop bits.

QM_UART_LC_7O1 

7 data bits, odd parity, 1 stop bit.

QM_UART_LC_7O2 

7 data bits, odd parity, 2 stop bits.

QM_UART_LC_8N1 

8 data bits, no parity, 1 stop bit.

QM_UART_LC_8N2 

8 data bits, no parity, 2 stop bits.

QM_UART_LC_8E1 

8 data bits, even parity, 1 stop bit.

QM_UART_LC_8E2 

8 data bits, even parity, 2 stop bits.

QM_UART_LC_8O1 

8 data bits, odd parity, 1 stop bit.

QM_UART_LC_8O2 

8 data bits, odd parity, 2 stop bits.

Definition at line 22 of file qm_uart.h.

UART Status type.

Enumerator
QM_UART_IDLE 

IDLE.

QM_UART_RX_OE 

Receiver overrun.

QM_UART_RX_PE 

Parity error.

QM_UART_RX_FE 

Framing error.

QM_UART_RX_BI 

Break interrupt.

QM_UART_TX_BUSY 

TX Busy flag.

QM_UART_RX_BUSY 

RX Busy flag.

QM_UART_TX_NFULL 

TX FIFO not full.

QM_UART_RX_NEMPTY 

RX FIFO not empty.

Definition at line 52 of file qm_uart.h.

Function Documentation

int qm_uart_dma_channel_config ( const qm_uart_t  uart,
const qm_dma_t  dma_ctrl_id,
const qm_dma_channel_id_t  dma_channel_id,
const qm_dma_channel_direction_t  dma_channel_direction 
)

Configure a DMA channel with a specific transfer direction.

The user is responsible for managing the allocation of the pool of DMA channels provided by each DMA core to the different peripheral drivers that require them.

This function configures DMA channel parameters that are unlikely to change between transfers, like transaction width, burst size, and handshake interface parameters. The user will likely only call this function once for the lifetime of an application unless the channel needs to be repurposed.

Note that qm_dma_init() must first be called before configuring a channel.

Parameters
[in]uartUART identifier.
[in]dma_ctrl_idDMA controller identifier.
[in]dma_channel_idDMA channel identifier.
[in]dma_channel_directionDMA channel direction, either QM_DMA_MEMORY_TO_PERIPHERAL (write transfer) or QM_DMA_PERIPHERAL_TO_MEMORY (read transfer).
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 530 of file qm_uart.c.

References qm_dma_channel_config_t::callback_context, qm_dma_channel_config_t::channel_direction, qm_dma_channel_config_t::client_callback, qm_dma_channel_config_t::destination_burst_length, qm_dma_channel_config_t::destination_transfer_width, DMA_HW_IF_UART_A_RX, DMA_HW_IF_UART_A_TX, DMA_HW_IF_UART_B_RX, DMA_HW_IF_UART_B_TX, qm_dma_channel_config_t::handshake_interface, qm_dma_channel_config_t::handshake_polarity, QM_DMA_BURST_TRANS_LENGTH_8, QM_DMA_CHANNEL_NUM, qm_dma_channel_set_config(), QM_DMA_HANDSHAKE_POLARITY_LOW, QM_DMA_MEMORY_TO_PERIPHERAL, QM_DMA_NUM, QM_DMA_PERIPHERAL_TO_MEMORY, QM_DMA_TRANS_WIDTH_8, QM_DMA_TYPE_SINGLE, qm_dma_channel_config_t::source_burst_length, qm_dma_channel_config_t::source_transfer_width, and qm_dma_channel_config_t::transfer_type.

int qm_uart_dma_read ( const qm_uart_t  uart,
const qm_uart_transfer_t *const  xfer 
)

Perform a DMA-based RX transfer on the UART bus.

In order for this call to succeed, previously the user must have configured a DMA channel with direction QM_DMA_PERIPHERAL_TO_MEMORY to be used on this UART, calling qm_uart_dma_channel_config(). The transfer length is limited to 4KB.

Parameters
[in]uartUART identifer.
[in]xferStructure containing a pre-allocated read buffer and callback functions. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 625 of file qm_uart.c.

References qm_dma_transfer_t::block_size, qm_uart_transfer_t::data, qm_uart_transfer_t::data_len, qm_dma_transfer_t::destination_address, qm_uart_reg_t::iir_fcr, qm_dma_transfer_set_config(), qm_dma_transfer_start(), qm_uart_reg_t::rbr_thr_dll, and qm_dma_transfer_t::source_address.

int qm_uart_dma_read_terminate ( const qm_uart_t  uart)

Terminate the current DMA RX transfer on the UART bus.

This will cause the relevant callbacks to be called.

Parameters
[in]uartUART identifer.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 668 of file qm_uart.c.

References qm_dma_transfer_terminate().

int qm_uart_dma_write ( const qm_uart_t  uart,
const qm_uart_transfer_t *const  xfer 
)

Perform a DMA-based TX transfer on the UART bus.

In order for this call to succeed, previously the user must have configured a DMA channel with direction QM_DMA_MEMORY_TO_PERIPHERAL to be used on this UART, calling qm_uart_dma_channel_config(). The transfer length is limited to 4KB.

Note that this function uses the UART TX FIFO empty interrupt and therefore, in addition to the DMA interrupts, the ISR of the corresponding UART must be registered before using this function.

Parameters
[in]uartUART identifer.
[in]xferStructure containing a pre-allocated write buffer and callback functions. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 591 of file qm_uart.c.

References qm_dma_transfer_t::block_size, qm_uart_transfer_t::data, qm_uart_transfer_t::data_len, qm_dma_transfer_t::destination_address, qm_uart_reg_t::iir_fcr, qm_dma_transfer_set_config(), qm_dma_transfer_start(), qm_uart_reg_t::rbr_thr_dll, and qm_dma_transfer_t::source_address.

int qm_uart_dma_write_terminate ( const qm_uart_t  uart)

Terminate the current DMA TX transfer on the UART bus.

This will cause the relevant callbacks to be called.

Parameters
[in]uartUART identifer.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 658 of file qm_uart.c.

References qm_dma_transfer_terminate().

int qm_uart_get_status ( const qm_uart_t  uart,
qm_uart_status_t *const  status 
)

Get UART bus status.

Retrieve UART interface status. Return QM_UART_BUSY if transmitting data; QM_UART_IDLE if available for transfer; QM_UART_TX_ERROR if an error has occurred in transmission.

The user may call this function before performing an UART transfer in order to guarantee that the UART interface is available.

Parameters
[in]uartWhich UART to read the status of.
[out]statusCurrent UART status. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 253 of file qm_uart.c.

References qm_uart_reg_t::lsr, QM_UART_RX_BUSY, QM_UART_TX_BUSY, and qm_uart_reg_t::scr.

int qm_uart_irq_read ( const qm_uart_t  uart,
const qm_uart_transfer_t *const  xfer 
)

Interrupt based RX on UART.

Perform an interrupt based RX transfer on the UART bus. The function will read back the RX FIFOs on UART empty interrupts.

Parameters
[in]uartUART identifier.
[in]xferStructure containing pre-allocated read buffer and callback functions. The structure must not be NULL and must be kept valid until the transfer is complete.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 389 of file qm_uart.c.

References qm_uart_reg_t::ier_dlh, and qm_uart_reg_t::iir_fcr.

int qm_uart_irq_read_terminate ( const qm_uart_t  uart)

Terminate UART IRQ RX transfer.

Terminate the current IRQ RX transfer on the UART bus. This will cause the relevant callbacks to be called.

Parameters
[in]uartUART identifier.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 429 of file qm_uart.c.

References qm_uart_transfer_t::callback, qm_uart_transfer_t::callback_data, qm_uart_reg_t::ier_dlh, and QM_UART_IDLE.

int qm_uart_irq_write ( const qm_uart_t  uart,
const qm_uart_transfer_t *const  xfer 
)

Interrupt based TX on UART.

Perform an interrupt based TX transfer on the UART bus. The function will replenish the TX FIFOs on UART empty interrupts.

Parameters
[in]uartUART identifier.
[in]xferStructure containing pre-allocated write buffer and callback functions. The structure must not be NULL and must be kept valid until the transfer is complete.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 368 of file qm_uart.c.

References qm_uart_reg_t::ier_dlh, and qm_uart_reg_t::iir_fcr.

int qm_uart_irq_write_terminate ( const qm_uart_t  uart)

Terminate UART IRQ TX transfer.

Terminate the current IRQ TX transfer on the UART bus. This will cause the relevant callbacks to be called.

Parameters
[in]uartUART identifier.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 412 of file qm_uart.c.

References qm_uart_transfer_t::callback, qm_uart_transfer_t::callback_data, qm_uart_reg_t::ier_dlh, and QM_UART_IDLE.

int qm_uart_read ( const qm_uart_t  uart,
uint8_t *const  data,
qm_uart_status_t *const  status 
)

UART character data read.

Perform a single character read from the UART interface. This is a blocking synchronous call.

Parameters
[in]uartUART identifer.
[out]dataData to read from UART. This must not be NULL.
[out]statusUART specific status.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 296 of file qm_uart.c.

References qm_uart_reg_t::lsr, and qm_uart_reg_t::rbr_thr_dll.

int qm_uart_read_non_block ( const qm_uart_t  uart,
uint8_t *const  data 
)

UART character data read.

Perform a single character read from the UART interface. This is a non-blocking synchronous call.

Parameters
[in]uartUART identifer.
[out]dataCharacter read. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 331 of file qm_uart.c.

References qm_uart_reg_t::rbr_thr_dll.

int qm_uart_restore_context ( const qm_uart_t  uart,
const qm_uart_context_t *const  ctx 
)

Restore UART context.

Restore the configuration of the specified UART peripheral after exiting sleep.

FIFO control register cannot be read back, the default configuration is applied for this register. Application will need to restore its own parameters.

Parameters
[in]uartUART port index.
[in]ctxUART context structure. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 742 of file qm_uart.c.

References qm_uart_reg_t::dlf, qm_uart_context_t::dlf, qm_uart_context_t::dlh, qm_uart_context_t::dll, qm_uart_reg_t::htx, qm_uart_context_t::htx, qm_uart_context_t::ier, qm_uart_reg_t::ier_dlh, qm_uart_reg_t::iir_fcr, qm_uart_reg_t::lcr, qm_uart_context_t::lcr, qm_uart_reg_t::mcr, qm_uart_context_t::mcr, qm_uart_reg_t::rbr_thr_dll, qm_uart_reg_t::scr, and qm_uart_context_t::scr.

int qm_uart_save_context ( const qm_uart_t  uart,
qm_uart_context_t *const  ctx 
)

Save UART context.

Saves the configuration of the specified UART peripheral before entering sleep.

Parameters
[in]uartUART port index.
[out]ctxUART context structure. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 734 of file qm_uart.c.

References qm_uart_reg_t::dlf, qm_uart_context_t::dlf, qm_uart_context_t::dlh, qm_uart_context_t::dll, qm_uart_reg_t::htx, qm_uart_context_t::htx, qm_uart_context_t::ier, qm_uart_reg_t::ier_dlh, qm_uart_reg_t::lcr, qm_uart_context_t::lcr, qm_uart_reg_t::mcr, qm_uart_context_t::mcr, qm_uart_reg_t::rbr_thr_dll, qm_uart_reg_t::scr, and qm_uart_context_t::scr.

int qm_uart_set_config ( const qm_uart_t  uart,
const qm_uart_config_t *const  cfg 
)

Set UART configuration.

Change the configuration of a UART module. This includes line control, baud rate and hardware flow control.

Parameters
[in]uartWhich UART module to configure.
[in]cfgNew configuration for UART. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 215 of file qm_uart.c.

References qm_uart_config_t::baud_divisor, qm_uart_reg_t::dlf, qm_uart_config_t::hw_fc, qm_uart_reg_t::ier_dlh, qm_uart_reg_t::iir_fcr, qm_uart_reg_t::lcr, qm_uart_config_t::line_control, qm_uart_reg_t::lsr, qm_uart_reg_t::mcr, and qm_uart_reg_t::rbr_thr_dll.

int qm_uart_write ( const qm_uart_t  uart,
const uint8_t  data 
)

UART character data write.

Perform a single character write on the UART interface. This is a blocking synchronous call.

Parameters
[in]uartUART identifer.
[in]dataData to write to UART.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 280 of file qm_uart.c.

References qm_uart_reg_t::lsr, and qm_uart_reg_t::rbr_thr_dll.

int qm_uart_write_buffer ( const qm_uart_t  uart,
const uint8_t *const  data,
const uint32_t  len 
)

UART multi-byte data write.

Perform a write on the UART interface. This is a blocking synchronous call. The function will block until all data has been transferred.

Parameters
[in]uartUART controller identifier
[in]dataData to write to UART. This must not be NULL.
[in]lenLength of data to write to UART.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 342 of file qm_uart.c.

References qm_uart_reg_t::lsr, and qm_uart_reg_t::rbr_thr_dll.

int qm_uart_write_non_block ( const qm_uart_t  uart,
const uint8_t  data 
)

UART character data write.

Perform a single character write on the UART interface. This is a non-blocking synchronous call.

Parameters
[in]uartUART identifier.
[in]dataData to write to UART.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 320 of file qm_uart.c.

References qm_uart_reg_t::rbr_thr_dll.