ADuCM302x Device Drivers API Reference Manual  Release 3.1.2.0
UART Driver

UART Driver. More...

Modules

 Static Configuration
 

Macros

#define ADI_UART_UNIDIR_MEMORY_SIZE   (48u + (60u + ADI_SEM_SIZE))
 
#define ADI_UART_BIDIR_MEMORY_SIZE   (48u + (60u + ADI_SEM_SIZE)*2u)
 
#define ADI_UART_NUM_DEVICES   (sizeof(uart_device_info)/sizeof(ADI_UART_DEVICE_INFO))
 

Typedefs

typedef struct _ADI_UART_DEVICE * ADI_UART_HANDLE
 
typedef const struct _ADI_UART_DEVICE * ADI_UART_CONST_HANDLE
 

Enumerations

enum  ADI_UART_DIRECTION {
  ADI_UART_DIR_TRANSMIT,
  ADI_UART_DIR_RECEIVE,
  ADI_UART_DIR_BIDIRECTION
}
 
enum  ADI_UART_EVENT {
  ADI_UART_EVENT_RX_BUFFER_PROCESSED,
  ADI_UART_EVENT_TX_BUFFER_PROCESSED,
  ADI_UART_EVENT_NO_RX_BUFFER_EVENT,
  ADI_UART_EVENT_AUTOBAUD_COMPLETE,
  ADI_UART_EVENT_HW_ERROR_DETECTED,
  ADI_UART_EVENT_AUTOBAUD_ERROR_DETECTED
}
 
enum  ADI_UART_RESULT {
  ADI_UART_SUCCESS,
  ADI_UART_FAILED,
  ADI_UART_SEMAPHORE_FAILED,
  ADI_UART_INVALID_HANDLE,
  ADI_UART_DEVICE_IN_USE,
  ADI_UART_INVALID_DEVICE_NUM,
  ADI_UART_INVALID_POINTER,
  ADI_UART_INSUFFICIENT_MEMORY,
  ADI_UART_INVALID_DIR,
  ADI_UART_OPERATION_NOT_ALLOWED,
  ADI_UART_INVALID_PARAMETER,
  ADI_UART_BUFFER_NOT_SUBMITTED,
  ADI_UART_INVALID_DATA_TRANSFER_MODE,
  ADI_UART_HW_ERROR_DETECTED,
  ADI_UART_AUTOBAUD_ERROR_DETECTED,
  ADI_UART_ERR_DMA_REGISTER,
  ADI_UART_INVALID_DATA_SIZE
}
 
enum  ADI_UART_HW_ERRORS {
  ADI_UART_NO_HW_ERROR = 0x00,
  ADI_UART_HW_ERR_FRAMING = 0x10,
  ADI_UART_HW_ERR_PARITY = 0x20,
  ADI_UART_HW_ERR_OVERRUN = 0x40,
  ADI_UART_BREAK_INTERRUPT = 0x80,
  ADI_UART_HW_ERR_RX_CHAN_DMA_BUS_FAULT = 0x100,
  ADI_UART_HW_ERR_TX_CHAN_DMA_BUS_FAULT = 0x200,
  ADI_UART_HW_ERR_RX_CHAN_DMA_INVALID_DESCR = 0x400,
  ADI_UART_HW_ERR_TX_CHAN_DMA_INVALID_DESCR = 0x800,
  ADI_UART_HW_ERR_RX_CHAN_DMA_UNKNOWN_ERROR = 0x1000,
  ADI_UART_HW_ERR_TX_CHAN_DMA_UNKNOWN_ERROR = 0x2000
}
 
enum  ADI_UART_AUTOBAUD_ERRORS {
  ADI_UART_AUTOBAUD_NO_ERROR = 0x000,
  ADI_UART_AUTOBAUD_TIMEOUT_NO_START_EDGE = 0x100,
  ADI_UART_AUTOBAUD_TIMEOUT_LONGBREAK = 0x200,
  ADI_UART_AUTOBAUD_TIMEOUT_NO_END_EDGE = 0x400
}
 
enum  ADI_UART_TRIG_LEVEL {
  ADI_UART_RX_FIFO_TRIG_LEVEL_1BYTE = 0 << BITP_UART_FCR_RFTRIG,
  ADI_UART_RX_FIFO_TRIG_LEVEL_4BYTE = 1 << BITP_UART_FCR_RFTRIG,
  ADI_UART_RX_FIFO_TRIG_LEVEL_8BYTE = 2 << BITP_UART_FCR_RFTRIG,
  ADI_UART_RX_FIFO_TRIG_LEVEL_14BYTE = 3 << BITP_UART_FCR_RFTRIG
}
 
enum  ADI_UART_WORDLEN {
  ADI_UART_WORDLEN_5BITS,
  ADI_UART_WORDLEN_6BITS,
  ADI_UART_WORDLEN_7BITS,
  ADI_UART_WORDLEN_8BITS
}
 
