Driver API for Universal Synchronous Asynchronous Receiver/Transmitter (Driver_USART.h) More...

Content
	USART Status Error Codes
	Negative values indicate errors (USART has specific codes in addition to common Status Error Codes).

	USART Events
	The USART driver generates call back events that are notified via the function ARM_USART_SignalEvent.

	USART Control Codes
	Many parameters of the USART driver are configured using the ARM_USART_Control function.

Data Structures
struct	ARM_DRIVER_USART
	Access structure of the USART Driver. More...

struct	ARM_USART_CAPABILITIES
	USART Device Driver Capabilities. More...

struct	ARM_USART_STATUS
	USART Status. More...

struct	ARM_USART_MODEM_STATUS
	USART Modem Status. More...

Typedefs
typedef void(*	ARM_USART_SignalEvent_t) (uint32_t event)
	Pointer to ARM_USART_SignalEvent : Signal USART Event.

Enumerations
enum	ARM_USART_MODEM_CONTROL { ARM_USART_RTS_CLEAR , ARM_USART_RTS_SET , ARM_USART_DTR_CLEAR , ARM_USART_DTR_SET }
	USART Modem Control. More...

Functions
ARM_DRIVER_VERSION	ARM_USART_GetVersion (void)
	Get driver version.

ARM_USART_CAPABILITIES	ARM_USART_GetCapabilities (void)
	Get driver capabilities.

int32_t	ARM_USART_Initialize (ARM_USART_SignalEvent_t cb_event)
	Initialize USART Interface.

int32_t	ARM_USART_Uninitialize (void)
	De-initialize USART Interface.

int32_t	ARM_USART_PowerControl (ARM_POWER_STATE state)
	Control USART Interface Power.

int32_t	ARM_USART_Send (const void *data, uint32_t num)
	Start sending data to USART transmitter.

int32_t	ARM_USART_Receive (void *data, uint32_t num)
	Start receiving data from USART receiver.

int32_t	ARM_USART_Transfer (const void data_out, void data_in, uint32_t num)
	Start sending/receiving data to/from USART transmitter/receiver.

uint32_t	ARM_USART_GetTxCount (void)
	Get transmitted data count.

uint32_t	ARM_USART_GetRxCount (void)
	Get received data count.

int32_t	ARM_USART_Control (uint32_t control, uint32_t arg)
	Control USART Interface.

ARM_USART_STATUS	ARM_USART_GetStatus (void)
	Get USART status.

int32_t	ARM_USART_SetModemControl (ARM_USART_MODEM_CONTROL control)
	Set USART Modem Control line state.

ARM_USART_MODEM_STATUS	ARM_USART_GetModemStatus (void)
	Get USART Modem Status lines state.

void	ARM_USART_SignalEvent (uint32_t event)
	Signal USART Events.

Description

Driver API for Universal Synchronous Asynchronous Receiver/Transmitter (Driver_USART.h)

The Universal Synchronous Asynchronous Receiver/Transmitter (USART) implements a synchronous and asynchronous serial bus for exchanging data. When only asynchronous mode is supported it is called Universal Asynchronous Receiver/Transmitter (UART).
Almost all microcontrollers have a serial interface (UART/USART peripheral). A UART is a simple device to send data to a PC via a terminal emulation program (Hyperterm, TeraTerm) or to another microcontroller. A UART takes bytes of data and transmits the individual bits in a sequential mode. At the destination, a second UART reassembles the bits into complete bytes. Each UART contains a shift register for converting between serial and parallel transmission forms. Wikipedia offers more information about
the Universal asynchronous receiver/transmitter.

USART API

The following header files define the Application Programming Interface (API) for the USART interface:

Driver_USART.h : Driver API for Universal Synchronous Asynchronous Receiver/Transmitter

The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.

Driver Functions

The driver functions are published in the access struct as explained in Common Driver Functions

ARM_DRIVER_USART : access struct for USART driver functions

Example Code

The following example code shows the usage of the USART interface for asynchronous communication.

#include "Driver_USART.h"
#include "cmsis_os.h"                   /* ARM::CMSIS:RTOS:Keil RTX */
#include <stdio.h>
#include <string.h>
 
void myUART_Thread(void const *argument);
osThreadId tid_myUART_Thread;
 
