1/*
2 * Copyright (c) 2020 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup IotHardware
18 * @{
19 *
20 * @brief Provides APIs for operating devices,
21 * including flash, GPIO, I2C, PWM, UART, and watchdog APIs.
22 *
23 *
24 *
25 * @since 2.2
26 * @version 2.2
27 */
28
29/**
30 * @file iot_uart.h
31 *
32 * @brief Declares UART functions.
33 *
34 * These functions are used for UART initialization,
35 * data input/output, and data flow control. \n
36 *
37 * @since 2.2
38 * @version 2.2
39 */
40
41#ifndef IOT_UART_H
42#define IOT_UART_H
43
44/**
45 * @brief Enumerates the number of UART data bits.
46 *
47 * @since 2.2
48 * @version 2.2
49 */
50typedef enum {
51    /** 5 data bits */
52    IOT_UART_DATA_BIT_5 = 5,
53    /** 6 data bits */
54    IOT_UART_DATA_BIT_6,
55    /** 7 data bits */
56    IOT_UART_DATA_BIT_7,
57    /** 8 data bits */
58    IOT_UART_DATA_BIT_8,
59} IotUartIdxDataBit;
60
61/**
62 * @brief Enumerates the number of UART stop bits.
63 *
64 * @since 2.2
65 * @version 2.2
66 */
67typedef enum {
68    /** 1 stop bit */
69    IOT_UART_STOP_BIT_1 = 1,
70    /** 2 stop bits */
71    IOT_UART_STOP_BIT_2 = 2,
72} IotUartStopBit;
73
74/**
75 * @brief Enumerates UART parity bits.
76 *
77 * @since 2.2
78 * @version 2.2
79 */
80typedef enum {
81    /** No parity */
82    IOT_UART_PARITY_NONE = 0,
83    /** Odd parity */
84    IOT_UART_PARITY_ODD = 1,
85    /** Even parity */
86    IOT_UART_PARITY_EVEN = 2,
87} IotUartParity;
88
89/**
90 * @brief Enumerates UART block states.
91 *
92 * @since 2.2
93 * @version 2.2
94 */
95typedef enum {
96    /** Block disabled */
97    IOT_UART_BLOCK_STATE_NONE_BLOCK = 0,
98    /** Block enabled */
99    IOT_UART_BLOCK_STATE_BLOCK,
100} IotUartBlockState;
101
102/**
103 * @brief Enumerates hardware flow control modes.
104 *
105 * @since 2.2
106 * @version 2.2
107 */
108typedef enum {
109    /** Hardware flow control disabled */
110    IOT_FLOW_CTRL_NONE,
111    /** RTS and CTS hardware flow control enabled */
112    IOT_FLOW_CTRL_RTS_CTS,
113    /** RTS hardware flow control enabled */
114    IOT_FLOW_CTRL_RTS_ONLY,
115     /** CTS hardware flow control enabled */
116    IOT_FLOW_CTRL_CTS_ONLY,
117} IotFlowCtrl;
118
119/**
120 * @brief Defines basic attributes of a UART port.
121 *
122 * @since 2.2
123 * @version 2.2
124 */
125typedef struct {
126    /** Baud rate */
127    unsigned int baudRate;
128    /** Data bits */
129    IotUartIdxDataBit dataBits;
130    /** Stop bit */
131    IotUartStopBit stopBits;
132    /** Parity */
133    IotUartParity parity;
134    /** Rx block state */
135    IotUartBlockState rxBlock;
136    /** Tx block state */
137    IotUartBlockState txBlock;
138    /** Padding bit */
139    unsigned char pad;
140} IotUartAttribute;
141
142/**
143 * @brief Configures a UART device with the port number specified by <b>id</b>
144 * based on the basic and extended attributes.
145 *
146 *
147 *
148 * @param id Indicates the port number of the UART device.
149 * @param param Indicates the pointer to the UART attributes.
150 * @return Returns {@link IOT_SUCCESS} if the UART device is configured successfully;
151 * returns {@link IOT_FAILURE} otherwise. For details about other return values, see the chip description.
152 * @since 2.2
153 * @version 2.2
154 */
155unsigned int IoTUartInit(unsigned int id, const IotUartAttribute *param);
156
157/**
158 * @brief Reads a specified length of data from a UART device with the port number specified by <b>id</b>.
159 *
160 *
161 *
162 * @param id Indicates the port number of the UART device.
163 * @param data Indicates the pointer to the start address of the data to read.
164 * @param dataLen Indicates the number of bytes to read.
165 * @return Returns the number of bytes read if the operation is successful; returns <b>-1</b> otherwise.
166 * @since 2.2
167 * @version 2.2
168 */
169int IoTUartRead(unsigned int id, unsigned char *data, unsigned int dataLen);
170
171/**
172 * @brief Writes a specified length of data to a UART device with the port number specified by <b>id</b>.
173 *
174 *
175 *
176 * @param id Indicates the port number of the UART device.
177 * @param data Indicates the pointer to the start address of the data to write.
178 * @param dataLen Indicates the number of bytes to write.
179 * @return Returns the number of bytes written if the operation is successful; returns <b>-1</b> otherwise.
180 * @since 2.2
181 * @version 2.2
182 */
183int IoTUartWrite(unsigned int id, const unsigned char *data, unsigned int dataLen);
184
185/**
186 * @brief Deinitializes a UART device.
187 *
188 * @param id Indicates the port number of the UART device.
189 * @return Returns {@link IOT_SUCCESS} if the UART device is deinitialized;
190 * returns {@link IOT_FAILURE} otherwise. For details about other return values, see the chip description.
191 * @since 2.2
192 * @version 2.2
193 */
194unsigned int IoTUartDeinit(unsigned int id);
195
196/**
197 * @brief Sets flow control for a UART device with the port number specified by <b>id</b>.
198 *
199 *
200 *
201 * @param id Indicates the port number of the UART device.
202 * @param flowCtrl Indicates the flow control parameters, as enumerated in {@link IotFlowCtrl}.
203 * @return Returns {@link IOT_SUCCESS} if flow control is set successfully;
204 * returns {@link IOT_FAILURE} otherwise. For details about other return values, see the chip description.
205 * @since 2.2
206 * @version 2.2
207 */
208unsigned int IoTUartSetFlowCtrl(unsigned int id, IotFlowCtrl flowCtrl);
209
210#endif // IOT_UART_H
211/** @} */
212