UART
|
Detailed Description
- Date
- 2015-12-17
NOTE: This file is generated by DAVE. Any manual modification done to this file will be lost when the code is regenerated.
Definition in file UART.c.
#include "uart.h"
Functions | |
DAVE_APP_VERSION_t | UART_GetAppVersion () |
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_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_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_SetBaudrate (const UART_t *handle, uint32_t baud, uint32_t oversampling) |
Changes the baudrate of UART channel. More... | |
Function Documentation
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.
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.
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.