/* USART Driver */
extern ARM_DRIVER_USART Driver_USART3;
 
 
void myUSART_callback(uint32_t event)
{
  uint32_t mask;
 
  mask = ARM_USART_EVENT_RECEIVE_COMPLETE  |
         ARM_USART_EVENT_TRANSFER_COMPLETE |
         ARM_USART_EVENT_SEND_COMPLETE     |
         ARM_USART_EVENT_TX_COMPLETE       ;
 
  if (event & mask) {
    /* Success: Wakeup Thread */
    osSignalSet(tid_myUART_Thread, 0x01);
  }
 
  if (event & ARM_USART_EVENT_RX_TIMEOUT) {
    __breakpoint(0);  /* Error: Call debugger or replace with custom error handling */
  }
 
  if (event & (ARM_USART_EVENT_RX_OVERFLOW | ARM_USART_EVENT_TX_UNDERFLOW)) {
    __breakpoint(0);  /* Error: Call debugger or replace with custom error handling */
  }
}
 
 
/* CMSIS-RTOS Thread - UART command thread */
void myUART_Thread(const void* args)
{
    static ARM_DRIVER_USART * USARTdrv = &Driver_USART3;
    ARM_DRIVER_VERSION     version;
    ARM_USART_CAPABILITIES drv_capabilities;
    char                   cmd;
 
  #ifdef DEBUG
    version = USARTdrv->GetVersion();
    if (version.api < 0x200)   /* requires at minimum API version 2.00 or higher */
    {                          /* error handling */
        return;
    }
    drv_capabilities = USARTdrv->GetCapabilities();
    if (drv_capabilities.event_tx_complete == 0)
    {                          /* error handling */
        return;
    }
  #endif
 
    /*Initialize the USART driver */
    USARTdrv->Initialize(myUSART_callback);
    /*Power up the USART peripheral */
    USARTdrv->PowerControl(ARM_POWER_FULL);
    /*Configure the USART to 4800 Bits/sec */
    USARTdrv->Control(ARM_USART_MODE_ASYNCHRONOUS |
                      ARM_USART_DATA_BITS_8 |
                      ARM_USART_PARITY_NONE |
                      ARM_USART_STOP_BITS_1 |
                      ARM_USART_FLOW_CONTROL_NONE, 4800);
     
    /* Enable Receiver and Transmitter lines */
    USARTdrv->Control (ARM_USART_CONTROL_TX, 1);
    USARTdrv->Control (ARM_USART_CONTROL_RX, 1);
 
    USARTdrv->Send("\nPress Enter to receive a message", 34);
    osSignalWait(0x01, osWaitForever);
     
    while (1)
    {
        USARTdrv->Receive(&cmd, 1);          /* Get byte from UART */
        osSignalWait(0x01, osWaitForever);
        if (cmd == 13)                       /* CR, send greeting  */
        {
          USARTdrv->Send("\nHello World!", 12);
          osSignalWait(0x01, osWaitForever);
        }
 
    }
}

Data Structure Documentation

◆ ARM_DRIVER_USART

struct ARM_DRIVER_USART

Access structure of the USART Driver.

The functions of the USART driver are accessed by function pointers exposed by this structure. Refer to Common Driver Functions for overview information.

Each instance of an USART interface provides such an access structure. The instance is identified by a postfix number in the symbol name of the access structure, for example:

Driver_USART0 is the name of the access struct of the first instance (no. 0).
Driver_USART1 is the name of the access struct of the second instance (no. 1).

A middleware configuration setting allows connecting the middleware to a specific driver instance Driver_USARTn. The default is 0, which connects a middleware to the first instance of a driver.

Data Fields
ARM_DRIVER_VERSION(*	GetVersion )(void)
	Pointer to ARM_USART_GetVersion : Get driver version.

ARM_USART_CAPABILITIES(*	GetCapabilities )(void)
	Pointer to ARM_USART_GetCapabilities : Get driver capabilities.

int32_t(*	Initialize )(ARM_USART_SignalEvent_t cb_event)
	Pointer to ARM_USART_Initialize : Initialize USART Interface.

int32_t(*	Uninitialize )(void)
	Pointer to ARM_USART_Uninitialize : De-initialize USART Interface.

int32_t(*	PowerControl )(ARM_POWER_STATE state)
	Pointer to ARM_USART_PowerControl : Control USART Interface Power.

int32_t(*	Send )(const void *data, uint32_t num)
	Pointer to ARM_USART_Send : Start sending data to USART transmitter.

int32_t(*	Receive )(void *data, uint32_t num)
	Pointer to ARM_USART_Receive : Start receiving data from USART receiver.

int32_t(*	Transfer )(const void data_out, void data_in, uint32_t num)
	Pointer to ARM_USART_Transfer : Start sending/receiving data to/from USART.

uint32_t(*	GetTxCount )(void)
	Pointer to ARM_USART_GetTxCount : Get transmitted data count.

uint32_t(*	GetRxCount )(void)
	Pointer to ARM_USART_GetRxCount : Get received data count.

int32_t(*	Control )(uint32_t control, uint32_t arg)
	Pointer to ARM_USART_Control : Control USART Interface.

