UARTDRV
[EM_Drivers]

UARTDRV Universal asynchronous receiver/transmitter driver, see UARTDRV Universal asynchronous receiver/transmitter driver page for detailed documentation. More...

Collaboration diagram for UARTDRV:

Data Structures

struct  UARTDRV_Buffer_t
 UART transfer buffer. More...
struct  UARTDRV_Buffer_FifoQueue_t
 Transfer operation FIFO queue typedef. More...
struct  UARTDRV_Init_t
 UART driver instance initialization structure. More...
struct  UARTDRV_HandleData_t
 UART driver instance handle data structure. More...

Defines

#define ECODE_EMDRV_UARTDRV_OK   (ECODE_OK)
 Success return value.
#define ECODE_EMDRV_UARTDRV_WAITING   (ECODE_EMDRV_UARTDRV_BASE | 0x00000001)
 Operation is waiting in queue.
#define ECODE_EMDRV_UARTDRV_ILLEGAL_HANDLE   (ECODE_EMDRV_UARTDRV_BASE | 0x00000002)
 Illegal UART handle.
#define ECODE_EMDRV_UARTDRV_PARAM_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x00000003)
 Illegal input parameter.
#define ECODE_EMDRV_UARTDRV_BUSY   (ECODE_EMDRV_UARTDRV_BASE | 0x00000004)
 The UART port is busy.
#define ECODE_EMDRV_UARTDRV_ILLEGAL_OPERATION   (ECODE_EMDRV_UARTDRV_BASE | 0x00000005)
 Illegal operation on UART port.
#define ECODE_EMDRV_UARTDRV_IDLE   (ECODE_EMDRV_UARTDRV_BASE | 0x00000008)
 No UART transfer in progress.
#define ECODE_EMDRV_UARTDRV_ABORTED   (ECODE_EMDRV_UARTDRV_BASE | 0x00000009)
 UART transfer has been aborted.
#define ECODE_EMDRV_UARTDRV_QUEUE_FULL   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000A)
 UART operation queue is full.
#define ECODE_EMDRV_UARTDRV_QUEUE_EMPTY   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000B)
 UART operation queue is empty.
#define ECODE_EMDRV_UARTDRV_PARITY_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000C)
 UART parity error frame. Data is ignored.
#define ECODE_EMDRV_UARTDRV_FRAME_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000D)
 UART frame error. Data is ignored.
#define ECODE_EMDRV_UARTDRV_DMA_ALLOC_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000E)
 Unable to allocated DMA channels.
#define DEFINE_BUF_QUEUE(qSize, qName)
 Macros to define fifo and buffer queues, can't use a typedef becuase the size of the fifo array in the queues can change.
#define EMDRV_UARTDRV_MAX_CONCURRENT_TX_BUFS   6
 Maximum concurrent receive operations.
#define EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE   1
 Set to 1 to enable hardware flow control.
#define EMDRV_UARTDRV_MAX_DRIVER_INSTANCES   4
 Maximum number of driver instances. This maximum applies only when EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE = 1.
#define UARTDRV_FC_SW_XON   0x11
 UART software flow control code: request peer to start TX.
#define UARTDRV_FC_SW_XOFF   0x13
 UART software flow control code: request peer to stop TX.

Typedefs

typedef uint32_t UARTDRV_Count_t
typedef uint32_t UARTDRV_Status_t
 UART status return type.
typedef void(* UARTDRV_Callback_t )(struct UARTDRV_HandleData *handle, Ecode_t transferStatus, uint8_t *data, UARTDRV_Count_t transferCount)
 UARTDRV transfer completion callback function.
typedef UARTDRV_HandleData_tUARTDRV_Handle_t
 Handle pointer.

Enumerations

enum  UARTDRV_FlowControlType_t {
  uartdrvFlowControlNone = 0,
  uartdrvFlowControlSw = 1,
  uartdrvFlowControlHw = 2
}
 

Flow Control method.

More...
enum  UARTDRV_FlowControlState_t {
  uartdrvFlowControlOn = 0,
  uartdrvFlowControlOff = 1,
  uartdrvFlowControlAuto = 2
}
 

Flow Control state.

More...
enum  UARTDRV_AbortType_t {
  uartdrvAbortTransmit = 1,
  uartdrvAbortReceive = 2,
  uartdrvAbortAll = 3
}
 

Transfer abort type.

More...

Functions

Ecode_t UARTDRV_Init (UARTDRV_Handle_t handle, UARTDRV_Init_t *initData)
 Initialize a UART driver instance.
Ecode_t UARTDRV_DeInit (UARTDRV_Handle_t handle)
 Deinitialize a UART driver instance.