enum  ADI_UART_PARITY {
  ADI_UART_NO_PARITY = 0x0,
  ADI_UART_ODD_PARITY = 0x8,
  ADI_UART_EVEN_PARITY = 0x18,
  ADI_UART_ODD_PARITY_STICKY = 0x28,
  ADI_UART_EVEN_PARITY_STICKY = 0x38
}
 
enum  ADI_UART_STOPBITS {
  ADI_UART_ONE_STOPBIT = 0x00,
  ADI_UART_ONE_AND_HALF_TWO_STOPBITS = 0x04
}
 
enum  ADI_UART_TRANSFER_MODE {
  ADI_UART_DATA_TRANSFER_MODE_NONE,
  ADI_UART_DATA_TRANSFER_MODE_BLOCKING,
  ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING
}
 

Functions

ADI_UART_RESULT adi_uart_Open (uint32_t const nDeviceNum, ADI_UART_DIRECTION const eDirection, void *pMemory, uint32_t const nMemSize, ADI_UART_HANDLE *const phDevice)
 Initialization function for the UART device. More...
 
ADI_UART_RESULT adi_uart_Close (ADI_UART_HANDLE const hDevice)
 Uninitialize the memory for the specified UART instance. More...
 
ADI_UART_RESULT adi_uart_SubmitTxBuffer (ADI_UART_HANDLE const hDevice, void *const pBuffer, uint32_t const nBufSize, bool const bDMA)
 Submit a "filled" buffer for transmitting data in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. This function sets up the apropriate interrupts associated with the transaction and marks the buffer as submitted. More...
 
ADI_UART_RESULT adi_uart_SubmitRxBuffer (ADI_UART_HANDLE const hDevice, void *const pBuffer, uint32_t const nBufSize, bool const bDMA)
 Submit an empty buffer for receiving the data in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. This will set up the Rx channel for notification on incoming data using either the DMA or UART interrupts, as well as mark the buffer as submitted. More...
 
ADI_UART_RESULT adi_uart_GetTxBuffer (ADI_UART_HANDLE const hDevice, void **const ppBuffer, uint32_t *pHwError)
 Transfer buffer ownership from the device back to the API if the data transmit has completed. Otherwise it will block until completion. This allows a nonblocking call to become blocking. This function is only called in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. More...
 
ADI_UART_RESULT adi_uart_GetRxBuffer (ADI_UART_HANDLE const hDevice, void **const ppBuffer, uint32_t *pHwError)
 Transfer buffer ownership from the device back to the API if the data receive has completed. Otherwise it will block until completion. This allows a nonblocking call to become blocking. This function is only called in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. More...
 
ADI_UART_RESULT adi_uart_IsTxBufferAvailable (ADI_UART_HANDLE const hDevice, bool *const pbAvailable)
 Peek function to know if an empty buffer is avilable. More...
 
ADI_UART_RESULT adi_uart_IsRxBufferAvailable (ADI_UART_HANDLE const hDevice, bool *const pbAvailable)
 Peek function to know if a filled buffer is available. More...
 
ADI_UART_RESULT adi_uart_Write (ADI_UART_HANDLE const hDevice, void *const pBuffer, uint32_t const nBufSize, bool const bDMA, uint32_t *pHwError)
 Submit the buffer for transmitting the data in ADI_UART_DATA_TRANSFER_MODE_BLOCKING. Call to this function will not return until the entire buffer is transmitted. Returns error if this function is called when device is operating in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. i.e Function "adi_uart_SubmitTxBuffer()" is called and the transfer is not yet complete. More...
 
ADI_UART_RESULT adi_uart_Read (ADI_UART_HANDLE const hDevice, void *const pBuffer, uint32_t const nBufSize, bool const bDMA, uint32_t *pHwError)
 Submit the buffer for reading the data in ADI_UART_DATA_TRANSFER_MODE_BLOCKING. Call to this function will not return until the entire buffer is filled up. Returns error if this function is called when device is operating in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. i.e The function "adi_uart_SubmitRxBuffer()" is called when the transfer is not yet complete. More...
 
ADI_UART_RESULT adi_uart_EnableLoopBack (ADI_UART_HANDLE const hDevice, bool const bEnable)
 Enable/Disable the loopback for the specified UART device. More...
 
ADI_UART_RESULT adi_uart_EnableAutobaud (ADI_UART_HANDLE const hDevice, bool const bEnable, bool const bAutobaudCallbackMode)
 Enable/Disable UART autobaud detection as well as configures the device for autobaud detection. More...
 
ADI_UART_RESULT adi_uart_SetRxFifoTriggerLevel (ADI_UART_HANDLE const hDevice, ADI_UART_TRIG_LEVEL const eTriglevel)
 Sets the RX FIFO trigger level. This will be the amount of data in the FIFO that will trigger an interrupt. More...
 
ADI_UART_RESULT adi_uart_EnableFifo (ADI_UART_HANDLE const hDevice, bool const bEnable)
 Enables internal FIFO as to work in 16550 mode. This helps to minimize system overhead and maximize system efficiency. More...
 