ARM_USART_STATUS(*	GetStatus )(void)
	Pointer to ARM_USART_GetStatus : Get USART status.

int32_t(*	SetModemControl )(ARM_USART_MODEM_CONTROL control)
	Pointer to ARM_USART_SetModemControl : Set USART Modem Control line state.

ARM_USART_MODEM_STATUS(*	GetModemStatus )(void)
	Pointer to ARM_USART_GetModemStatus : Get USART Modem Status lines state.

Field Documentation

◆ GetVersion

ARM_DRIVER_VERSION(* GetVersion) (void)

Pointer to ARM_USART_GetVersion : Get driver version.

◆ GetCapabilities

ARM_USART_CAPABILITIES(* GetCapabilities) (void)

Pointer to ARM_USART_GetCapabilities : Get driver capabilities.

◆ Initialize

int32_t(* Initialize) (ARM_USART_SignalEvent_t cb_event)

Pointer to ARM_USART_Initialize : Initialize USART Interface.

◆ Uninitialize

int32_t(* Uninitialize) (void)

Pointer to ARM_USART_Uninitialize : De-initialize USART Interface.

◆ PowerControl

int32_t(* PowerControl) (ARM_POWER_STATE state)

Pointer to ARM_USART_PowerControl : Control USART Interface Power.

◆ Send

int32_t(* Send) (const void *data, uint32_t num)

Pointer to ARM_USART_Send : Start sending data to USART transmitter.

◆ Receive

int32_t(* Receive) (void *data, uint32_t num)

Pointer to ARM_USART_Receive : Start receiving data from USART receiver.

◆ Transfer

int32_t(* Transfer) (const void *data_out, void *data_in, uint32_t num)

Pointer to ARM_USART_Transfer : Start sending/receiving data to/from USART.

◆ GetTxCount

uint32_t(* GetTxCount) (void)

Pointer to ARM_USART_GetTxCount : Get transmitted data count.

◆ GetRxCount

uint32_t(* GetRxCount) (void)

Pointer to ARM_USART_GetRxCount : Get received data count.

◆ Control

int32_t(* Control) (uint32_t control, uint32_t arg)

Pointer to ARM_USART_Control : Control USART Interface.

◆ GetStatus

ARM_USART_STATUS(* GetStatus) (void)

Pointer to ARM_USART_GetStatus : Get USART status.

◆ SetModemControl

int32_t(* SetModemControl) (ARM_USART_MODEM_CONTROL control)

Pointer to ARM_USART_SetModemControl : Set USART Modem Control line state.

◆ GetModemStatus

ARM_USART_MODEM_STATUS(* GetModemStatus) (void)

Pointer to ARM_USART_GetModemStatus : Get USART Modem Status lines state.

◆ ARM_USART_CAPABILITIES

struct ARM_USART_CAPABILITIES

USART Device Driver Capabilities.

An USART driver can be implemented with different capabilities. The data fields of this structure encode the capabilities implemented by this driver.

Returned by:

ARM_USART_GetCapabilities

Data Fields
uint32_t	asynchronous: 1	supports UART (Asynchronous) mode
uint32_t	synchronous_master: 1	supports Synchronous Master mode
uint32_t	synchronous_slave: 1	supports Synchronous Slave mode
uint32_t	single_wire: 1	supports UART Single-wire mode
uint32_t	irda: 1	supports UART IrDA mode
uint32_t	smart_card: 1	supports UART Smart Card mode
uint32_t	smart_card_clock: 1	Smart Card Clock generator available.
uint32_t	flow_control_rts: 1	RTS Flow Control available.
uint32_t	flow_control_cts: 1	CTS Flow Control available.
uint32_t	event_tx_complete: 1	Transmit completed event: ARM_USART_EVENT_TX_COMPLETE.
uint32_t	event_rx_timeout: 1	Signal receive character timeout event: ARM_USART_EVENT_RX_TIMEOUT.
uint32_t	rts: 1	RTS Line: 0=not available, 1=available.
uint32_t	cts: 1	CTS Line: 0=not available, 1=available.
uint32_t	dtr: 1	DTR Line: 0=not available, 1=available.
uint32_t	dsr: 1	DSR Line: 0=not available, 1=available.
uint32_t	dcd: 1	DCD Line: 0=not available, 1=available.
uint32_t	ri: 1	RI Line: 0=not available, 1=available.
uint32_t	event_cts: 1	Signal CTS change event: ARM_USART_EVENT_CTS.
uint32_t	event_dsr: 1	Signal DSR change event: ARM_USART_EVENT_DSR.
uint32_t	event_dcd: 1	Signal DCD change event: ARM_USART_EVENT_DCD.
uint32_t	event_ri: 1	Signal RI change event: ARM_USART_EVENT_RI.
uint32_t	reserved: 11	Reserved (must be zero)

