1 /* 2 * Copyright (c) 2022 FuZhou Lockzhiner Electronic Co., Ltd. All rights reserved. 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 Lockzhiner 18 * 19 * @file uart.h 20 */ 21 22 #ifndef LZ_HARDWARE_UART_H 23 #define LZ_HARDWARE_UART_H 24 25 /** 26 * @brief Enumerates the number of UART data bits. 27 * 28 * @since 2.2 29 * @version 2.2 30 */ 31 typedef enum { 32 /** 5 data bits */ 33 UART_DATA_BIT_5 = 5, 34 /** 6 data bits */ 35 UART_DATA_BIT_6, 36 /** 7 data bits */ 37 UART_DATA_BIT_7, 38 /** 8 data bits */ 39 UART_DATA_BIT_8, 40 } UartIdxDataBit; 41 42 /** 43 * @brief Enumerates the number of UART stop bits. 44 * 45 * @since 2.2 46 * @version 2.2 47 */ 48 typedef enum { 49 /** 1 stop bit */ 50 UART_STOP_BIT_1 = 1, 51 /** 2 stop bits */ 52 UART_STOP_BIT_2 = 2, 53 } UartStopBit; 54 55 /** 56 * @brief Enumerates UART parity bits. 57 * 58 * @since 2.2 59 * @version 2.2 60 */ 61 typedef enum { 62 /** No parity */ 63 UART_PARITY_NONE = 0, 64 /** Odd parity */ 65 UART_PARITY_ODD = 1, 66 /** Even parity */ 67 UART_PARITY_EVEN = 2, 68 } UartParity; 69 70 /** 71 * @brief Enumerates UART block states. 72 * 73 * @since 2.2 74 * @version 2.2 75 */ 76 typedef enum { 77 /** Block disabled */ 78 UART_BLOCK_STATE_NONE_BLOCK = 0, 79 /** Block enabled */ 80 UART_BLOCK_STATE_BLOCK, 81 } UartBlockState; 82 83 /** 84 * @brief Enumerates hardware flow control modes. 85 * 86 * @since 2.2 87 * @version 2.2 88 */ 89 typedef enum { 90 /** Hardware flow control disabled */ 91 FLOW_CTRL_NONE, 92 /** RTS and CTS hardware flow control enabled */ 93 FLOW_CTRL_RTS_CTS, 94 /** RTS hardware flow control enabled */ 95 FLOW_CTRL_RTS_ONLY, 96 /** CTS hardware flow control enabled */ 97 FLOW_CTRL_CTS_ONLY, 98 } FlowCtrl; 99 100 /** 101 * @brief Defines basic attributes of a UART port. 102 * 103 * @since 2.2 104 * @version 2.2 105 */ 106 typedef struct { 107 /** Baud rate */ 108 unsigned int baudRate; 109 /** Data bits */ 110 UartIdxDataBit dataBits; 111 /** Stop bit */ 112 UartStopBit stopBits; 113 /** Parity */ 114 UartParity parity; 115 /** Rx block state */ 116 UartBlockState rxBlock; 117 /** Tx block state */ 118 UartBlockState txBlock; 119 /** Padding bit */ 120 unsigned char pad; 121 } UartAttribute; 122 123 /** 124 * @brief Configures a UART device with the port number specified by <b>id</b> 125 * based on the basic and extended attributes. 126 * 127 * 128 * 129 * @param id Indicates the port number of the UART device. 130 * @param param Indicates the pointer to the UART attributes. 131 * @return Returns {@link LZ_HARDWARE_SUCCESS} if the UART device is configured successfully; 132 * returns {@link LZ_HARDWARE_FAILURE} otherwise. For details about other return values, see the chip description. 133 */ 134 unsigned int LzUartInit(unsigned int id, const UartAttribute *param); 135 136 /** 137 * @brief Reads a specified length of data from a UART device with the port number specified by <b>id</b>. 138 * 139 * 140 * 141 * @param id Indicates the port number of the UART device. 142 * @param data Indicates the pointer to the start address of the data to read. 143 * @param dataLen Indicates the number of bytes to read. 144 * @return Returns the number of bytes read if the operation is successful; returns <b>-1</b> otherwise. 145 */ 146 unsigned int LzUartRead(unsigned int id, unsigned char *data, unsigned int dataLen); 147 148 /** 149 * @brief Writes a specified length of data to a UART device with the port number specified by <b>id</b>. 150 * 151 * 152 * 153 * @param id Indicates the port number of the UART device. 154 * @param data Indicates the pointer to the start address of the data to write. 155 * @param dataLen Indicates the number of bytes to write. 156 * @return Returns the number of bytes written if the operation is successful; returns <b>-1</b> otherwise. 157 */ 158 unsigned int LzUartWrite(unsigned int id, const unsigned char *data, unsigned int dataLen); 159 160 /** 161 * @brief Writes a character to a UART device with the port number specified by <b>id</b>. 162 * 163 * 164 * 165 * @param id Indicates the port number of the UART device. 166 * @param c Indicates a character to write. 167 * @return Returns the number of bytes written if the operation is successful; returns <b>-1</b> otherwise. 168 */ 169 unsigned int LzUartPutc(unsigned int id, char c); 170 171 /** 172 * @brief Deinitializes a UART device. 173 * 174 * @param id Indicates the port number of the UART device. 175 * @return Returns {@link LZ_HARDWARE_SUCCESS} if the UART device is deinitialized; 176 * returns {@link LZ_HARDWARE_FAILURE} otherwise. For details about other return values, see the chip description. 177 */ 178 unsigned int LzUartDeinit(unsigned int id); 179 180 /** 181 * @brief Sets flow control for a UART device with the port number specified by <b>id</b>. 182 * 183 * 184 * 185 * @param id Indicates the port number of the UART device. 186 * @param flowCtrl Indicates the flow control parameters, as enumerated in {@link FlowCtrl}. 187 * @return Returns {@link LZ_HARDWARE_SUCCESS} if flow control is set successfully; 188 * returns {@link LZ_HARDWARE_FAILURE} otherwise. For details about other return values, see the chip description. 189 */ 190 unsigned int LzUartSetFlowCtrl(unsigned int id, FlowCtrl flowCtrl); 191 192 unsigned int DebugWrite(unsigned int id, const unsigned char *data, unsigned int dataLen); 193 unsigned int DebugPutc(unsigned int id, char c); 194 195 #endif 196 197