ADI_UART_RESULT adi_uart_GetBaudRate (ADI_UART_HANDLE const hDevice, uint32_t *pnBaudRate, uint32_t *pAutobaudError)
 Get the baudrate of the UART device instance. This is used in the scenario when a callback has not been initialized. This allows the the API to know if autobaud is complete. If this returns a baudrate other than 0, it indicates that the autobaud completed, otherwise autobaud is still in progress. More...
 
ADI_UART_RESULT adi_uart_ForceTxBreak (ADI_UART_HANDLE const hDevice, bool const bEnable)
 Forces the UART to send out a break signal. More...
 
ADI_UART_RESULT adi_uart_SetConfiguration (ADI_UART_HANDLE const hDevice, ADI_UART_PARITY const eParity, ADI_UART_STOPBITS const eStopBits, ADI_UART_WORDLEN const eWordLength)
 Configuration of UART data. More...
 
ADI_UART_RESULT adi_uart_ConfigBaudRate (ADI_UART_HANDLE const hDevice, uint16_t const nDivC, uint8_t const nDivM, uint16_t const nDivN, uint8_t const nOSR)
 Set baudrate by configuring the fractional dividors. More...
 
ADI_UART_RESULT adi_uart_FlushTxFifo (ADI_UART_CONST_HANDLE const hDevice)
 To flush the TX FIFO. More...
 
ADI_UART_RESULT adi_uart_FlushRxFifo (ADI_UART_CONST_HANDLE const hDevice)
 Flush the RX FIFO. More...
 
ADI_UART_RESULT adi_uart_FlushRxChannel (ADI_UART_CONST_HANDLE const hDevice)
 Flush the Rx channel and disable interrupts. This will stop any buffers in flight and clear out any data that was in the RX holding register as well as the Rx fifo. Once this is done, in order to turn back on Rx interrupts, a new transaction will need to be started (adi_uart_Read() or adi_uart_SubmitRxBuffer()). More...
 
ADI_UART_RESULT adi_uart_FlushTxChannel (ADI_UART_CONST_HANDLE const hDevice)
 Flush the Tx channel and disable interrupts.This will stop any buffers in flight and clear out any data that was in the TX holding register. Any data in the TX shift register will still finish transmitting. More...
 
ADI_UART_RESULT adi_uart_IsTxComplete (ADI_UART_HANDLE const hDevice, bool *const pbComplete)
 Function to let the API know if all the data had been drained from the Tx shift registers. More...
 
ADI_UART_RESULT adi_uart_RegisterCallback (ADI_UART_HANDLE const hDevice, const ADI_CALLBACK pfCallback, void *const pCBParam)
 Registering a callback function. More...
 

Detailed Description

UART Driver.

Note
The application must include drivers/uart/adi_uart.h to use this driver
This driver requires the DMA driver.The application must include the DMA driver sources to avoid link errors.
This documentation presented here is API documentation only. The device drive user's guide, located in the Documents folder, explains how to use these APIs in an application.

Macro Definition Documentation

◆ ADI_UART_UNIDIR_MEMORY_SIZE

#define ADI_UART_UNIDIR_MEMORY_SIZE   (48u + (60u + ADI_SEM_SIZE))

Amount of memory(bytes) required by the UART device driver for operating unidirectionally(Either RX or TX). This memory is completely owned by the driver until the end of the operation.

Definition at line 76 of file adi_uart.h.

Referenced by adi_uart_Open().

◆ ADI_UART_BIDIR_MEMORY_SIZE

#define ADI_UART_BIDIR_MEMORY_SIZE   (48u + (60u + ADI_SEM_SIZE)*2u)

Amount of memory(bytes) required by the UART device driver for operating bidirectionally(Both RX and TX). This memory is completely owned by the driver until the end of the operation.

Definition at line 81 of file adi_uart.h.

Referenced by adi_uart_Open().

◆ ADI_UART_NUM_DEVICES

#define ADI_UART_NUM_DEVICES   (sizeof(uart_device_info)/sizeof(ADI_UART_DEVICE_INFO))

Number of UART devices available on the chip.

Definition at line 204 of file adi_uart.c.

Referenced by adi_uart_Open().

Typedef Documentation

◆ ADI_UART_HANDLE

typedef struct _ADI_UART_DEVICE* ADI_UART_HANDLE

Handle for managing the UART device typedef.

Definition at line 86 of file adi_uart.h.

◆ ADI_UART_CONST_HANDLE

typedef const struct _ADI_UART_DEVICE* ADI_UART_CONST_HANDLE

Handle for managing the UART device typedef 'const' version.

Definition at line 91 of file adi_uart.h.

Enumeration Type Documentation

◆ ADI_UART_DIRECTION

Enumeration for the UART direction.

Enumerator
ADI_UART_DIR_TRANSMIT 

UART is only transmitting.

ADI_UART_DIR_RECEIVE 

UART is only receiving.

ADI_UART_DIR_BIDIRECTION 

UART in bidirectional.

Definition at line 98 of file adi_uart.h.

◆ ADI_UART_EVENT