◆ ARM_USART_STATUS

struct ARM_USART_STATUS

USART Status.

Structure with information about the status of the USART. The data fields encode busy flags and error flags.

Returned by:

ARM_USART_GetStatus

Data Fields
uint32_t	tx_busy: 1	Transmitter busy flag.
uint32_t	rx_busy: 1	Receiver busy flag.
uint32_t	tx_underflow: 1	Transmit data underflow detected (cleared on start of next send operation)
uint32_t	rx_overflow: 1	Receive data overflow detected (cleared on start of next receive operation)
uint32_t	rx_break: 1	Break detected on receive (cleared on start of next receive operation)
uint32_t	rx_framing_error: 1	Framing error detected on receive (cleared on start of next receive operation)
uint32_t	rx_parity_error: 1	Parity error detected on receive (cleared on start of next receive operation)
uint32_t	reserved: 25

◆ ARM_USART_MODEM_STATUS

struct ARM_USART_MODEM_STATUS

USART Modem Status.

Structure with information about the status of modem lines. The data fields encode states of modem status lines.

Returned by:

ARM_USART_GetModemStatus

Data Fields
uint32_t	cts: 1	CTS state: 1=Active, 0=Inactive.
uint32_t	dsr: 1	DSR state: 1=Active, 0=Inactive.
uint32_t	dcd: 1	DCD state: 1=Active, 0=Inactive.
uint32_t	ri: 1	RI state: 1=Active, 0=Inactive.
uint32_t	reserved: 28

Typedef Documentation

◆ ARM_USART_SignalEvent_t

ARM_USART_SignalEvent_t

Pointer to ARM_USART_SignalEvent : Signal USART Event.

Provides the typedef for the callback function ARM_USART_SignalEvent.

Parameter for:

ARM_USART_Initialize

Enumeration Type Documentation

◆ ARM_USART_MODEM_CONTROL

enum ARM_USART_MODEM_CONTROL

USART Modem Control.

Specifies values for controlling the modem control lines.

Parameter for:

ARM_USART_SetModemControl

Enumerator
ARM_USART_RTS_CLEAR	Deactivate RTS.
ARM_USART_RTS_SET	Activate RTS.
ARM_USART_DTR_CLEAR	Deactivate DTR.
ARM_USART_DTR_SET	Activate DTR.

Function Documentation

◆ ARM_USART_GetVersion()

ARM_DRIVER_VERSION ARM_USART_GetVersion ( void )

Get driver version.

Returns: ARM_DRIVER_VERSION

The function ARM_USART_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION

API version is the version of the CMSIS-Driver specification used to implement this driver.
Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_USART Driver_USART0;
ARM_DRIVER_USART *drv_info;
 
void setup_usart (void)  {
  ARM_DRIVER_VERSION  version;
 
  drv_info = &Driver_USART0;  
  version = drv_info->GetVersion ();
  if (version.api < 0x10A)  {      // requires at minimum API version 1.10 or higher
    // error handling
    return;
  }
}

◆ ARM_USART_GetCapabilities()

ARM_USART_CAPABILITIES ARM_USART_GetCapabilities ( void )

Get driver capabilities.

Returns: ARM_USART_CAPABILITIES

The function ARM_USART_GetCapabilities returns information about capabilities in this driver implementation. The data fields of the structure ARM_USART_CAPABILITIES encode various capabilities, for example: supported modes, if hardware and driver are capable of signaling events using the ARM_USART_SignalEvent callback function ...

Example:

extern ARM_DRIVER_USART Driver_USART0;
ARM_DRIVER_USART *drv_info;
  
void read_capabilities (void)  {
  ARM_USART_CAPABILITIES drv_capabilities;
 
  drv_info = &Driver_USART0;  
  drv_capabilities = drv_info->GetCapabilities ();
  // interrogate capabilities
 
}

◆ ARM_USART_Initialize()

int32_t ARM_USART_Initialize ( ARM_USART_SignalEvent_t cb_event )

Initialize USART Interface.

Parameters

[in] cb_event Pointer to ARM_USART_SignalEvent

Returns: Status Error Codes

The function ARM_USART_Initialize initializes the USART interface. It is called when the middleware component starts operation.

The function performs the following operations:

Initializes the resources needed for the USART interface.
Registers the ARM_USART_SignalEvent callback function.

The parameter cb_event is a pointer to the ARM_USART_SignalEvent callback function; use a NULL pointer when no callback signals are required.

Example:

see USART Interface - Driver Functions

◆ ARM_USART_Uninitialize()

int32_t ARM_USART_Uninitialize ( void )

De-initialize USART Interface.

Returns: Status Error Codes

The function ARM_USART_Uninitialize de-initializes the resources of USART interface.

