VSF Documented
usart.h
Go to the documentation of this file.
1/*****************************************************************************
2 * Copyright(C)2009-2022 by VSF Team *
3 * *
4 * Licensed under the Apache License, Version 2.0 (the "License"); *
5 * you may not use this file except in compliance with the License. *
6 * You may obtain a copy of the License at *
7 * *
8 * http://www.apache.org/licenses/LICENSE-2.0 *
9 * *
10 * Unless required by applicable law or agreed to in writing, software *
11 * distributed under the License is distributed on an "AS IS" BASIS, *
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
13 * See the License for the specific language governing permissions and *
14 * limitations under the License. *
15 * *
16 ****************************************************************************/
17
18#ifndef __HAL_DRIVER_${SERIES/USART_IP}_USART_H__
19#define __HAL_DRIVER_${SERIES/USART_IP}_USART_H__
20
21/*============================ INCLUDES ======================================*/
22
23#include "hal/vsf_hal_cfg.h"
24
25#if VSF_HAL_USE_USART == ENABLED
26
27// HW/IPCore
32// HW/IPCore end
33
34/*\note Refer to template/README.md for usage cases.
35 * For peripheral drivers, blackbox mode is recommended but not required, reimplementation part MUST be open.
36 * For IPCore drivers, class structure, MULTI_CLASS configuration, reimplementation and class APIs should be open to user.
37 * For emulated drivers, **** No reimplementation ****.
38 */
39
40/*\note Includes CAN ONLY be put here. */
41/*\note If current header is for a peripheral driver(hw driver), and inherit from an IPCore driver, include IPCore header here. */
42
43// IPCore
44#if defined(__VSF_HAL_${USART_IP}_USART_CLASS_IMPLEMENT)
45# define __VSF_CLASS_IMPLEMENT__
46#elif defined(__VSF_HAL_${USART_IP}_USART_CLASS_INHERIT__)
47# define __VSF_CLASS_INHERIT__
48#endif
49
50#include "utilities/ooc_class.h"
51// IPCore end
52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57/*============================ MACROS ========================================*/
58
59/*\note VSF_${USART_IP}_USART_CFG_MULTI_CLASS should be implemented for IP drives and open to user,
60 * while VSF_HW_USART_CFG_MULTI_CLASS should be in usart.c.
61 */
62
63// IPCore
64#ifndef VSF_${USART_IP}_USART_CFG_MULTI_CLASS
65# define VSF_${USART_IP}_USART_CFG_MULTI_CLASS VSF_USART_CFG_MULTI_CLASS
66#endif
67// IPCore end
68
69// HW
70/*\note hw USART driver can reimplement following types:
71 * To enable reimplementation, please enable macro below:
72 * VSF_USART_CFG_REIMPLEMENT_TYPE_MODE for vsf_usart_mode_t
73 * VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS for vsf_usart_status_t
74 * VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK for vsf_usart_irq_mask_t
75 * VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL for vsf_usart_ctrl_t
76 * VSF_USART_CFG_REIMPLEMENT_TYPE_CFG for vsf_usart_cfg_t
77 * VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY for vsf_usart_capability_t
78 * Reimplementation is used for optimization hw/IPCore drivers, reimplement the bit mask according to hw registers.
79 * *** DO NOT reimplement these in emulated drivers. ***
80 */
81
82#define VSF_USART_CFG_REIMPLEMENT_TYPE_MODE ENABLED
83#define VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS ENABLED
84#define VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK ENABLED
85#define VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL ENABLED
86#define VSF_USART_CFG_REIMPLEMENT_TYPE_CFG ENABLED
87#define VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY ENABLED
88// HW end
89
90// TODO: add comments about fifo2req
91
92/*============================ TYPES =========================================*/
93
94// IPCore
95vsf_class(vsf_${usart_ip}_usart_t) {
96#if VSF_${USART_IP}_CFG_MULTI_CLASS == ENABLED
97 public_member(
98 vsf_usart_t vsf_usart;
99 )
100#endif
101
102/*\note You can add more member in vsf_${usart_ip}_usart_t instance.
103 * For members accessible from child, put in protected_member.
104 * Else, put in private_member.
105 */
106
107 protected_member(
108 vsf_${usart_ip}_iwc_reg_t *reg;
111};
112// IPCore end
113
114// HW/IPCore, not for emulated drivers
115#if VSF_USART_CFG_REIMPLEMENT_TYPE_MODE == ENABLED
116typedef enum vsf_usart_mode_t {
117 VSF_USART_NO_PARITY = (0x0ul << 0),
118 VSF_USART_EVEN_PARITY = (0x1ul << 0),
119 VSF_USART_ODD_PARITY = (0x2ul << 0),
122
123 VSF_USART_1_STOPBIT = (0x0ul << 3),
124 VSF_USART_1_5_STOPBIT = (0x1ul << 3),
125 VSF_USART_0_5_STOPBIT = (0x2ul << 3),
126 VSF_USART_2_STOPBIT = (0x3ul << 3),
127
134
139
140 VSF_USART_TX_ENABLE = (0x0ul << 9),
141 VSF_USART_TX_DISABLE = (0x1ul << 9),
142
143 VSF_USART_RX_ENABLE = (0x0ul << 10),
144 VSF_USART_RX_DISABLE = (0x1ul << 10),
145
148
151
154 = (0x1ul << 13),
156 = (0x2ul << 15),
157
159 = (0x0ul << 15),
161 = (0x1ul << 15),
163
168
169 // more vendor specified modes can be added here
171#endif
172
173#if VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK == ENABLED
175 // request_rx/request_tx complete
178
179 // TX/RX reach fifo threshold, threshold on some devices is bound to 1
180 VSF_USART_IRQ_MASK_TX = (0x1ul << 2),
181 VSF_USART_IRQ_MASK_RX = (0x1ul << 3),
183
184 // clear to send interrupt
186
187 // Error interrupt
192
193 // only include VSF_USART_IRQ_MASK_TX_OVERFLOW_ERR if hardware supports TX_OVERFLOW_ERR interrupt
194 //VSF_USART_IRQ_MASK_TX_OVERFLOW_ERR = (0x1ul << 10),
195 //#define VSF_USART_IRQ_MASK_TX_OVERFLOW_ERR VSF_USART_IRQ_MASK_TX_OVERFLOW_ERR
196
197 // only include VSF_USART_IRQ_MASK_TX_IDLE if hardware supports TX_IDLE interrupt
198 //VSF_USART_IRQ_MASK_TX_IDLE = (0x1ul << 11),
199 //#define VSF_USART_IRQ_MASK_TX_IDLE VSF_USART_IRQ_MASK_TX_IDLE
200
201 // only include VSF_USART_IRQ_MASK_RX_IDLE if hardware supports configurable RX_IDLE count and RX_IDLE interrupt
202 // or VSF_USART_IRQ_MASK_RX_IDLE will be mapped to VSF_USART_IRQ_MASK_RX_TIMEOUT
203 //VSF_USART_IRQ_MASK_RX_IDLE = (0x1ul << 12),
204 //#define VSF_USART_IRQ_MASK_RX_IDLE VSF_USART_IRQ_MASK_RX_IDLE
205
206 // more vendor specified irq_masks can be added here
208#endif
209
210#if VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL == ENABLED
211// By default, the template contains two control commands:
212// - send BREAK signal (self-clearing)
213// - set and clear BREAK signal
214// The driver needs to select and implement according to the hardware support situation.
215typedef enum vsf_usart_ctrl_t {
216 // usart default command
219
221 #define VSF_USART_CTRL_SET_BREAK VSF_USART_CTRL_SET_BREAK
224
225 // more vendor specified command can be added here
227#endif
228
233#if VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS == ENABLED
234typedef struct vsf_usart_status_t {
235 union {
238 struct {
239 uint32_t is_busy : 1;
244 };
245 };
247#endif
248
253#if VSF_USART_CFG_REIMPLEMENT_TYPE_CFG == ENABLED
255typedef void vsf_usart_isr_handler_t(void *target_ptr,
256 vsf_usart_t *usart_ptr,
258typedef struct vsf_usart_isr_t {
260 void *target_ptr;
263typedef struct vsf_usart_cfg_t {
267# ifdef VSF_USART_IRQ_MASK_RX_IDLE
269# endif
271
272 // more vendor specified cfg can be added here
274#endif
275
276#if VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY == ENABLED
277typedef struct vsf_usart_capability_t {
279
282
285
288
293# ifdef VSF_USART_IRQ_MASK_TX_IDLE
295# endif
296# ifdef VSF_USART_IRQ_MASK_RX_IDLE
298# endif
299
300 // more vendor specified capability can be added here
302#endif
303// HW/IPCore end
304
305/*============================ GLOBAL VARIABLES ==============================*/
306/*============================ PROTOTYPES ====================================*/
307
308// IPCore
309/*\note Extern APIs for ip core diriver.
310 * There is no requirement about how APIs of IPCore drivers should be implemented.
311 * Just consider the simplicity for actual peripheral drivers.
312 */
313// IPCore end
314
315#ifdef __cplusplus
316}
317#endif
318
319// IPCore
320#undef __VSF_HAL_${USART_IP}_USART_CLASS_IMPLEMENT
321#undef __VSF_HAL_${USART_IP}_USART_CLASS_INHERIT__
322// IPCore end
323
324#endif // VSF_HAL_USE_USART
325#endif // __HAL_DRIVER_${SERIES/USART_IP}_USART_H__
326/* EOF */
vsf_usart_mode_t
Definition uart.h:32
vsf_usart_irq_mask_t
Definition uart.h:106
vsf_usart_mode_t
Definition usart.h:86
@ VSF_USART_HALF_DUPLEX_DISABLE
Definition usart.h:108
@ VSF_USART_SYNC_CLOCK_ENABLE
Definition usart.h:116
@ VSF_USART_SYNC_CLOCK_PHASE_1_EDGE
Definition usart.h:122
@ VSF_USART_10_BIT_LENGTH
Definition usart.h:132
@ VSF_USART_RTS_HWCONTROL
Definition usart.h:101
@ VSF_USART_RX_ENABLE
Definition usart.h:96
@ VSF_USART_FORCE_0_PARITY
Definition usart.h:186
@ VSF_USART_TX_ENABLE
Definition usart.h:94
@ VSF_USART_SYNC_CLOCK_POLARITY_HIGH
Definition usart.h:120
@ VSF_USART_1_STOPBIT
Definition usart.h:89
@ VSF_USART_FORCE_1_PARITY
Definition usart.h:187
@ VSF_USART_SYNC_CLOCK_POLARITY_LOW
Definition usart.h:119
@ VSF_USART_RX_DISABLE
Definition usart.h:97
@ VSF_USART_2_STOPBIT
Definition usart.h:91
@ VSF_USART_CTS_HWCONTROL
Definition usart.h:102
@ VSF_USART_SYNC_CLOCK_DISABLE
Definition usart.h:117
@ VSF_USART_RTS_CTS_HWCONTROL
Definition usart.h:103
@ VSF_USART_SYNC_CLOCK_PHASE_2_EDGE
Definition usart.h:123
@ VSF_USART_HALF_DUPLEX_ENABLE
Definition usart.h:107
@ VSF_USART_TX_DISABLE
Definition usart.h:95
@ VSF_USART_0_5_STOPBIT
Definition usart.h:88
@ VSF_USART_NO_HWCONTROL
Definition usart.h:100
@ VSF_USART_1_5_STOPBIT
Definition usart.h:90
vsf_usart_irq_mask_t
Definition usart.h:207
@ VSF_USART_IRQ_MASK_TX_CPL
Definition usart.h:222
@ VSF_USART_IRQ_MASK_CTS
Definition usart.h:217
@ VSF_USART_IRQ_MASK_TX
Definition usart.h:212
@ VSF_USART_IRQ_MASK_BREAK_ERR
Definition usart.h:248
@ VSF_USART_IRQ_MASK_RX
Definition usart.h:210
@ VSF_USART_IRQ_MASK_RX_TIMEOUT
Definition usart.h:214
@ VSF_USART_IRQ_MASK_RX_OVERFLOW_ERR
Definition usart.h:249
@ VSF_USART_IRQ_MASK_RX_CPL
Definition usart.h:221
@ VSF_USART_IRQ_MASK_PARITY_ERR
Definition usart.h:226
@ VSF_USART_IRQ_MASK_FRAME_ERR
Definition usart.h:247
vsf_usart_ctrl_t
Definition usart.h:256
@ VSF_USART_CTRL_CLEAR_BREAK
Definition usart.h:260
@ VSF_USART_CTRL_SEND_BREAK
Definition usart.h:257
@ VSF_USART_CTRL_SET_BREAK
Definition usart.h:259
struct vsf_usart_cfg_t vsf_usart_cfg_t
struct vsf_usart_capability_t vsf_usart_capability_t
@ VSF_USART_EVEN_PARITY
Definition usart.h:76
@ VSF_USART_ODD_PARITY
Definition usart.h:75
@ VSF_USART_NO_PARITY
Definition usart.h:74
#define VSF_USART_9_BIT_LENGTH
Definition usart.h:81
#define VSF_USART_RX_FIFO_THRESHOLD_HALF_FULL
Definition usart.h:131
#define VSF_USART_TX_FIFO_THRESHOLD_EMPTY
Definition usart.h:126
struct vsf_usart_isr_t vsf_usart_isr_t
#define VSF_USART_RX_FIFO_THRESHOLD_FULL
Definition usart.h:139
#define VSF_USART_RX_FIFO_THRESHOLD_NOT_EMPTY
Definition usart.h:129
#define VSF_USART_TX_FIFO_THRESHOLD_HALF_EMPTY
Definition usart.h:118
void vsf_usart_isr_handler_t(void *target_ptr, vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask)
Definition usart.h:367
#define VSF_USART_TX_FIFO_THRESHOLD_NOT_FULL
Definition usart.h:116
@ VSF_USART_8_BIT_LENGTH
Definition usart.h:43
@ VSF_USART_7_BIT_LENGTH
Definition usart.h:44
@ VSF_USART_5_BIT_LENGTH
Definition usart.h:46
@ VSF_USART_6_BIT_LENGTH
Definition usart.h:45
struct vsf_usart_status_t vsf_usart_status_t
Definition adc.h:92
vsf_arch_prio_t
Definition cortex_a_generic.h:88
#define vsf_class(__name)
Definition ooc_class.h:48
const i_spi_t vsf_spi_irq_mask_t irq_mask
Definition spi_interface.h:38
unsigned uint32_t
Definition stdint.h:9
unsigned char uint8_t
Definition stdint.h:5
Definition vsf_template_hal_driver.h:196
USART capability structure Defines the hardware capabilities and limitations of the USART interface.
Definition vsf_template_usart.h:797
uint8_t support_tx_idle
Support TX idle interrupt.
Definition vsf_template_usart.h:817
uint8_t max_data_bits
Maximum data bits per frame.
Definition vsf_template_usart.h:809
uint8_t support_set_and_clear_break
Support set and clear break.
Definition vsf_template_usart.h:814
vsf_usart_irq_mask_t irq_mask
Definition usart.h:387
uint8_t support_rx_timeout
Support receive timeout.
Definition vsf_template_usart.h:812
uint8_t rxfifo_depth
RX FIFO depth in data frames (0 means no FIFO)
Definition vsf_template_usart.h:807
uint8_t support_rx_idle
Support RX idle interrupt.
Definition vsf_template_usart.h:820
uint8_t support_send_break
Support send break.
Definition vsf_template_usart.h:813
uint8_t txfifo_depth
TX FIFO depth in data frames (0 means no FIFO)
Definition vsf_template_usart.h:806
uint8_t min_data_bits
Minimum data bits per frame.
Definition vsf_template_usart.h:810
uint32_t min_baudrate
Minimum supported baudrate (bps) according to current clock configurations.
Definition vsf_template_usart.h:804
uint32_t max_baudrate
Maximum supported baudrate (bps) according to current clock configurations.
Definition vsf_template_usart.h:803
uint8_t support_sync_clock
Support Synchronous clock.
Definition vsf_template_usart.h:815
USART configuration structure Contains all parameters needed to initialize and configure a USART inst...
Definition vsf_template_usart.h:687
uint32_t mode
USART working mode.
Definition vsf_template_usart.h:688
uint32_t baudrate
Baudrate in Hz.
Definition vsf_template_usart.h:689
uint32_t rx_timeout
RX timeout in microseconds.
Definition vsf_template_usart.h:690
uint32_t rx_idle_cnt
Definition vsf_template_usart.h:692
vsf_usart_isr_t isr
Interrupt configuration.
Definition vsf_template_usart.h:694
USART interrupt configuration structure Contains all necessary information for configuring USART inte...
Definition vsf_template_usart.h:673
vsf_usart_isr_handler_t * handler_fn
Interrupt handler function pointer.
Definition vsf_template_usart.h:674
vsf_arch_prio_t prio
Interrupt priority.
Definition vsf_template_usart.h:676
void * target_ptr
User target pointer.
Definition vsf_template_usart.h:675
USART status information structure Contains the current status of USART operations and FIFO threshold...
Definition uart.h:157
uint32_t is_busy
USART is busy with any operation.
Definition vsf_template_usart.h:778
uint32_t is_tx_busy
TX is busy transmitting data.
Definition vsf_template_usart.h:779
uint32_t value
Definition usart.h:284
uint32_t tx_fifo_thresh
TX FIFO threshold level (0-255)
Definition vsf_template_usart.h:781
uint32_t rx_fifo_thresh
RX FIFO threshold level (0-255)
Definition vsf_template_usart.h:782
uint32_t is_rx_busy
RX is busy receiving data.
Definition vsf_template_usart.h:780
USART instance structure Used for USART Multi Class support.
Definition vsf_template_usart.h:850
class vsf_$ * reg
vsf_usart_isr_t isr
Definition usart.h:110
void vsf_usart_isr_handler_t(void *target_ptr, vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask)
Definition usart.h:255
vsf_usart_ctrl_t
USART control commands Defines the available control operations for USART instances.
Definition vsf_template_usart.h:707
Generated from commit: vsfteam/vsf@74aa6ce