1 /* ----------------------------------------------------------------------------- 2 * SPDX-License-Identifier: Zlib 3 * Copyright (c) 2013-2014 ARM Ltd. 4 * 5 * This software is provided 'as-is', without any express or implied warranty. 6 * In no event will the authors be held liable for any damages arising from 7 * the use of this software. Permission is granted to anyone to use this 8 * software for any purpose, including commercial applications, and to alter 9 * it and redistribute it freely, subject to the following restrictions: 10 * 11 * 1. The origin of this software must not be misrepresented; you must not 12 * claim that you wrote the original software. If you use this software in 13 * a product, an acknowledgment in the product documentation would be 14 * appreciated but is not required. 15 * 16 * 2. Altered source versions must be plainly marked as such, and must not be 17 * misrepresented as being the original software. 18 * 19 * 3. This notice may not be removed or altered from any source distribution. 20 * 21 * 22 * $Date: 24. Nov 2014 23 * $Revision: V2.02 24 * 25 * Project: USART (Universal Synchronous Asynchronous Receiver Transmitter) 26 * Driver definitions 27 * -------------------------------------------------------------------------- */ 28 29 /* History: 30 * Version 2.02 31 * Corrected ARM_USART_CPOL_Pos and ARM_USART_CPHA_Pos definitions 32 * Version 2.01 33 * Removed optional argument parameter from Signal Event 34 * Version 2.00 35 * New simplified driver: 36 * complexity moved to upper layer (especially data handling) 37 * more unified API for different communication interfaces 38 * renamed driver UART -> USART (Asynchronous & Synchronous) 39 * Added modes: 40 * Synchronous 41 * Single-wire 42 * IrDA 43 * Smart Card 44 * Changed prefix ARM_DRV -> ARM_DRIVER 45 * Version 1.10 46 * Namespace prefix ARM_ added 47 * Version 1.01 48 * Added events: 49 * ARM_UART_EVENT_TX_EMPTY, ARM_UART_EVENT_RX_TIMEOUT 50 * ARM_UART_EVENT_TX_THRESHOLD, ARM_UART_EVENT_RX_THRESHOLD 51 * Added functions: SetTxThreshold, SetRxThreshold 52 * Added "rx_timeout_event" to capabilities 53 * Version 1.00 54 * Initial release 55 */ 56 57 #ifndef __DRIVER_USART_H 58 #define __DRIVER_USART_H 59 60 #include "Driver_Common.h" 61 62 #define ARM_USART_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,02) /* API version */ 63 64 65 /****** USART Control Codes *****/ 66 67 #define ARM_USART_CONTROL_Pos 0 68 #define ARM_USART_CONTROL_Msk (0xFFUL << ARM_USART_CONTROL_Pos) 69 70 /*----- USART Control Codes: Mode -----*/ 71 #define ARM_USART_MODE_ASYNCHRONOUS (0x01UL << ARM_USART_CONTROL_Pos) ///< UART (Asynchronous); arg = Baudrate 72 #define ARM_USART_MODE_SYNCHRONOUS_MASTER (0x02UL << ARM_USART_CONTROL_Pos) ///< Synchronous Master (generates clock signal); arg = Baudrate 73 #define ARM_USART_MODE_SYNCHRONOUS_SLAVE (0x03UL << ARM_USART_CONTROL_Pos) ///< Synchronous Slave (external clock signal) 74 #define ARM_USART_MODE_SINGLE_WIRE (0x04UL << ARM_USART_CONTROL_Pos) ///< UART Single-wire (half-duplex); arg = Baudrate 75 #define ARM_USART_MODE_IRDA (0x05UL << ARM_USART_CONTROL_Pos) ///< UART IrDA; arg = Baudrate 76 #define ARM_USART_MODE_SMART_CARD (0x06UL << ARM_USART_CONTROL_Pos) ///< UART Smart Card; arg = Baudrate 77 78 /*----- USART Control Codes: Mode Parameters: Data Bits -----*/ 79 #define ARM_USART_DATA_BITS_Pos 8 80 #define ARM_USART_DATA_BITS_Msk (7UL << ARM_USART_DATA_BITS_Pos) 81 #define ARM_USART_DATA_BITS_5 (5UL << ARM_USART_DATA_BITS_Pos) ///< 5 Data bits 82 #define ARM_USART_DATA_BITS_6 (6UL << ARM_USART_DATA_BITS_Pos) ///< 6 Data bit 83 #define ARM_USART_DATA_BITS_7 (7UL << ARM_USART_DATA_BITS_Pos) ///< 7 Data bits 84 #define ARM_USART_DATA_BITS_8 (0UL << ARM_USART_DATA_BITS_Pos) ///< 8 Data bits (default) 85 #define ARM_USART_DATA_BITS_9 (1UL << ARM_USART_DATA_BITS_Pos) ///< 9 Data bits 86 87 /*----- USART Control Codes: Mode Parameters: Parity -----*/ 88 #define ARM_USART_PARITY_Pos 12 89 #define ARM_USART_PARITY_Msk (3UL << ARM_USART_PARITY_Pos) 90 #define ARM_USART_PARITY_NONE (0UL << ARM_USART_PARITY_Pos) ///< No Parity (default) 91 #define ARM_USART_PARITY_EVEN (1UL << ARM_USART_PARITY_Pos) ///< Even Parity 92 #define ARM_USART_PARITY_ODD (2UL << ARM_USART_PARITY_Pos) ///< Odd Parity 93 94 /*----- USART Control Codes: Mode Parameters: Stop Bits -----*/ 95 #define ARM_USART_STOP_BITS_Pos 14 96 #define ARM_USART_STOP_BITS_Msk (3UL << ARM_USART_STOP_BITS_Pos) 97 #define ARM_USART_STOP_BITS_1 (0UL << ARM_USART_STOP_BITS_Pos) ///< 1 Stop bit (default) 98 #define ARM_USART_STOP_BITS_2 (1UL << ARM_USART_STOP_BITS_Pos) ///< 2 Stop bits 99 #define ARM_USART_STOP_BITS_1_5 (2UL << ARM_USART_STOP_BITS_Pos) ///< 1.5 Stop bits 100 #define ARM_USART_STOP_BITS_0_5 (3UL << ARM_USART_STOP_BITS_Pos) ///< 0.5 Stop bits 101 102 /*----- USART Control Codes: Mode Parameters: Flow Control -----*/ 103 #define ARM_USART_FLOW_CONTROL_Pos 16 104 #define ARM_USART_FLOW_CONTROL_Msk (3UL << ARM_USART_FLOW_CONTROL_Pos) 105 #define ARM_USART_FLOW_CONTROL_NONE (0UL << ARM_USART_FLOW_CONTROL_Pos) ///< No Flow Control (default) 106 #define ARM_USART_FLOW_CONTROL_RTS (1UL << ARM_USART_FLOW_CONTROL_Pos) ///< RTS Flow Control 107 #define ARM_USART_FLOW_CONTROL_CTS (2UL << ARM_USART_FLOW_CONTROL_Pos) ///< CTS Flow Control 108 #define ARM_USART_FLOW_CONTROL_RTS_CTS (3UL << ARM_USART_FLOW_CONTROL_Pos) ///< RTS/CTS Flow Control 109 110 /*----- USART Control Codes: Mode Parameters: Clock Polarity (Synchronous mode) -----*/ 111 #define ARM_USART_CPOL_Pos 18 112 #define ARM_USART_CPOL_Msk (1UL << ARM_USART_CPOL_Pos) 113 #define ARM_USART_CPOL0 (0UL << ARM_USART_CPOL_Pos) ///< CPOL = 0 (default) 114 #define ARM_USART_CPOL1 (1UL << ARM_USART_CPOL_Pos) ///< CPOL = 1 115 116 /*----- USART Control Codes: Mode Parameters: Clock Phase (Synchronous mode) -----*/ 117 #define ARM_USART_CPHA_Pos 19 118 #define ARM_USART_CPHA_Msk (1UL << ARM_USART_CPHA_Pos) 119 #define ARM_USART_CPHA0 (0UL << ARM_USART_CPHA_Pos) ///< CPHA = 0 (default) 120 #define ARM_USART_CPHA1 (1UL << ARM_USART_CPHA_Pos) ///< CPHA = 1 121 122 123 /*----- USART Control Codes: Miscellaneous Controls -----*/ 124 #define ARM_USART_SET_DEFAULT_TX_VALUE (0x10UL << ARM_USART_CONTROL_Pos) ///< Set default Transmit value (Synchronous Receive only); arg = value 125 #define ARM_USART_SET_IRDA_PULSE (0x11UL << ARM_USART_CONTROL_Pos) ///< Set IrDA Pulse in ns; arg: 0=3/16 of bit period 126 #define ARM_USART_SET_SMART_CARD_GUARD_TIME (0x12UL << ARM_USART_CONTROL_Pos) ///< Set Smart Card Guard Time; arg = number of bit periods 127 #define ARM_USART_SET_SMART_CARD_CLOCK (0x13UL << ARM_USART_CONTROL_Pos) ///< Set Smart Card Clock in Hz; arg: 0=Clock not generated 128 #define ARM_USART_CONTROL_SMART_CARD_NACK (0x14UL << ARM_USART_CONTROL_Pos) ///< Smart Card NACK generation; arg: 0=disabled, 1=enabled 129 #define ARM_USART_CONTROL_TX (0x15UL << ARM_USART_CONTROL_Pos) ///< Transmitter; arg: 0=disabled, 1=enabled 130 #define ARM_USART_CONTROL_RX (0x16UL << ARM_USART_CONTROL_Pos) ///< Receiver; arg: 0=disabled, 1=enabled 131 #define ARM_USART_CONTROL_BREAK (0x17UL << ARM_USART_CONTROL_Pos) ///< Continuous Break transmission; arg: 0=disabled, 1=enabled 132 #define ARM_USART_ABORT_SEND (0x18UL << ARM_USART_CONTROL_Pos) ///< Abort \ref ARM_USART_Send 133 #define ARM_USART_ABORT_RECEIVE (0x19UL << ARM_USART_CONTROL_Pos) ///< Abort \ref ARM_USART_Receive 134 #define ARM_USART_ABORT_TRANSFER (0x1AUL << ARM_USART_CONTROL_Pos) ///< Abort \ref ARM_USART_Transfer 135 136 137 138 /****** USART specific error codes *****/ 139 #define ARM_USART_ERROR_MODE (ARM_DRIVER_ERROR_SPECIFIC - 1) ///< Specified Mode not supported 140 #define ARM_USART_ERROR_BAUDRATE (ARM_DRIVER_ERROR_SPECIFIC - 2) ///< Specified baudrate not supported 141 #define ARM_USART_ERROR_DATA_BITS (ARM_DRIVER_ERROR_SPECIFIC - 3) ///< Specified number of Data bits not supported 142 #define ARM_USART_ERROR_PARITY (ARM_DRIVER_ERROR_SPECIFIC - 4) ///< Specified Parity not supported 143 #define ARM_USART_ERROR_STOP_BITS (ARM_DRIVER_ERROR_SPECIFIC - 5) ///< Specified number of Stop bits not supported 144 #define ARM_USART_ERROR_FLOW_CONTROL (ARM_DRIVER_ERROR_SPECIFIC - 6) ///< Specified Flow Control not supported 145 #define ARM_USART_ERROR_CPOL (ARM_DRIVER_ERROR_SPECIFIC - 7) ///< Specified Clock Polarity not supported 146 #define ARM_USART_ERROR_CPHA (ARM_DRIVER_ERROR_SPECIFIC - 8) ///< Specified Clock Phase not supported 147 148 149 /** 150 \brief USART Status 151 */ 152 typedef struct _ARM_USART_STATUS { 153 unsigned int tx_busy : 1; ///< Transmitter busy flag 154 unsigned int rx_busy : 1; ///< Receiver busy flag 155 unsigned int tx_underflow : 1; ///< Transmit data underflow detected (cleared on start of next send operation) 156 unsigned int rx_overflow : 1; ///< Receive data overflow detected (cleared on start of next receive operation) 157 unsigned int rx_break : 1; ///< Break detected on receive (cleared on start of next receive operation) 158 unsigned int rx_framing_error : 1; ///< Framing error detected on receive (cleared on start of next receive operation) 159 unsigned int rx_parity_error : 1; ///< Parity error detected on receive (cleared on start of next receive operation) 160 } ARM_USART_STATUS; 161 162 /** 163 \brief USART Modem Control 164 */ 165 typedef enum _ARM_USART_MODEM_CONTROL { 166 ARM_USART_RTS_CLEAR, ///< Deactivate RTS 167 ARM_USART_RTS_SET, ///< Activate RTS 168 ARM_USART_DTR_CLEAR, ///< Deactivate DTR 169 ARM_USART_DTR_SET ///< Activate DTR 170 } ARM_USART_MODEM_CONTROL; 171 172 /** 173 \brief USART Modem Status 174 */ 175 typedef struct _ARM_USART_MODEM_STATUS { 176 unsigned int cts : 1; ///< CTS state: 1=Active, 0=Inactive 177 unsigned int dsr : 1; ///< DSR state: 1=Active, 0=Inactive 178 unsigned int dcd : 1; ///< DCD state: 1=Active, 0=Inactive 179 unsigned int ri : 1; ///< RI state: 1=Active, 0=Inactive 180 } ARM_USART_MODEM_STATUS; 181 182 183 /****** USART Event *****/ 184 #define ARM_USART_EVENT_SEND_COMPLETE (1UL << 0) ///< Send completed; however USART may still transmit data 185 #define ARM_USART_EVENT_RECEIVE_COMPLETE (1UL << 1) ///< Receive completed 186 #define ARM_USART_EVENT_TRANSFER_COMPLETE (1UL << 2) ///< Transfer completed 187 #define ARM_USART_EVENT_TX_COMPLETE (1UL << 3) ///< Transmit completed (optional) 188 #define ARM_USART_EVENT_TX_UNDERFLOW (1UL << 4) ///< Transmit data not available (Synchronous Slave) 189 #define ARM_USART_EVENT_RX_OVERFLOW (1UL << 5) ///< Receive data overflow 190 #define ARM_USART_EVENT_RX_TIMEOUT (1UL << 6) ///< Receive character timeout (optional) 191 #define ARM_USART_EVENT_RX_BREAK (1UL << 7) ///< Break detected on receive 192 #define ARM_USART_EVENT_RX_FRAMING_ERROR (1UL << 8) ///< Framing error detected on receive 193 #define ARM_USART_EVENT_RX_PARITY_ERROR (1UL << 9) ///< Parity error detected on receive 194 #define ARM_USART_EVENT_CTS (1UL << 10) ///< CTS state changed (optional) 195 #define ARM_USART_EVENT_DSR (1UL << 11) ///< DSR state changed (optional) 196 #define ARM_USART_EVENT_DCD (1UL << 12) ///< DCD state changed (optional) 197 #define ARM_USART_EVENT_RI (1UL << 13) ///< RI state changed (optional) 198 199 200 // Function documentation 201 /** 202 \fn ARM_DRIVER_VERSION ARM_USART_GetVersion (void) 203 \brief Get driver version. 204 \return \ref ARM_DRIVER_VERSION 205 206 \fn ARM_USART_CAPABILITIES ARM_USART_GetCapabilities (void) 207 \brief Get driver capabilities 208 \return \ref ARM_USART_CAPABILITIES 209 210 \fn int32_t ARM_USART_Initialize (ARM_USART_SignalEvent_t cb_event) 211 \brief Initialize USART Interface. 212 \param[in] cb_event Pointer to \ref ARM_USART_SignalEvent 213 \return \ref execution_status 214 215 \fn int32_t ARM_USART_Uninitialize (void) 216 \brief De-initialize USART Interface. 217 \return \ref execution_status 218 219 \fn int32_t ARM_USART_PowerControl (ARM_POWER_STATE state) 220 \brief Control USART Interface Power. 221 \param[in] state Power state 222 \return \ref execution_status 223 224 \fn int32_t ARM_USART_Send (const void *data, uint32_t num) 225 \brief Start sending data to USART transmitter. 226 \param[in] data Pointer to buffer with data to send to USART transmitter 227 \param[in] num Number of data items to send 228 \return \ref execution_status 229 230 \fn int32_t ARM_USART_Receive (void *data, uint32_t num) 231 \brief Start receiving data from USART receiver. 232 \param[out] data Pointer to buffer for data to receive from USART receiver 233 \param[in] num Number of data items to receive 234 \return \ref execution_status 235 236 \fn int32_t ARM_USART_Transfer (const void *data_out, 237 void *data_in, 238 uint32_t num) 239 \brief Start sending/receiving data to/from USART transmitter/receiver. 240 \param[in] data_out Pointer to buffer with data to send to USART transmitter 241 \param[out] data_in Pointer to buffer for data to receive from USART receiver 242 \param[in] num Number of data items to transfer 243 \return \ref execution_status 244 245 \fn uint32_t ARM_USART_GetTxCount (void) 246 \brief Get transmitted data count. 247 \return number of data items transmitted 248 249 \fn uint32_t ARM_USART_GetRxCount (void) 250 \brief Get received data count. 251 \return number of data items received 252 253 \fn int32_t ARM_USART_Control (uint32_t control, uint32_t arg) 254 \brief Control USART Interface. 255 \param[in] control Operation 256 \param[in] arg Argument of operation (optional) 257 \return common \ref execution_status and driver specific \ref usart_execution_status 258 259 \fn ARM_USART_STATUS ARM_USART_GetStatus (void) 260 \brief Get USART status. 261 \return USART status \ref ARM_USART_STATUS 262 263 \fn int32_t ARM_USART_SetModemControl (ARM_USART_MODEM_CONTROL control) 264 \brief Set USART Modem Control line state. 265 \param[in] control \ref ARM_USART_MODEM_CONTROL 266 \return \ref execution_status 267 268 \fn ARM_USART_MODEM_STATUS ARM_USART_GetModemStatus (void) 269 \brief Get USART Modem Status lines state. 270 \return modem status \ref ARM_USART_MODEM_STATUS 271 272 \fn void ARM_USART_SignalEvent (uint32_t event) 273 \brief Signal USART Events. 274 \param[in] event \ref USART_events notification mask 275 \return none 276 */ 277 278 typedef void (*ARM_USART_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_USART_SignalEvent : Signal USART Event. 279 280 281 /** 282 \brief USART Device Driver Capabilities. 283 */ 284 typedef struct _ARM_USART_CAPABILITIES { 285 unsigned int asynchronous : 1; ///< supports UART (Asynchronous) mode 286 unsigned int synchronous_master : 1; ///< supports Synchronous Master mode 287 unsigned int synchronous_slave : 1; ///< supports Synchronous Slave mode 288 unsigned int single_wire : 1; ///< supports UART Single-wire mode 289 unsigned int irda : 1; ///< supports UART IrDA mode 290 unsigned int smart_card : 1; ///< supports UART Smart Card mode 291 unsigned int smart_card_clock : 1; ///< Smart Card Clock generator available 292 unsigned int flow_control_rts : 1; ///< RTS Flow Control available 293 unsigned int flow_control_cts : 1; ///< CTS Flow Control available 294 unsigned int event_tx_complete : 1; ///< Transmit completed event: \ref ARM_USART_EVENT_TX_COMPLETE 295 unsigned int event_rx_timeout : 1; ///< Signal receive character timeout event: \ref ARM_USART_EVENT_RX_TIMEOUT 296 unsigned int rts : 1; ///< RTS Line: 0=not available, 1=available 297 unsigned int cts : 1; ///< CTS Line: 0=not available, 1=available 298 unsigned int dtr : 1; ///< DTR Line: 0=not available, 1=available 299 unsigned int dsr : 1; ///< DSR Line: 0=not available, 1=available 300 unsigned int dcd : 1; ///< DCD Line: 0=not available, 1=available 301 unsigned int ri : 1; ///< RI Line: 0=not available, 1=available 302 unsigned int event_cts : 1; ///< Signal CTS change event: \ref ARM_USART_EVENT_CTS 303 unsigned int event_dsr : 1; ///< Signal DSR change event: \ref ARM_USART_EVENT_DSR 304 unsigned int event_dcd : 1; ///< Signal DCD change event: \ref ARM_USART_EVENT_DCD 305 unsigned int event_ri : 1; ///< Signal RI change event: \ref ARM_USART_EVENT_RI 306 } ARM_USART_CAPABILITIES; 307 308 309 /** 310 \brief Access structure of the USART Driver. 311 */ 312 typedef struct _ARM_DRIVER_USART { 313 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USART_GetVersion : Get driver version. 314 ARM_USART_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_USART_GetCapabilities : Get driver capabilities. 315 int32_t (*Initialize) (ARM_USART_SignalEvent_t cb_event); ///< Pointer to \ref ARM_USART_Initialize : Initialize USART Interface. 316 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_USART_Uninitialize : De-initialize USART Interface. 317 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_USART_PowerControl : Control USART Interface Power. 318 int32_t (*Send) (const void *data, uint32_t num); ///< Pointer to \ref ARM_USART_Send : Start sending data to USART transmitter. 319 int32_t (*Receive) (const void *data, uint32_t num); ///< Pointer to \ref ARM_USART_Receive : Start receiving data from USART receiver. 320 int32_t (*Transfer) (const void *data_out, 321 void *data_in, 322 uint32_t num); ///< Pointer to \ref ARM_USART_Transfer : Start sending/receiving data to/from USART. 323 uint32_t (*GetTxCount) (void); ///< Pointer to \ref ARM_USART_GetTxCount : Get transmitted data count. 324 uint32_t (*GetRxCount) (void); ///< Pointer to \ref ARM_USART_GetRxCount : Get received data count. 325 int32_t (*Control) (uint32_t control, uint32_t arg); ///< Pointer to \ref ARM_USART_Control : Control USART Interface. 326 ARM_USART_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_USART_GetStatus : Get USART status. 327 int32_t (*SetModemControl) (ARM_USART_MODEM_CONTROL control); ///< Pointer to \ref ARM_USART_SetModemControl : Set USART Modem Control line state. 328 ARM_USART_MODEM_STATUS (*GetModemStatus) (void); ///< Pointer to \ref ARM_USART_GetModemStatus : Get USART Modem Status lines state. 329 } const ARM_DRIVER_USART; 330 331 #endif /* __DRIVER_USART_H */ 332