It is called when the middleware component stops operation and releases the software resources used by the interface.

◆ ARM_USART_PowerControl()

int32_t ARM_USART_PowerControl ( ARM_POWER_STATE state )

Control USART Interface Power.

Parameters

[in] state Power state

Returns: Status Error Codes

The function ARM_USART_PowerControl operates the power modes of the USART interface.

The parameter state sets the operation and can have the following values:

ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. If the peripheral is already in this mode the function performs no operation and returns with ARM_DRIVER_OK.
ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.

Refer to Function Call Sequence for more information.

◆ ARM_USART_Send()

int32_t ARM_USART_Send	(	const void *	data,
		uint32_t	num
	)

Start sending data to USART transmitter.

Parameters

[in]	data	Pointer to buffer with data to send to USART transmitter
[in]	num	Number of data items to send

Returns: Status Error Codes

This functions ARM_USART_Send is used in asynchronous mode to send data to the USART transmitter. It can also be used in synchronous mode when sending data only (received data is ignored).

Transmitter needs to be enabled by calling ARM_USART_Control with ARM_USART_CONTROL_TX as the control parameter and 1 as argument.

The function parameters specify the buffer with data and the number of items to send. The item size is defined by the data type which depends on the configured number of data bits.

Data type is:

uint8_t when configured for 5..8 data bits
uint16_t when configured for 9 data bits

Calling the function ARM_USART_Send only starts the send operation. 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). When in synchronous slave mode the operation is only registered and started when the master starts the transfer. 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. When send operation is completed (requested number of items sent) the ARM_USART_EVENT_SEND_COMPLETE event is generated. Progress of send operation can also be monitored by reading the number of items already sent by calling ARM_USART_GetTxCount.

After send operation has completed there might still be some data left in the driver's hardware buffer which is still being transmitted. When all data has been physically transmitted the ARM_USART_EVENT_TX_COMPLETE event is generated (if supported and reported by event_tx_complete in ARM_USART_CAPABILITIES). At that point also the tx_busy data field in ARM_USART_STATUS is cleared.

Status of the transmitter can be monitored by calling the ARM_USART_GetStatus and checking the tx_busy flag which indicates if transmission is still in progress.

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 ARM_USART_EVENT_TX_UNDERFLOW event is generated.

Send operation can be aborted by calling ARM_USART_Control with ARM_USART_ABORT_SEND as the control parameter.

◆ ARM_USART_Receive()

int32_t ARM_USART_Receive	(	void *	data,
		uint32_t	num
	)

Start receiving data from USART receiver.

Parameters

[out]	data	Pointer to buffer for data to receive from USART receiver
[in]	num	Number of data items to receive

Returns: Status Error Codes

This functions ARM_USART_Receive is used in asynchronous mode to receive data from the USART receiver. It can also be used in synchronous mode when receiving data only (transmits the default value as specified by ARM_USART_Control with ARM_USART_SET_DEFAULT_TX_VALUE as control parameter).

Receiver needs to be enabled by calling ARM_USART_Control with ARM_USART_CONTROL_RX as the control parameter and 1 as argument.

The function parameters specify the buffer for data and the number of items to receive. The item size is defined by the data type which depends on the configured number of data bits.

Data type is:

uint8_t when configured for 5..8 data bits
uint16_t when configured for 9 data bits

Calling the function ARM_USART_Receive only starts the receive operation. 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). When in synchronous slave mode the operation is only registered and started when the master starts the transfer. 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. When receive operation is completed (requested number of items received) the ARM_USART_EVENT_RECEIVE_COMPLETE event is generated. Progress of receive operation can also be monitored by reading the number of items already received by calling ARM_USART_GetRxCount.

Status of the receiver can be monitored by calling the ARM_USART_GetStatus and checking the rx_busy flag which indicates if reception is still in progress.

During reception the following events can be generated (in asynchronous mode):

ARM_USART_EVENT_RX_TIMEOUT : Receive timeout between consecutive characters detected (optional)
ARM_USART_EVENT_RX_BREAK : Break detected (Framing error is not generated for Break condition)
ARM_USART_EVENT_RX_FRAMING_ERROR : Framing error detected
ARM_USART_EVENT_RX_PARITY_ERROR : Parity error detected
ARM_USART_EVENT_RX_OVERFLOW : Data overflow detected (also in synchronous slave mode)

ARM_USART_EVENT_RX_OVERFLOW event is also generated when receiver is enabled but data is lost because receive operation in asynchronous mode or receive/send/transfer operation in synchronous slave mode has not been started.

Receive operation can be aborted by calling ARM_USART_Control with ARM_USART_ABORT_RECEIVE as the control parameter.

◆ ARM_USART_Transfer()

