1 /*
2  * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _ROM_UART_H_
8 #define _ROM_UART_H_
9 
10 #include "esp_types.h"
11 #include "esp_attr.h"
12 #include "ets_sys.h"
13 #include "soc/soc.h"
14 #include "soc/uart_reg.h"
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 /** \defgroup uart_apis, uart configuration and communication related apis
21   * @brief uart apis
22   */
23 
24 /** @addtogroup uart_apis
25   * @{
26   */
27 
28 #define RX_BUFF_SIZE                     0x400
29 #define TX_BUFF_SIZE                     100
30 
31 //uart int enalbe register ctrl bits
32 #define UART_RCV_INTEN                   BIT0
33 #define UART_TRX_INTEN                   BIT1
34 #define UART_LINE_STATUS_INTEN           BIT2
35 
36 //uart int identification ctrl bits
37 #define UART_INT_FLAG_MASK               0x0E
38 
39 //uart fifo ctrl bits
40 #define UART_CLR_RCV_FIFO                BIT1
41 #define UART_CLR_TRX_FIFO                BIT2
42 #define UART_RCVFIFO_TRG_LVL_BITS        BIT6
43 
44 //uart line control bits
45 #define  UART_DIV_LATCH_ACCESS_BIT       BIT7
46 
47 //uart line status bits
48 #define  UART_RCV_DATA_RDY_FLAG          BIT0
49 #define  UART_RCV_OVER_FLOW_FLAG         BIT1
50 #define  UART_RCV_PARITY_ERR_FLAG        BIT2
51 #define  UART_RCV_FRAME_ERR_FLAG         BIT3
52 #define  UART_BRK_INT_FLAG               BIT4
53 #define  UART_TRX_FIFO_EMPTY_FLAG        BIT5
54 #define  UART_TRX_ALL_EMPTY_FLAG         BIT6   // include fifo and shift reg
55 #define  UART_RCV_ERR_FLAG               BIT7
56 
57 //send and receive message frame head
58 #define FRAME_FLAG                       0x7E
59 
60 typedef enum {
61     UART_LINE_STATUS_INT_FLAG  = 0x06,
62     UART_RCV_FIFO_INT_FLAG     = 0x04,
63     UART_RCV_TMOUT_INT_FLAG    = 0x0C,
64     UART_TXBUFF_EMPTY_INT_FLAG = 0x02
65 } UartIntType;   //consider bit0 for int_flag
66 
67 typedef enum {
68     RCV_ONE_BYTE      = 0x0,
69     RCV_FOUR_BYTE     = 0x1,
70     RCV_EIGHT_BYTE    = 0x2,
71     RCV_FOURTEEN_BYTE = 0x3
72 } UartRcvFifoTrgLvl;
73 
74 typedef enum {
75     FIVE_BITS  = 0x0,
76     SIX_BITS   = 0x1,
77     SEVEN_BITS = 0x2,
78     EIGHT_BITS = 0x3
79 } UartBitsNum4Char;
80 
81 typedef enum {
82     ONE_STOP_BIT      = 1,
83     ONE_HALF_STOP_BIT = 2,
84     TWO_STOP_BIT      = 3
85 } UartStopBitsNum;
86 
87 typedef enum {
88     NONE_BITS = 0,
89     ODD_BITS  = 2,
90     EVEN_BITS = 3
91 
92 } UartParityMode;
93 
94 typedef enum {
95     STICK_PARITY_DIS = 0,
96     STICK_PARITY_EN  = 2
97 } UartExistParity;
98 
99 typedef enum {
100     BIT_RATE_9600   = 9600,
101     BIT_RATE_19200  = 19200,
102     BIT_RATE_38400  = 38400,
103     BIT_RATE_57600  = 57600,
104     BIT_RATE_115200 = 115200,
105     BIT_RATE_230400 = 230400,
106     BIT_RATE_460800 = 460800,
107     BIT_RATE_921600 = 921600
108 } UartBautRate;
109 
110 typedef enum {
111     NONE_CTRL,
112     HARDWARE_CTRL,
113     XON_XOFF_CTRL
114 } UartFlowCtrl;
115 
116 typedef enum {
117     EMPTY_,
118     UNDER_WRITE,
119     WRITE_OVER
120 } RcvMsgBuffState;
121 
122 typedef struct {
123     uint8_t *pRcvMsgBuff;
124     uint8_t *pWritePos;
125     uint8_t *pReadPos;
126     uint8_t  TrigLvl;
127     RcvMsgBuffState BuffState;
128 } RcvMsgBuff;
129 
130 typedef struct {
131     uint32_t  TrxBuffSize;
132     uint8_t  *pTrxBuff;
133 } TrxMsgBuff;
134 
135 typedef enum {
136     BAUD_RATE_DET,
137     WAIT_SYNC_FRM,
138     SRCH_MSG_HEAD,
139     RCV_MSG_BODY,
140     RCV_ESC_CHAR,
141 } RcvMsgState;
142 
143 typedef struct {
144     UartBautRate     baut_rate;
145     UartBitsNum4Char data_bits;
146     UartExistParity  exist_parity;
147     UartParityMode   parity;    // chip size in byte
148     UartStopBitsNum  stop_bits;
149     UartFlowCtrl     flow_ctrl;
150     uint8_t          buff_uart_no;  //indicate which uart use tx/rx buffer
151     RcvMsgBuff       rcv_buff;
152 //    TrxMsgBuff       trx_buff;
153     RcvMsgState      rcv_state;
154     int              received;
155 } UartDevice;
156 
157 /**
158   * @brief Init uart device struct value and reset uart0/uart1 rx.
159   *        Please do not call this function in SDK.
160   *
161   * @param  rxBuffer, must be a pointer to RX_BUFF_SIZE bytes or NULL
162   *
163   * @return None
164   */
165 void uartAttach(void *rxBuffer);
166 
167 /**
168   * @brief Init uart0 or uart1 for UART download booting mode.
169   *        Please do not call this function in SDK.
170   *
171   * @param  uint8_t uart_no : 0 for UART0, else for UART1.
172   *
173   * @param  uint32_t clock : clock used by uart module, to adjust baudrate.
174   *
175   * @return None
176   */
177 void Uart_Init(uint8_t uart_no, uint32_t clock);
178 
179 /**
180   * @brief Modify uart baudrate.
181   *        This function will reset RX/TX fifo for uart.
182   *
183   * @param  uint8_t uart_no : 0 for UART0, 1 for UART1.
184   *
185   * @param  uint32_t DivLatchValue : (clock << 4)/baudrate.
186   *
187   * @return None
188   */
189 void uart_div_modify(uint8_t uart_no, uint32_t DivLatchValue);
190 
191 /**
192   * @brief Output a char to printf channel, wait until fifo not full.
193   *
194   * @param  None
195   *
196   * @return OK.
197   */
198 ETS_STATUS uart_tx_one_char(uint8_t TxChar);
199 
200 /**
201   * @brief Output a char to message exchange channel, wait until fifo not full.
202   *        Please do not call this function in SDK.
203   *
204   * @param  None
205   *
206   * @return OK.
207   */
208 ETS_STATUS uart_tx_one_char2(uint8_t TxChar);
209 
210 /**
211   * @brief Wait until uart tx full empty.
212   *
213   * @param  uint8_t uart_no : 0 for UART0, 1 for UART1.
214   *
215   * @return None.
216   */
217 void uart_tx_flush(uint8_t uart_no);
218 
219 /**
220   * @brief Wait until uart tx full empty and the last char send ok.
221   *
222   * @param  uart_no : 0 for UART0, 1 for UART1
223   *
224   * The function defined in ROM code has a bug, so we define the correct version
225   * here for compatibility.
226   */
227 void uart_tx_wait_idle(uint8_t uart_no);
228 
229 /**
230   * @brief Get an input char from message channel.
231   *        Please do not call this function in SDK.
232   *
233   * @param  uint8_t *pRxChar : the pointer to store the char.
234   *
235   * @return OK for successful.
236   *         FAIL for failed.
237   */
238 ETS_STATUS uart_rx_one_char(uint8_t *pRxChar);
239 
240 /**
241   * @brief Get an input char from message channel, wait until successful.
242   *        Please do not call this function in SDK.
243   *
244   * @param  None
245   *
246   * @return char : input char value.
247   */
248 char uart_rx_one_char_block(void);
249 
250 /**
251   * @brief Get an input string line from message channel.
252   *        Please do not call this function in SDK.
253   *
254   * @param  uint8_t *pString : the pointer to store the string.
255   *
256   * @param  uint8_t MaxStrlen : the max string length, incude '\0'.
257   *
258   * @return OK.
259   */
260 ETS_STATUS UartRxString(uint8_t *pString, uint8_t MaxStrlen);
261 
262 /**
263   * @brief Get an char from receive buffer.
264   *        Please do not call this function in SDK.
265   *
266   * @param  RcvMsgBuff *pRxBuff : the pointer to the struct that include receive buffer.
267   *
268   * @param  uint8_t *pRxByte : the pointer to store the char.
269   *
270   * @return OK for successful.
271   *         FAIL for failed.
272   */
273 ETS_STATUS uart_rx_readbuff( RcvMsgBuff *pRxBuff, uint8_t *pRxByte);
274 
275 /**
276   * @brief Get uart configuration struct.
277   *        Please do not call this function in SDK.
278   *
279   * @param  None
280   *
281   * @return UartDevice * : uart configuration struct pointer.
282   */
283 UartDevice *GetUartDevice(void);
284 
285 /**
286   * @brief Send an packet to download tool, with SLIP escaping.
287   *        Please do not call this function in SDK.
288   *
289   * @param  uint8_t *p : the pointer to output string.
290   *
291   * @param  int len : the string length.
292   *
293   * @return None.
294   */
295 void send_packet(uint8_t *p, int len);
296 
297 /**
298   * @brief Receive an packet from download tool, with SLIP escaping.
299   *        Please do not call this function in SDK.
300   *
301   * @param  uint8_t *p : the pointer to input string.
302   *
303   * @param  int len : If string length > len, the string will be truncated.
304   *
305   * @param  uint8_t is_sync : 0, only one UART module;
306   *                           1, two UART modules.
307   *
308   * @return int : the length of the string.
309   */
310 int recv_packet(uint8_t *p, int len, uint8_t is_sync);
311 
312 extern UartDevice UartDev;
313 
314 /**
315   * @}
316   */
317 
318 #ifdef __cplusplus
319 }
320 #endif
321 
322 #endif /* _ROM_UART_H_ */
323