EFM32 Happy Gecko Software Documentation  efm32hg-doc-4.2.1
uartdrv.h
Go to the documentation of this file.
1 /***************************************************************************/
16 #ifndef __SILICON_LABS_UARTDRV_H__
17 #define __SILICON_LABS_UARTDRV_H__
18 
19 #include "em_device.h"
20 #include "em_usart.h"
21 #include "em_cmu.h"
22 #include "ecode.h"
23 #include "uartdrv_config.h"
24 #include "dmadrv.h"
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 /***************************************************************************/
35 /***************************************************************************/
43 #define ECODE_EMDRV_UARTDRV_OK (ECODE_OK)
44 #define ECODE_EMDRV_UARTDRV_WAITING (ECODE_EMDRV_UARTDRV_BASE | 0x00000001)
45 #define ECODE_EMDRV_UARTDRV_ILLEGAL_HANDLE (ECODE_EMDRV_UARTDRV_BASE | 0x00000002)
46 #define ECODE_EMDRV_UARTDRV_PARAM_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x00000003)
47 #define ECODE_EMDRV_UARTDRV_BUSY (ECODE_EMDRV_UARTDRV_BASE | 0x00000004)
48 #define ECODE_EMDRV_UARTDRV_ILLEGAL_OPERATION (ECODE_EMDRV_UARTDRV_BASE | 0x00000005)
49 #define ECODE_EMDRV_UARTDRV_IDLE (ECODE_EMDRV_UARTDRV_BASE | 0x00000008)
50 #define ECODE_EMDRV_UARTDRV_ABORTED (ECODE_EMDRV_UARTDRV_BASE | 0x00000009)
51 #define ECODE_EMDRV_UARTDRV_QUEUE_FULL (ECODE_EMDRV_UARTDRV_BASE | 0x0000000A)
52 #define ECODE_EMDRV_UARTDRV_QUEUE_EMPTY (ECODE_EMDRV_UARTDRV_BASE | 0x0000000B)
53 #define ECODE_EMDRV_UARTDRV_PARITY_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x0000000C)
54 #define ECODE_EMDRV_UARTDRV_FRAME_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x0000000D)
55 #define ECODE_EMDRV_UARTDRV_DMA_ALLOC_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x0000000E)
56 
57 #if defined(UART_PRESENT) && defined(USART_PRESENT)
59 #define UART_NUM_PORTS (UART_COUNT + USART_COUNT)
60 #elif defined(UART_PRESENT)
61 #define UART_NUM_PORTS (UART_COUNT)
62 #else
63 #define UART_NUM_PORTS (USART_COUNT)
64 #endif
65 
67 typedef uint32_t UARTDRV_Count_t;
68 typedef uint32_t UARTDRV_Status_t;
69 
72 {
77 
80 {
85 
87 typedef enum UARTDRV_AbortType
88 {
93 
94 struct UARTDRV_HandleData;
95 
96 /***************************************************************************/
113 typedef void (*UARTDRV_Callback_t)(struct UARTDRV_HandleData *handle,
114  Ecode_t transferStatus,
115  uint8_t *data,
116  UARTDRV_Count_t transferCount);
117 
119 typedef struct
120 {
121  uint8_t *data;
122  UARTDRV_Count_t transferCount;
123  UARTDRV_Count_t itemsRemaining;
127 
129 typedef struct
130 {
131  uint16_t head;
132  uint16_t tail;
133  uint16_t used;
134  const uint16_t size;
137 
140 #define DEFINE_BUF_QUEUE(qSize, qName) \
141 typedef struct { \
142  uint16_t head; \
143  uint16_t tail; \
144  uint16_t used; \
145  const uint16_t size; \
146  UARTDRV_Buffer_t fifo[qSize]; \
147 } _##qName; \
148 static volatile _##qName qName = \
149 { \
150  .head = 0, \
151  .tail = 0, \
152  .used = 0, \
153  .size = qSize, \
154 }
155 
156 
162 typedef struct
163 {
165  uint32_t baudRate;
166 #if defined( _USART_ROUTELOC0_MASK )
167  uint8_t portLocationTx;
168  uint8_t portLocationRx;
169 #else
170  uint8_t portLocation;
171 #endif
175 #if defined(USART_CTRL_MVDIS)
176  bool mvdis;
177 #endif
180  uint8_t ctsPin;
182  uint8_t rtsPin;
186 
191 typedef struct UARTDRV_HandleData
192 {
194  UARTDRV_Init_t initData; // Driver instance initialization data
195  unsigned int txDmaCh; // DMA ch assigned to Tx
196  unsigned int rxDmaCh; // DMA ch assigned to Rx
197  DMADRV_PeripheralSignal_t txDmaSignal; // DMA Tx trigger source signal
198  DMADRV_PeripheralSignal_t rxDmaSignal; // DMA Rx trigger source signal
199  UARTDRV_FlowControlState_t fcSelfState; // Current flow control state of self
200  UARTDRV_FlowControlState_t fcSelfCfg; // Flow control override configuration of self
201  UARTDRV_FlowControlState_t fcPeerState; // Current flow control state of peer
202  bool IgnoreRestrain; // Transmit does not respect uartdrvFlowControlOff
203  GPIO_Port_TypeDef rxPort; // RX pin port number
204  uint8_t rxPin; // RX pin number
205  GPIO_Port_TypeDef txPort; // TX pin port number
206  uint8_t txPin; // RTS pin number
207  CMU_Clock_TypeDef uartClock; // Clock source select
208  UARTDRV_Buffer_FifoQueue_t *rxQueue; // Receive operation queue
209  UARTDRV_Buffer_FifoQueue_t *txQueue; // Transmit operation queue
210  volatile bool rxDmaActive; // Receive DMA is currently active
211  volatile bool txDmaActive; // Transmit DMA is currently active
214 
217 
218 Ecode_t UARTDRV_Init(UARTDRV_Handle_t handle, UARTDRV_Init_t *initData);
219 
220 Ecode_t UARTDRV_DeInit(UARTDRV_Handle_t handle);
221 
222 UARTDRV_Status_t UARTDRV_GetReceiveStatus(UARTDRV_Handle_t handle,
223  uint8_t **buffer,
224  UARTDRV_Count_t *bytesReceived,
225  UARTDRV_Count_t *bytesRemaining);
226 
227 UARTDRV_Status_t UARTDRV_GetTransmitStatus(UARTDRV_Handle_t handle,
228  uint8_t **buffer,
229  UARTDRV_Count_t *bytesSent,
230  UARTDRV_Count_t *bytesRemaining);
231 
232 uint8_t UARTDRV_GetReceiveDepth(UARTDRV_Handle_t handle);
233 
234 uint8_t UARTDRV_GetTransmitDepth(UARTDRV_Handle_t handle);
235 
236 Ecode_t UARTDRV_Transmit(UARTDRV_Handle_t handle,
237  uint8_t *data,
238  UARTDRV_Count_t count,
239  UARTDRV_Callback_t callback);
240 
241 Ecode_t UARTDRV_Receive(UARTDRV_Handle_t handle,
242  uint8_t *data,
243  UARTDRV_Count_t count,
244  UARTDRV_Callback_t callback);
245 
246 Ecode_t UARTDRV_TransmitB(UARTDRV_Handle_t handle,
247  uint8_t *data,
248  UARTDRV_Count_t count);
249 
250 Ecode_t UARTDRV_ReceiveB(UARTDRV_Handle_t handle,
251  uint8_t *data,
252  UARTDRV_Count_t count);
253 
254 Ecode_t UARTDRV_ForceTransmit(UARTDRV_Handle_t handle,
255  uint8_t *data,
256  UARTDRV_Count_t count);
257 
258 UARTDRV_Count_t UARTDRV_ForceReceive(UARTDRV_Handle_t handle,
259  uint8_t *data,
260  UARTDRV_Count_t maxLength);
261 
262 Ecode_t UARTDRV_Abort(UARTDRV_Handle_t handle, UARTDRV_AbortType_t type);
263 
265 
267 
268 Ecode_t UARTDRV_FlowControlSet(UARTDRV_Handle_t handle, UARTDRV_FlowControlState_t state);
269 
270 Ecode_t UARTDRV_FlowControlIgnoreRestrain(UARTDRV_Handle_t handle);
271 
275 #ifdef __cplusplus
276 }
277 #endif
278 #endif // __SILICON_LABS_UARTDRV_H__
Clock management unit (CMU) API.
Software XON/XOFF.
Definition: uartdrv.h:74
XOFF or nRTS/nCTS high.
Definition: uartdrv.h:82
UARTDRV_Buffer_FifoQueue_t * txQueue
Transmit operation queue.
Definition: uartdrv.h:184
Ecode_t UARTDRV_Transmit(UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count, UARTDRV_Callback_t callback)
Start a non-blocking transmit.
Definition: uartdrv.c:1350
DMADRV API definition.
uint8_t UARTDRV_GetTransmitDepth(UARTDRV_Handle_t handle)
Returns the number of queued transmit operations.
Definition: uartdrv.c:993
UARTDRV_Buffer_FifoQueue_t * rxQueue
Receive operation queue.
Definition: uartdrv.h:183
GPIO_Port_TypeDef
Definition: em_gpio.h:232
enum UARTDRV_AbortType UARTDRV_AbortType_t
Transfer abort type.
Abort all current and queued operations.
Definition: uartdrv.h:91
Ecode_t transferStatus
Completion status of transfer operation.
Definition: uartdrv.h:125
Energy Aware drivers error code definitions.
UARTDRV_FlowControlState_t UARTDRV_FlowControlGetSelfStatus(UARTDRV_Handle_t handle)
Checks the self's flow control status.
Definition: uartdrv.c:1094
UARTDRV_AbortType
Transfer abort type.
Definition: uartdrv.h:87
GPIO_Port_TypeDef rtsPort
RTS pin port number.
Definition: uartdrv.h:181
USART_OVS_TypeDef oversampling
Oversampling mode.
Definition: uartdrv.h:174
USART_TypeDef * port
The peripheral used for UART.
Definition: uartdrv.h:164
USART_Stopbits_TypeDef
Definition: em_usart.h:118
CMSIS Cortex-M Peripheral Access Layer for Silicon Laboratories microcontroller devices.
Universal synchronous/asynchronous receiver/transmitter (USART/UART) peripheral API.
uint8_t rtsPin
RTS pin number.
Definition: uartdrv.h:182
Ecode_t UARTDRV_Init(UARTDRV_Handle_t handle, UARTDRV_Init_t *initData)
Initialize a UART driver instance.
Definition: uartdrv.c:591
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.
Definition: uartdrv.c:1055
const uint16_t size
Size of FIFO.
Definition: uartdrv.h:134
This driver controls the state.
Definition: uartdrv.h:83
UARTDRV_Count_t transferCount
Transfer item count.
Definition: uartdrv.h:122
USART_Stopbits_TypeDef stopBits
Number of stop bits.
Definition: uartdrv.h:172
bool mvdis
Majority Vote Disable for 16x, 8x and 6x oversampling modes.
Definition: uartdrv.h:176
enum UARTDRV_FlowControlState UARTDRV_FlowControlState_t
Flow Control state.
Transfer operation FIFO queue typedef.
Definition: uartdrv.h:129
UARTDRV_HandleData_t * UARTDRV_Handle_t
Handle pointer.
Definition: uartdrv.h:216
UARTDRV_FlowControlType
Flow Control method.
Definition: uartdrv.h:71
nRTS/nCTS hardware handshake
Definition: uartdrv.h:75
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 enable...
Definition: uartdrv.c:1187
XON or nRTS/nCTS low.
Definition: uartdrv.h:81
USART_Parity_TypeDef parity
Parity configuration.
Definition: uartdrv.h:173
UARTDRV_Count_t itemsRemaining
Transfer items remaining.
Definition: uartdrv.h:123
Ecode_t UARTDRV_ReceiveB(UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count)
Start a blocking receive.
Definition: uartdrv.c:1293
CMU_Clock_TypeDef
Definition: em_cmu.h:256
UARTDRV_Callback_t callback
Completion callback.
Definition: uartdrv.h:124
struct UARTDRV_HandleData UARTDRV_HandleData_t
uint8_t portLocation
Location number for UART pins.
Definition: uartdrv.h:170
uint32_t baudRate
UART baud rate.
Definition: uartdrv.h:165
uint8_t ctsPin
CTS pin number.
Definition: uartdrv.h:180
UART transfer buffer.
Definition: uartdrv.h:119
void(* UARTDRV_Callback_t)(struct UARTDRV_HandleData *handle, Ecode_t transferStatus, uint8_t *data, UARTDRV_Count_t transferCount)
UARTDRV transfer completion callback function.
Definition: uartdrv.h:113
Ecode_t UARTDRV_Receive(UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count, UARTDRV_Callback_t callback)
Start a non-blocking receive.
Definition: uartdrv.c:1241
Ecode_t UARTDRV_DeInit(UARTDRV_Handle_t handle)
Deinitialize a UART driver instance.
Definition: uartdrv.c:809
Abort current and queued receive operations.
Definition: uartdrv.h:90
UARTDRV_Count_t UARTDRV_ForceReceive(UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t maxLength)
Direct receive without interrupts or callback. Blocking function.
Definition: uartdrv.c:1130
GPIO_Port_TypeDef ctsPort
CTS pin port number.
Definition: uartdrv.h:179
uint32_t UARTDRV_Count_t
UART transfer count.
Definition: uartdrv.h:67
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.
Definition: uartdrv.c:956
USART_OVS_TypeDef
Definition: em_usart.h:99
uint8_t UARTDRV_GetReceiveDepth(UARTDRV_Handle_t handle)
Returns the number of queued receive operations.
Definition: uartdrv.c:934
enum UARTDRV_FlowControlType UARTDRV_FlowControlType_t
Flow Control method.
uint8_t * data
Transfer data buffer.
Definition: uartdrv.h:121
uint32_t Ecode_t
Typedef for API function errorcode return values.
Definition: ecode.h:31
Ecode_t UARTDRV_Abort(UARTDRV_Handle_t handle, UARTDRV_AbortType_t type)
Abort an ongoing UART transfer.
Definition: uartdrv.c:862
UARTDRV_FlowControlType_t fcType
Flow control mode.
Definition: uartdrv.h:178
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.
Definition: uartdrv.c:1015
UARTDRV_FlowControlState_t UARTDRV_FlowControlGetPeerStatus(UARTDRV_Handle_t handle)
Checks the peer's flow control status.
Definition: uartdrv.c:1079
Ecode_t UARTDRV_TransmitB(UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count)
Start a blocking transmit.
Definition: uartdrv.c:1397
UARTDRV_FlowControlState
Flow Control state.
Definition: uartdrv.h:79
uint16_t used
Number of bytes queued.
Definition: uartdrv.h:133
Ecode_t UARTDRV_FlowControlIgnoreRestrain(UARTDRV_Handle_t handle)
Enables transmission when restrained by flow control.
Definition: uartdrv.c:1109
USART_Parity_TypeDef
Definition: em_usart.h:109
uint16_t head
Index of next byte to send.
Definition: uartdrv.h:131
Abort current and queued transmit operations.
Definition: uartdrv.h:89
uint32_t UARTDRV_Status_t
UART status return type.
Definition: uartdrv.h:68
uint16_t tail
Index of where to enqueue next message.
Definition: uartdrv.h:132