MSPM0G1X0X_G3X0X TI-Driver Library
1.20.01.06
|
Modules | |
UART MSPM0G1X0X_G3X0X driver APIs | |
UART MSPM0G1X0X_G3X0X driver supporting APIs | |
UART status codes | |
Data Structures | |
struct | UART_Params |
UART Parameters. More... | |
Typedefs | |
typedef struct UART_Config_ * | UART_Handle |
A handle that is returned from a UART_open() call. | |
typedef void(* | UART_Callback) (UART_Handle handle, void *buf, size_t count, void *userArg, int_fast16_t status) |
The definition of a callback function used by the UART driver when used in UART_Mode_CALLBACK. The callback can occur in task or interrupt context. More... | |
typedef void(* | UART_EventCallback) (UART_Handle handle, uint32_t event, uint32_t data, void *userArg) |
The definition of a callback function used by the UART driver. The callback can occur in task or interrupt context. More... | |
Enumerations | |
enum | UART_Mode { UART_Mode_BLOCKING = 0, UART_Mode_CALLBACK, UART_Mode_NONBLOCKING } |
UART mode settings. More... | |
enum | UART_ReadReturnMode { UART_ReadReturnMode_FULL = 0, UART_ReadReturnMode_PARTIAL } |
UART return mode settings. More... | |
enum | UART_DataLen { UART_DataLen_5 = DL_UART_WORD_LENGTH_5_BITS, UART_DataLen_6 = DL_UART_WORD_LENGTH_6_BITS, UART_DataLen_7 = DL_UART_WORD_LENGTH_7_BITS, UART_DataLen_8 = DL_UART_WORD_LENGTH_8_BITS } |
UART data length settings. More... | |
enum | UART_StopBits { UART_StopBits_1 = DL_UART_STOP_BITS_ONE, UART_StopBits_2 = DL_UART_STOP_BITS_TWO } |
UART stop bit settings. More... | |
enum | UART_Parity { UART_Parity_NONE = DL_UART_PARITY_NONE, UART_Parity_EVEN = DL_UART_PARITY_EVEN, UART_Parity_ODD = DL_UART_PARITY_ODD, UART_Parity_ZERO = DL_UART_PARITY_STICK_ZERO, UART_Parity_ONE = DL_UART_PARITY_STICK_ONE } |
UART parity type settings. More... | |
Functions | |
void | UART_Params_init (UART_Params *params) |
Function to initialize the UART_Params struct to its defaults. More... | |
UART_Handle | UART_open (uint_least8_t index, UART_Params *params) |
Function to initialize a given UART peripheral. More... | |
void | UART_close (UART_Handle handle) |
Function to close a UART peripheral specified by the UART handle. More... | |
int_fast16_t | UART_read (UART_Handle handle, void *buf, size_t size, size_t *bytesRead) |
Function that reads data from a UART. More... | |
int_fast16_t | UART_write (UART_Handle handle, const void *buf, size_t size, size_t *bytesWritten) |
Function that writes data to a UART. More... | |
int_fast16_t | UART_readTimeout (UART_Handle handle, void *buf, size_t size, size_t *bytesRead, uint32_t timeout) |
UART read with timeout. Note that the timeout parameter is different from the hardware read timeout. More... | |
int_fast16_t | UART_writeTimeout (UART_Handle handle, const void *buf, size_t size, size_t *bytesWritten, uint32_t timeout) |
UART write with timeout. Note that the timeout parameter is different from the hardware read timeout. More... | |
void | UART_readCancel (UART_Handle handle) |
Function that cancels a UART_read() function call. More... | |
void | UART_writeCancel (UART_Handle handle) |
Function that cancels a UART_write() function call. More... | |
void | UART_rxDisable (UART_Handle handle) |
Function that disables collecting of RX data into the circular buffer. More... | |
void | UART_rxEnable (UART_Handle handle) |
Function that enables collecting of RX data into the circular buffer. More... | |
void | UART_flushRx (UART_Handle handle) |
Function to flush data in the UART RX FIFO. More... | |
void | UART_getRxCount (UART_Handle handle) |
Get the number of bytes available in the circular buffer. More... | |
The UART header file should be included in an application as follows:
UART has both RX and TX ring buffers for receiving/sending data. UART uses DMA to transfer data between the UART FIFOs and the RX and TX ring buffers in blocking mode. In callback mode, DMA will transfer data straight between the hardware FIFO and the source/destination buffer supplied by the application. NOTE: If the source-buffer for a TX operation resides in flash, the driver will constrain the flash to remain on during idle. The UART APIs for reading and writing data have been made more posix-like. UART provides for event notification, allowing the application to receive TX start and completion events, and RX error events.
To use the UART driver, ensure that the correct driver library for your device is linked in and include this header file as follows:
typedef void(* UART_Callback) (UART_Handle handle, void *buf, size_t count, void *userArg, int_fast16_t status) |
The definition of a callback function used by the UART driver when used in UART_Mode_CALLBACK. The callback can occur in task or interrupt context.
[in] | UART_Handle | UART_Handle. |
[in] | buf | Pointer to read/write buffer. |
[in] | count | Number of elements read/written. |
[in] | userArg | A user supplied argument specified in UART_Params. |
[in] | status | A UART status codes code indicating success or failure of the transfer. |
typedef void(* UART_EventCallback) (UART_Handle handle, uint32_t event, uint32_t data, void *userArg) |
The definition of a callback function used by the UART driver. The callback can occur in task or interrupt context.
[in] | UART_Handle | UART_Handle. |
[in] | event | UART_EVENT that has occurred. |
[in] | data | One of the following
|
[in] | userArg | A user supplied argument specified in UART_Params. |
[in] | status | A UART_STATUS code indicating success or failure of the transfer. |
enum UART_Mode |
UART mode settings.
This enum defines the read and write modes for the configured UART.
Enumerator | |
---|---|
UART_Mode_BLOCKING | UART_write() will block the calling task until all of the data can be accepted by the device driver. UART_read() will block until some data becomes available. |
UART_Mode_CALLBACK | Non-blocking, UART_write() or UART_read() will return immediately. When the transfer has finished, the callback function is called from either the caller's context or from an interrupt context. |
UART_Mode_NONBLOCKING | Non-blocking, UART_write() or UART_read() will return immediately. UART_write() will copy as much data into the transmit buffer as space allows. UART_read() will copy as much data from the receive buffer as is immediately available. |
enum UART_ReadReturnMode |
UART return mode settings.
This enumeration defines the return modes for UART_read().
UART_ReadReturnMode_FULL unblocks or performs a callback when the read buffer has been filled with the number of bytes passed to UART_read(). UART_ReadReturnMode_PARTIAL unblocks or performs a callback whenever a read timeout error occurs on the UART peripheral. This timeout error is not the same as the blocking read timeout in the UART_Params; the read timeout occurs if the read FIFO is non-empty and no new data has been received for a device/baudrate dependent number of clock cycles. This mode can be used when the exact number of bytes to be read is not known.
Enumerator | |
---|---|
UART_ReadReturnMode_FULL | Unblock/callback when buffer is full. |
UART_ReadReturnMode_PARTIAL | Unblock/callback when no new data comes in. |
enum UART_DataLen |
enum UART_StopBits |
enum UART_Parity |
void UART_Params_init | ( | UART_Params * | params | ) |
Function to initialize the UART_Params struct to its defaults.
[in] | params | A pointer to UART_Params structure for initialization. |
Defaults values are:
UART_Handle UART_open | ( | uint_least8_t | index, |
UART_Params * | params | ||
) |
Function to initialize a given UART peripheral.
Function to initialize a given UART peripheral specified by the particular index value.
[in] | index | Logical peripheral number for the UART indexed into the UART_config table. |
[in] | params | Pointer to a UART_Params structure. If NULL, default parameter values will be used. All the fields in this structure are read-only. |
void UART_close | ( | UART_Handle | handle | ) |
Function to close a UART peripheral specified by the UART handle.
[in] | handle | A UART_Handle returned from UART_open(). |
int_fast16_t UART_read | ( | UART_Handle | handle, |
void * | buf, | ||
size_t | size, | ||
size_t * | bytesRead | ||
) |
Function that reads data from a UART.
UART_read() reads data from a UART controller. The destination is specified by buffer and the number of bytes to read is given by size.
In UART_Mode_BLOCKING, UART_read() blocks task execution until all the data in buffer has been read, if the read return mode is UART_ReadReturnMode_FULL. If the read return mode is UART_ReadReturnMode_PARTIAL, UART_read() returns before all the data has been read, if some data has been received, but reception has been inactive sufficiently long for a hardware read timeout to occur (e.g., for a 32-bit period). If a receive error occurs (e.g., framing, FIFO overrun), UART_read() will return with the number of bytes read up to the occurrence of the error.
In UART_Mode_CALLBACK, UART_read() does not block task execution. Instead, a callback function specified by UART_Params::readCallback is called when the transfer is finished (UART_ReadReturnMode_FULL), or reception has become inactive (UART_ReadReturnMode_PARTIAL). The callback function can occur in the caller's context or in SWI context, depending on the device-specific implementation. An unfinished asynchronous read operation must always be cancelled using UART_readCancel() before calling UART_close().
[in] | handle | A UART_Handle returned by UART_open(). |
[in] | buf | A pointer to an empty buffer to which received data should be read. |
[in] | size | The number of bytes to be read into buffer. |
[out] | bytesRead | If non-NULL, the location to store the number of bytes actually read into the buffer. If NULL, this parameter will be ignored. In callback mode, NULL could be passed in for this parameter, since the callback function will be passed the number of bytes read. In blocking mode, NULL can be passed, however, status should be checked in case the number of bytes requested was not received due to errors. |
UART_STATUS_SUCCESS | The call was successful. |
UART_STATUS_EINUSE | Another read from the UART is currently ongoing. |
UART_STATUS_ECANCELLED | In UART_Mode_BLOCKING, the read was canceled by a call to UART_readCancel() before any data could be received. |
int_fast16_t UART_write | ( | UART_Handle | handle, |
const void * | buf, | ||
size_t | size, | ||
size_t * | bytesWritten | ||
) |
Function that writes data to a UART.
UART_write() writes data from a memory buffer to the UART interface. The source is specified by buffer and the number of bytes to write is given by size.
In UART_Mode_BLOCKING, UART_write() blocks task execution until all the data in buffer has been transmitted onto the TX pin.
In UART_Mode_CALLBACK, UART_write() does not block task execution. Instead, a callback function specified by UART_Params::writeCallback is called when all data has been written to the hardware FIFO. This means that that driver is ready to accept another call to UART_write().
The buffer passed to UART_write() in UART_Mode_CALLBACK is not copied. The buffer must remain coherent until all the characters have been sent (ie until the write callback has been called with a byte count equal to that passed to UART_write()). The callback function can occur in the caller's task context or in interrupt context, depending on the device implementation. An unfinished asynchronous write operation must always be cancelled using UART_writeCancel() before calling UART_close().
The bytesWritten parameter should not be NULL so the application can determine the number of bytes actually written.
[in] | handle | A UART_Handle returned by UART_open(). |
[in] | buf | A read-only pointer to buffer containing data to be written to the UART. |
[in] | size | The number of bytes in the buffer that should be written to the UART. |
[out] | bytesWritten | If non-NULL, the location to store the number of bytes actually written to the UART in UART_Mode_BLOCKING. In UART_Mode_CALLBACK, bytesWritten will be set to 0. If bytesWritten is NULL, this parameter will be ignored. |
UART_STATUS_SUCCESS | The call was successful. |
UART_STATUS_EINUSE | Another write to the UART is currently ongoing. |
int_fast16_t UART_readTimeout | ( | UART_Handle | handle, |
void * | buf, | ||
size_t | size, | ||
size_t * | bytesRead, | ||
uint32_t | timeout | ||
) |
UART read with timeout. Note that the timeout parameter is different from the hardware read timeout.
[in] | handle | UART_Handle instance from UART_open(). |
[in] | buf | location where the data to be written. |
[in] | size | amount of data to write in bytes. |
[out] | bytesRead | If non-NULL, the location to store the number of bytes actually read into the buffer. If NULL, this parameter will be ignored. |
[in] | timeout | The number of system clock ticks to wait until all data is received. If not all requested data was received within the timeout period, an error of UART_STATUS_ETIMEOUT will be returned. This parameter is only applicable to UART_Mode_BLOCKING. |
UART_STATUS_SUCCESS | The call was successful. |
UART_STATUS_EINUSE | Another read from the UART is currently ongoing. |
UART_STATUS_ECANCELLED | In UART_Mode_BLOCKING, the read was canceled by a call to UART_readCancel() before any data could be received. |
UART_STATUS_ETIMEOUT | The read operation timed out. |
int_fast16_t UART_writeTimeout | ( | UART_Handle | handle, |
const void * | buf, | ||
size_t | size, | ||
size_t * | bytesWritten, | ||
uint32_t | timeout | ||
) |
UART write with timeout. Note that the timeout parameter is different from the hardware read timeout.
[in] | handle | UART_Handle instance from UART_open(). |
[in] | buf | location to write data from. |
[in] | size | amount of data to write in bytes. |
[out] | bytesWritten | If non-NULL, the location to store the number of bytes actually written into the buffer. If NULL, this parameter will be ignored. |
[in] | timeout | The number of system clock ticks to wait for the write to complete (UART_Mode_BLOCKING only). If the timeout expires before all bytes are written, a status of UART_STATUS_ETIMEOUT will be returned. |
UART_STATUS_SUCCESS | The call was successful. |
UART_STATUS_EINUSE | Another write to the UART is currently ongoing. |
UART_STATUS_ETIMEOUT | The write operation timed out. |
void UART_readCancel | ( | UART_Handle | handle | ) |
Function that cancels a UART_read() function call.
This function cancels an asynchronous UART_read() operation in in UART_Mode_CALLBACK, or unblocks a UART_read() call in UART_Mode_BLOCKING. In UART_Mode_CALLBACK, UART_readCancel() calls the registered read callback function with the number of bytes received so far. It is the application's responsibility to check the count argument in the callback function and handle the case where only a subset of the bytes were received. The callback function will be passed a status of UART_STATUS_ECANCELLED.
In UART_Mode_BLOCKING, UART_read() will return UART_STATUS_ECANCELLED, and the bytesRead parameter will be set to the number of bytes received so far.
[in] | handle | A UART_Handle returned by UART_open(). |
void UART_writeCancel | ( | UART_Handle | handle | ) |
Function that cancels a UART_write() function call.
This function cancels an asynchronous UART_write() operation when write mode is UART_Mode_CALLBACK. In callback mode, UART_writeCancel() calls the registered write callback function no matter how many bytes were sent. It is the application's responsibility to check the count argument in the callback function and handle cases where only a subset of the bytes were sent. The callback function will be passed a status of UART_STATUS_ECANCELLED. In blocking mode, UART_write() will return UART_STATUS_ECANCELLED.
[in] | handle | A UART_Handle returned by UART_open(). |
void UART_rxDisable | ( | UART_Handle | handle | ) |
Function that disables collecting of RX data into the circular buffer.
The driver implementation uses a circular buffer to collect RX data while a UART_read() is not in progress. This function will disable buffering of RX data into the circular buffer. UART_read() will read directly from the UART driver's RX buffer. Disabling the circular buffer will also allow the device to go into low power modes.
[in] | handle | A UART_Handle returned by UART_open(). |
void UART_rxEnable | ( | UART_Handle | handle | ) |
Function that enables collecting of RX data into the circular buffer.
The driver implementation uses a circular buffer to collect RX data while a UART_read() is not in progress. This function will enable buffering of RX data into the circular buffer. UART_read() will read directly from the UART drivers RX buffer. Enabling the circular buffer will also prevent the device from going into low power modes.
[in] | handle | A UART_Handle returned by UART_open(). |
void UART_flushRx | ( | UART_Handle | handle | ) |
Function to flush data in the UART RX FIFO.
This function can be called to remove all data from the RX FIFO, for example, after a UART read error has occurred. All data in the RX circular buffer will be discarded.
[in] | handle | A UART_Handle returned from UART_open(). |
void UART_getRxCount | ( | UART_Handle | handle | ) |
Get the number of bytes available in the circular buffer.
[in] | handle | A UART_Handle returned from UART_open(). |