UARTDRV_Status_t UARTDRV_GetReceiveStatus (UARTDRV_Handle_t handle, uint8_t **buffer, UARTDRV_Count_t *bytesReceived, UARTDRV_Count_t *bytesRemaining)
 Check the status of the UART and gather information about any ongoing receive operations.
UARTDRV_Status_t UARTDRV_GetTransmitStatus (UARTDRV_Handle_t handle, uint8_t **buffer, UARTDRV_Count_t *bytesSent, UARTDRV_Count_t *bytesRemaining)
 Check the status of the UART and gather information about any ongoing transmit operations.
uint8_t UARTDRV_GetReceiveDepth (UARTDRV_Handle_t handle)
 Returns the number of queued receive operations.
uint8_t UARTDRV_GetTransmitDepth (UARTDRV_Handle_t handle)
 Returns the number of queued transmit operations.
Ecode_t UARTDRV_Transmit (UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count, UARTDRV_Callback_t callback)
 Start a non-blocking transmit.
Ecode_t UARTDRV_Receive (UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count, UARTDRV_Callback_t callback)
 Start a non-blocking receive.
Ecode_t UARTDRV_TransmitB (UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count)
 Start a blocking transmit.
Ecode_t UARTDRV_ReceiveB (UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count)
 Start a blocking receive.
Ecode_t UARTDRV_ForceTransmit (UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count)
 Direct transmit without interrupts or callback.
UARTDRV_Count_t UARTDRV_ForceReceive (UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t maxLength)
 Direct receive without interrupts or callback.
Ecode_t UARTDRV_Abort (UARTDRV_Handle_t handle, UARTDRV_AbortType_t type)
 Abort an ongoing UART transfer.
UARTDRV_FlowControlState_t UARTDRV_FlowControlGetSelfStatus (UARTDRV_Handle_t handle)
 Checks the self's flow control status.
UARTDRV_FlowControlState_t UARTDRV_FlowControlGetPeerStatus (UARTDRV_Handle_t handle)
 Checks the peer's flow control status.
Ecode_t UARTDRV_FlowControlSet (UARTDRV_Handle_t handle, UARTDRV_FlowControlState_t state)
 Set UART flow control state.
Ecode_t UARTDRV_FlowControlIgnoreRestrain (UARTDRV_Handle_t handle)
 Enables transmission when restrained by flow control.

Detailed Description

UARTDRV Universal asynchronous receiver/transmitter driver, see UARTDRV Universal asynchronous receiver/transmitter driver page for detailed documentation.


Define Documentation

#define DEFINE_BUF_QUEUE ( qSize,
qName   ) 
Value:
typedef struct {                        \
  uint16_t head;                        \
  uint16_t tail;                        \
  uint16_t used;                        \
  const uint16_t size;                  \
  UARTDRV_Buffer_t fifo[qSize];         \
} _##qName;                             \
static volatile _##qName qName =        \
{                                       \
  .head = 0,                            \
  .tail = 0,                            \
  .used = 0,                            \
  .size = qSize,                        \
}

Macros to define fifo and buffer queues, can't use a typedef becuase the size of the fifo array in the queues can change.

Definition at line 140 of file uartdrv.h.

#define ECODE_EMDRV_UARTDRV_ABORTED   (ECODE_EMDRV_UARTDRV_BASE | 0x00000009)

UART transfer has been aborted.

Definition at line 50 of file uartdrv.h.

Referenced by UARTDRV_Abort().

#define ECODE_EMDRV_UARTDRV_BUSY   (ECODE_EMDRV_UARTDRV_BASE | 0x00000004)

The UART port is busy.

Definition at line 47 of file uartdrv.h.

#define ECODE_EMDRV_UARTDRV_DMA_ALLOC_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000E)

Unable to allocated DMA channels.

Definition at line 55 of file uartdrv.h.

Referenced by UARTDRV_Init().

#define ECODE_EMDRV_UARTDRV_FRAME_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000D)

UART frame error. Data is ignored.

Definition at line 54 of file uartdrv.h.

#define ECODE_EMDRV_UARTDRV_IDLE   (ECODE_EMDRV_UARTDRV_BASE | 0x00000008)

No UART transfer in progress.

Definition at line 49 of file uartdrv.h.

Referenced by UARTDRV_Abort().

#define ECODE_EMDRV_UARTDRV_ILLEGAL_HANDLE   (ECODE_EMDRV_UARTDRV_BASE | 0x00000002)

Illegal UART handle.

Definition at line 45 of file uartdrv.h.

Referenced by UARTDRV_Abort(), UARTDRV_DeInit(), and UARTDRV_Init().