int32_t ARM_USART_Transfer	(	const void *	data_out,
		void *	data_in,
		uint32_t	num
	)

Start sending/receiving data to/from USART transmitter/receiver.

Parameters

[in]	data_out	Pointer to buffer with data to send to USART transmitter
[out]	data_in	Pointer to buffer for data to receive from USART receiver
[in]	num	Number of data items to transfer

Returns: Status Error Codes

This functions 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.

Transmitter needs to be enabled by calling ARM_USART_Control with ARM_USART_CONTROL_TX as the control parameter and 1 as argument. Receiver needs to be enabled by calling ARM_USART_Control with ARM_USART_CONTROL_RX as the control parameter and 1 as argument.

The function parameters specify the buffer with data to send, the buffer for data to receive and the number of items to transfer. The item size is defined by the data type which depends on the configured number of data bits.

Data type is:

uint8_t when configured for 5..8 data bits
uint16_t when configured for 9 data bits

Calling the function ARM_USART_Transfer only starts the transfer operation. 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). When in synchronous slave mode the operation is only registered and started when the master starts the transfer. 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. When transfer operation is completed (requested number of items transferred) the ARM_USART_EVENT_TRANSFER_COMPLETE event is generated. Progress of transfer operation can also be monitored by reading the number of items already transferred by calling ARM_USART_GetTxCount or ARM_USART_GetRxCount.

Status of the transmitter or receiver can be monitored by calling the ARM_USART_GetStatus and checking the tx_busy or rx_busy flag.

When in synchronous slave mode also the following events can be generated:

ARM_USART_EVENT_TX_UNDERFLOW : transmitter is enabled but transfer operation is not started and data is requested by the master
ARM_USART_EVENT_RX_OVERFLOW : data lost during transfer or because receiver is enabled but transfer operation has not been started

Transfer operation can also be aborted by calling ARM_USART_Control with ARM_USART_ABORT_TRANSFER as the control parameter.

◆ ARM_USART_GetTxCount()

uint32_t ARM_USART_GetTxCount ( void )

Get transmitted data count.

Returns: number of data items transmitted

The function ARM_USART_GetTxCount returns the number of the currently transmitted data items during ARM_USART_Send and ARM_USART_Transfer operation.

◆ ARM_USART_GetRxCount()

uint32_t ARM_USART_GetRxCount ( void )

Get received data count.

Returns: number of data items received

The function ARM_USART_GetRxCount returns the number of the currently received data items during ARM_USART_Receive and ARM_USART_Transfer operation.

◆ ARM_USART_Control()

int32_t ARM_USART_Control	(	uint32_t	control,
		uint32_t	arg
	)

Control USART Interface.

Parameters

[in]	control	Operation
[in]	arg	Argument of operation (optional)

Returns: common Status Error Codes and driver specific USART Status Error Codes

The function ARM_USART_Control control the USART interface settings and execute various operations.

The parameter control sets the operation and is explained in the table below. Values from different categories can be ORed with the exception of Miscellaneous Operations.

The parameter arg provides, depending on the operation, additional information, for example the baudrate.

The table lists the available control operations.

