1 /**
2 \defgroup usart_interface_gr USART Interface
3 \brief Driver API for Universal Synchronous Asynchronous Receiver/Transmitter (%Driver_USART.h)
4 \details
5 The <b>Universal Synchronous Asynchronous Receiver/Transmitter</b> (USART) implements a synchronous and asynchronous serial bus for exchanging data.
6 When only asynchronous mode is supported it is called Universal Asynchronous Receiver/Transmitter (UART).
7 Almost all microcontrollers have a serial interface (UART/USART peripheral). A UART is a simple device to send data to a PC
8 via a terminal emulation program (Hyperterm, TeraTerm) or to another microcontroller.
9 A UART takes bytes of data and transmits the individual bits in a sequential mode. At the destination,
10 a second UART reassembles the bits into complete bytes. Each UART contains a shift register for converting between serial and parallel transmission forms.
11 Wikipedia offers more information about
12 the <a href="https://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter" target="_blank"><b>Universal asynchronous receiver/transmitter</b></a>.
13
14
15 <b>USART API</b>
16
17 The following header files define the Application Programming Interface (API) for the USART interface:
18 - \b %Driver_USART.h : Driver API for Universal Synchronous Asynchronous Receiver/Transmitter
19
20 The driver implementation is a typical part of the Device Family Pack (DFP) that supports the
21 peripherals of the microcontroller family.
22
23
24 <b>Driver Functions</b>
25
26 The driver functions are published in the access struct as explained in \ref DriverFunctions
27 - \ref ARM_DRIVER_USART : access struct for USART driver functions
28
29
30 <b>Example Code</b>
31
32 The following example code shows the usage of the USART interface for asynchronous communication.
33
34 \include USART_Demo.c
35
36 @{
37 */
38
39 /**
40 \struct ARM_DRIVER_USART
41 \details
42 The functions of the USART driver are accessed by function pointers exposed by this structure.
43 Refer to \ref DriverFunctions for overview information.
44
45 Each instance of an USART interface provides such an access structure.
46 The instance is identified by a postfix number in the symbol name of the access structure, for example:
47 - \b Driver_USART0 is the name of the access struct of the first instance (no. 0).
48 - \b Driver_USART1 is the name of the access struct of the second instance (no. 1).
49
50 A middleware configuration setting allows connecting the middleware to a specific driver instance \b %Driver_USART<i>n</i>.
51 The default is \token{0}, which connects a middleware to the first instance of a driver.
52 *****************************************************************************************************************/
53
54 /**
55 \struct ARM_USART_CAPABILITIES
56 \details
57 An USART driver can be implemented with different capabilities.
58 The data fields of this structure encode the capabilities implemented by this driver.
59
60 <b>Returned by:</b>
61 - \ref ARM_USART_GetCapabilities
62 *****************************************************************************************************************/
63
64 /**
65 \struct ARM_USART_STATUS
66 \details
67 Structure with information about the status of the USART. The data fields encode busy flags and error flags.
68
69 <b>Returned by:</b>
70 - \ref ARM_USART_GetStatus
71 *****************************************************************************************************************/
72
73 /**
74 \typedef ARM_USART_MODEM_CONTROL
75 \details
76 Specifies values for controlling the modem control lines.
77
78 <b>Parameter for:</b>
79 - \ref ARM_USART_SetModemControl
80 *****************************************************************************************************************/
81
82 /**
83 \struct ARM_USART_MODEM_STATUS
84 \details
85 Structure with information about the status of modem lines. The data fields encode states of modem status lines.
86
87 <b>Returned by:</b>
88 - \ref ARM_USART_GetModemStatus
89 *****************************************************************************************************************/
90
91
92 /**
93 \typedef ARM_USART_SignalEvent_t
94 \details
95 Provides the typedef for the callback function \ref ARM_USART_SignalEvent.
96
97 <b>Parameter for:</b>
98 - \ref ARM_USART_Initialize
99 *******************************************************************************************************************/
100
101
102 /**
103 \defgroup usart_execution_status USART Status Error Codes
104 \ingroup usart_interface_gr
105 \brief Negative values indicate errors (USART has specific codes in addition to common \ref execution_status).
106 \details
107 The USART driver has additional status error codes that are listed below.
108 Note that the USART driver also returns the common \ref execution_status.
109
110 @{
111 \def ARM_USART_ERROR_MODE
112 The \b mode requested with the function \ref ARM_USART_Control is not supported by this driver.
113
114 \def ARM_USART_ERROR_BAUDRATE
115 The <b>baud rate</b> requested with the function \ref ARM_USART_Control is not supported by this driver.
116
117 \def ARM_USART_ERROR_DATA_BITS
118 The number of <b>data bits</b> requested with the function \ref ARM_USART_Control is not supported by this driver.
119
120 \def ARM_USART_ERROR_PARITY
121 The <b>parity bit</b> requested with the function \ref ARM_USART_Control is not supported by this driver.
122
123 \def ARM_USART_ERROR_STOP_BITS
124 The <b>stop bit</b> requested with the function \ref ARM_USART_Control is not supported by this driver.
125
126 \def ARM_USART_ERROR_FLOW_CONTROL
127 The <b>flow control</b> requested with the function \ref ARM_USART_Control is not supported by this driver.
128
129 \def ARM_USART_ERROR_CPOL
130 The <b>clock polarity</b> requested with the function \ref ARM_USART_Control is not supported by this driver.
131
132 \def ARM_USART_ERROR_CPHA
133 The <b>clock phase</b> requested with the function \ref ARM_USART_Control is not supported by this driver.
134 @}
135 */
136
137
138 /**
139 \defgroup USART_events USART Events
140 \ingroup usart_interface_gr
141 \brief The USART driver generates call back events that are notified via the function \ref ARM_USART_SignalEvent.
142 \details
143 This section provides the event values for the \ref ARM_USART_SignalEvent callback function.
144
145 The following call back notification events are generated:
146 @{
147 \def ARM_USART_EVENT_SEND_COMPLETE
148 \def ARM_USART_EVENT_RECEIVE_COMPLETE
149 \def ARM_USART_EVENT_TRANSFER_COMPLETE
150 \def ARM_USART_EVENT_TX_COMPLETE
151 \def ARM_USART_EVENT_TX_UNDERFLOW
152 \def ARM_USART_EVENT_RX_OVERFLOW
153 \def ARM_USART_EVENT_RX_TIMEOUT
154 \def ARM_USART_EVENT_RX_BREAK
155 \def ARM_USART_EVENT_RX_FRAMING_ERROR
156 \def ARM_USART_EVENT_RX_PARITY_ERROR
157 \def ARM_USART_EVENT_CTS
158 \def ARM_USART_EVENT_DSR
159 \def ARM_USART_EVENT_DCD
160 \def ARM_USART_EVENT_RI
161 @}
162 */
163
164
165 /**
166 \defgroup USART_control USART Control Codes
167 \ingroup usart_interface_gr
168 \brief Many parameters of the USART driver are configured using the \ref ARM_USART_Control function.
169 \details
170 @{
171 The various USART control codes define:
172 - \ref usart_mode_control specifies USART mode
173 - \ref usart_data_bits defines the number of data bits
174 - \ref usart_parity_bit defines the parity bit
175 - \ref usart_stop_bits defines the number of stop bits
176 - \ref usart_flow_control specifies RTS/CTS flow control
177 - \ref usart_clock_polarity defines the clock polarity for the synchronous mode
178 - \ref usart_clock_phase defines the clock phase for the synchronous mode
179 - \ref usart_misc_control specifies additional miscellaneous controls
180
181 Refer to the \ref ARM_USART_Control function for further details.
182
183 */
184
185
186 /**
187 \defgroup usart_mode_control USART Mode Control
188 \ingroup USART_control
189 \brief Specify USART mode.
190 \details
191 @{
192 \def ARM_USART_MODE_ASYNCHRONOUS
193 \sa ARM_USART_Control
194 \def ARM_USART_MODE_SYNCHRONOUS_MASTER
195 \sa ARM_USART_Control
196 \def ARM_USART_MODE_SYNCHRONOUS_SLAVE
197 \sa ARM_USART_Control
198 \def ARM_USART_MODE_SINGLE_WIRE
199 \sa ARM_USART_Control
200 \def ARM_USART_MODE_IRDA
201 \sa ARM_USART_Control
202 \def ARM_USART_MODE_SMART_CARD
203 \sa ARM_USART_Control
204 @}
205 */
206
207
208 /**
209 \defgroup usart_misc_control USART Miscellaneous Control
210 \ingroup USART_control
211 \brief Specifies additional miscellaneous controls.
212 \details
213 @{
214 \def ARM_USART_SET_DEFAULT_TX_VALUE
215 \sa ARM_USART_Control; ARM_USART_Receive;
216 \def ARM_USART_SET_IRDA_PULSE
217 \sa ARM_USART_Control
218 \def ARM_USART_SET_SMART_CARD_GUARD_TIME
219 \sa ARM_USART_Control
220 \def ARM_USART_SET_SMART_CARD_CLOCK
221 \sa ARM_USART_Control
222 \def ARM_USART_CONTROL_SMART_CARD_NACK
223 \sa ARM_USART_Control
224 \def ARM_USART_CONTROL_TX
225 \sa ARM_USART_Control; ARM_USART_Send; ARM_USART_Transfer
226 \def ARM_USART_CONTROL_RX
227 \sa ARM_USART_Control; ARM_USART_Receive; ARM_USART_Transfer;
228 \def ARM_USART_CONTROL_BREAK
229 \sa ARM_USART_Control
230 \def ARM_USART_ABORT_SEND
231 \sa ARM_USART_Control;
232 \def ARM_USART_ABORT_RECEIVE
233 \sa ARM_USART_Control;
234 \def ARM_USART_ABORT_TRANSFER
235 \sa ARM_USART_Control;
236 @}
237 */
238
239 /**
240 \defgroup usart_data_bits USART Data Bits
241 \ingroup USART_control
242 \brief Defines the number of data bits.
243 \details
244 @{
245 \def ARM_USART_DATA_BITS_5
246 \sa ARM_USART_Control
247 \def ARM_USART_DATA_BITS_6
248 \sa ARM_USART_Control
249 \def ARM_USART_DATA_BITS_7
250 \sa ARM_USART_Control
251 \def ARM_USART_DATA_BITS_8
252 \sa ARM_USART_Control
253 \def ARM_USART_DATA_BITS_9
254 \sa ARM_USART_Control
255 @}
256 */
257
258 /**
259 \defgroup usart_parity_bit USART Parity Bit
260 \ingroup USART_control
261 \brief Defines the parity bit.
262 \details
263 @{
264 \def ARM_USART_PARITY_NONE
265 \sa ARM_USART_Control
266 \def ARM_USART_PARITY_EVEN
267 \sa ARM_USART_Control
268 \def ARM_USART_PARITY_ODD
269 \sa ARM_USART_Control
270 @}
271 */
272
273 /**
274 \defgroup usart_stop_bits USART Stop Bits
275 \ingroup USART_control
276 \brief Defines the number of stop bits.
277 \details
278 @{
279 \sa ARM_USART_Control
280 \def ARM_USART_STOP_BITS_1
281 \sa ARM_USART_Control
282 \def ARM_USART_STOP_BITS_2
283 \sa ARM_USART_Control
284 \def ARM_USART_STOP_BITS_1_5
285 \sa ARM_USART_Control
286 \def ARM_USART_STOP_BITS_0_5
287 \sa ARM_USART_Control
288 @}
289 */
290
291 /**
292 \defgroup usart_flow_control USART Flow Control
293 \ingroup USART_control
294 \brief Specifies RTS/CTS flow control.
295 \details
296 @{
297 \def ARM_USART_FLOW_CONTROL_NONE
298 \sa ARM_USART_Control
299 \def ARM_USART_FLOW_CONTROL_RTS
300 \sa ARM_USART_Control
301 \def ARM_USART_FLOW_CONTROL_CTS
302 \sa ARM_USART_Control
303 \def ARM_USART_FLOW_CONTROL_RTS_CTS
304 \sa ARM_USART_Control
305 @}
306 */
307
308 /**
309 \defgroup usart_clock_polarity USART Clock Polarity
310 \ingroup USART_control
311 \brief Defines the clock polarity for the synchronous mode.
312 \details
313 @{
314 \def ARM_USART_CPOL0
315 \sa ARM_USART_Control; ARM_USART_Receive; ARM_USART_Send; ARM_USART_Transfer
316 \def ARM_USART_CPOL1
317 \sa ARM_USART_Control; ARM_USART_Receive; ARM_USART_Send; ARM_USART_Transfer
318 @}
319 */
320
321 /**
322 \defgroup usart_clock_phase USART Clock Phase
323 \ingroup USART_control
324 \brief Defines the clock phase for the synchronous mode.
325 \details
326 @{
327 \def ARM_USART_CPHA0
328 \sa ARM_USART_Control; ARM_USART_Receive; ARM_USART_Send; ARM_USART_Transfer
329 \def ARM_USART_CPHA1
330 \sa ARM_USART_Control; ARM_USART_Receive; ARM_USART_Send; ARM_USART_Transfer
331 @}
332 */
333
334 /**
335 @}
336 */
337 // end group USART_control
338
339
340 //
341 // Functions
342 //
343
ARM_USART_GetVersion(void)344 ARM_DRIVER_VERSION ARM_USART_GetVersion (void) {
345 return { 0, 0 };
346 }
347 /**
348 \fn ARM_DRIVER_VERSION ARM_USART_GetVersion (void)
349 \details
350 The function \b ARM_USART_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
351 - API version is the version of the CMSIS-Driver specification used to implement this driver.
352 - Driver version is source code version of the actual driver implementation.
353
354 Example:
355 \code
356 extern ARM_DRIVER_USART Driver_USART0;
357 ARM_DRIVER_USART *drv_info;
358
359 void setup_usart (void) {
360 ARM_DRIVER_VERSION version;
361
362 drv_info = &Driver_USART0;
363 version = drv_info->GetVersion ();
364 if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
365 // error handling
366 return;
367 }
368 }
369 \endcode
370 *****************************************************************************************************************/
371
ARM_USART_GetCapabilities(void)372 ARM_USART_CAPABILITIES ARM_USART_GetCapabilities (void) {
373 return { 0 } ;
374 }
375 /**
376 \fn ARM_USART_CAPABILITIES ARM_USART_GetCapabilities (void)
377 \details
378 The function \b ARM_USART_GetCapabilities returns information about capabilities in this driver implementation.
379 The data fields of the structure \ref ARM_USART_CAPABILITIES encode various capabilities, for example:
380 supported modes, if hardware and driver are capable of signaling events using the \ref ARM_USART_SignalEvent
381 callback function ...
382
383 Example:
384 \code
385 extern ARM_DRIVER_USART Driver_USART0;
386 ARM_DRIVER_USART *drv_info;
387
388 void read_capabilities (void) {
389 ARM_USART_CAPABILITIES drv_capabilities;
390
391 drv_info = &Driver_USART0;
392 drv_capabilities = drv_info->GetCapabilities ();
393 // interrogate capabilities
394
395 }
396 \endcode
397 *****************************************************************************************************************/
398
ARM_USART_Initialize(ARM_USART_SignalEvent_t cb_event)399 int32_t ARM_USART_Initialize (ARM_USART_SignalEvent_t cb_event) {
400 return ARM_DRIVER_OK;
401 }
402 /**
403 \fn int32_t ARM_USART_Initialize (ARM_USART_SignalEvent_t cb_event)
404 \details
405 The function \b ARM_USART_Initialize initializes the USART interface.
406 It is called when the middleware component starts operation.
407
408 The function performs the following operations:
409 - Initializes the resources needed for the USART interface.
410 - Registers the \ref ARM_USART_SignalEvent callback function.
411
412 The parameter \em cb_event is a pointer to the \ref ARM_USART_SignalEvent callback function; use a NULL pointer
413 when no callback signals are required.
414
415 \b Example:
416 - see \ref usart_interface_gr - Driver Functions
417
418 *****************************************************************************************************************/
419
ARM_USART_Uninitialize(void)420 int32_t ARM_USART_Uninitialize (void) {
421 return ARM_DRIVER_OK;
422 }
423 /**
424 \fn int32_t ARM_USART_Uninitialize (void)
425 \details
426 The function \b ARM_USART_Uninitialize de-initializes the resources of USART interface.
427
428 It is called when the middleware component stops operation and releases the software resources used by the interface.
429 *****************************************************************************************************************/
430
ARM_USART_PowerControl(ARM_POWER_STATE state)431 int32_t ARM_USART_PowerControl (ARM_POWER_STATE state) {
432 return ARM_DRIVER_OK;
433 }
434 /**
435 \fn int32_t ARM_USART_PowerControl (ARM_POWER_STATE state)
436 \details
437 The function \b ARM_USART_PowerControl operates the power modes of the USART interface.
438
439 The parameter \em state sets the operation and can have the following values:
440 - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
441 Can be called multiple times. If the peripheral is already in this mode the function performs
442 no operation and returns with \ref ARM_DRIVER_OK.
443 - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
444 - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
445
446 Refer to \ref CallSequence for more information.
447
448 *****************************************************************************************************************/
449
ARM_USART_Send(const void * data,uint32_t num)450 int32_t ARM_USART_Send (const void *data, uint32_t num) {
451 return ARM_DRIVER_OK;
452 }
453 /**
454 \fn int32_t ARM_USART_Send (const void *data, uint32_t num)
455 \details
456 This functions \b ARM_USART_Send is used in asynchronous mode to send data to the USART transmitter.
457 It can also be used in synchronous mode when sending data only (received data is ignored).
458
459 Transmitter needs to be enabled by calling \ref ARM_USART_Control with \ref ARM_USART_CONTROL_TX as the control parameter and \token{1} as argument.
460
461 The function parameters specify the buffer with data and the number of items to send.
462 The item size is defined by the data type which depends on the configured number of data bits.
463
464 Data type is:
465 - \em uint8_t when configured for 5..8 data bits
466 - \em uint16_t when configured for 9 data bits
467
468 Calling the function <b>ARM_USART_Send</b> only starts the send operation.
469 The function is non-blocking and returns as soon as the driver has started the operation (driver typically configures DMA or the interrupt system for continuous transfer).
470 When in synchronous slave mode the operation is only registered and started when the master starts the transfer.
471 During the operation it is not allowed to call this function again or any other data transfer function when in synchronous mode. Also the data buffer must stay allocated and the contents of unsent data must not be modified.
472 When send operation is completed (requested number of items sent) the \ref ARM_USART_EVENT_SEND_COMPLETE event is generated.
473 Progress of send operation can also be monitored by reading the number of items already sent by calling \ref ARM_USART_GetTxCount.
474
475 After send operation has completed there might still be some data left in the driver's hardware buffer which is still being transmitted.
476 When all data has been physically transmitted the \ref ARM_USART_EVENT_TX_COMPLETE event is generated (if supported and reported by \em event_tx_complete in \ref ARM_USART_CAPABILITIES).
477 At that point also the \em tx_busy data field in \ref ARM_USART_STATUS is cleared.
478
479 Status of the transmitter can be monitored by calling the \ref ARM_USART_GetStatus and checking the \em tx_busy flag
480 which indicates if transmission is still in progress.
481
482 When in synchronous slave mode and transmitter is enabled but send/receive/transfer operation is not started and data is requested by the master then the \ref ARM_USART_EVENT_TX_UNDERFLOW event is generated.
483
484 Send operation can be aborted by calling \ref ARM_USART_Control with \ref ARM_USART_ABORT_SEND as the control parameter.
485 *****************************************************************************************************************/
486
ARM_USART_Receive(void * data,uint32_t num)487 int32_t ARM_USART_Receive (void *data, uint32_t num) {
488 return ARM_DRIVER_OK;
489 }
490 /**
491 \fn int32_t ARM_USART_Receive (void *data, uint32_t num)
492 \details
493 This functions \b ARM_USART_Receive is used in asynchronous mode to receive data from the USART receiver.
494 It can also be used in synchronous mode when receiving data only (transmits the default value as specified by \ref ARM_USART_Control with \ref ARM_USART_SET_DEFAULT_TX_VALUE as control parameter).
495
496 Receiver needs to be enabled by calling \ref ARM_USART_Control with \ref ARM_USART_CONTROL_RX as the control parameter and \token{1} as argument.
497
498 The function parameters specify the buffer for data and the number of items to receive.
499 The item size is defined by the data type which depends on the configured number of data bits.
500
501 Data type is:
502 - \em uint8_t when configured for 5..8 data bits
503 - \em uint16_t when configured for 9 data bits
504
505 Calling the function <b>ARM_USART_Receive</b> only starts the receive operation.
506 The function is non-blocking and returns as soon as the driver has started the operation (driver typically configures DMA or the interrupt system for continuous transfer).
507 When in synchronous slave mode the operation is only registered and started when the master starts the transfer.
508 During the operation it is not allowed to call this function again or any other data transfer function when in synchronous mode. Also the data buffer must stay allocated.
509 When receive operation is completed (requested number of items received) the \ref ARM_USART_EVENT_RECEIVE_COMPLETE event is generated.
510 Progress of receive operation can also be monitored by reading the number of items already received by calling \ref ARM_USART_GetRxCount.
511
512 Status of the receiver can be monitored by calling the \ref ARM_USART_GetStatus and checking the \em rx_busy flag
513 which indicates if reception is still in progress.
514
515 During reception the following events can be generated (in asynchronous mode):
516 - \ref ARM_USART_EVENT_RX_TIMEOUT : Receive timeout between consecutive characters detected (optional)
517 - \ref ARM_USART_EVENT_RX_BREAK : Break detected (Framing error is not generated for Break condition)
518 - \ref ARM_USART_EVENT_RX_FRAMING_ERROR : Framing error detected
519 - \ref ARM_USART_EVENT_RX_PARITY_ERROR : Parity error detected
520 - \ref ARM_USART_EVENT_RX_OVERFLOW : Data overflow detected (also in synchronous slave mode)
521
522 \ref ARM_USART_EVENT_RX_OVERFLOW event is also generated when receiver is enabled but data is lost because
523 receive operation in asynchronous mode or receive/send/transfer operation in synchronous slave mode has not been started.
524
525 Receive operation can be aborted by calling \ref ARM_USART_Control with \ref ARM_USART_ABORT_RECEIVE as the control parameter.
526 *****************************************************************************************************************/
527
ARM_USART_Transfer(const void * data_out,void * data_in,uint32_t num)528 int32_t ARM_USART_Transfer (const void *data_out, void *data_in, uint32_t num) {
529 return ARM_DRIVER_OK;
530 }
531 /**
532 \fn int32_t ARM_USART_Transfer (const void *data_out, void *data_in, uint32_t num)
533 \details
534 This functions \b ARM_USART_Transfer is used in synchronous mode to transfer data via USART. It synchronously sends data to the USART transmitter and receives data from the USART receiver.
535
536 Transmitter needs to be enabled by calling \ref ARM_USART_Control with \ref ARM_USART_CONTROL_TX as the control parameter and \token{1} as argument.
537 Receiver needs to be enabled by calling \ref ARM_USART_Control with \ref ARM_USART_CONTROL_RX as the control parameter and \token{1} as argument.
538
539 The function parameters specify the buffer with data to send, the buffer for data to receive and the number of items to transfer.
540 The item size is defined by the data type which depends on the configured number of data bits.
541
542 Data type is:
543 - \em uint8_t when configured for 5..8 data bits
544 - \em uint16_t when configured for 9 data bits
545
546 Calling the function <b>ARM_USART_Transfer</b> only starts the transfer operation.
547 The function is non-blocking and returns as soon as the driver has started the operation (driver typically configures DMA or the interrupt system for continuous transfer).
548 When in synchronous slave mode the operation is only registered and started when the master starts the transfer.
549 During the operation it is not allowed to call this function or any other data transfer function again. Also the data buffers must stay allocated and the contents of unsent data must not be modified.
550 When transfer operation is completed (requested number of items transferred) the \ref ARM_USART_EVENT_TRANSFER_COMPLETE event is generated.
551 Progress of transfer operation can also be monitored by reading the number of items already transferred by calling \ref ARM_USART_GetTxCount or \ref ARM_USART_GetRxCount.
552
553 Status of the transmitter or receiver can be monitored by calling the \ref ARM_USART_GetStatus and checking the \em tx_busy or \em rx_busy flag.
554
555 When in synchronous slave mode also the following events can be generated:
556 - \ref ARM_USART_EVENT_TX_UNDERFLOW : transmitter is enabled but transfer operation is not started and data is requested by the master
557 - \ref ARM_USART_EVENT_RX_OVERFLOW : data lost during transfer or because receiver is enabled but transfer operation has not been started
558
559 Transfer operation can also be aborted by calling \ref ARM_USART_Control with \ref ARM_USART_ABORT_TRANSFER as the control parameter.
560 *****************************************************************************************************************/
561
ARM_USART_GetTxCount(void)562 uint32_t ARM_USART_GetTxCount (void) {
563 return 0;
564 }
565 /**
566 \fn uint32_t ARM_USART_GetTxCount (void)
567 \details
568 The function \b ARM_USART_GetTxCount returns the number of the currently transmitted data items during \ref ARM_USART_Send and \ref ARM_USART_Transfer operation.
569 *****************************************************************************************************************/
570
ARM_USART_GetRxCount(void)571 uint32_t ARM_USART_GetRxCount (void) {
572 return 0;
573 }
574 /**
575 \fn uint32_t ARM_USART_GetRxCount (void)
576 \details
577 The function \b ARM_USART_GetRxCount returns the number of the currently received data items during \ref ARM_USART_Receive and \ref ARM_USART_Transfer operation.
578 *****************************************************************************************************************/
579
ARM_USART_Control(uint32_t control,uint32_t arg)580 int32_t ARM_USART_Control (uint32_t control, uint32_t arg) {
581 return ARM_DRIVER_OK;
582 }
583 /**
584 \fn int32_t ARM_USART_Control (uint32_t control, uint32_t arg)
585 \details
586 The function \b ARM_USART_Control control the USART interface settings and execute various operations.
587
588 The parameter \em control sets the operation and is explained in the table below.
589 Values from different categories can be ORed with the exception of \ref usart_misc_tab "Miscellaneous Operations".
590
591 The parameter \em arg provides, depending on the operation, additional information, for example the baudrate.
592
593 The table lists the available \em control operations.
594
595 <TABLE class="cmtable" summary="">
596 <TR><TH>Parameter \em control </TH> <TH style="text-align:right"> Bit </TH> <TH> Category </TH> <TH>Description </TH></TR>
597 <TR><TD>\ref ARM_USART_MODE_ASYNCHRONOUS</TD> <td rowspan="6" style="text-align:right"> 0..7 </td> <td rowspan="6"> Operation Mode </td><TD>Set to asynchronous UART mode. \em arg specifies baudrate.</TD></TR>
598 <TR><TD>\ref ARM_USART_MODE_SYNCHRONOUS_MASTER</TD> <TD>Set to synchronous master mode with clock signal generation. \em arg specifies baudrate.</TD></TR>
599 <TR><TD>\ref ARM_USART_MODE_SYNCHRONOUS_SLAVE</TD> <TD>Set to synchronous slave mode with external clock signal.</TD></TR>
600 <TR><TD>\ref ARM_USART_MODE_SINGLE_WIRE</TD> <TD>Set to single-wire (half-duplex) mode. \em arg specifies baudrate.</TD></TR>
601 <TR><TD>\ref ARM_USART_MODE_IRDA</TD> <TD>Set to Infra-red data mode. \em arg specifies baudrate.</TD></TR>
602 <TR><TD>\ref ARM_USART_MODE_SMART_CARD</TD> <TD>Set to Smart Card mode. \em arg specifies baudrate.</TD></TR>
603 <TR><TD>\ref ARM_USART_DATA_BITS_5</TD> <td rowspan="5" style="text-align:right"> 8..11 </td> <td rowspan="5"> Data Bits </td><TD>Set to \token{5} data bits</TD></TR>
604 <TR><TD>\ref ARM_USART_DATA_BITS_6</TD> <TD>Set to \token{6} data bits</TD></TR>
605 <TR><TD>\ref ARM_USART_DATA_BITS_7</TD> <TD>Set to \token{7} data bits</TD></TR>
606 <TR><TD>\ref ARM_USART_DATA_BITS_8</TD> <TD>Set to \token{8} data bits (default)</TD></TR>
607 <TR><TD>\ref ARM_USART_DATA_BITS_9</TD> <TD>Set to \token{9} data bits</TD></TR>
608 <TR><TD>\ref ARM_USART_PARITY_EVEN</TD> <td rowspan="3" style="text-align:right"> 12..13 </td> <td rowspan="3"> Parity Bit </td><TD>Set to Even Parity</TD></TR>
609 <TR><TD>\ref ARM_USART_PARITY_NONE</TD> <TD>Set to No Parity (default)</TD></TR>
610 <TR><TD>\ref ARM_USART_PARITY_ODD</TD> <TD>Set to Odd Parity</TD></TR>
611 <TR><TD>\ref ARM_USART_STOP_BITS_1</TD> <td rowspan="4" style="text-align:right"> 14..15 </td> <td rowspan="4"> Stop Bit </td><TD>Set to \token{1} Stop bit (default)</TD></TR>
612 <TR><TD>\ref ARM_USART_STOP_BITS_2</TD> <TD>Set to \token{2} Stop bits</TD></TR>
613 <TR><TD>\ref ARM_USART_STOP_BITS_1_5</TD> <TD>Set to \token{1.5} Stop bits</TD></TR>
614 <TR><TD>\ref ARM_USART_STOP_BITS_0_5</TD> <TD>Set to \token{0.5} Stop bits</TD></TR>
615 <TR><TD>\ref ARM_USART_FLOW_CONTROL_NONE</TD> <td rowspan="4" style="text-align:right"> 16..17 </td> <td rowspan="4"> Flow Control </td><TD>No flow control signal (default)</TD></TR>
616 <TR><TD>\ref ARM_USART_FLOW_CONTROL_CTS</TD> <TD>Set to use the CTS flow control signal</TD></TR>
617 <TR><TD>\ref ARM_USART_FLOW_CONTROL_RTS</TD> <TD>Set to use the RTS flow control signal</TD></TR>
618 <TR><TD>\ref ARM_USART_FLOW_CONTROL_RTS_CTS</TD> <TD>Set to use the RTS and CTS flow control signal</TD></TR>
619 <TR><TD>\ref ARM_USART_CPOL0</TD> <td rowspan="2" style="text-align:right"> 18 </td> <td rowspan="2"> Clock Polarity </td><TD>CPOL=\token{0} (default) : data are captured on rising edge (low->high transition)</TD></TR>
620 <TR><TD>\ref ARM_USART_CPOL1</TD> <TD>CPOL=\token{1} : data are captured on falling edge (high->low transition)</TD></TR>
621 <TR><TD>\ref ARM_USART_CPHA0</TD> <td rowspan="2" style="text-align:right"> 19 </td> <td rowspan="2"> Clock Phase </td><TD>CPHA=\token{0} (default) : sample on first (leading) edge</TD></TR>
622 <TR><TD>\ref ARM_USART_CPHA1</TD> <TD>CPHA=\token{1} : sample on second (trailing) edge</TD></TR>
623 <TR><TD>\ref ARM_USART_ABORT_RECEIVE</TD> <td rowspan="11" style="text-align:right"> 0..19 </td> <td rowspan="11"> \anchor usart_misc_tab Miscellaneous Operations <br>(cannot be ORed) </td><TD>Abort receive operation (see also: \ref ARM_USART_Receive)</TD></TR>
624 <TR> <TD>\ref ARM_USART_ABORT_SEND</TD> <TD>Abort send operation (see also: \ref ARM_USART_Send)</TD></TR>
625 <TR> <TD>\ref ARM_USART_ABORT_TRANSFER</TD> <TD>Abort transfer operation (see also: \ref ARM_USART_Transfer)</TD></TR>
626 <TR> <TD>\ref ARM_USART_CONTROL_BREAK</TD> <TD>Enable or disable continuous Break transmission; \em arg : \token{0=disabled; 1=enabled}</TD></TR>
627 <TR> <TD>\ref ARM_USART_CONTROL_RX</TD> <TD>Enable or disable receiver; \em arg : \token{0=disabled; 1=enabled} (see also: \ref ARM_USART_Receive; \ref ARM_USART_Transfer)</TD></TR>
628 <TR> <TD>\ref ARM_USART_CONTROL_SMART_CARD_NACK</TD> <TD>Enable or disable Smart Card NACK generation; \em arg : \token{0=disabled; 1=enabled}</TD></TR>
629 <TR> <TD>\ref ARM_USART_CONTROL_TX</TD> <TD>Enable or disable transmitter; \em arg : \token{0=disabled; 1=enabled} (see also: \ref ARM_USART_Send; \ref ARM_USART_Transfer)</TD></TR>
630 <TR> <TD>\ref ARM_USART_SET_DEFAULT_TX_VALUE</TD> <TD>Set the default transmit value (synchronous receive only); \em arg specifies the value. (see also: \ref ARM_USART_Receive)</TD></TR>
631 <TR> <TD>\ref ARM_USART_SET_IRDA_PULSE</TD> <TD>Set the IrDA pulse value in \token{ns}; \em arg : \token{0=3/16 of bit period}</TD></TR>
632 <TR> <TD>\ref ARM_USART_SET_SMART_CARD_CLOCK</TD> <TD>Set the Smart Card Clock in \token{Hz}; \em arg : \token{0=Clock not set}</TD></TR>
633 <TR> <TD>\ref ARM_USART_SET_SMART_CARD_GUARD_TIME</TD> <TD>Set the Smart Card guard time; \em arg = number of bit periods</TD></TR>
634 </TABLE>
635
636 \b Example
637
638 \code
639 extern ARM_DRIVER_USART Driver_USART0;
640
641 // configure to UART mode: 8 bits, no parity, 1 stop bit, no flow control, 9600 bps
642 status = Driver_USART0.Control(ARM_USART_MODE_ASYNCHRONOUS |
643 ARM_USART_DATA_BITS_8 |
644 ARM_USART_PARITY_NONE |
645 ARM_USART_STOP_BITS_1 |
646 ARM_USART_FLOW_CONTROL_NONE, 9600);
647
648 // identical with above settings (default settings removed)
649 // configure to UART mode: 8 bits, no parity, 1 stop bit, flow control, 9600 bps
650 status = Driver_USART0.Control(ARM_USART_MODE_ASYNCHRONOUS, 9600);
651
652 // enable TX output
653 status = Driver_USART0.Control(ARM_USART_CONTROL_TX, 1);
654
655 // disable RX output
656 status = Driver_USART0.Control(ARM_USART_CONTROL_RX, 0);
657 \endcode
658 *****************************************************************************************************************/
659
ARM_USART_GetStatus(void)660 ARM_USART_STATUS ARM_USART_GetStatus (void) {
661 return { 0 };
662 }
663 /**
664 \fn ARM_USART_STATUS ARM_USART_GetStatus (void)
665 \details
666 The function \b ARM_USART_GetStatus retrieves the current USART interface status.
667
668 *****************************************************************************************************************/
669
ARM_USART_SetModemControl(ARM_USART_MODEM_CONTROL control)670 int32_t ARM_USART_SetModemControl (ARM_USART_MODEM_CONTROL control) {
671 return ARM_DRIVER_OK;
672 }
673 /**
674 \fn int32_t ARM_USART_SetModemControl (ARM_USART_MODEM_CONTROL control)
675 \details
676 The function \b ARM_USART_SetModemControl activates or deactivates the selected USART modem control line.
677
678 The function \ref ARM_USART_GetModemStatus returns information about status of the modem lines.
679
680 *****************************************************************************************************************/
681
ARM_USART_GetModemStatus(void)682 ARM_USART_MODEM_STATUS ARM_USART_GetModemStatus (void) {
683 return { 0 };
684 }
685 /**
686 \fn ARM_USART_MODEM_STATUS ARM_USART_GetModemStatus (void)
687 \details
688 The function \b ARM_USART_GetModemStatus returns the current USART Modem Status lines state.
689
690 The function \ref ARM_USART_SetModemControl sets the modem control lines of the USART.
691
692 *****************************************************************************************************************/
693
ARM_USART_SignalEvent(uint32_t event)694 void ARM_USART_SignalEvent (uint32_t event) {
695 // function body
696 }
697 /**
698 \fn void ARM_USART_SignalEvent (uint32_t event)
699 \details
700 The function \b ARM_USART_SignalEvent is a callback function registered by the function \ref ARM_USART_Initialize.
701
702 The parameter \em event indicates one or more events that occurred during driver operation.
703 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
704
705 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
706 data fields of the structure \ref ARM_USART_CAPABILITIES, which can be retrieved with the function \ref ARM_USART_GetCapabilities.
707
708 The following events can be generated:
709
710 <table class="cmtable" summary="">
711 <tr>
712 <th> Parameter \em event </th><th> Bit </th><th> Description </th>
713 <th> supported when ARM_USART_CAPABILITIES </th>
714 </tr>
715 <tr>
716 <td> \ref ARM_USART_EVENT_SEND_COMPLETE </td><td> 0 </td><td> Occurs after call to \ref ARM_USART_Send to indicate that all the data to be sent
717 was processed by the driver. All the data might have been already transmitted
718 or parts of it are still queued in transmit buffers. The driver is ready for the next
719 call to \ref ARM_USART_Send; however USART may still transmit data. </td>
720 <td> <i>always supported</i> </td>
721 </tr>
722 <tr>
723 <td> \ref ARM_USART_EVENT_RECEIVE_COMPLETE </td><td> 1 </td><td> Occurs after call to \ref ARM_USART_Receive to indicate that all the data has been
724 received. The driver is ready for the next call to \ref ARM_USART_Receive. </td>
725 <td> <i>always supported</i> </td>
726 </tr>
727 <tr>
728 <td> \ref ARM_USART_EVENT_TRANSFER_COMPLETE </td><td> 2 </td><td> Occurs after call to \ref ARM_USART_Transfer to indicate that all the data has been
729 transferred. The driver is ready for the next call to \ref ARM_USART_Transfer. </td>
730 <td> <i>always supported</i> </td>
731 </tr>
732 <tr>
733 <td> \ref ARM_USART_EVENT_TX_COMPLETE </td><td> 3 </td><td> Occurs after call to \ref ARM_USART_Send to indicate that all the data has been
734 physically transmitted on the wires. </td>
735 <td> data field \em event_tx_complete = \token{1} </td>
736 </tr>
737 <tr>
738 <td> \ref ARM_USART_EVENT_TX_UNDERFLOW </td><td> 4 </td><td> Occurs in synchronous slave mode when data is requested by the master but
739 send/receive/transfer operation has not been started.
740 Data field \em rx_underflow = \token{1} of \ref ARM_USART_STATUS. </td>
741 <td> <i>always supported</i> </td>
742 </tr>
743 <tr>
744 <td> \ref ARM_USART_EVENT_RX_OVERFLOW </td><td> 5 </td><td> Occurs when data is lost during receive/transfer operation or when data is lost
745 because receive operation in asynchronous mode or receive/send/transfer operation in
746 synchronous slave mode has not been started.
747 Data field \em rx_overflow = \token{1} of \ref ARM_USART_STATUS. </td>
748 <td> <i>always supported</i> </td>
749 </tr>
750 <tr>
751 <td> ARM_USART_EVENT_RX_TIMEOUT </td><td> 6 </td><td> Occurs during receive when idle time is detected between consecutive characters
752 (idle time is hardware dependent).</td>
753 <td> data field \em event_rx_timeout = \token{1} </td>
754 </tr>
755 <tr>
756 <td> \ref ARM_USART_EVENT_RX_BREAK </td><td> 7 </td><td> Occurs when break is detected during receive.
757 Data field \em rx_break = \token{1} of \ref ARM_USART_STATUS. </td>
758 <td> <i>always supported</i> </td>
759 </tr>
760 <tr>
761 <td> \ref ARM_USART_EVENT_RX_FRAMING_ERROR </td><td> 8 </td><td> Occurs when framing error is detected during receive.
762 Data field \em rx_framing_error = \token{1} of \ref ARM_USART_STATUS. </td>
763 <td> <i>always supported</i> </td>
764 </tr>
765 <tr>
766 <td> \ref ARM_USART_EVENT_RX_PARITY_ERROR </td><td> 9 </td><td> Occurs when parity error is detected during receive.
767 Data field \em rx_parity_error = \token{1} of \ref ARM_USART_STATUS. </td>
768 <td> <i>always supported</i> </td>
769 </tr>
770 <tr>
771 <td> ARM_USART_EVENT_CTS </td><td> 10 </td><td> Indicates that CTS modem line state has changed.
772 Data field \em cts of \ref ARM_USART_MODEM_STATUS has changed. </td>
773 <td> data field \em event_cts = \token{1} and <br>
774 data field \em cts = \token{1} </td>
775 </tr>
776 <tr>
777 <td> ARM_USART_EVENT_DSR </td><td> 11 </td><td> Indicates that DSR modem line state has changed.
778 Data field \em dsr of \ref ARM_USART_MODEM_STATUS has changed. </td>
779 <td> data field \em event_dsr = \token{1} and <br>
780 data field \em dsr = \token{1} </td>
781 </tr>
782 <tr>
783 <td> ARM_USART_EVENT_DCD </td><td> 12 </td><td> Indicates that DCD modem line state has changed.
784 Data field \em dcd of \ref ARM_USART_MODEM_STATUS has changed. </td>
785 <td> data field \em event_dcd = \token{1} and <br>
786 data field \em dcd = \token{1} </td>
787 </tr>
788 <tr>
789 <td> ARM_USART_EVENT_RI </td><td> 13 </td><td> Indicates that RI modem line state has changed from active to inactive
790 (trailing edge on RI).
791 Data field \em ri of \ref ARM_USART_MODEM_STATUS has changed from \token{1} to \token{0}. </td>
792 <td> data field \em event_ri = \token{1} and <br>
793 data field \em ri = \token{1} </td>
794 </tr>
795 </table>
796 *****************************************************************************************************************/
797
798 /**
799 @}
800 */
801 // End USART Interface
802
