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

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Enumerations | Functions
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

enum qm_uart_lc_t

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.

enum qm_uart_status_t

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] | uart | UART identifier.
  [in] | dma_ctrl_id | DMA controller identifier.
  [in] | dma_channel_id | DMA channel identifier.
  [in] | dma_channel_direction | DMA 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

  0 | on success.
  Negative | errno 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] | uart | UART identifer.
  [in] | xfer | Structure containing a pre-allocated read buffer and callback functions. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifer.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifer.
  [in] | xfer | Structure containing a pre-allocated write buffer and callback functions. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifer.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | Which UART to read the status of.
  [out] | status | Current UART status. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifier.
  [in] | xfer | Structure 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

  0 | on success.
  Negative | errno 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] | uart | UART identifier.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifier.
  [in] | xfer | Structure 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

  0 | on success.
  Negative | errno 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] | uart | UART identifier.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifer.
  [out] | data | Data to read from UART. This must not be NULL.
  [out] | status | UART specific status.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifer.
  [out] | data | Character read. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART port index.
  [in] | ctx | UART context structure. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART port index.
  [out] | ctx | UART context structure. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | Which UART module to configure.
  [in] | cfg | New configuration for UART. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifer.
  [in] | data | Data to write to UART.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART controller identifier
  [in] | data | Data to write to UART. This must not be NULL.
  [in] | len | Length of data to write to UART.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | uart | UART identifier.
  [in] | data | Data to write to UART.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 320 of file qm_uart.c.

References qm_uart_reg_t::rbr_thr_dll.