Enumeration of events notified in the application provided callback.

Enumerator
ADI_UART_EVENT_RX_BUFFER_PROCESSED 

Rx buffer is processed.

ADI_UART_EVENT_TX_BUFFER_PROCESSED 

Tx buffer is processed.

ADI_UART_EVENT_NO_RX_BUFFER_EVENT 

No Rx buffer but data is in FIFO.

ADI_UART_EVENT_AUTOBAUD_COMPLETE 

Autobaud is complete.

ADI_UART_EVENT_HW_ERROR_DETECTED 

Hardware error detected.

ADI_UART_EVENT_AUTOBAUD_ERROR_DETECTED 

Autobaud error detected.

Definition at line 114 of file adi_uart.h.

◆ ADI_UART_RESULT

Enumeration for result code returned from the UART device driver functions. The return value of all UART APIs returning ADI_UART_RESULT should always be tested at the application level for success or failure.

Enumerator
ADI_UART_SUCCESS 

Generic success.

ADI_UART_FAILED 

Generic failure.

ADI_UART_SEMAPHORE_FAILED 

Semaphore error.

ADI_UART_INVALID_HANDLE 

Invalid device handle.

ADI_UART_DEVICE_IN_USE 

UART device in use.

ADI_UART_INVALID_DEVICE_NUM 

Invalid device number.

ADI_UART_INVALID_POINTER 

NULL data pointer is not allowed.

ADI_UART_INSUFFICIENT_MEMORY 

Insufficent memory.

ADI_UART_INVALID_DIR 

Invalid UART direction.

ADI_UART_OPERATION_NOT_ALLOWED 

Invalid operation.

ADI_UART_INVALID_PARAMETER 

Invalid parameter.

ADI_UART_BUFFER_NOT_SUBMITTED 

Buffer not submitted.

ADI_UART_INVALID_DATA_TRANSFER_MODE 

Invalid transfer mode. Adi_uart_Read()/adi_uart_Write() is used in nonblocking mode or adi_uart_SubmitRxBuffer()/adi_uart_SubmitTxBuffer() is used in blocking mode.

ADI_UART_HW_ERROR_DETECTED 

Hardware error detected.

ADI_UART_AUTOBAUD_ERROR_DETECTED 

Autobaud error detected.

ADI_UART_ERR_DMA_REGISTER 

Error while registering the DMA callback.

ADI_UART_INVALID_DATA_SIZE 

Invalid transfer size. Must be less than 1025 bytes

Definition at line 138 of file adi_uart.h.

◆ ADI_UART_HW_ERRORS

Enumeration for UART hardware errors. If hardware error(s) occur in either callback or interrupt mode, they are mapped to ADI_UART_HW_ERRORS. Interpretation of the break condition is application specific.

Enumerator
ADI_UART_NO_HW_ERROR 

No hardware error.

ADI_UART_HW_ERR_FRAMING 

Rx framing error.

ADI_UART_HW_ERR_PARITY 

Rx parity error.

ADI_UART_HW_ERR_OVERRUN 

Receive overrun.

ADI_UART_BREAK_INTERRUPT 

Break condition.

ADI_UART_HW_ERR_RX_CHAN_DMA_BUS_FAULT 

Rx DMA channel bus fault detected.

ADI_UART_HW_ERR_TX_CHAN_DMA_BUS_FAULT 

Tx DMA channel bus fault detected.

ADI_UART_HW_ERR_RX_CHAN_DMA_INVALID_DESCR 

Rx DMA channel invalid descriptor detected.

ADI_UART_HW_ERR_TX_CHAN_DMA_INVALID_DESCR 

Tx DMA channel invalid descriptor detected.

ADI_UART_HW_ERR_RX_CHAN_DMA_UNKNOWN_ERROR 

Rx DMA channel unknown error detected.

ADI_UART_HW_ERR_TX_CHAN_DMA_UNKNOWN_ERROR 

Tx DMA channel unknown error detected.

Definition at line 187 of file adi_uart.h.

◆ ADI_UART_AUTOBAUD_ERRORS

Enumeration for UART autobaud errors. If autobaud related error(s) occur they are mapped to ADI_UART_AUTOBAUD_ERRORS.

Enumerator
ADI_UART_AUTOBAUD_NO_ERROR 

No autobaud error.

ADI_UART_AUTOBAUD_TIMEOUT_NO_START_EDGE 

Timeout due to no valid start edge found during autobaud.

ADI_UART_AUTOBAUD_TIMEOUT_LONGBREAK 

Timeout due to break condition detected during autobaud.

ADI_UART_AUTOBAUD_TIMEOUT_NO_END_EDGE 

Timeout due to no valid end edge found during autobaud.

Definition at line 219 of file adi_uart.h.

◆ ADI_UART_TRIG_LEVEL

Enumeration for the FIFO trigger level.

Enumerator
ADI_UART_RX_FIFO_TRIG_LEVEL_1BYTE 

1-byte to trigger RX interrupt.

ADI_UART_RX_FIFO_TRIG_LEVEL_4BYTE 