Parameter control	Bit	Category	Description
ARM_USART_MODE_ASYNCHRONOUS	0..7	Operation Mode	Set to asynchronous UART mode. arg specifies baudrate.
ARM_USART_MODE_SYNCHRONOUS_MASTER			Set to synchronous master mode with clock signal generation. arg specifies baudrate.
ARM_USART_MODE_SYNCHRONOUS_SLAVE			Set to synchronous slave mode with external clock signal.
ARM_USART_MODE_SINGLE_WIRE			Set to single-wire (half-duplex) mode. arg specifies baudrate.
ARM_USART_MODE_IRDA			Set to Infra-red data mode. arg specifies baudrate.
ARM_USART_MODE_SMART_CARD			Set to Smart Card mode. arg specifies baudrate.
ARM_USART_DATA_BITS_5	8..11	Data Bits	Set to 5 data bits
ARM_USART_DATA_BITS_6			Set to 6 data bits
ARM_USART_DATA_BITS_7			Set to 7 data bits
ARM_USART_DATA_BITS_8			Set to 8 data bits (default)
ARM_USART_DATA_BITS_9			Set to 9 data bits
ARM_USART_PARITY_EVEN	12..13	Parity Bit	Set to Even Parity
ARM_USART_PARITY_NONE			Set to No Parity (default)
ARM_USART_PARITY_ODD			Set to Odd Parity
ARM_USART_STOP_BITS_1	14..15	Stop Bit	Set to 1 Stop bit (default)
ARM_USART_STOP_BITS_2			Set to 2 Stop bits
ARM_USART_STOP_BITS_1_5			Set to 1.5 Stop bits
ARM_USART_STOP_BITS_0_5			Set to 0.5 Stop bits
ARM_USART_FLOW_CONTROL_NONE	16..17	Flow Control	No flow control signal (default)
ARM_USART_FLOW_CONTROL_CTS			Set to use the CTS flow control signal
ARM_USART_FLOW_CONTROL_RTS			Set to use the RTS flow control signal
ARM_USART_FLOW_CONTROL_RTS_CTS			Set to use the RTS and CTS flow control signal
ARM_USART_CPOL0	18	Clock Polarity	CPOL=0 (default) : data are captured on rising edge (low->high transition)
ARM_USART_CPOL1	18	Clock Polarity	CPOL=1 : data are captured on falling edge (high->low transition)
ARM_USART_CPHA0	19	Clock Phase	CPHA=0 (default) : sample on first (leading) edge
ARM_USART_CPHA1	19	Clock Phase	CPHA=1 : sample on second (trailing) edge
ARM_USART_ABORT_RECEIVE	0..19	Miscellaneous Operations (cannot be ORed)	Abort receive operation (see also: ARM_USART_Receive)
ARM_USART_ABORT_SEND			Abort send operation (see also: ARM_USART_Send)
ARM_USART_ABORT_TRANSFER			Abort transfer operation (see also: ARM_USART_Transfer)
ARM_USART_CONTROL_BREAK			Enable or disable continuous Break transmission; arg : 0=disabled; 1=enabled
ARM_USART_CONTROL_RX			Enable or disable receiver; arg : 0=disabled; 1=enabled (see also: ARM_USART_Receive; ARM_USART_Transfer)
ARM_USART_CONTROL_SMART_CARD_NACK			Enable or disable Smart Card NACK generation; arg : 0=disabled; 1=enabled
ARM_USART_CONTROL_TX			Enable or disable transmitter; arg : 0=disabled; 1=enabled (see also: ARM_USART_Send; ARM_USART_Transfer)
ARM_USART_SET_DEFAULT_TX_VALUE			Set the default transmit value (synchronous receive only); arg specifies the value. (see also: ARM_USART_Receive)
ARM_USART_SET_IRDA_PULSE			Set the IrDA pulse value in ns; arg : 0=3/16 of bit period
ARM_USART_SET_SMART_CARD_CLOCK			Set the Smart Card Clock in Hz; arg : 0=Clock not set
ARM_USART_SET_SMART_CARD_GUARD_TIME			Set the Smart Card guard time; arg = number of bit periods

Example

extern ARM_DRIVER_USART Driver_USART0;
 
// configure to UART mode: 8 bits, no parity, 1 stop bit, no flow control, 9600 bps
status = Driver_USART0.Control(ARM_USART_MODE_ASYNCHRONOUS | 
                               ARM_USART_DATA_BITS_8 | 
                               ARM_USART_PARITY_NONE | 
                               ARM_USART_STOP_BITS_1 | 
                               ARM_USART_FLOW_CONTROL_NONE, 9600);
 
// identical with above settings (default settings removed)
// configure to UART mode: 8 bits, no parity, 1 stop bit, flow control, 9600 bps
status = Driver_USART0.Control(ARM_USART_MODE_ASYNCHRONOUS, 9600);
 
// enable TX output
status = Driver_USART0.Control(ARM_USART_CONTROL_TX, 1);
 
// disable RX output
status = Driver_USART0.Control(ARM_USART_CONTROL_RX, 0);

◆ ARM_USART_GetStatus()

ARM_USART_STATUS ARM_USART_GetStatus ( void )

Get USART status.

Returns: USART status ARM_USART_STATUS

The function ARM_USART_GetStatus retrieves the current USART interface status.

◆ ARM_USART_SetModemControl()

int32_t ARM_USART_SetModemControl ( ARM_USART_MODEM_CONTROL control )

Set USART Modem Control line state.

Parameters

[in] control ARM_USART_MODEM_CONTROL

Returns: Status Error Codes

The function ARM_USART_SetModemControl activates or deactivates the selected USART modem control line.

The function ARM_USART_GetModemStatus returns information about status of the modem lines.

◆ ARM_USART_GetModemStatus()

ARM_USART_MODEM_STATUS ARM_USART_GetModemStatus ( void )

Get USART Modem Status lines state.

Returns: modem status ARM_USART_MODEM_STATUS

The function ARM_USART_GetModemStatus returns the current USART Modem Status lines state.

The function ARM_USART_SetModemControl sets the modem control lines of the USART.

◆ ARM_USART_SignalEvent()

void ARM_USART_SignalEvent ( uint32_t event )

Signal USART Events.

Parameters

[in] event USART Events notification mask

The function ARM_USART_SignalEvent is a callback function registered by the function ARM_USART_Initialize.

