1 //***************************************************************************** 2 // 3 // am_hal_uart.h 4 //! @file 5 //! 6 //! @brief Functions for accessing and configuring the UART. 7 //! 8 //! @addtogroup uart2 UART 9 //! @ingroup apollo2hal 10 //! @{ 11 // 12 //***************************************************************************** 13 14 //***************************************************************************** 15 // 16 // Copyright (c) 2017, Ambiq Micro 17 // All rights reserved. 18 // 19 // Redistribution and use in source and binary forms, with or without 20 // modification, are permitted provided that the following conditions are met: 21 // 22 // 1. Redistributions of source code must retain the above copyright notice, 23 // this list of conditions and the following disclaimer. 24 // 25 // 2. Redistributions in binary form must reproduce the above copyright 26 // notice, this list of conditions and the following disclaimer in the 27 // documentation and/or other materials provided with the distribution. 28 // 29 // 3. Neither the name of the copyright holder nor the names of its 30 // contributors may be used to endorse or promote products derived from this 31 // software without specific prior written permission. 32 // 33 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 34 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 35 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 36 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 37 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 38 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 39 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 40 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 41 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 42 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 43 // POSSIBILITY OF SUCH DAMAGE. 44 // 45 // This is part of revision 1.2.11 of the AmbiqSuite Development Package. 46 // 47 //***************************************************************************** 48 #ifndef AM_HAL_UART_H 49 #define AM_HAL_UART_H 50 51 //***************************************************************************** 52 // 53 //! @name UART Interrupts 54 //! @brief Macro definitions for UART FIFO levels. 55 //! 56 //! They may be used with the \e am_hal_uart_fifo_config() function. 57 //! 58 //! @{ 59 // 60 //***************************************************************************** 61 #define AM_HAL_UART_INT_OVER_RUN AM_REG_UART_IER_OEIM_M 62 #define AM_HAL_UART_INT_BREAK_ERR AM_REG_UART_IER_BEIM_M 63 #define AM_HAL_UART_INT_PARITY_ERR AM_REG_UART_IER_PEIM_M 64 #define AM_HAL_UART_INT_FRAME_ERR AM_REG_UART_IER_FEIM_M 65 #define AM_HAL_UART_INT_RX_TMOUT AM_REG_UART_IER_RTIM_M 66 #define AM_HAL_UART_INT_TX AM_REG_UART_IER_TXIM_M 67 #define AM_HAL_UART_INT_RX AM_REG_UART_IER_RXIM_M 68 #define AM_HAL_UART_INT_DSRM AM_REG_UART_IER_DSRMIM_M 69 #define AM_HAL_UART_INT_DCDM AM_REG_UART_IER_DCDMIM_M 70 #define AM_HAL_UART_INT_CTSM AM_REG_UART_IER_CTSMIM_M 71 #define AM_HAL_UART_INT_TXCMP AM_REG_UART_IER_TXCMPMIM_M 72 //! @} 73 74 //***************************************************************************** 75 // 76 //! @name UART FIFO Levels 77 //! @brief Macro definitions for RTV interrupt status bits. 78 //! 79 //! These macros correspond to the bits in the UART interrupt status register. 80 //! They may be used with any of the \e am_hal_uart_int_x() functions. 81 //! 82 //! @{ 83 // 84 //***************************************************************************** 85 //TX 86 #define AM_HAL_UART_TX_FIFO_1_8 AM_REG_UART_IFLS_TXIFLSEL(0) 87 #define AM_HAL_UART_TX_FIFO_1_4 AM_REG_UART_IFLS_TXIFLSEL(1) 88 #define AM_HAL_UART_TX_FIFO_1_2 AM_REG_UART_IFLS_TXIFLSEL(2) 89 #define AM_HAL_UART_TX_FIFO_3_4 AM_REG_UART_IFLS_TXIFLSEL(3) 90 #define AM_HAL_UART_TX_FIFO_7_8 AM_REG_UART_IFLS_TXIFLSEL(4) 91 // RX 92 #define AM_HAL_UART_RX_FIFO_1_8 AM_REG_UART_IFLS_RXIFLSEL(0) 93 #define AM_HAL_UART_RX_FIFO_1_4 AM_REG_UART_IFLS_RXIFLSEL(1) 94 #define AM_HAL_UART_RX_FIFO_1_2 AM_REG_UART_IFLS_RXIFLSEL(2) 95 #define AM_HAL_UART_RX_FIFO_3_4 AM_REG_UART_IFLS_RXIFLSEL(3) 96 #define AM_HAL_UART_RX_FIFO_7_8 AM_REG_UART_IFLS_RXIFLSEL(4) 97 //! @} 98 99 //***************************************************************************** 100 // 101 //! @name UART Status Register 102 //! @brief Macro definitions for UART Status Register Bits. 103 //! 104 //! They may be used with the \e am_hal_uart_status_get() function. 105 //! 106 //! @{ 107 // 108 //***************************************************************************** 109 // This is the overrun error indicator. 110 #define AM_HAL_UART_RSR_OVERRUN_NOERR AM_REG_UART_RSR_OESTAT_NOERR 111 #define AM_HAL_UART_RSR_OVERRUN_ERROR AM_REG_UART_RSR_OESTAT_ERR 112 113 // This is the break error indicator. 114 #define AM_HAL_UART_RSR_BREAK_NOERR AM_REG_UART_RSR_BESTAT_NOERR 115 #define AM_HAL_UART_RSR_BREAK_ERROR AM_REG_UART_RSR_BESTAT_ERR 116 117 // This is the parity error indicator. 118 #define AM_HAL_UART_RSR_PARITY_NOERR AM_REG_UART_RSR_PESTAT_NOERR 119 #define AM_HAL_UART_RSR_PARITY_ERROR AM_REG_UART_RSR_PESTAT_ERR 120 121 // This is the framing error indicator. 122 #define AM_HAL_UART_RSR_FRAME_ERROR_NOERR AM_REG_UART_RSR_FESTAT_NOERR 123 #define AM_HAL_UART_RSR_FRAME_ERROR_ERROR AM_REG_UART_RSR_FESTAT_ERR 124 //! @} 125 126 //***************************************************************************** 127 // 128 //! @name UART Flag Register 129 //! @brief Macro definitions for UART Flag Register Bits. 130 //! 131 //! They may be used with the \e am_hal_uart_flags_get() function. 132 //! 133 //! @{ 134 // 135 //***************************************************************************** 136 #define AM_HAL_UART_FR_RING AM_REG_UART_FR_RI_M 137 #define AM_HAL_UART_FR_TX_EMPTY AM_REG_UART_FR_TXFE_XMTFIFO_EMPTY 138 #define AM_HAL_UART_FR_RX_FULL AM_REG_UART_FR_RXFF_RCVFIFO_FULL 139 #define AM_HAL_UART_FR_TX_FULL AM_REG_UART_FR_TXFF_XMTFIFO_FULL 140 #define AM_HAL_UART_FR_RX_EMPTY AM_REG_UART_FR_RXFE_RCVFIFO_EMPTY 141 #define AM_HAL_UART_FR_BUSY AM_REG_UART_FR_BUSY_BUSY 142 #define AM_HAL_UART_FR_DCD_DETECTED AM_REG_UART_FR_DCD_DETECTED 143 #define AM_HAL_UART_FR_DSR_READY AM_REG_UART_FR_DSR_READY 144 #define AM_HAL_UART_FR_CTS AM_REG_UART_FR_CTS_M 145 //! @} 146 147 148 //***************************************************************************** 149 // 150 //! @name UART Config Macros 151 //! @brief Macro definitions for available Data bits. 152 //! 153 //! They may be used with the \e am_hal_uart_config_t structure used by \e 154 //! am_hal_uart_config(). 155 //! 156 //! @{ 157 // 158 //***************************************************************************** 159 //***************************************************************************** 160 // 161 // Data bits defines. 162 // 163 //***************************************************************************** 164 #define AM_HAL_UART_DATA_BITS_8 AM_REG_UART_LCRH_WLEN(3) 165 #define AM_HAL_UART_DATA_BITS_7 AM_REG_UART_LCRH_WLEN(2) 166 #define AM_HAL_UART_DATA_BITS_6 AM_REG_UART_LCRH_WLEN(1) 167 #define AM_HAL_UART_DATA_BITS_5 0 168 169 //***************************************************************************** 170 // 171 // Parity defines. 172 // 173 //***************************************************************************** 174 #define AM_HAL_UART_PARITY_NONE 0 175 #define AM_HAL_UART_PARITY_ODD AM_REG_UART_LCRH_PEN_M 176 #define AM_HAL_UART_PARITY_EVEN AM_REG_UART_LCRH_PEN_M | \ 177 AM_REG_UART_LCRH_EPS_M 178 179 //***************************************************************************** 180 // 181 // Flow control defines. 182 // 183 //***************************************************************************** 184 #define AM_HAL_UART_FLOW_CTRL_NONE 0 185 #define AM_HAL_UART_FLOW_CTRL_RTS_CTS AM_REG_UART_CR_CTSEN_M | \ 186 AM_REG_UART_CR_RTSEN_M 187 //! @} 188 189 //***************************************************************************** 190 // 191 //! UART configuration structure 192 // 193 //***************************************************************************** 194 typedef struct 195 { 196 // 197 //! Desired Baudrate for the UART. 198 // 199 uint32_t ui32BaudRate; 200 201 // 202 //! Number of data bits. 203 //! 204 //! Valid values for ui32DataBits are: 205 //! 206 //! AM_HAL_UART_DATA_BITS_8 207 //! AM_HAL_UART_DATA_BITS_7 208 //! AM_HAL_UART_DATA_BITS_6 209 //! AM_HAL_UART_DATA_BITS_5 210 // 211 uint32_t ui32DataBits; 212 213 // 214 //! Use two stop bits. 215 // 216 bool bTwoStopBits; 217 218 // 219 //! Parity. 220 //! 221 //! Valid values for ui32Parity are: 222 //! 223 //! AM_HAL_UART_PARITY_NONE 224 //! AM_HAL_UART_PARITY_ODD 225 //! AM_HAL_UART_PARITY_EVEN 226 // 227 uint32_t ui32Parity; 228 229 // 230 //! Flow control. 231 //! 232 //! Valid values for ui32FlowCtrl are: 233 //! 234 //! AM_HAL_UART_FLOW_CTRL_NONE 235 //! AM_HAL_UART_FLOW_CTRL_RTS_CTS 236 // 237 uint32_t ui32FlowCtrl; 238 } 239 am_hal_uart_config_t; 240 241 //***************************************************************************** 242 // 243 // Structure for containing information about the UART's configuration while 244 // it is powered down. 245 // 246 //***************************************************************************** 247 typedef struct 248 { 249 uint32_t ILPR; 250 uint32_t IBRD; 251 uint32_t FBRD; 252 uint32_t LCRH; 253 uint32_t CR; 254 uint32_t IFLS; 255 uint32_t IER; 256 uint32_t UARTEN; 257 uint32_t bValid; 258 } 259 am_hal_uart_pwrsave_t; 260 261 //***************************************************************************** 262 // 263 // Global Variables 264 // 265 //***************************************************************************** 266 extern am_hal_uart_pwrsave_t am_hal_uart_pwrsave[AM_REG_UART_NUM_MODULES]; 267 268 #ifdef __cplusplus 269 extern "C" 270 { 271 #endif 272 273 //***************************************************************************** 274 // 275 // External function definitions 276 // 277 //***************************************************************************** 278 extern void am_hal_uart_pwrctrl_enable(uint32_t ui32Module); 279 extern void am_hal_uart_pwrctrl_disable(uint32_t ui32Module); 280 extern void am_hal_uart_power_on_restore(uint32_t ui32Module); 281 extern void am_hal_uart_power_off_save(uint32_t ui32Module); 282 extern void am_hal_uart_config(uint32_t ui32Module, 283 am_hal_uart_config_t *psConfig); 284 extern uint32_t am_hal_uart_status_get(uint32_t ui32Module); 285 extern uint32_t am_hal_uart_int_status_get(uint32_t ui32Module, 286 bool bEnabledOnly); 287 extern void am_hal_uart_int_clear(uint32_t ui32Module, 288 uint32_t ui32Interrupt); 289 extern void am_hal_uart_int_disable(uint32_t ui32Module, 290 uint32_t ui32Interrupt); 291 extern void am_hal_uart_int_enable(uint32_t ui32Module, 292 uint32_t ui32Interrupt); 293 extern uint32_t am_hal_uart_int_enable_get(uint32_t ui32Module); 294 extern void am_hal_uart_enable(uint32_t ui32Module); 295 extern void am_hal_uart_disable(uint32_t ui32Module); 296 extern void am_hal_uart_clock_enable(uint32_t ui32Module); 297 extern void am_hal_uart_clock_disable(uint32_t ui32Module); 298 extern void am_hal_uart_fifo_config(uint32_t ui32Module, uint32_t ui32LvlCfg); 299 extern uint32_t am_hal_uart_flags_get(uint32_t ui32Module); 300 301 // rx/tx polled 302 extern void am_hal_uart_char_transmit_polled(uint32_t ui32Module, 303 char cChar); 304 extern void am_hal_uart_string_transmit_polled(uint32_t ui32Module, 305 char *pcString); 306 extern void am_hal_uart_char_receive_polled(uint32_t ui32Module, 307 char *pcChar); 308 extern void am_hal_uart_line_receive_polled(uint32_t ui32Module, 309 uint32_t ui32MaxChars, 310 char *pcChar); 311 312 // rx/tx buffered 313 extern void am_hal_uart_init_buffered(uint32_t ui32Module, 314 uint8_t *pui8RxArray, 315 uint32_t ui32RxSize, 316 uint8_t *pui8TxArray, 317 uint32_t ui32TxSize); 318 extern void am_hal_uart_get_status_buffered(uint32_t ui32Module, 319 uint32_t *pui32RxSize, 320 uint32_t *pui32TxSize); 321 extern void am_hal_uart_service_buffered(uint32_t ui32Module, 322 uint32_t ui32Status); 323 324 extern void am_hal_uart_service_buffered_timeout_save(uint32_t ui32Module, 325 uint32_t ui32Status); 326 extern void am_hal_uart_char_transmit_buffered(uint32_t ui32Module, 327 char cChar); 328 extern void am_hal_uart_string_transmit_buffered(uint32_t ui32Module, 329 char *pcString); 330 extern uint32_t am_hal_uart_char_receive_buffered(uint32_t ui32Module, 331 char *pcString, 332 uint32_t ui32MaxChars); 333 334 #ifdef __cplusplus 335 } 336 #endif 337 338 #endif // AM_HAL_UART_H 339 340 //***************************************************************************** 341 // 342 // End Doxygen group. 343 //! @} 344 // 345 //***************************************************************************** 346