#define ECODE_EMDRV_UARTDRV_ILLEGAL_OPERATION   (ECODE_EMDRV_UARTDRV_BASE | 0x00000005)

Illegal operation on UART port.

Definition at line 48 of file uartdrv.h.

#define ECODE_EMDRV_UARTDRV_OK   (ECODE_OK)
#define ECODE_EMDRV_UARTDRV_PARAM_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x00000003)

Illegal input parameter.

Definition at line 46 of file uartdrv.h.

Referenced by UARTDRV_Init().

#define ECODE_EMDRV_UARTDRV_PARITY_ERROR   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000C)

UART parity error frame. Data is ignored.

Definition at line 53 of file uartdrv.h.

#define ECODE_EMDRV_UARTDRV_QUEUE_EMPTY   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000B)

UART operation queue is empty.

Definition at line 52 of file uartdrv.h.

#define ECODE_EMDRV_UARTDRV_QUEUE_FULL   (ECODE_EMDRV_UARTDRV_BASE | 0x0000000A)

UART operation queue is full.

Definition at line 51 of file uartdrv.h.

#define ECODE_EMDRV_UARTDRV_WAITING   (ECODE_EMDRV_UARTDRV_BASE | 0x00000001)

Operation is waiting in queue.

Definition at line 44 of file uartdrv.h.

Referenced by UARTDRV_Receive(), UARTDRV_ReceiveB(), UARTDRV_Transmit(), and UARTDRV_TransmitB().

#define EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE   1

Set to 1 to enable hardware flow control.

Definition at line 40 of file uartdrv_config.h.

#define EMDRV_UARTDRV_MAX_CONCURRENT_TX_BUFS   6

Maximum concurrent receive operations.

Maximum concurrent transmit operations

Definition at line 35 of file uartdrv_config.h.

#define EMDRV_UARTDRV_MAX_DRIVER_INSTANCES   4

Maximum number of driver instances. This maximum applies only when EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE = 1.

Definition at line 45 of file uartdrv_config.h.

#define UARTDRV_FC_SW_XOFF   0x13

UART software flow control code: request peer to stop TX.

Definition at line 55 of file uartdrv_config.h.

#define UARTDRV_FC_SW_XON   0x11

UART software flow control code: request peer to start TX.

Definition at line 50 of file uartdrv_config.h.


Typedef Documentation

typedef void(* UARTDRV_Callback_t)(struct UARTDRV_HandleData *handle, Ecode_t transferStatus, uint8_t *data, UARTDRV_Count_t transferCount)

UARTDRV transfer completion callback function.

The callback function is called when a transfer has completed. An application should check the transferStatus and itemsTransferred values.

Parameters:
[in] handle The UARTDRV device handle used to start the transfer.
[in] transferStatus Number of bytes actually transferred.
[in] itemsTransferred Number of bytes transferred.

Definition at line 113 of file uartdrv.h.

typedef uint32_t UARTDRV_Count_t

UART transfer count

Definition at line 67 of file uartdrv.h.

Handle pointer.

Definition at line 216 of file uartdrv.h.

typedef uint32_t UARTDRV_Status_t

UART status return type.

Definition at line 68 of file uartdrv.h.


Enumeration Type Documentation

Transfer abort type.

Enumerator:
uartdrvAbortTransmit 

Abort current and queued transmit operations.

uartdrvAbortReceive 

Abort current and queued receive operations.

uartdrvAbortAll 

Abort all current and queued operations.

Definition at line 87 of file uartdrv.h.

Flow Control state.

Enumerator:
uartdrvFlowControlOn 

XON or nRTS/nCTS low.

uartdrvFlowControlOff 

XOFF or nRTS/nCTS high.

uartdrvFlowControlAuto 

This driver controls the state.

Definition at line 79 of file uartdrv.h.

Flow Control method.

Enumerator:
uartdrvFlowControlNone 

None.

uartdrvFlowControlSw 

Software XON/XOFF.

uartdrvFlowControlHw 

nRTS/nCTS hardware handshake

Definition at line 71 of file uartdrv.h.


Function Documentation

Ecode_t UARTDRV_Abort ( UARTDRV_Handle_t  handle,
UARTDRV_AbortType_t  type 
)

Abort an ongoing UART transfer.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] type Abort type
Returns:
ECODE_EMDRV_UARTDRV_OK on success, ECODE_EMDRV_UARTDRV_IDLE if the UART is idle. On failure an appropriate UARTDRV Ecode_t is returned.

Definition at line 855 of file uartdrv.c.