The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.

Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the data fields of the structure ARM_USART_CAPABILITIES, which can be retrieved with the function ARM_USART_GetCapabilities.

The following events can be generated:

Parameter event	Bit	Description	supported when ARM_USART_CAPABILITIES
ARM_USART_EVENT_SEND_COMPLETE	0	Occurs after call to ARM_USART_Send to indicate that all the data to be sent was processed by the driver. All the data might have been already transmitted or parts of it are still queued in transmit buffers. The driver is ready for the next call to ARM_USART_Send; however USART may still transmit data.	always supported
ARM_USART_EVENT_RECEIVE_COMPLETE	1	Occurs after call to ARM_USART_Receive to indicate that all the data has been received. The driver is ready for the next call to ARM_USART_Receive.	always supported
ARM_USART_EVENT_TRANSFER_COMPLETE	2	Occurs after call to ARM_USART_Transfer to indicate that all the data has been transferred. The driver is ready for the next call to ARM_USART_Transfer.	always supported
ARM_USART_EVENT_TX_COMPLETE	3	Occurs after call to ARM_USART_Send to indicate that all the data has been physically transmitted on the wires.	data field event_tx_complete = 1
ARM_USART_EVENT_TX_UNDERFLOW	4	Occurs in synchronous slave mode when data is requested by the master but send/receive/transfer operation has not been started. Data field rx_underflow = 1 of ARM_USART_STATUS.	always supported
ARM_USART_EVENT_RX_OVERFLOW	5	Occurs when data is lost during receive/transfer operation or when data is lost because receive operation in asynchronous mode or receive/send/transfer operation in synchronous slave mode has not been started. Data field rx_overflow = 1 of ARM_USART_STATUS.	always supported
ARM_USART_EVENT_RX_TIMEOUT	6	Occurs during receive when idle time is detected between consecutive characters (idle time is hardware dependent).	data field event_rx_timeout = 1
ARM_USART_EVENT_RX_BREAK	7	Occurs when break is detected during receive. Data field rx_break = 1 of ARM_USART_STATUS.	always supported
ARM_USART_EVENT_RX_FRAMING_ERROR	8	Occurs when framing error is detected during receive. Data field rx_framing_error = 1 of ARM_USART_STATUS.	always supported
ARM_USART_EVENT_RX_PARITY_ERROR	9	Occurs when parity error is detected during receive. Data field rx_parity_error = 1 of ARM_USART_STATUS.	always supported
ARM_USART_EVENT_CTS	10	Indicates that CTS modem line state has changed. Data field cts of ARM_USART_MODEM_STATUS has changed.	data field event_cts = 1 and data field cts = 1
ARM_USART_EVENT_DSR	11	Indicates that DSR modem line state has changed. Data field dsr of ARM_USART_MODEM_STATUS has changed.	data field event_dsr = 1 and data field dsr = 1
ARM_USART_EVENT_DCD	12	Indicates that DCD modem line state has changed. Data field dcd of ARM_USART_MODEM_STATUS has changed.	data field event_dcd = 1 and data field dcd = 1
ARM_USART_EVENT_RI	13	Indicates that RI modem line state has changed from active to inactive (trailing edge on RI). Data field ri of ARM_USART_MODEM_STATUS has changed from 1 to 0.	data field event_ri = 1 and data field ri = 1

Content

Data Structures

Typedefs

Enumerations

Functions

Description

Data Structure Documentation

◆ ARM_DRIVER_USART

Data Fields

Field Documentation

◆ GetVersion

◆ GetCapabilities

◆ Initialize

◆ Uninitialize

◆ PowerControl

◆ Send

◆ Receive

◆ Transfer

◆ GetTxCount

◆ GetRxCount

◆ Control

◆ GetStatus

◆ SetModemControl

◆ GetModemStatus

◆ ARM_USART_CAPABILITIES

◆ ARM_USART_STATUS

◆ ARM_USART_MODEM_STATUS

Typedef Documentation

◆ ARM_USART_SignalEvent_t

Enumeration Type Documentation

◆ ARM_USART_MODEM_CONTROL

Function Documentation

◆ ARM_USART_GetVersion()

◆ ARM_USART_GetCapabilities()

◆ ARM_USART_Initialize()

◆ ARM_USART_Uninitialize()

◆ ARM_USART_PowerControl()

◆ ARM_USART_Send()

◆ ARM_USART_Receive()

◆ ARM_USART_Transfer()

◆ ARM_USART_GetTxCount()

◆ ARM_USART_GetRxCount()

◆ ARM_USART_Control()

◆ ARM_USART_GetStatus()

◆ ARM_USART_SetModemControl()

◆ ARM_USART_GetModemStatus()

◆ ARM_USART_SignalEvent()