EFM32 Happy Gecko Software Documentation  efm32hg-doc-5.1.2
uartdrv.h
Go to the documentation of this file.
1 /***************************************************************************/
16 #ifndef UARTDRV_H
17 #define UARTDRV_H
18 
19 #include "em_device.h"
20 #include "em_usart.h"
21 #include "em_leuart.h"
22 #include "em_gpio.h"
23 #include "em_cmu.h"
24 #include "ecode.h"
25 #include "uartdrv_config.h"
26 #include "dmadrv.h"
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /***************************************************************************/
37 /***************************************************************************/
42 #define ECODE_EMDRV_UARTDRV_OK (ECODE_OK)
43 #define ECODE_EMDRV_UARTDRV_WAITING (ECODE_EMDRV_UARTDRV_BASE | 0x00000001)
44 #define ECODE_EMDRV_UARTDRV_ILLEGAL_HANDLE (ECODE_EMDRV_UARTDRV_BASE | 0x00000002)
45 #define ECODE_EMDRV_UARTDRV_PARAM_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x00000003)
46 #define ECODE_EMDRV_UARTDRV_BUSY (ECODE_EMDRV_UARTDRV_BASE | 0x00000004)
47 #define ECODE_EMDRV_UARTDRV_ILLEGAL_OPERATION (ECODE_EMDRV_UARTDRV_BASE | 0x00000005)
48 #define ECODE_EMDRV_UARTDRV_IDLE (ECODE_EMDRV_UARTDRV_BASE | 0x00000008)
49 #define ECODE_EMDRV_UARTDRV_ABORTED (ECODE_EMDRV_UARTDRV_BASE | 0x00000009)
50 #define ECODE_EMDRV_UARTDRV_QUEUE_FULL (ECODE_EMDRV_UARTDRV_BASE | 0x0000000A)
51 #define ECODE_EMDRV_UARTDRV_QUEUE_EMPTY (ECODE_EMDRV_UARTDRV_BASE | 0x0000000B)
52 #define ECODE_EMDRV_UARTDRV_PARITY_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x0000000C)
53 #define ECODE_EMDRV_UARTDRV_FRAME_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x0000000D)
54 #define ECODE_EMDRV_UARTDRV_DMA_ALLOC_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x0000000E)
55 #define ECODE_EMDRV_UARTDRV_CLOCK_ERROR (ECODE_EMDRV_UARTDRV_BASE | 0x0000000F)
56 
57 // UARTDRV status codes
58 #define UARTDRV_STATUS_RXEN (1 << 0)
59 #define UARTDRV_STATUS_TXEN (1 << 1)
60 #define UARTDRV_STATUS_RXBLOCK (1 << 3)
61 #define UARTDRV_STATUS_TXTRI (1 << 4)
62 #define UARTDRV_STATUS_TXC (1 << 5)
63 #define UARTDRV_STATUS_TXBL (1 << 6)
64 #define UARTDRV_STATUS_RXDATAV (1 << 7)
65 #define UARTDRV_STATUS_RXFULL (1 << 8)
66 #define UARTDRV_STATUS_TXIDLE (1 << 13)
67 
68 typedef uint32_t UARTDRV_Count_t;
69 typedef uint32_t UARTDRV_Status_t;
70 
73 {
79 
82 {
87 
89 typedef enum UARTDRV_AbortType
90 {
95 
98 typedef enum UARTDRV_UartType
99 {
100  uartdrvUartTypeUart = 0,
101  uartdrvUartTypeLeuart = 1
102 } UARTDRV_UartType_t;
104 
105 struct UARTDRV_HandleData;
106 
107 /***************************************************************************/
127 typedef void (*UARTDRV_Callback_t)(struct UARTDRV_HandleData *handle,
128  Ecode_t transferStatus,
129  uint8_t *data,
130  UARTDRV_Count_t transferCount);
131 
133 typedef struct
134 {
135  uint8_t *data;
136  UARTDRV_Count_t transferCount;
137  volatile UARTDRV_Count_t itemsRemaining;
141 
143 typedef struct
144 {
145  volatile uint16_t head;
146  volatile uint16_t tail;
147  volatile uint16_t used;
148  const uint16_t size;
151 
154 #define DEFINE_BUF_QUEUE(qSize, qName) \
155 typedef struct { \
156  uint16_t head; \
157  uint16_t tail; \
158  volatile uint16_t used; \
159  const uint16_t size; \
160  UARTDRV_Buffer_t fifo[qSize]; \
161 } _##qName; \
162 static volatile _##qName qName = \
163 { \
164  .head = 0, \
165  .tail = 0, \
166  .used = 0, \
167  .size = qSize, \
168 }
169 
170 
176 typedef struct
177 {
179  uint32_t baudRate;
180 #if defined( _USART_ROUTELOC0_MASK )
181  uint8_t portLocationTx;
182  uint8_t portLocationRx;
183 #else
184  uint8_t portLocation;
185 #endif
189 #if defined(USART_CTRL_MVDIS)
190  bool mvdis;
191 #endif
194  uint8_t ctsPin;
196  uint8_t rtsPin;
199 #if defined( _USART_ROUTELOC1_MASK )
200  uint8_t portLocationCts;
201  uint8_t portLocationRts;
202 #endif
204 
208 typedef UARTDRV_InitUart_t UARTDRV_Init_t;
210 
216 typedef struct
217 {
219  uint32_t baudRate;
220 #if defined( _LEUART_ROUTELOC0_MASK )
221  uint8_t portLocationTx;
222  uint8_t portLocationRx;
223 #else
224  uint8_t portLocation;
225 #endif
230  uint8_t ctsPin;
232  uint8_t rtsPin;
236 
241 typedef struct UARTDRV_HandleData
242 {
244  union peripheral {
245  USART_TypeDef * uart;
246  LEUART_TypeDef * leuart;
247  } peripheral;
248  unsigned int txDmaCh; // DMA ch assigned to Tx
249  unsigned int rxDmaCh; // DMA ch assigned to Rx
250  DMADRV_PeripheralSignal_t txDmaSignal; // DMA Tx trigger source signal
251  DMADRV_PeripheralSignal_t rxDmaSignal; // DMA Rx trigger source signal
252  UARTDRV_FlowControlState_t fcSelfState; // Current flow control state of self
253  UARTDRV_FlowControlState_t fcSelfCfg; // Flow control override configuration of self
254  UARTDRV_FlowControlState_t fcPeerState; // Current flow control state of peer
255  GPIO_Port_TypeDef txPort; // TX pin port number
256  GPIO_Port_TypeDef rxPort; // RX pin port number
257  GPIO_Port_TypeDef ctsPort; // CTS pin port number
258  GPIO_Port_TypeDef rtsPort; // RTS pin port number
259  uint8_t txPin; // TX pin number
260  uint8_t rxPin; // RX pin number
261  uint8_t ctsPin; // CTS pin number
262  uint8_t rtsPin; // RTS pin number
263  CMU_Clock_TypeDef uartClock; // Clock source select
264  UARTDRV_Buffer_FifoQueue_t *rxQueue; // Receive operation queue
265  UARTDRV_Buffer_FifoQueue_t *txQueue; // Transmit operation queue
266  volatile bool rxDmaActive; // Receive DMA is currently active
267  volatile bool txDmaActive; // Transmit DMA is currently active
268  volatile uint8_t txDmaPaused; // Transmit DMA pause counter
269  bool IgnoreRestrain; // Transmit does not respect uartdrvFlowControlOff
270  bool hasTransmitted; // Whether the handle has transmitted data
271  UARTDRV_FlowControlType_t fcType; // Flow control mode
272  UARTDRV_UartType_t type; // Type of UART
275 
278 
279 Ecode_t UARTDRV_InitUart(UARTDRV_Handle_t handle,
280  const UARTDRV_InitUart_t * initData);
281 
282 Ecode_t UARTDRV_InitLeuart(UARTDRV_Handle_t handle,
283  const UARTDRV_InitLeuart_t * initData);
284 
285 Ecode_t UARTDRV_DeInit(UARTDRV_Handle_t handle);
286 
287 UARTDRV_Status_t UARTDRV_GetPeripheralStatus(UARTDRV_Handle_t handle);
288 
289 UARTDRV_Status_t UARTDRV_GetReceiveStatus(UARTDRV_Handle_t handle,
290  uint8_t **buffer,
291  UARTDRV_Count_t *bytesReceived,
292  UARTDRV_Count_t *bytesRemaining);
293 
294 UARTDRV_Status_t UARTDRV_GetTransmitStatus(UARTDRV_Handle_t handle,
295  uint8_t **buffer,
296  UARTDRV_Count_t *bytesSent,
297  UARTDRV_Count_t *bytesRemaining);
298 
299 uint8_t UARTDRV_GetReceiveDepth(UARTDRV_Handle_t handle);
300 
301 uint8_t UARTDRV_GetTransmitDepth(UARTDRV_Handle_t handle);
302 
303 Ecode_t UARTDRV_Transmit(UARTDRV_Handle_t handle,
304  uint8_t *data,
305  UARTDRV_Count_t count,
306  UARTDRV_Callback_t callback);
307 
308 Ecode_t UARTDRV_Receive(UARTDRV_Handle_t handle,
309  uint8_t *data,
310  UARTDRV_Count_t count,
311  UARTDRV_Callback_t callback);
312 
313 Ecode_t UARTDRV_TransmitB(UARTDRV_Handle_t handle,
314  uint8_t *data,
315  UARTDRV_Count_t count);
316 
317 Ecode_t UARTDRV_ReceiveB(UARTDRV_Handle_t handle,
318  uint8_t *data,
319  UARTDRV_Count_t count);
320 
321 Ecode_t UARTDRV_ForceTransmit(UARTDRV_Handle_t handle,
322  uint8_t *data,
323  UARTDRV_Count_t count);
324 
325 UARTDRV_Count_t UARTDRV_ForceReceive(UARTDRV_Handle_t handle,
326  uint8_t *data,
327  UARTDRV_Count_t maxLength);
328 
329 Ecode_t UARTDRV_Abort(UARTDRV_Handle_t handle, UARTDRV_AbortType_t type);
330 
331 Ecode_t UARTDRV_PauseTransmit(UARTDRV_Handle_t handle);
332 
333 Ecode_t UARTDRV_ResumeTransmit(UARTDRV_Handle_t handle);
334 
336 
338 
339 Ecode_t UARTDRV_FlowControlSet(UARTDRV_Handle_t handle, UARTDRV_FlowControlState_t state);
340 
342 
343 Ecode_t UARTDRV_FlowControlIgnoreRestrain(UARTDRV_Handle_t handle);
344 
345 
346 // --------------------------------
347 // Deprecated items
348 
349 /***************************************************************************/
366 __STATIC_INLINE Ecode_t UARTDRV_Init(UARTDRV_Handle_t handle, UARTDRV_InitUart_t *initData)
367 {
368  return UARTDRV_InitUart(handle, initData);
369 }
370 
375 #if defined(EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE)
376 #undef EMDRV_UARTDRV_FLOW_CONTROL_ENABLE
377 #define EMDRV_UARTDRV_FLOW_CONTROL_ENABLE EMDRV_UARTDRV_HW_FLOW_CONTROL_ENABLE
378 #endif
379 
383 #ifdef __cplusplus
384 }
385 #endif
386 #endif // UARTDRV_H
Clock management unit (CMU) API.
Software XON/XOFF.
Definition: uartdrv.h:75
XOFF or nRTS/nCTS high.
Definition: uartdrv.h:84
USART_TypeDef * port
The peripheral used for UART.
Definition: uartdrv.h:178
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:2290
DMADRV API definition.
uint8_t UARTDRV_GetTransmitDepth(UARTDRV_Handle_t handle)
Returns the number of queued transmit operations.
Definition: uartdrv.c:1751
uint8_t ctsPin
CTS pin number.
Definition: uartdrv.h:194
LEUART_Parity_TypeDef
Definition: em_leuart.h:86
GPIO_Port_TypeDef
Definition: em_gpio.h:345
enum UARTDRV_AbortType UARTDRV_AbortType_t
Transfer abort type.
Abort all current and queued operations.
Definition: uartdrv.h:93
Ecode_t transferStatus
Completion status of transfer operation.
Definition: uartdrv.h:139
uint8_t ctsPin
CTS pin number.
Definition: uartdrv.h:230
GPIO_Port_TypeDef rtsPort
RTS pin port number.
Definition: uartdrv.h:195
uint32_t baudRate
UART baud rate.
Definition: uartdrv.h:179
UARTDRV_Buffer_FifoQueue_t * rxQueue
Receive operation queue.
Definition: uartdrv.h:233
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:1894
USART_Parity_TypeDef parity
Parity configuration.
Definition: uartdrv.h:187
USART_Stopbits_TypeDef stopBits
Number of stop bits.
Definition: uartdrv.h:186
UARTDRV_AbortType
Transfer abort type.
Definition: uartdrv.h:89
USART_Stopbits_TypeDef
Definition: em_usart.h:160
CMSIS Cortex-M Peripheral Access Layer for Silicon Laboratories microcontroller devices.
volatile UARTDRV_Count_t itemsRemaining
Transfer items remaining.
Definition: uartdrv.h:137
Universal synchronous/asynchronous receiver/transmitter (USART/UART) peripheral API.
UARTDRV_FlowControlType_t fcType
Flow control mode.
Definition: uartdrv.h:192
Ecode_t UARTDRV_InitUart(UARTDRV_Handle_t handle, const UARTDRV_InitUart_t *initData)
Initialize a U(S)ART driver instance.
Definition: uartdrv.c:1015
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. Send XON/XOFF if softw...
Definition: uartdrv.c:1816
uint32_t baudRate
UART baud rate.
Definition: uartdrv.h:219
const uint16_t size
Size of FIFO.
Definition: uartdrv.h:148
uint8_t portLocation
Location number for UART pins.
Definition: uartdrv.h:184
uint8_t rtsPin
RTS pin number.
Definition: uartdrv.h:196
GPIO_Port_TypeDef ctsPort
CTS pin port number.
Definition: uartdrv.h:229
This driver controls the state.
Definition: uartdrv.h:85
UARTDRV_Count_t transferCount
Transfer item count.
Definition: uartdrv.h:136
LEUART_Stopbits_TypeDef stopBits
Number of stop bits.
Definition: uartdrv.h:226
enum UARTDRV_FlowControlState UARTDRV_FlowControlState_t
Flow Control state.
Transfer operation FIFO queue typedef.
Definition: uartdrv.h:143
UARTDRV_HandleData_t * UARTDRV_Handle_t
Handle pointer.
Definition: uartdrv.h:277
UARTDRV_Buffer_FifoQueue_t * txQueue
Transmit operation queue.
Definition: uartdrv.h:198
uint8_t rtsPin
RTS pin number.
Definition: uartdrv.h:232
UARTDRV_FlowControlType
Flow Control method.
Definition: uartdrv.h:72
nRTS/nCTS hardware handshake
Definition: uartdrv.h:76
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:2015
LEUART_TypeDef * port
The peripheral used for LEUART.
Definition: uartdrv.h:218
XON or nRTS/nCTS low.
Definition: uartdrv.h:83
volatile uint16_t head
Index of next byte to send.
Definition: uartdrv.h:145
Ecode_t UARTDRV_ReceiveB(UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count)
Start a blocking receive.
Definition: uartdrv.c:2196
GPIO_Port_TypeDef rtsPort
RTS pin port number.
Definition: uartdrv.h:231
General Purpose IO (GPIO) peripheral API.
CMU_Clock_TypeDef
Definition: em_cmu.h:257
uint32_t Ecode_t
Typedef for API function error code return values.
Definition: ecode.h:51
The UART peripheral controls nRTS/nCTS.
Definition: uartdrv.h:77
UARTDRV_Callback_t callback
Completion callback.
Definition: uartdrv.h:138
struct UARTDRV_HandleData UARTDRV_HandleData_t
volatile uint16_t used
Number of bytes queued.
Definition: uartdrv.h:147
UARTDRV_FlowControlType_t fcType
Flow control mode.
Definition: uartdrv.h:228
Low Energy Universal Asynchronous Receiver/Transmitter (LEUART) peripheral API.
UART transfer buffer.
Definition: uartdrv.h:133
LEUART_Stopbits_TypeDef
Definition: em_leuart.h:95
volatile uint16_t tail
Index of where to enqueue next message.
Definition: uartdrv.h:146
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:127
__STATIC_INLINE Ecode_t UARTDRV_Init(UARTDRV_Handle_t handle, UARTDRV_InitUart_t *initData)
Initialize a U(S)ART driver instance.
Definition: uartdrv.h:366
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:2141
Ecode_t UARTDRV_DeInit(UARTDRV_Handle_t handle)
Deinitialize a UART driver instance.
Definition: uartdrv.c:1446
Abort current and queued receive operations.
Definition: uartdrv.h:92
LEUART_Parity_TypeDef parity
Parity configuration.
Definition: uartdrv.h:227
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:1930
UARTDRV_Status_t UARTDRV_GetPeripheralStatus(UARTDRV_Handle_t handle)
Returns the status of the UART peripheral associated with a given handle.
Definition: uartdrv.c:1624
uint32_t UARTDRV_Count_t
UART transfer count.
Definition: uartdrv.h:68
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:1709
Ecode_t UARTDRV_PauseTransmit(UARTDRV_Handle_t handle)
Pause an ongoing transmit operation.
Definition: uartdrv.c:2098
USART_OVS_TypeDef
Definition: em_usart.h:141
uint8_t UARTDRV_GetReceiveDepth(UARTDRV_Handle_t handle)
Returns the number of queued receive operations.
Definition: uartdrv.c:1687
enum UARTDRV_FlowControlType UARTDRV_FlowControlType_t
Flow Control method.
uint8_t * data
Transfer data buffer.
Definition: uartdrv.h:135
GPIO_Port_TypeDef ctsPort
CTS pin port number.
Definition: uartdrv.h:193
Ecode_t UARTDRV_Abort(UARTDRV_Handle_t handle, UARTDRV_AbortType_t type)
Abort ongoing UART transfers.
Definition: uartdrv.c:1511
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:1772
uint8_t portLocation
Location number for LEUART pins.
Definition: uartdrv.h:224
Ecode_t UARTDRV_InitLeuart(UARTDRV_Handle_t handle, const UARTDRV_InitLeuart_t *initData)
Initialize a LEUART driver instance.
Definition: uartdrv.c:1249
UARTDRV_FlowControlState_t UARTDRV_FlowControlGetPeerStatus(UARTDRV_Handle_t handle)
Checks the peer's flow control status.
Definition: uartdrv.c:1879
UARTDRV_Buffer_FifoQueue_t * rxQueue
Receive operation queue.
Definition: uartdrv.h:197
Ecode_t UARTDRV_TransmitB(UARTDRV_Handle_t handle, uint8_t *data, UARTDRV_Count_t count)
Start a blocking transmit.
Definition: uartdrv.c:2343
UARTDRV_FlowControlState
Flow Control state.
Definition: uartdrv.h:81
Ecode_t UARTDRV_FlowControlIgnoreRestrain(UARTDRV_Handle_t handle)
Enables transmission when restrained by flow control.
Definition: uartdrv.c:1909
USART_Parity_TypeDef
Definition: em_usart.h:151
UARTDRV_Buffer_FifoQueue_t * txQueue
Transmit operation queue.
Definition: uartdrv.h:234
Abort current and queued transmit operations.
Definition: uartdrv.h:91
uint32_t UARTDRV_Status_t
UART status return type. Bitfield of UARTDRV_STATUS_* values.
Definition: uartdrv.h:69
Ecode_t UARTDRV_ResumeTransmit(UARTDRV_Handle_t handle)
Resume a paused transmit operation.
Definition: uartdrv.c:2250
bool mvdis
Majority Vote Disable for 16x, 8x and 6x oversampling modes.
Definition: uartdrv.h:190
USART_OVS_TypeDef oversampling
Oversampling mode.
Definition: uartdrv.h:188
Ecode_t UARTDRV_FlowControlSetPeerStatus(UARTDRV_Handle_t handle, UARTDRV_FlowControlState_t state)
Set peer UART flow control state. Pause/resume transmit accordingly. Only for manual software flow co...
Definition: uartdrv.c:1846