References UARTDRV_Buffer_t::callback, DMADRV_StopTransfer(), DMADRV_TransferRemainingCount(), ECODE_EMDRV_UARTDRV_ABORTED, ECODE_EMDRV_UARTDRV_IDLE, ECODE_EMDRV_UARTDRV_ILLEGAL_HANDLE, ECODE_EMDRV_UARTDRV_OK, UARTDRV_Buffer_t::itemsRemaining, UARTDRV_Buffer_t::transferStatus, uartdrvAbortAll, uartdrvAbortReceive, and uartdrvAbortTransmit.

Here is the call graph for this function:

Ecode_t UARTDRV_DeInit ( UARTDRV_Handle_t  handle  ) 

Deinitialize a UART driver instance.

Parameters:
[in] handle Pointer to a UART driver handle.
Returns:
ECODE_EMDRV_UARTDRV_OK on success. On failure an appropriate UARTDRV Ecode_t is returned.

Definition at line 802 of file uartdrv.c.

References DMADRV_DeInit(), DMADRV_FreeChannel(), DMADRV_StopTransfer(), ECODE_EMDRV_UARTDRV_ILLEGAL_HANDLE, ECODE_EMDRV_UARTDRV_OK, GPIOINT_CallbackRegister(), UARTDRV_FlowControlSet(), and uartdrvFlowControlOn.

Here is the call graph for this function:

UARTDRV_FlowControlState_t UARTDRV_FlowControlGetPeerStatus ( UARTDRV_Handle_t  handle  ) 

Checks the peer's flow control status.

Parameters:
[in] handle Pointer to a UART driver handle.
Returns:
Returns uartdrvFlowControlOn if clear to send.

Definition at line 1072 of file uartdrv.c.

UARTDRV_FlowControlState_t UARTDRV_FlowControlGetSelfStatus ( UARTDRV_Handle_t  handle  ) 

Checks the self's flow control status.

Parameters:
[in] handle Pointer to a UART driver handle.
Returns:
Returns uartdrvFlowControlOn if requesting to send.

Definition at line 1087 of file uartdrv.c.

Ecode_t UARTDRV_FlowControlIgnoreRestrain ( UARTDRV_Handle_t  handle  ) 

Enables transmission when restrained by flow control.

Parameters:
[in] handle Pointer to a UART driver handle.
Returns:
ECODE_EMDRV_UARTDRV_OK on success.

Definition at line 1102 of file uartdrv.c.

References ECODE_EMDRV_UARTDRV_OK.

Ecode_t UARTDRV_FlowControlSet ( UARTDRV_Handle_t  handle,
UARTDRV_FlowControlState_t  state 
)

Set UART flow control state.

Set nRTS pin if hardware flow control is enabled.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] state Flow control state.
Returns:
ECODE_EMDRV_UARTDRV_OK on success.

Definition at line 1048 of file uartdrv.c.

References ECODE_EMDRV_UARTDRV_OK, and uartdrvFlowControlAuto.

Referenced by UARTDRV_DeInit().

Here is the caller graph for this function:

UARTDRV_Count_t UARTDRV_ForceReceive ( UARTDRV_Handle_t  handle,
uint8_t *  data,
UARTDRV_Count_t  maxCount 
)

Direct receive without interrupts or callback.

Blocking function.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] data pointer to buffer.
[in] maxCount Maximum number of bytes to receive.
Returns:
Number of bytes received.

Definition at line 1123 of file uartdrv.c.

References ECODE_EMDRV_UARTDRV_OK.

Ecode_t UARTDRV_ForceTransmit ( UARTDRV_Handle_t  handle,
uint8_t *  data,
UARTDRV_Count_t  count 
)

Direct transmit without interrupts or callback.

Blocking function that ignores flow control if enabled.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] data Pointer to buffer.
[in] count Number of bytes to transmit.
Returns:
ECODE_EMDRV_UARTDRV_OK on success.

Definition at line 1180 of file uartdrv.c.

References ECODE_EMDRV_UARTDRV_OK.

uint8_t UARTDRV_GetReceiveDepth ( UARTDRV_Handle_t  handle  ) 

Returns the number of queued receive operations.

Parameters:
[in] handle Pointer to a UART driver handle.
Returns:
The number of queued operations.

Definition at line 927 of file uartdrv.c.

UARTDRV_Status_t UARTDRV_GetReceiveStatus ( UARTDRV_Handle_t  handle,
uint8_t **  buffer,
UARTDRV_Count_t itemsReceived,
UARTDRV_Count_t itemsRemaining 
)

Check the status of the UART and gather information about any ongoing receive operations.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] buffer Pointer to the current data buffer.
[in] itemsReceived Current bytes received count.
[in] itemsRemaining Current bytes remaining count.
Returns:
UART status.

