UART
|
DAVE_APP_VERSION_t | UART_GetAppVersion (void) |
Get the UART APP version. More... | |
UART_STATUS_t | UART_Init (const UART_t *const handle) |
Initializes the UART module as per the configuration made in UI. More... | |
UART_STATUS_t | UART_Receive (const UART_t *const handle, uint8_t *data_ptr, uint32_t count) |
Registers a request for receiving data over UART channel. More... | |
UART_STATUS_t | UART_Transmit (const UART_t *const handle, uint8_t *data_ptr, uint32_t count) |
Registers a request for transmitting data over UART channel. More... | |
UART_STATUS_t | UART_SetBaudrate (const UART_t *handle, uint32_t baud, uint32_t oversampling) |
Changes the baudrate of UART channel. More... | |
__STATIC_INLINE uint32_t | UART_GetTXFIFOStatus (const UART_t *const handle) |
Gets the transmit FIFO event flags. More... | |
__STATIC_INLINE uint8_t | UART_GetReceivedWord (const UART_t *const handle) |
Provides the received data from receive buffer. More... | |
__STATIC_INLINE void | UART_TransmitWord (const UART_t *const handle, uint8_t data) |
Transmits a word of data. More... | |
__STATIC_INLINE void | UART_EnableEvent (const UART_t *const handle, uint32_t events) |
Enables the selected protocol events for interrupt generation. More... | |
__STATIC_INLINE void | UART_DisableEvent (const UART_t *const handle, uint32_t events) |
Disables selected events from generating interrupt. More... | |
__STATIC_INLINE bool | UART_IsTXFIFOFull (const UART_t *const handle) |
Checks if the transmit FIFO is full. More... | |
__STATIC_INLINE bool | UART_IsRXFIFOEmpty (const UART_t *const handle) |
Checks if the receive FIFO is empty. More... | |
__STATIC_INLINE void | UART_SetTXFIFOTriggerLimit (const UART_t *const handle, uint32_t limit) |
Configures trigger limit for the transmit FIFO. More... | |
__STATIC_INLINE void | UART_SetRXFIFOTriggerLimit (const UART_t *const handle, uint32_t limit) |
Configures trigger limit for the receive FIFO. More... | |
__STATIC_INLINE uint32_t | UART_GetRXFIFOStatus (const UART_t *const handle) |
Gets the status of event flags related to receive FIFO. More... | |
__STATIC_INLINE void | UART_ClearTXFIFOStatus (const UART_t *const handle, const uint32_t flag) |
Function clears the specified FIFO event flag related to transmit FIFO. More... | |
__STATIC_INLINE void | UART_ClearRXFIFOStatus (const UART_t *const handle, const uint32_t flag) |
Function clears the specified FIFO event flag related to receive FIFO. It should be used to clear the status of standard receive buffer interrupt, alternative receive buffer interupt and receive buffer error interrupt flags. More... | |
__STATIC_INLINE uint32_t | UART_GetFlagStatus (const UART_t *const handle, uint32_t protocol_status) |
Provides the status of protocol events. More... | |
__STATIC_INLINE void | UART_ClearFlag (const UART_t *const handle, const uint32_t protocol_status) |
Clears the event status in the register(PSR_ASCMode). More... | |
__STATIC_INLINE bool | UART_IsTxBusy (const UART_t *const handle) |
Checks if the transmission is in progress. More... | |
__STATIC_INLINE bool | UART_IsRxBusy (const UART_t *const handle) |
Checks if data reception is in progress. More... | |
Detailed Description
Methods
Function Documentation
__STATIC_INLINE void UART_ClearFlag | ( | const UART_t *const | handle, |
const uint32_t | protocol_status | ||
) |
Clears the event status in the register(PSR_ASCMode).
- Parameters
-
handle UART APP handle pointer of type UART_t protocol_status Event whose status is to be cleared.
Range: Use type XMC_UART_CH_STATUS_FLAG_t for input. Multiple events can be combined using OR operation.
- Returns
- None
- Description:
- Clears a given protocol event flag bit using the PSCR register. This function is an inline wrapper for the API provided by xmc_uart.h file. The user should mask the input value based on the events to be cleared.
Example Usage:
Definition at line 2046 of file UART.h.
References UART::channel.
__STATIC_INLINE void UART_ClearRXFIFOStatus | ( | const UART_t *const | handle, |
const uint32_t | flag | ||
) |
Function clears the specified FIFO event flag related to receive FIFO. It should be used to clear the status of standard receive buffer interrupt, alternative receive buffer interupt and receive buffer error interrupt flags.
- Parameters
-
handle UART APP handle pointer of type UART_t flag Value with event bits at the bit positions in TRBSR register to be cleared.
Range: Use type XMC_USIC_CH_RXFIFO_EVENT_t for providing events. Multiple events can be input by using OR operation.
- Returns
- None
- Description:
- Function clears a status bit in TRBSR using the TRBSCR register. The function does not mask the input value to clear only receive buffer events. So user should appropriately mask the input value before calling the function.
Example Usage:
Definition at line 1899 of file UART.h.
References UART::channel.
__STATIC_INLINE void UART_ClearTXFIFOStatus | ( | const UART_t *const | handle, |
const uint32_t | flag | ||
) |
Function clears the specified FIFO event flag related to transmit FIFO.
- Parameters
-
handle UART APP handle pointer of type UART_t flag Value with event bits at their bit positions in TRBSR register to be cleared.
Range: Use type XMC_USIC_CH_TXFIFO_EVENT_t. Multiple events can be combined using OR operation.
- Returns
- None
- Description:
- Function clears a status bit in TRBSR register using the TRBSCR register. But the function does not mask the input value with the bit positions restricted to transmit FIFO status bits. User should ensure that the input value is appropriately masked.
Example Usage:
Definition at line 1828 of file UART.h.
References UART::channel.
__STATIC_INLINE void UART_DisableEvent | ( | const UART_t *const | handle, |
uint32_t | events | ||
) |
Disables selected events from generating interrupt.
- Parameters
-
handle UART APP handle pointer of type UART_t events Events to be disabled from generating interrupt.
: Use type to select the event. Multiple events can be combined using the bitwise OR operation.
- Returns
- None
- Description:
- Events are disabled by clearing their respective bits in either CCR, TBCTR or RBCTR.
Example Usage:
Definition at line 1432 of file UART.h.
References UART::channel.
__STATIC_INLINE void UART_EnableEvent | ( | const UART_t *const | handle, |
uint32_t | events | ||
) |
Enables the selected protocol events for interrupt generation.
- Parameters
-
handle UART APP handle pointer of type UART_t events Protocol events to be enabled for interrupt generation.
: Use type to select the event. Multiple events can be combined using the bitwise OR operation.
- Returns
- None
- Description:
- Enables the events by configuring CCR or PCR register based on the event. When the event is enabled, an interrupt can be generated on occurrence of the event. The API should be used only for Direct mode related events. Using this API for non Direct mode may not yield expected result.
Example Usage:
Definition at line 1369 of file UART.h.
References UART::channel.
DAVE_APP_VERSION_t UART_GetAppVersion | ( | void | ) |
Get the UART APP version.
- Returns
- DAVE_APP_VERSION_t APP version information (major, minor and patch number)
Example Usage:
__STATIC_INLINE uint32_t UART_GetFlagStatus | ( | const UART_t *const | handle, |
uint32_t | protocol_status | ||
) |
Provides the status of protocol events.
- Parameters
-
handle UART APP handle pointer of type UART_t protocol_status Event whose status is to be read.
Range: Use type XMC_UART_CH_STATUS_FLAG_t for input. Multiple events can be combined using OR operation.
- Returns
- uint32_t: Status of selected protocol events read from PSR_ASCMode register.
Range: Use type XMC_UART_CH_STATUS_FLAG_t for comparing the return value with event bitmasks. Status of multiple events can be checked by combining enum values using OR operation while comparing.
- Description:
- Reads the protocol status bits from the register PSR_ASCMode and compares the values with the input value of selected events. Returns the masked value of selected events with the status register value. This function is an inline wrapper for the API provided by xmc_uart.h file.
Example Usage:
Definition at line 1979 of file UART.h.
References UART::channel.
__STATIC_INLINE uint8_t UART_GetReceivedWord | ( | const UART_t *const | handle | ) |
Provides the received data from receive buffer.
- Returns
- uint8_t: Data read from RBUF.
- Description:
- This can be used in receive mode "Direct" to read the received data. If Rx FIFO is not configured, function reads the value of RBUF register. Otherwise it reads the data from OUTR register. User can poll for receive event or configure an interrupt by connecting the external INTERRUPT APP to receive event signals. This API can be used inside the ISR to read the received data.
Example Usage:
Definition at line 1244 of file UART.h.
References UART::channel.
__STATIC_INLINE uint32_t UART_GetRXFIFOStatus | ( | const UART_t *const | handle | ) |
Gets the status of event flags related to receive FIFO.
- Returns
- uint32_t: Status of standard receive buffer event, alternative receive buffer event and receive buffer error event in their bit positions in TRBSR register.
Range: Use type XMC_USIC_CH_RXFIFO_EVENT_t for event bitmasks. Multiple events' status can be combined for comparison using OR operation.
- Description:
- It provides the status of standard receive buffer event, alternative receive buffer event and receive buffer error event. Function masks the TRBSR register with the bitmask of SRBI, ARBI and RBERI flags. User has to mask the bits of interest before checking the status.
Example Usage:
Definition at line 1766 of file UART.h.
References UART::channel.
__STATIC_INLINE uint32_t UART_GetTXFIFOStatus | ( | const UART_t *const | handle | ) |
Gets the transmit FIFO event flags.
- Returns
- uint32_t: Status of the STBI and TBERI bits in TRBSR register in their bit positions.
Range: Use type XMC_USIC_CH_TXFIFO_EVENT_t for the bitmask of events.
- Description:
- Function reads the value of TRBSR register. It masks the standard transmit buffer interrupt flag and transmit buffer error flag before providing the value. User has to mask the bits of interest before checking the status.
Example Usage:
Definition at line 1153 of file UART.h.
References UART::channel.
UART_STATUS_t UART_Init | ( | const UART_t *const | handle | ) |
Initializes the UART module as per the configuration made in UI.
- Parameters
-
handle Pointer to static and dynamic content of APP configuration.
- Returns
- UART_STATUS_t: Status of UART driver initialization.
UART_STATUS_SUCCESS - on successful initialization.
UART_STATUS_FAILURE - if initialization fails.
UART_STATUS_BUSY - if UART channel is busy.
- Description:
- Initializes IO pins used for the UART communication, configures USIC registers based on the settings provided in the GUI. Calculates divider values PDIV and STEP for a precise baudrate. It also enables configured interrupt flags and service request values.
Example Usage:
Definition at line 143 of file UART.c.
References UART::config, UART_CONFIG::fptr_uart_config, UART::runtime, and UART_STATUS_SUCCESS.
__STATIC_INLINE bool UART_IsRxBusy | ( | const UART_t *const | handle | ) |
Checks if data reception is in progress.
- Returns
- bool: Status of data reception.
Range: true - if reception is ongoing.
false- if reception is not active.
- Description:
- Indicates if the communication channel is configured for receiving data, initiated using UART_Receive, UART_StartReceiveIRQ or UART_StartReceiveDMA API.
Example Usage:
Definition at line 2181 of file UART.h.
References UART::runtime, and UART_RUNTIME::rx_busy.
__STATIC_INLINE bool UART_IsRXFIFOEmpty | ( | const UART_t *const | handle | ) |
Checks if the receive FIFO is empty.
- Returns
- bool Status of receive FIFO filling level. : - if receive FIFO is empty.
- if receive FIFO still has data.
- Description:
- Checks the status using the register TRBSR. Can be used while reading data from the receive FIFO.
Example Usage:
Definition at line 1553 of file UART.h.
References UART::channel.
__STATIC_INLINE bool UART_IsTxBusy | ( | const UART_t *const | handle | ) |
Checks if the transmission is in progress.
- Returns
- bool: Status of data transmission.
Range: true - if transmission is ongoing.
false- if transmission is not active.
- Description:
- Indicates if the communication channel is busy in transmitting data provided using UART_Transmit, UART_StartTransmitIRQ or UART_StartTransmitDMA API.
Example Usage:
Definition at line 2116 of file UART.h.
References UART::runtime, and UART_RUNTIME::tx_busy.
__STATIC_INLINE bool UART_IsTXFIFOFull | ( | const UART_t *const | handle | ) |
Checks if the transmit FIFO is full.
- Returns
- bool Status of transmit FIFO filling level. : - if transmit FIFO is full.
- if transmit FIFO is not full.
- Description:
- Checks the status using the register TRBSR. Can be used while filling data to the transmit FIFO.
Example Usage:
Definition at line 1490 of file UART.h.
References UART::channel.
UART_STATUS_t UART_Receive | ( | const UART_t *const | handle, |
uint8_t * | data_ptr, | ||
uint32_t | count | ||
) |
Registers a request for receiving data over UART channel.
- Parameters
-
handle Pointer to UART_t handle structure data_ptr Pointer to data of type uint8_t. count Total no of bytes to be received.
Range: minimum= 1, maximum= maximum value supported by type uint32_t.
- Returns
- UART_STATUS_t: Status for receive request.
UART_STATUS_SUCCESS if the request is accepted.
UART_STATUS_BUSY if a reception is in progress.
UART_STATUS_BUFFER_INVALID if the data_ptr is NULL or count is 0.
- Description:
- Data will be received asynchronously. After the requested number of data bytes are received, optionally, the user configured callback function will be executed. Data reception is accomplished using the receive mode selected in the UI. Interrupt:
Based on the UI configuration, either standard receive buffer(RBUF) or receive FIFO(OUT) is used for data reception. An interrupt is configured for reading received data from the bus. This function only registers a request to receive a number of data bytes from a USIC channel. If FIFO is configured for reception, the FIFO limit is dynamically configured to optimally utilize the CPU load. Before starting data reception, the receive buffers are flushed. So only those data, received after calling the API, will be placed in the user buffer. When all the requested number of data bytes are received, the configured callback function will be executed. If a callback function is not configured, the user has to poll for the value of the variable, handle->runtime->rx_busy to be false. The value is updated to false when all the requested number of data bytes are received.
DMA:
DMA mode is available only in XMC4x family of microcontrollers. In this mode, a DMA channel is configured for receiving data from standard receive buffer(RBUF) to the user buffer. By calling this API, the DMA channel destination address is configured to the user buffer and the channel is enabled. FIFO will not be used when the receive mode is DMA. Before starting data reception, the receive buffers are flushed. So only those data, received after calling the API, will be placed in the user buffer. When all the requested number of data bytes are received, the configured callback function will be executed. If a callback function is not configured, the user has to poll for the value of the variable, handle->runtime->rx_busy to be false. The value is updated to false when all the requested number of data bytes are received.
Direct
In Direct receive mode, neither interrupt nor DMA is used. The API polls the receive flag to read the received data and waits for all the requested number of bytes to be received. Based on FIFO configuration, either RBUF or OUT register is used for reading received data. Before starting data reception, the receive buffers are flushed. So only those data, received after calling the API, will be placed in the user buffer. Note: In Direct mode, the API blocks the CPU until the count of bytes requested is received. If this behaviour is not desired, use other APIs like UART_GetReceivedWord, UART_GetProtocolStatus etc.
Example Usage:
Definition at line 211 of file UART.c.
References UART::config, UART_CONFIG::receive_mode, UART_STATUS_MODE_MISMATCH, UART_TRANSFER_MODE_DIRECT, UART_TRANSFER_MODE_DMA, and UART_TRANSFER_MODE_INTERRUPT.
UART_STATUS_t UART_SetBaudrate | ( | const UART_t * | handle, |
uint32_t | baud, | ||
uint32_t | oversampling | ||
) |
Changes the baudrate of UART channel.
- Parameters
-
UART_t * Pointer to the UART APP handle. baud Value of new baudrate. oversampling Number of samples to be considered for each symbol. 16 is the standard value.
- Returns
- UART_STATUS_t UART_STATUS_SUCCESS if baudrate changed successfully. UART_STATUS_FAILURE if baudrate could not be changed.
- Description:
- The function stops the channel, calculates the clock divider values to achieve the desired baudrate. Sets the divider values and reconfigures the channel as per the configuration in the UI. The channel is enabled at the end of configuration.
Example Usage: Please disable the receive FIFO in the 'Advanced Settings' tab
Definition at line 388 of file UART.c.
References UART::channel, UART_TX_CONFIG::config, UART::config, UART_CONFIG::mode, UART_TX_CONFIG::pin, UART_TX_CONFIG::port, UART::runtime, UART_RUNTIME::rx_busy, UART_RUNTIME::tx_busy, UART_CONFIG::tx_pin_config, UART_MODE_LOOPBACK, UART_STATUS_BUSY, and UART_STATUS_SUCCESS.
__STATIC_INLINE void UART_SetRXFIFOTriggerLimit | ( | const UART_t *const | handle, |
uint32_t | limit | ||
) |
Configures trigger limit for the receive FIFO.
- Parameters
-
handle UART APP handle pointer of type UART_t limit Value of receive FIFO filling level, transition above which the interrupt should be generated.
: 0 to receive FIFO size.
e.g, If receive FIFO size is 16, and limit is configured as 8, FIFO receive buffer interrupt will be generated when the FIFO filling level rises from 8 to 9.
- Returns
- None
- Description:
- Receive FIFO trigger limit is configured by setting its value in the RBCTR register. Receive FIFO is configured to generate interrupt when the FIFO filling level rises above the trigger limit.
Example Usage:
Definition at line 1699 of file UART.h.
References UART::channel, UART::config, and UART_CONFIG::rx_fifo_size.
__STATIC_INLINE void UART_SetTXFIFOTriggerLimit | ( | const UART_t *const | handle, |
uint32_t | limit | ||
) |
Configures trigger limit for the transmit FIFO.
- Parameters
-
handle UART APP handle pointer of type UART_t limit Value of transmit FIFO filling level, transition below which the interrupt should be generated.
: 0 to transmit FIFO size.
e.g, If transmit FIFO size is 16, and limit is configured as 8, FIFO standard transmit buffer interrupt will be generated when the FIFO filling level drops from 8 to 7.
- Returns
- None
- Description:
- Transmit FIFO trigger limit is configured by setting its value in the TBCTR register. Transmit FIFO is configured to generate interrupt when the FIFO filling level drops below the trigger limit.
Example Usage:
Definition at line 1626 of file UART.h.
References UART::channel, UART::config, and UART_CONFIG::tx_fifo_size.
UART_STATUS_t UART_Transmit | ( | const UART_t *const | handle, |
uint8_t * | data_ptr, | ||
uint32_t | count | ||
) |
Registers a request for transmitting data over UART channel.
- Parameters
-
handle UART APP handle pointer of type UART_t data_ptr Pointer to data of type uint8_t. count Total no of words to be transmitted.
Range: minimum= 1, maximum= maximum supported by uint32_t.
- Returns
- UART_STATUS_t: Status of transmit request.
UART_STATUS_SUCCESS if the request is accepted.
UART_STATUS_BUSY if a transmission is in progress.
UART_STATUS_BUFFER_INVALID if the data_ptr is NULL or count is 0.
Imp Note: Return value should be validated by user to ensure that the request is registered.
- Description:
- Transmits data using the UART channel. Transmission is accomplished using the transmit mode as configured in the UI.
Interrupt:
The data transmission is accomplished using transmit interrupt. User can configure a callback function in the APP UI. When the data is fully transmitted, the callback function will be executed. If transmit FIFO is enabled, the trigger limit is set to 1. So the transmit interrupt will be generated when all the data in FIFO is moved out of FIFO. The APP handle's runtime structure is used to store the data pointer, count, data index and status of transmission. This function only registers a data transmission request if there is no active transmission in progress. Actual data transmission happens in the transmit interrupt service routine. A trigger is generated for the transmit interrupt to start loading the data to the transmit buffer. If transmit FIFO is configured, the data is filled into the FIFO. Transmit interrupt will be generated subsequently when the transmit FIFO is empty. At this point of time, if there is some more data to be transmitted, it is loaded to the FIFO again. When FIFO is not enabled, data is transmitted one byte at a time. On transmission of each byte an interrupt is generated and the next byte is transmitted in the interrupt service routine. Callback function is executed when all the data bytes are transmitted. If a callback function is not configured, user has to poll for the value of tx_busy flag of the APP handle structure( handle->runtime->tx_busy ) to check for the completion of data transmission.
DMA:
A DMA channel is configured to provide data to the UART transmit buffer. This removes the load off the CPU. This API will only configure and enable the DMA channel by specifying the data buffer and count of bytes to transmit. Rest is taken care without the CPU's intervention. User can configure a callback function in the APP UI. When the transmission is complete, the callback function will be executed. FIFO will not be used in DMA mode. Transmit buffer interrupt is configured for triggering the DMA channel. So each byte is transmitted in the background through the DMA channel. If the callback function is not configured, handle->runtime->tx_busy flag can be checked to verify if the transmission is complete. Direct:
Data will be transmitted using polling method. Status flags are used to check if data can be transmitted. Note: In Direct mode, the API blocks the CPU until the count of bytes requested is transmitted. If this behaviour is not desired, use other APIs like UART_TransmitWord, UART_GetProtocolStatus etc.
Example Usage:
Definition at line 170 of file UART.c.
References UART::config, UART_CONFIG::transmit_mode, UART_STATUS_MODE_MISMATCH, UART_TRANSFER_MODE_DIRECT, UART_TRANSFER_MODE_DMA, and UART_TRANSFER_MODE_INTERRUPT.
__STATIC_INLINE void UART_TransmitWord | ( | const UART_t *const | handle, |
uint8_t | data | ||
) |
Transmits a word of data.
- Returns
- None
- Description:
- Transmits a byte of data through the UART channel. If Tx FIFO is configured, the data is placed in the IN[0] register of the USIC channel used. If Tx FIFO is not configured, API waits for the TBUF to be free and then places the data in the TBUF register. User can poll for receive event or configure interrupt by connecting an external INTERRUPT APP. This API can be used inside the ISR to read the received data.
Example Usage:
Definition at line 1305 of file UART.h.
References UART::channel.