1 /* 2 * Copyright (c) 2016-2018 ARM Limited 3 * SPDX-License-Identifier: Apache-2.0 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /** 19 * \file arm_uart_drv.h 20 * \brief Generic driver for ARM UART. 21 */ 22 23 #ifndef __ARM_UART_DRV_H__ 24 #define __ARM_UART_DRV_H__ 25 26 #include <stdint.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /* ARM UART device configuration structure */ 33 struct arm_uart_dev_cfg_t { 34 const uint32_t base; /*!< UART base address */ 35 const uint32_t default_baudrate; /*!< Default baudrate */ 36 }; 37 38 /* ARM UART device data structure */ 39 struct arm_uart_dev_data_t { 40 uint32_t state; /*!< Indicates if the uart driver 41 is initialized and enabled */ 42 uint32_t system_clk; /*!< System clock */ 43 uint32_t baudrate; /*!< Baudrate */ 44 }; 45 46 /* ARM UART device structure */ 47 struct arm_uart_dev_t { 48 const struct arm_uart_dev_cfg_t* cfg; /*!< UART configuration */ 49 struct arm_uart_dev_data_t* data; /*!< UART data */ 50 }; 51 52 /* ARM UART enumeration types */ 53 enum arm_uart_error_t { 54 ARM_UART_ERR_NONE = 0, /*!< No error */ 55 ARM_UART_ERR_INVALID_ARG, /*!< Error invalid input argument */ 56 ARM_UART_ERR_INVALID_BAUD, /*!< Invalid baudrate */ 57 ARM_UART_ERR_NOT_INIT, /*!< Error UART not initialized */ 58 ARM_UART_ERR_NOT_READY, /*!< Error UART not ready */ 59 }; 60 61 enum arm_uart_irq_t { 62 ARM_UART_IRQ_RX, /*!< RX interrupt source */ 63 ARM_UART_IRQ_TX, /*!< TX interrupt source */ 64 ARM_UART_IRQ_COMBINED, /*!< RX-TX combined interrupt source */ 65 ARM_UART_IRQ_NONE = 0xFF /*!< RX-TX combined interrupt source */ 66 }; 67 68 /** 69 * \brief Initializes UART. It uses the default baudrate to configure 70 * the peripheral at this point. 71 * 72 * \param[in] dev UART device struct \ref arm_uart_dev_t 73 * \param[in] system_clk System clock used by the device. 74 * 75 * \return Returns error code as specified in \ref arm_uart_error_t 76 * 77 * \note This function doesn't check if dev is NULL. 78 */ 79 enum arm_uart_error_t arm_uart_init(struct arm_uart_dev_t* dev, 80 uint32_t system_clk); 81 82 /** 83 * \brief Sets the UART baudrate. 84 * 85 * \param[in] dev UART device struct \ref arm_uart_dev_t 86 * \param[in] baudrate New baudrate. 87 * 88 * \return Returns error code as specified in \ref arm_uart_error_t 89 * 90 * \note This function doesn't check if dev is NULL. 91 */ 92 enum arm_uart_error_t arm_uart_set_baudrate(struct arm_uart_dev_t* dev, 93 uint32_t baudrate); 94 95 /** 96 * \brief Gets the UART baudrate. 97 * 98 * \param[in] dev UART device struct \ref arm_uart_dev_t 99 * 100 * \return Returns the UART baudrate. 101 * 102 * \note This function doesn't check if dev is NULL. 103 */ 104 uint32_t arm_uart_get_baudrate(struct arm_uart_dev_t* dev); 105 106 /** 107 * \brief Sets system clock. 108 * 109 * \param[in] dev UART device struct \ref arm_uart_dev_t 110 * \param[in] system_clk System clock used by the device. 111 * 112 * \return Returns error code as specified in \ref arm_uart_error_t 113 * 114 * \note This function doesn't check if dev is NULL. 115 */ 116 enum arm_uart_error_t arm_uart_set_clock(struct arm_uart_dev_t* dev, 117 uint32_t system_clk); 118 /** 119 * \brief Reads one byte from UART dev. 120 * 121 * \param[in] dev UART device struct \ref arm_uart_dev_t 122 * \param[in] byte Pointer to byte. 123 * 124 * \return Returns error code as specified in \ref arm_uart_error_t 125 * 126 * \note For better performance, this function doesn't check if dev and byte 127 * pointer are NULL, and if the driver is initialized. 128 */ 129 enum arm_uart_error_t arm_uart_read(struct arm_uart_dev_t* dev, uint8_t* byte); 130 131 /** 132 * \brief Writes a byte to UART dev. 133 * 134 * \param[in] dev UART device struct \ref arm_uart_dev_t 135 * \param[in] byte Byte to write. 136 * 137 * \return Returns error code as specified in \ref arm_uart_error_t 138 * 139 * \note For better performance, this function doesn't check if dev is NULL and 140 * if the driver is initialized to have better performance. 141 */ 142 enum arm_uart_error_t arm_uart_write(struct arm_uart_dev_t* dev, uint8_t byte); 143 144 /** 145 * \brief Enables TX interrupt. 146 * 147 * \param[in] dev UART device struct \ref arm_uart_dev_t 148 * 149 * \return Returns error code as specified in \ref arm_uart_error_t 150 * 151 * \note This function doesn't check if dev is NULL. 152 */ 153 enum arm_uart_error_t arm_uart_irq_tx_enable(struct arm_uart_dev_t* dev); 154 155 /** 156 * \brief Disables TX interrupt. 157 * 158 * \param[in] dev UART device struct \ref arm_uart_dev_t 159 * 160 * \note This function doesn't check if dev is NULL. 161 */ 162 void arm_uart_irq_tx_disable(struct arm_uart_dev_t* dev); 163 164 /** 165 * \brief Verifies if Tx is ready to send more data. 166 * 167 * \param[in] dev UART device struct \ref arm_uart_dev_t 168 * 169 * \return 1 if TX is ready, 0 otherwise. 170 * 171 * \note This function doesn't check if dev is NULL. 172 */ 173 uint32_t arm_uart_tx_ready(struct arm_uart_dev_t* dev); 174 175 /** 176 * \brief Enables RX interrupt. 177 * 178 * \param[in] dev UART device struct \ref arm_uart_dev_t 179 * 180 * \return Returns error code as specified in \ref arm_uart_error_t 181 * 182 * \note This function doesn't check if dev is NULL. 183 */ 184 enum arm_uart_error_t arm_uart_irq_rx_enable(struct arm_uart_dev_t* dev); 185 186 /** 187 * \brief Disables RX interrupt 188 * 189 * \param[in] dev UART device struct \ref arm_uart_dev_t 190 * 191 * \note This function doesn't check if dev is NULL. 192 */ 193 void arm_uart_irq_rx_disable(struct arm_uart_dev_t* dev); 194 195 /** 196 * \brief Verifies if Rx has data. 197 * 198 * \param[in] dev UART device struct \ref arm_uart_dev_t 199 * 200 * \return 1 if RX has data, 0 otherwise. 201 * 202 * \note This function doesn't check if dev is NULL. 203 */ 204 uint32_t arm_uart_rx_ready(struct arm_uart_dev_t* dev); 205 206 /** 207 * \brief Clears UART interrupt. 208 * 209 * \param[in] dev UART device struct \ref arm_uart_dev_t 210 * \param[in] irq IRQ source to clean \ref arm_uart_irq_t 211 * 212 * \note This function doesn't check if dev is NULL. 213 */ 214 void arm_uart_clear_interrupt(struct arm_uart_dev_t* dev, 215 enum arm_uart_irq_t irq); 216 217 /** 218 * \brief Returns UART interrupt status. 219 * 220 * \param[in] dev UART device struct \ref arm_uart_dev_t 221 * 222 * \return IRQ status \ref arm_uart_irq_t 223 * 224 * \note This function doesn't check if dev is NULL. 225 */ 226 enum arm_uart_irq_t arm_uart_get_interrupt_status(struct arm_uart_dev_t* dev); 227 228 #ifdef __cplusplus 229 } 230 #endif 231 #endif /* __ARM_UART_DRV_H__ */