2 * Copyright (c) 2013-2016 ARM Limited. All rights reserved.
\r
4 * SPDX-License-Identifier: Apache-2.0
\r
6 * Licensed under the Apache License, Version 2.0 (the License); you may
\r
7 * not use this file except in compliance with the License.
\r
8 * You may obtain a copy of the License at
\r
10 * http://www.apache.org/licenses/LICENSE-2.0
\r
12 * Unless required by applicable law or agreed to in writing, software
\r
13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
\r
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
15 * See the License for the specific language governing permissions and
\r
16 * limitations under the License.
\r
18 * $Date: 24. Nov 2014
\r
21 * Project: USART (Universal Synchronous Asynchronous Receiver Transmitter)
\r
22 * Driver definitions
\r
27 * Corrected ARM_USART_CPOL_Pos and ARM_USART_CPHA_Pos definitions
\r
29 * Removed optional argument parameter from Signal Event
\r
31 * New simplified driver:
\r
32 * complexity moved to upper layer (especially data handling)
\r
33 * more unified API for different communication interfaces
\r
34 * renamed driver UART -> USART (Asynchronous & Synchronous)
\r
40 * Changed prefix ARM_DRV -> ARM_DRIVER
\r
42 * Namespace prefix ARM_ added
\r
45 * ARM_UART_EVENT_TX_EMPTY, ARM_UART_EVENT_RX_TIMEOUT
\r
46 * ARM_UART_EVENT_TX_THRESHOLD, ARM_UART_EVENT_RX_THRESHOLD
\r
47 * Added functions: SetTxThreshold, SetRxThreshold
\r
48 * Added "rx_timeout_event" to capabilities
\r
53 #ifndef __DRIVER_USART_H
\r
54 #define __DRIVER_USART_H
\r
56 #include "Driver_Common.h"
\r
58 #define ARM_USART_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,02) /* API version */
\r
61 /****** USART Control Codes *****/
\r
63 #define ARM_USART_CONTROL_Pos 0
\r
64 #define ARM_USART_CONTROL_Msk (0xFFUL << ARM_USART_CONTROL_Pos)
\r
66 /*----- USART Control Codes: Mode -----*/
\r
67 #define ARM_USART_MODE_ASYNCHRONOUS (0x01UL << ARM_USART_CONTROL_Pos) ///< UART (Asynchronous); arg = Baudrate
\r
68 #define ARM_USART_MODE_SYNCHRONOUS_MASTER (0x02UL << ARM_USART_CONTROL_Pos) ///< Synchronous Master (generates clock signal); arg = Baudrate
\r
69 #define ARM_USART_MODE_SYNCHRONOUS_SLAVE (0x03UL << ARM_USART_CONTROL_Pos) ///< Synchronous Slave (external clock signal)
\r
70 #define ARM_USART_MODE_SINGLE_WIRE (0x04UL << ARM_USART_CONTROL_Pos) ///< UART Single-wire (half-duplex); arg = Baudrate
\r
71 #define ARM_USART_MODE_IRDA (0x05UL << ARM_USART_CONTROL_Pos) ///< UART IrDA; arg = Baudrate
\r
72 #define ARM_USART_MODE_SMART_CARD (0x06UL << ARM_USART_CONTROL_Pos) ///< UART Smart Card; arg = Baudrate
\r
74 /*----- USART Control Codes: Mode Parameters: Data Bits -----*/
\r
75 #define ARM_USART_DATA_BITS_Pos 8
\r
76 #define ARM_USART_DATA_BITS_Msk (7UL << ARM_USART_DATA_BITS_Pos)
\r
77 #define ARM_USART_DATA_BITS_5 (5UL << ARM_USART_DATA_BITS_Pos) ///< 5 Data bits
\r
78 #define ARM_USART_DATA_BITS_6 (6UL << ARM_USART_DATA_BITS_Pos) ///< 6 Data bit
\r
79 #define ARM_USART_DATA_BITS_7 (7UL << ARM_USART_DATA_BITS_Pos) ///< 7 Data bits
\r
80 #define ARM_USART_DATA_BITS_8 (0UL << ARM_USART_DATA_BITS_Pos) ///< 8 Data bits (default)
\r
81 #define ARM_USART_DATA_BITS_9 (1UL << ARM_USART_DATA_BITS_Pos) ///< 9 Data bits
\r
83 /*----- USART Control Codes: Mode Parameters: Parity -----*/
\r
84 #define ARM_USART_PARITY_Pos 12
\r
85 #define ARM_USART_PARITY_Msk (3UL << ARM_USART_PARITY_Pos)
\r
86 #define ARM_USART_PARITY_NONE (0UL << ARM_USART_PARITY_Pos) ///< No Parity (default)
\r
87 #define ARM_USART_PARITY_EVEN (1UL << ARM_USART_PARITY_Pos) ///< Even Parity
\r
88 #define ARM_USART_PARITY_ODD (2UL << ARM_USART_PARITY_Pos) ///< Odd Parity
\r
90 /*----- USART Control Codes: Mode Parameters: Stop Bits -----*/
\r
91 #define ARM_USART_STOP_BITS_Pos 14
\r
92 #define ARM_USART_STOP_BITS_Msk (3UL << ARM_USART_STOP_BITS_Pos)
\r
93 #define ARM_USART_STOP_BITS_1 (0UL << ARM_USART_STOP_BITS_Pos) ///< 1 Stop bit (default)
\r
94 #define ARM_USART_STOP_BITS_2 (1UL << ARM_USART_STOP_BITS_Pos) ///< 2 Stop bits
\r
95 #define ARM_USART_STOP_BITS_1_5 (2UL << ARM_USART_STOP_BITS_Pos) ///< 1.5 Stop bits
\r
96 #define ARM_USART_STOP_BITS_0_5 (3UL << ARM_USART_STOP_BITS_Pos) ///< 0.5 Stop bits
\r
98 /*----- USART Control Codes: Mode Parameters: Flow Control -----*/
\r
99 #define ARM_USART_FLOW_CONTROL_Pos 16
\r
100 #define ARM_USART_FLOW_CONTROL_Msk (3UL << ARM_USART_FLOW_CONTROL_Pos)
\r
101 #define ARM_USART_FLOW_CONTROL_NONE (0UL << ARM_USART_FLOW_CONTROL_Pos) ///< No Flow Control (default)
\r
102 #define ARM_USART_FLOW_CONTROL_RTS (1UL << ARM_USART_FLOW_CONTROL_Pos) ///< RTS Flow Control
\r
103 #define ARM_USART_FLOW_CONTROL_CTS (2UL << ARM_USART_FLOW_CONTROL_Pos) ///< CTS Flow Control
\r
104 #define ARM_USART_FLOW_CONTROL_RTS_CTS (3UL << ARM_USART_FLOW_CONTROL_Pos) ///< RTS/CTS Flow Control
\r
106 /*----- USART Control Codes: Mode Parameters: Clock Polarity (Synchronous mode) -----*/
\r
107 #define ARM_USART_CPOL_Pos 18
\r
108 #define ARM_USART_CPOL_Msk (1UL << ARM_USART_CPOL_Pos)
\r
109 #define ARM_USART_CPOL0 (0UL << ARM_USART_CPOL_Pos) ///< CPOL = 0 (default)
\r
110 #define ARM_USART_CPOL1 (1UL << ARM_USART_CPOL_Pos) ///< CPOL = 1
\r
112 /*----- USART Control Codes: Mode Parameters: Clock Phase (Synchronous mode) -----*/
\r
113 #define ARM_USART_CPHA_Pos 19
\r
114 #define ARM_USART_CPHA_Msk (1UL << ARM_USART_CPHA_Pos)
\r
115 #define ARM_USART_CPHA0 (0UL << ARM_USART_CPHA_Pos) ///< CPHA = 0 (default)
\r
116 #define ARM_USART_CPHA1 (1UL << ARM_USART_CPHA_Pos) ///< CPHA = 1
\r
119 /*----- USART Control Codes: Miscellaneous Controls -----*/
\r
120 #define ARM_USART_SET_DEFAULT_TX_VALUE (0x10UL << ARM_USART_CONTROL_Pos) ///< Set default Transmit value (Synchronous Receive only); arg = value
\r
121 #define ARM_USART_SET_IRDA_PULSE (0x11UL << ARM_USART_CONTROL_Pos) ///< Set IrDA Pulse in ns; arg: 0=3/16 of bit period
\r
122 #define ARM_USART_SET_SMART_CARD_GUARD_TIME (0x12UL << ARM_USART_CONTROL_Pos) ///< Set Smart Card Guard Time; arg = number of bit periods
\r
123 #define ARM_USART_SET_SMART_CARD_CLOCK (0x13UL << ARM_USART_CONTROL_Pos) ///< Set Smart Card Clock in Hz; arg: 0=Clock not generated
\r
124 #define ARM_USART_CONTROL_SMART_CARD_NACK (0x14UL << ARM_USART_CONTROL_Pos) ///< Smart Card NACK generation; arg: 0=disabled, 1=enabled
\r
125 #define ARM_USART_CONTROL_TX (0x15UL << ARM_USART_CONTROL_Pos) ///< Transmitter; arg: 0=disabled, 1=enabled
\r
126 #define ARM_USART_CONTROL_RX (0x16UL << ARM_USART_CONTROL_Pos) ///< Receiver; arg: 0=disabled, 1=enabled
\r
127 #define ARM_USART_CONTROL_BREAK (0x17UL << ARM_USART_CONTROL_Pos) ///< Continuous Break transmission; arg: 0=disabled, 1=enabled
\r
128 #define ARM_USART_ABORT_SEND (0x18UL << ARM_USART_CONTROL_Pos) ///< Abort \ref ARM_USART_Send
\r
129 #define ARM_USART_ABORT_RECEIVE (0x19UL << ARM_USART_CONTROL_Pos) ///< Abort \ref ARM_USART_Receive
\r
130 #define ARM_USART_ABORT_TRANSFER (0x1AUL << ARM_USART_CONTROL_Pos) ///< Abort \ref ARM_USART_Transfer
\r
134 /****** USART specific error codes *****/
\r
135 #define ARM_USART_ERROR_MODE (ARM_DRIVER_ERROR_SPECIFIC - 1) ///< Specified Mode not supported
\r
136 #define ARM_USART_ERROR_BAUDRATE (ARM_DRIVER_ERROR_SPECIFIC - 2) ///< Specified baudrate not supported
\r
137 #define ARM_USART_ERROR_DATA_BITS (ARM_DRIVER_ERROR_SPECIFIC - 3) ///< Specified number of Data bits not supported
\r
138 #define ARM_USART_ERROR_PARITY (ARM_DRIVER_ERROR_SPECIFIC - 4) ///< Specified Parity not supported
\r
139 #define ARM_USART_ERROR_STOP_BITS (ARM_DRIVER_ERROR_SPECIFIC - 5) ///< Specified number of Stop bits not supported
\r
140 #define ARM_USART_ERROR_FLOW_CONTROL (ARM_DRIVER_ERROR_SPECIFIC - 6) ///< Specified Flow Control not supported
\r
141 #define ARM_USART_ERROR_CPOL (ARM_DRIVER_ERROR_SPECIFIC - 7) ///< Specified Clock Polarity not supported
\r
142 #define ARM_USART_ERROR_CPHA (ARM_DRIVER_ERROR_SPECIFIC - 8) ///< Specified Clock Phase not supported
\r
146 \brief USART Status
\r
148 typedef struct _ARM_USART_STATUS {
\r
149 uint32_t tx_busy : 1; ///< Transmitter busy flag
\r
150 uint32_t rx_busy : 1; ///< Receiver busy flag
\r
151 uint32_t tx_underflow : 1; ///< Transmit data underflow detected (cleared on start of next send operation)
\r
152 uint32_t rx_overflow : 1; ///< Receive data overflow detected (cleared on start of next receive operation)
\r
153 uint32_t rx_break : 1; ///< Break detected on receive (cleared on start of next receive operation)
\r
154 uint32_t rx_framing_error : 1; ///< Framing error detected on receive (cleared on start of next receive operation)
\r
155 uint32_t rx_parity_error : 1; ///< Parity error detected on receive (cleared on start of next receive operation)
\r
156 } ARM_USART_STATUS;
\r
159 \brief USART Modem Control
\r
161 typedef enum _ARM_USART_MODEM_CONTROL {
\r
162 ARM_USART_RTS_CLEAR, ///< Deactivate RTS
\r
163 ARM_USART_RTS_SET, ///< Activate RTS
\r
164 ARM_USART_DTR_CLEAR, ///< Deactivate DTR
\r
165 ARM_USART_DTR_SET ///< Activate DTR
\r
166 } ARM_USART_MODEM_CONTROL;
\r
169 \brief USART Modem Status
\r
171 typedef struct _ARM_USART_MODEM_STATUS {
\r
172 uint32_t cts : 1; ///< CTS state: 1=Active, 0=Inactive
\r
173 uint32_t dsr : 1; ///< DSR state: 1=Active, 0=Inactive
\r
174 uint32_t dcd : 1; ///< DCD state: 1=Active, 0=Inactive
\r
175 uint32_t ri : 1; ///< RI state: 1=Active, 0=Inactive
\r
176 } ARM_USART_MODEM_STATUS;
\r
179 /****** USART Event *****/
\r
180 #define ARM_USART_EVENT_SEND_COMPLETE (1UL << 0) ///< Send completed; however USART may still transmit data
\r
181 #define ARM_USART_EVENT_RECEIVE_COMPLETE (1UL << 1) ///< Receive completed
\r
182 #define ARM_USART_EVENT_TRANSFER_COMPLETE (1UL << 2) ///< Transfer completed
\r
183 #define ARM_USART_EVENT_TX_COMPLETE (1UL << 3) ///< Transmit completed (optional)
\r
184 #define ARM_USART_EVENT_TX_UNDERFLOW (1UL << 4) ///< Transmit data not available (Synchronous Slave)
\r
185 #define ARM_USART_EVENT_RX_OVERFLOW (1UL << 5) ///< Receive data overflow
\r
186 #define ARM_USART_EVENT_RX_TIMEOUT (1UL << 6) ///< Receive character timeout (optional)
\r
187 #define ARM_USART_EVENT_RX_BREAK (1UL << 7) ///< Break detected on receive
\r
188 #define ARM_USART_EVENT_RX_FRAMING_ERROR (1UL << 8) ///< Framing error detected on receive
\r
189 #define ARM_USART_EVENT_RX_PARITY_ERROR (1UL << 9) ///< Parity error detected on receive
\r
190 #define ARM_USART_EVENT_CTS (1UL << 10) ///< CTS state changed (optional)
\r
191 #define ARM_USART_EVENT_DSR (1UL << 11) ///< DSR state changed (optional)
\r
192 #define ARM_USART_EVENT_DCD (1UL << 12) ///< DCD state changed (optional)
\r
193 #define ARM_USART_EVENT_RI (1UL << 13) ///< RI state changed (optional)
\r
196 // Function documentation
\r
198 \fn ARM_DRIVER_VERSION ARM_USART_GetVersion (void)
\r
199 \brief Get driver version.
\r
200 \return \ref ARM_DRIVER_VERSION
\r
202 \fn ARM_USART_CAPABILITIES ARM_USART_GetCapabilities (void)
\r
203 \brief Get driver capabilities
\r
204 \return \ref ARM_USART_CAPABILITIES
\r
206 \fn int32_t ARM_USART_Initialize (ARM_USART_SignalEvent_t cb_event)
\r
207 \brief Initialize USART Interface.
\r
208 \param[in] cb_event Pointer to \ref ARM_USART_SignalEvent
\r
209 \return \ref execution_status
\r
211 \fn int32_t ARM_USART_Uninitialize (void)
\r
212 \brief De-initialize USART Interface.
\r
213 \return \ref execution_status
\r
215 \fn int32_t ARM_USART_PowerControl (ARM_POWER_STATE state)
\r
216 \brief Control USART Interface Power.
\r
217 \param[in] state Power state
\r
218 \return \ref execution_status
\r
220 \fn int32_t ARM_USART_Send (const void *data, uint32_t num)
\r
221 \brief Start sending data to USART transmitter.
\r
222 \param[in] data Pointer to buffer with data to send to USART transmitter
\r
223 \param[in] num Number of data items to send
\r
224 \return \ref execution_status
\r
226 \fn int32_t ARM_USART_Receive (void *data, uint32_t num)
\r
227 \brief Start receiving data from USART receiver.
\r
228 \param[out] data Pointer to buffer for data to receive from USART receiver
\r
229 \param[in] num Number of data items to receive
\r
230 \return \ref execution_status
\r
232 \fn int32_t ARM_USART_Transfer (const void *data_out,
\r
235 \brief Start sending/receiving data to/from USART transmitter/receiver.
\r
236 \param[in] data_out Pointer to buffer with data to send to USART transmitter
\r
237 \param[out] data_in Pointer to buffer for data to receive from USART receiver
\r
238 \param[in] num Number of data items to transfer
\r
239 \return \ref execution_status
\r
241 \fn uint32_t ARM_USART_GetTxCount (void)
\r
242 \brief Get transmitted data count.
\r
243 \return number of data items transmitted
\r
245 \fn uint32_t ARM_USART_GetRxCount (void)
\r
246 \brief Get received data count.
\r
247 \return number of data items received
\r
249 \fn int32_t ARM_USART_Control (uint32_t control, uint32_t arg)
\r
250 \brief Control USART Interface.
\r
251 \param[in] control Operation
\r
252 \param[in] arg Argument of operation (optional)
\r
253 \return common \ref execution_status and driver specific \ref usart_execution_status
\r
255 \fn ARM_USART_STATUS ARM_USART_GetStatus (void)
\r
256 \brief Get USART status.
\r
257 \return USART status \ref ARM_USART_STATUS
\r
259 \fn int32_t ARM_USART_SetModemControl (ARM_USART_MODEM_CONTROL control)
\r
260 \brief Set USART Modem Control line state.
\r
261 \param[in] control \ref ARM_USART_MODEM_CONTROL
\r
262 \return \ref execution_status
\r
264 \fn ARM_USART_MODEM_STATUS ARM_USART_GetModemStatus (void)
\r
265 \brief Get USART Modem Status lines state.
\r
266 \return modem status \ref ARM_USART_MODEM_STATUS
\r
268 \fn void ARM_USART_SignalEvent (uint32_t event)
\r
269 \brief Signal USART Events.
\r
270 \param[in] event \ref USART_events notification mask
\r
274 typedef void (*ARM_USART_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_USART_SignalEvent : Signal USART Event.
\r
278 \brief USART Device Driver Capabilities.
\r
280 typedef struct _ARM_USART_CAPABILITIES {
\r
281 uint32_t asynchronous : 1; ///< supports UART (Asynchronous) mode
\r
282 uint32_t synchronous_master : 1; ///< supports Synchronous Master mode
\r
283 uint32_t synchronous_slave : 1; ///< supports Synchronous Slave mode
\r
284 uint32_t single_wire : 1; ///< supports UART Single-wire mode
\r
285 uint32_t irda : 1; ///< supports UART IrDA mode
\r
286 uint32_t smart_card : 1; ///< supports UART Smart Card mode
\r
287 uint32_t smart_card_clock : 1; ///< Smart Card Clock generator available
\r
288 uint32_t flow_control_rts : 1; ///< RTS Flow Control available
\r
289 uint32_t flow_control_cts : 1; ///< CTS Flow Control available
\r
290 uint32_t event_tx_complete : 1; ///< Transmit completed event: \ref ARM_USART_EVENT_TX_COMPLETE
\r
291 uint32_t event_rx_timeout : 1; ///< Signal receive character timeout event: \ref ARM_USART_EVENT_RX_TIMEOUT
\r
292 uint32_t rts : 1; ///< RTS Line: 0=not available, 1=available
\r
293 uint32_t cts : 1; ///< CTS Line: 0=not available, 1=available
\r
294 uint32_t dtr : 1; ///< DTR Line: 0=not available, 1=available
\r
295 uint32_t dsr : 1; ///< DSR Line: 0=not available, 1=available
\r
296 uint32_t dcd : 1; ///< DCD Line: 0=not available, 1=available
\r
297 uint32_t ri : 1; ///< RI Line: 0=not available, 1=available
\r
298 uint32_t event_cts : 1; ///< Signal CTS change event: \ref ARM_USART_EVENT_CTS
\r
299 uint32_t event_dsr : 1; ///< Signal DSR change event: \ref ARM_USART_EVENT_DSR
\r
300 uint32_t event_dcd : 1; ///< Signal DCD change event: \ref ARM_USART_EVENT_DCD
\r
301 uint32_t event_ri : 1; ///< Signal RI change event: \ref ARM_USART_EVENT_RI
\r
302 } ARM_USART_CAPABILITIES;
\r
306 \brief Access structure of the USART Driver.
\r
308 typedef struct _ARM_DRIVER_USART {
\r
309 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USART_GetVersion : Get driver version.
\r
310 ARM_USART_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_USART_GetCapabilities : Get driver capabilities.
\r
311 int32_t (*Initialize) (ARM_USART_SignalEvent_t cb_event); ///< Pointer to \ref ARM_USART_Initialize : Initialize USART Interface.
\r
312 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_USART_Uninitialize : De-initialize USART Interface.
\r
313 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_USART_PowerControl : Control USART Interface Power.
\r
314 int32_t (*Send) (const void *data, uint32_t num); ///< Pointer to \ref ARM_USART_Send : Start sending data to USART transmitter.
\r
315 int32_t (*Receive) ( void *data, uint32_t num); ///< Pointer to \ref ARM_USART_Receive : Start receiving data from USART receiver.
\r
316 int32_t (*Transfer) (const void *data_out,
\r
318 uint32_t num); ///< Pointer to \ref ARM_USART_Transfer : Start sending/receiving data to/from USART.
\r
319 uint32_t (*GetTxCount) (void); ///< Pointer to \ref ARM_USART_GetTxCount : Get transmitted data count.
\r
320 uint32_t (*GetRxCount) (void); ///< Pointer to \ref ARM_USART_GetRxCount : Get received data count.
\r
321 int32_t (*Control) (uint32_t control, uint32_t arg); ///< Pointer to \ref ARM_USART_Control : Control USART Interface.
\r
322 ARM_USART_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_USART_GetStatus : Get USART status.
\r
323 int32_t (*SetModemControl) (ARM_USART_MODEM_CONTROL control); ///< Pointer to \ref ARM_USART_SetModemControl : Set USART Modem Control line state.
\r
324 ARM_USART_MODEM_STATUS (*GetModemStatus) (void); ///< Pointer to \ref ARM_USART_GetModemStatus : Get USART Modem Status lines state.
\r
325 } const ARM_DRIVER_USART;
\r
327 #endif /* __DRIVER_USART_H */
\r
begriffs.com / projects / cmsis / blob