4-byte to trigger RX interrupt.

ADI_UART_RX_FIFO_TRIG_LEVEL_8BYTE 

8-byte to trigger RX interrupt.

ADI_UART_RX_FIFO_TRIG_LEVEL_14BYTE 

14-byte to trigger RX interrupt.

Definition at line 236 of file adi_uart.h.

◆ ADI_UART_WORDLEN

Enumeration for data width.

Enumerator
ADI_UART_WORDLEN_5BITS 

5 bits wide.

ADI_UART_WORDLEN_6BITS 

6 bits wide.

ADI_UART_WORDLEN_7BITS 

7 bits wide.

ADI_UART_WORDLEN_8BITS 

8 bits wide.

Definition at line 254 of file adi_uart.h.

◆ ADI_UART_PARITY

Enumeration for parity check.

Enumerator
ADI_UART_NO_PARITY 

No parity.

ADI_UART_ODD_PARITY 

Odd parity.

ADI_UART_EVEN_PARITY 

Even Parity.

ADI_UART_ODD_PARITY_STICKY 

Sticky odd parity.

ADI_UART_EVEN_PARITY_STICKY 

Sticky even parity.

Definition at line 271 of file adi_uart.h.

◆ ADI_UART_STOPBITS

Enumeration for the number of stop bits.

Enumerator
ADI_UART_ONE_AND_HALF_TWO_STOPBITS 

One stop bit regardless of the word length

Definition at line 290 of file adi_uart.h.

◆ ADI_UART_TRANSFER_MODE

Enumeration for data transfer mode.

Enumerator
ADI_UART_DATA_TRANSFER_MODE_BLOCKING 

Mode of data transfer is not selected.

ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING 

Blocking mode. Only calls to adi_uart_Read or adi_uart_write are allowed for sending or receiving data.

Non-Blocking mode. Only calls to adi_uart_SubmitRxBuffer or adi_uart_SubmitTxBuffer are allowed for sending or receiving data.

Definition at line 305 of file adi_uart.h.

Function Documentation

◆ adi_uart_Open()

ADI_UART_RESULT adi_uart_Open ( uint32_t const  nDeviceNum,
ADI_UART_DIRECTION const  eDirection,
void *  pMemory,
uint32_t const  nMemSize,
ADI_UART_HANDLE *const  phDevice 
)

Initialization function for the UART device.

Opens the specified UART device. This function must be called before operating any UART device.

Parameters
[in]nDeviceNumUART device instance to be opened.
[in]eDirectionDirection of the UART operation. (i.e Rx or Tx)
[in]pMemoryPointer to a 32 bit aligned buffer the size of ADI_UART_UNIDIR_MEMORY_SIZE or ADI_UART_BIDIR_MEMORY_SIZE.
[in]nMemSizeSize of the buffer to which "pMemory" points. This will vary based on direction of operation for this device instance. (i.e Rx and Tx, Rx, Tx)
[out]phDeviceThe caller's device handle pointer for storing the initialized device instance data pointer.
Returns
Status
See also
adi_uart_Close()
Note
: Memory supplied by the API will be used by the driver for managing the UART device. This memory can be reused once device is closed.

Definition at line 315 of file adi_uart.c.

◆ adi_uart_Close()

ADI_UART_RESULT adi_uart_Close ( ADI_UART_HANDLE const  hDevice)

Uninitialize the memory for the specified UART instance.

Parameters
[in]hDeviceUART device handle whose operation is to be closed. This handle was obtained when the UART device instance was opened successfully.
Returns
Status

Closes the operation of specified UART device. Device needs to be opened again for any further use.

See also
adi_uart_Open()
Note
: It is the user's responsibility to free/reuse the memory supplied during the opening of the device.

Definition at line 507 of file adi_uart.c.

◆ adi_uart_SubmitTxBuffer()

ADI_UART_RESULT adi_uart_SubmitTxBuffer ( ADI_UART_HANDLE const  hDevice,
void *const  pBuffer,
uint32_t const  nBufSize,
bool const  bDMA 
)

Submit a "filled" buffer for transmitting data in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. This function sets up the apropriate interrupts associated with the transaction and marks the buffer as submitted.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]pBufferPointer to data supplied by the API that is to be transmitted.
[in]nBufSizeSize of the buffer to be transmitted(in bytes). Must be smaller than 1024 bytes for DMA transfers.
[in]bDMASubmit the buffer using the DMA flag.
Returns
Status
See also
adi_uart_IsTxBufferAvailable()
adi_uart_GetTxBuffer()
adi_uart_SubmitRxBuffer()
Note
: Only one transfer mode (DMA vs. PIO) can be used at once. For example, if you submit a buffer in PIO mode and then right away another using the DMA, this transaction will be denied.

Definition at line 594 of file adi_uart.c.

◆ adi_uart_SubmitRxBuffer()

ADI_UART_RESULT adi_uart_SubmitRxBuffer ( ADI_UART_HANDLE const  hDevice,
void *const  pBuffer,
uint32_t const  nBufSize,
bool const  bDMA 
)