Definition at line 949 of file uartdrv.c.

References UARTDRV_Buffer_t::data, DMADRV_TransferRemainingCount(), and UARTDRV_Buffer_t::transferCount.

Here is the call graph for this function:

uint8_t UARTDRV_GetTransmitDepth ( UARTDRV_Handle_t  handle  ) 

Returns the number of queued transmit operations.

Parameters:
[in] handle Pointer to a UART driver handle.
Returns:
The number of queued operations.

Definition at line 986 of file uartdrv.c.

UARTDRV_Status_t UARTDRV_GetTransmitStatus ( UARTDRV_Handle_t  handle,
uint8_t **  buffer,
UARTDRV_Count_t itemsSent,
UARTDRV_Count_t itemsRemaining 
)

Check the status of the UART and gather information about any ongoing transmit operations.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] buffer Pointer to the current data buffer.
[in] itemsSent Current bytes sent count.
[in] itemsRemaining Current bytes remaining count.
Returns:
UART status.

Definition at line 1008 of file uartdrv.c.

References UARTDRV_Buffer_t::data, DMADRV_TransferRemainingCount(), and UARTDRV_Buffer_t::transferCount.

Here is the call graph for this function:

Ecode_t UARTDRV_Init ( UARTDRV_Handle_t  handle,
UARTDRV_Init_t initData 
)
Ecode_t UARTDRV_Receive ( UARTDRV_Handle_t  handle,
uint8_t *  data,
UARTDRV_Count_t  count,
UARTDRV_Callback_t  callback 
)

Start a non-blocking receive.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] data Receive data buffer.
[in] count Number of bytes received.
[in] callback Transfer completion callback.
Returns:
ECODE_EMDRV_UARTDRV_OK on success.

Definition at line 1234 of file uartdrv.c.

References UARTDRV_Buffer_t::callback, UARTDRV_Buffer_t::data, ECODE_EMDRV_UARTDRV_OK, ECODE_EMDRV_UARTDRV_WAITING, UARTDRV_Buffer_t::itemsRemaining, UARTDRV_Buffer_t::transferCount, UARTDRV_Buffer_t::transferStatus, and uartdrvFlowControlOn.

Ecode_t UARTDRV_ReceiveB ( UARTDRV_Handle_t  handle,
uint8_t *  data,
UARTDRV_Count_t  count 
)

Start a blocking receive.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] data Receive data buffer.
[in] count Number of bytes received.
Returns:
ECODE_EMDRV_UARTDRV_OK on success.

Definition at line 1286 of file uartdrv.c.

References UARTDRV_Buffer_t::callback, UARTDRV_Buffer_t::data, ECODE_EMDRV_UARTDRV_OK, ECODE_EMDRV_UARTDRV_WAITING, UARTDRV_Buffer_t::itemsRemaining, UARTDRV_Buffer_t::transferCount, UARTDRV_Buffer_t::transferStatus, and uartdrvFlowControlOn.

Ecode_t UARTDRV_Transmit ( UARTDRV_Handle_t  handle,
uint8_t *  data,
UARTDRV_Count_t  count,
UARTDRV_Callback_t  callback 
)

Start a non-blocking transmit.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] data Transmit data buffer.
[in] count Number of bytes to transmit.
[in] callback Transfer completion callback.
Returns:
ECODE_EMDRV_UARTDRV_OK on success.

Definition at line 1343 of file uartdrv.c.

References UARTDRV_Buffer_t::callback, UARTDRV_Buffer_t::data, ECODE_EMDRV_UARTDRV_OK, ECODE_EMDRV_UARTDRV_WAITING, UARTDRV_Buffer_t::itemsRemaining, UARTDRV_Buffer_t::transferCount, and UARTDRV_Buffer_t::transferStatus.

Ecode_t UARTDRV_TransmitB ( UARTDRV_Handle_t  handle,
uint8_t *  data,
UARTDRV_Count_t  count 
)

Start a blocking transmit.

Parameters:
[in] handle Pointer to a UART driver handle.
[in] data Transmit data buffer.
[in] count Number of bytes to transmit.
Returns:
ECODE_EMDRV_UARTDRV_OK on success.

Definition at line 1390 of file uartdrv.c.

References UARTDRV_Buffer_t::callback, UARTDRV_Buffer_t::data, ECODE_EMDRV_UARTDRV_OK, ECODE_EMDRV_UARTDRV_WAITING, UARTDRV_Buffer_t::itemsRemaining, UARTDRV_Buffer_t::transferCount, and UARTDRV_Buffer_t::transferStatus.