Submit an empty buffer for receiving the data in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. This will set up the Rx channel for notification on incoming data using either the DMA or UART interrupts, as well as mark the buffer as submitted.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]pBufferPointer to buffer from that will be filled by the driver when data has been received.
[in]nBufSizeSize of the buffer(in bytes). Must be smaller than 1024 bytes for DMA transfers.
[in]bDMASubmit the buffer using DMA flag.
Returns
Status
See also
adi_uart_IsRxBufferAvailable()
adi_uart_GetRxBuffer()
adi_uart_SubmitTxBuffer()
Note
: Only one transfer mode (DMA vs. PIO) can be used at once. For example, if you submit a buffer in PIO mode and then right away another using the DMA, this transaction will be denied.

Definition at line 784 of file adi_uart.c.

◆ adi_uart_GetTxBuffer()

ADI_UART_RESULT adi_uart_GetTxBuffer ( ADI_UART_HANDLE const  hDevice,
void **const  ppBuffer,
uint32_t *  pHwError 
)

Transfer buffer ownership from the device back to the API if the data transmit has completed. Otherwise it will block until completion. This allows a nonblocking call to become blocking. This function is only called in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]ppBufferContains the address of the buffer passed down from the API for transmitting data.
[out]pHwErrorPointer to an integer that correlates with ADI_UART_HW_ERRORS, containg the hardware status. If there is no hardware event, this will be 0.
Returns
Status
See also
adi_uart_IsTxBufferAvailable()
adi_uart_SubmitTxBuffer()
Note
: If the transaction has already completed, this will return immediately rather than block.

Definition at line 970 of file adi_uart.c.

◆ adi_uart_GetRxBuffer()

ADI_UART_RESULT adi_uart_GetRxBuffer ( ADI_UART_HANDLE const  hDevice,
void **const  ppBuffer,
uint32_t *  pHwError 
)

Transfer buffer ownership from the device back to the API if the data receive has completed. Otherwise it will block until completion. This allows a nonblocking call to become blocking. This function is only called in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]ppBufferContains the address of the buffer passed down from the API for receiving data.
[out]pHwErrorPointer to an integer that correlates with ADI_UART_HW_ERRORS, containg the hardware status. If there is no hardware event, this will be 0.
Returns
Status
See also
adi_uart_IsRxBufferAvailable()
adi_uart_SubmitRxBuffer()
Note
: If the transaction has already completed, this will return immediately rather than block.

Definition at line 1028 of file adi_uart.c.

◆ adi_uart_IsTxBufferAvailable()

ADI_UART_RESULT adi_uart_IsTxBufferAvailable ( ADI_UART_HANDLE const  hDevice,
bool *const  pbAvailable 
)

Peek function to know if an empty buffer is avilable.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[out]pbAvailablePointer to a boolean variable. Contains "true" if there is an empty buffer and a call to "adi_uart_GetTxBuffer" is ensured to be successful. Contains "false" if there is no empty buffer.
Returns
Status
See also
adi_uart_GetTxBuffer()
adi_uart_IsRxBufferAvailable

Definition at line 1481 of file adi_uart.c.

◆ adi_uart_IsRxBufferAvailable()

ADI_UART_RESULT adi_uart_IsRxBufferAvailable ( ADI_UART_HANDLE const  hDevice,
bool *const  pbAvailable 
)

Peek function to know if a filled buffer is available.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[out]pbAvailablePointer to a boolean variable. Contains "true" if there is an empty buffer and a call to "adi_uart_GetTxBuffer" is ensured to be successful. Contains "false" if there is no empty buffer.
Returns
Status
See also
adi_uart_GetRxBuffer()

Definition at line 1537 of file adi_uart.c.

◆ adi_uart_Write()

ADI_UART_RESULT adi_uart_Write ( ADI_UART_HANDLE const  hDevice,
void *const  pBuffer,
uint32_t const  nBufSize,
bool const  bDMA,
uint32_t *  pHwError 
)

Submit the buffer for transmitting the data in ADI_UART_DATA_TRANSFER_MODE_BLOCKING. Call to this function will not return until the entire buffer is transmitted. Returns error if this function is called when device is operating in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. i.e Function "adi_uart_SubmitTxBuffer()" is called and the transfer is not yet complete.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]pBufferPointer to data supplied by the API that is to be transmitted.
[in]nBufSizeSize of the buffer(in bytes). Must be smaller than 1024 bytes for DMA transfers.
[in]bDMASubmit the buffer using the DMA flag.
[out]pHwErrorPointer to an integer that correlates with ADI_UART_HW_ERRORS, containg the hardware status. If there is no hardware event, this will be 0.
Returns
Status
See also
adi_uart_Read()
adi_uart_SubmitTxBuffer()
Note
: This function is a blocking function which means that the function returns only after the completion of buffer transmission.

Definition at line 1166 of file adi_uart.c.

◆ adi_uart_Read()

ADI_UART_RESULT adi_uart_Read ( ADI_UART_HANDLE const  hDevice,
void *const  pBuffer,
uint32_t const  nBufSize,
bool const  bDMA,
uint32_t *  pHwError 
)

Submit the buffer for reading the data in ADI_UART_DATA_TRANSFER_MODE_BLOCKING. Call to this function will not return until the entire buffer is filled up. Returns error if this function is called when device is operating in ADI_UART_DATA_TRANSFER_MODE_NONBLOCKING. i.e The function "adi_uart_SubmitRxBuffer()" is called when the transfer is not yet complete.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]pBufferPointer to buffer from that will be filled by the driver when data has been received.
[in]nBufSizeSize of the buffer(in bytes). Must be smaller than 1024 bytes for DMA transfers.
[in]bDMASubmit the buffer using DMA flag.
[out]pHwErrorPointer to an integer that correlates with ADI_UART_HW_ERRORS, containg the hardware status. If there is no hardware event, this will be 0.
Returns
Status
See also
adi_uart_Write()
adi_uart_SubmitTxBuffer()
Note
: This function is a blocking function which means that the function returns only after the completion of data receive.

Definition at line 1298 of file adi_uart.c.

◆ adi_uart_EnableLoopBack()

ADI_UART_RESULT adi_uart_EnableLoopBack ( ADI_UART_HANDLE const  hDevice,
bool const  bEnable 
)

Enable/Disable the loopback for the specified UART device.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]bEnableBoolean flag to indicate whether to enable or disable the loopback mode.
Returns
Status

Definition at line 1989 of file adi_uart.c.

◆ adi_uart_EnableAutobaud()

ADI_UART_RESULT adi_uart_EnableAutobaud ( ADI_UART_HANDLE const  hDevice,
bool const  bEnable,
bool const  bAutobaudCallbackMode 
)

Enable/Disable UART autobaud detection as well as configures the device for autobaud detection.

The baud rate is detected using the hardware support. After the baud rate is detected the interrupt handler is notified of the completion. When a callback is not registered with UART driver, the API adi_uart_GetBaudRate() can be used to know if autobaud is complete. Autobaud needs to be disabled in order to clear the internal counter and to close the device.

Parameters
[in]hDeviceHandle to UART device whose autobaud detection to be enabled/disabled.
[in]bEnableBoolean flag to indicate whether to enable or disable the autobaud.
[in]bAutobaudCallbackModeUse a callback to report autobaud errors or type ADI_UART_AUTOBAUD_ERRORS.
Returns
Status
See also
adi_uart_GetBaudRate()
Note
: For autobaud we assume the key character being used is a carrige return (0xD), so the start edge count is hardcoded to the second edge (first edge after start edge) and the last edge count is set to the fouth edge. This will give us a total bit count of 8 bits that we will time in order to figure out the baud rate (bits/second).

Definition at line 1878 of file adi_uart.c.

◆ adi_uart_SetRxFifoTriggerLevel()

ADI_UART_RESULT adi_uart_SetRxFifoTriggerLevel ( ADI_UART_HANDLE const  hDevice,
ADI_UART_TRIG_LEVEL const  eTriglevel 
)

Sets the RX FIFO trigger level. This will be the amount of data in the FIFO that will trigger an interrupt.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]eTriglevelTrigger level to be set in terms of number of bytes.
Returns
Status

Definition at line 2028 of file adi_uart.c.

◆ adi_uart_EnableFifo()

ADI_UART_RESULT adi_uart_EnableFifo ( ADI_UART_HANDLE const  hDevice,
bool const  bEnable 
)

Enables internal FIFO as to work in 16550 mode. This helps to minimize system overhead and maximize system efficiency.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]bEnableBoolean flag to indicate whether to enable or disable FIFO.
Returns
Status

Definition at line 2063 of file adi_uart.c.

◆ adi_uart_GetBaudRate()

ADI_UART_RESULT adi_uart_GetBaudRate ( ADI_UART_HANDLE const  hDevice,
uint32_t *  pnBaudRate,
uint32_t *  pAutobaudError 
)

Get the baudrate of the UART device instance. This is used in the scenario when a callback has not been initialized. This allows the the API to know if autobaud is complete. If this returns a baudrate other than 0, it indicates that the autobaud completed, otherwise autobaud is still in progress.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[out]pnBaudRatePointer to a location where baudrate is to be written.
[out]pAutobaudErrorPointer to an integer that will hold the value of any baudrate error(s), that correlates with ADI_UART_AUTOBAUD_ERRORS. This will be 0 if there are no errors.
Returns
Status

Definition at line 1809 of file adi_uart.c.

◆ adi_uart_ForceTxBreak()

ADI_UART_RESULT adi_uart_ForceTxBreak ( ADI_UART_HANDLE const  hDevice,
bool const  bEnable 
)

Forces the UART to send out a break signal.

Sets the UART Tx pin to a logic-low/high (depending upon the Tx polarity) asynchronously. The UART keeps transmitting break until it is disabled to send the break.

Parameters
[in]hDeviceHandle to the UART whose Tx is forced to send a break.
[in]bEnableFlag which indicates whether to enable or disable transmitting the break.
Returns
Status

Definition at line 1950 of file adi_uart.c.

◆ adi_uart_SetConfiguration()

ADI_UART_RESULT adi_uart_SetConfiguration ( ADI_UART_HANDLE const  hDevice,
ADI_UART_PARITY const  eParity,
ADI_UART_STOPBITS const  eStopBits,
ADI_UART_WORDLEN const  eWordLength 
)

Configuration of UART data.

Sets the configuration parameters for the specified UART device such as wordlength, whether to enable/disable the parity, and the number of stop bits. This function returns an error if the device has active data or autobaud is in progress.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]eParitySpecify the type of parity check for the UART device.
[in]eStopBitsSpecify the stop-bits for the UART device.
[in]eWordLengthSpecify the word size of the data for the UART device.
Returns
Status

Definition at line 1689 of file adi_uart.c.

◆ adi_uart_ConfigBaudRate()

ADI_UART_RESULT adi_uart_ConfigBaudRate ( ADI_UART_HANDLE const  hDevice,
uint16_t const  nDivC,
uint8_t const  nDivM,
uint16_t const  nDivN,
uint8_t const  nOSR 
)

Set baudrate by configuring the fractional dividors.

Baudrate is calculated as per below equation.

          Baudrate = (UARTCLK / (nDivM + nDivN/2048)*pow(2,nOSR+2)* nDivC)).
Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]nDivCSpecify the "nDivC" in the above equation.
[in]nDivMSpecify the "nDivM" in the above equation.
[in]nDivNSpecify the "nDivN" in the above equation.
[in]nOSRSpecify the "nOSR" " in the above equation.
Returns
Status
See also
adi_uart_GetBaudRate()
adi_uart_EnableAutobaud();
Note
It is expected that initialization of the power management driver is done before calling this function.

Definition at line 1751 of file adi_uart.c.

Referenced by adi_uart_FlushTxChannel().

◆ adi_uart_FlushTxFifo()

ADI_UART_RESULT adi_uart_FlushTxFifo ( ADI_UART_CONST_HANDLE const  hDevice)

To flush the TX FIFO.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
Returns
Status

Definition at line 2108 of file adi_uart.c.

◆ adi_uart_FlushRxFifo()

ADI_UART_RESULT adi_uart_FlushRxFifo ( ADI_UART_CONST_HANDLE const  hDevice)

Flush the RX FIFO.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
Returns
Status

Definition at line 2138 of file adi_uart.c.

◆ adi_uart_FlushRxChannel()

ADI_UART_RESULT adi_uart_FlushRxChannel ( ADI_UART_CONST_HANDLE const  hDevice)

Flush the Rx channel and disable interrupts. This will stop any buffers in flight and clear out any data that was in the RX holding register as well as the Rx fifo. Once this is done, in order to turn back on Rx interrupts, a new transaction will need to be started (adi_uart_Read() or adi_uart_SubmitRxBuffer()).

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
Returns
Status

Definition at line 2170 of file adi_uart.c.

◆ adi_uart_FlushTxChannel()

ADI_UART_RESULT adi_uart_FlushTxChannel ( ADI_UART_CONST_HANDLE const  hDevice)

Flush the Tx channel and disable interrupts.This will stop any buffers in flight and clear out any data that was in the TX holding register. Any data in the TX shift register will still finish transmitting.

Parameters
[in]hDeviceDevice handle to UART device obtained when an UART device is opened successfully.
Returns
Status

Definition at line 2221 of file adi_uart.c.

◆ adi_uart_IsTxComplete()

ADI_UART_RESULT adi_uart_IsTxComplete ( ADI_UART_HANDLE const  hDevice,
bool *const  pbComplete 
)

Function to let the API know if all the data had been drained from the Tx shift registers.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[out]pbCompletePointer to a boolean variable. Contains "true" if there is no data left in the device to transmit and device can be disabled without data loss. Contains "false" if the data transmission is not complete.
Returns
Status
Note
adi_uart_getTxBuffer() or the callback may indicate that a transmit transaction is complete when the device is using the DMA. This is because the interrupt will trigger once the transmit holding register is empty. However, there may still be a some data in the shift register. If the transmit channel needs to be closed then the application must poll the transmit channel to see if all data has indeed been transmitted before shutting down the channel. Otherwise data will be lost.

Definition at line 1596 of file adi_uart.c.

◆ adi_uart_RegisterCallback()

ADI_UART_RESULT adi_uart_RegisterCallback ( ADI_UART_HANDLE const  hDevice,
const ADI_CALLBACK  pfCallback,
void *const  pCBParam 
)

Registering a callback function.

Parameters
[in]hDeviceDevice handle obtained from adi_uart_Open().
[in]pfCallbackFunction pointer to callback. Passing a NULL pointer will unregister the callback function.
[in]pCBParamCallback function parameter.
Returns
Status

Definition at line 1638 of file adi_uart.c.