CMSIS-Driver  Version 2.02
Peripheral Interface for Middleware and Application Code
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAI Interface

Driver API for Serial Audio Interface (Driver_SAI.h) More...

Content

 Status Error Codes
 Negative values indicate errors (SAI has specific codes in addition to common Status Error Codes).
 
 SAI Events
 The SAI driver generates call back events that are notified via the function ARM_SAI_SignalEvent.
 
 SAI Control Codes
 Many parameters of the SAI driver are configured using the ARM_SAI_Control function.
 

Data Structures

struct  ARM_DRIVER_SAI
 Access structure of the SAI Driver. More...
 
struct  ARM_SAI_CAPABILITIES
 SAI Driver Capabilities. More...
 
struct  ARM_SAI_STATUS
 SAI Status. More...
 

Typedefs

typedef void(* ARM_SAI_SignalEvent_t )(uint32_t event)
 Pointer to ARM_SAI_SignalEvent : Signal SAI Event.
 

Functions

ARM_DRIVER_VERSION ARM_SAI_GetVersion (void)
 Get driver version.
 
ARM_SAI_CAPABILITIES ARM_SAI_GetCapabilities (void)
 Get driver capabilities.
 
int32_t ARM_SAI_Initialize (ARM_SAI_SignalEvent_t cb_event)
 Initialize SAI Interface.
 
int32_t ARM_SAI_Uninitialize (void)
 De-initialize SAI Interface.
 
int32_t ARM_SAI_PowerControl (ARM_POWER_STATE state)
 Control SAI Interface Power.
 
int32_t ARM_SAI_Send (const void *data, uint32_t num)
 Start sending data to SAI transmitter.
 
int32_t ARM_SAI_Receive (void *data, uint32_t num)
 Start receiving data from SAI receiver.
 
uint32_t ARM_SAI_GetTxCount (void)
 Get transmitted data count.
 
uint32_t ARM_SAI_GetRxCount (void)
 Get received data count.
 
int32_t ARM_SAI_Control (uint32_t control, uint32_t arg1, uint32_t arg2)
 Control SAI Interface.
 
ARM_SAI_STATUS ARM_SAI_GetStatus (void)
 Get SAI status.
 
void ARM_SAI_SignalEvent (uint32_t event)
 Signal SAI Events.
 

Description

Driver API for Serial Audio Interface (Driver_SAI.h)

The Serial Audio Interface (SAI) implements a synchronous serial bus interface for connecting digital audio devices. It is by far the most common mechanism used to transfer two channels of audio data between devices within a system. SAI can transfer digital audio using various protocols: I2S, MSB/LSB justified, PCM, TDM, AC'97.

SAI Structure

 

SAI_Schematics.png
Simplified SAI Schematic

 

SAI API

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

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 Driver Functions


Data Structure Documentation

struct ARM_DRIVER_SAI

Access structure of the SAI Driver.

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

Each instance of an SAI 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_SAI0 is the name of the access struct of the first instance (no. 0).
  • Driver_SAI1 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_SAIn. 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_SAI_GetVersion : Get driver version.
 
ARM_SAI_CAPABILITIES(* GetCapabilities )(void)
 Pointer to ARM_SAI_GetCapabilities : Get driver capabilities.
 
int32_t(* Initialize )(ARM_SAI_SignalEvent_t cb_event)
 Pointer to ARM_SAI_Initialize : Initialize SAI Interface.
 
int32_t(* Uninitialize )(void)
 Pointer to ARM_SAI_Uninitialize : De-initialize SAI Interface.
 
int32_t(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_SAI_PowerControl : Control SAI Interface Power.
 
int32_t(* Send )(const void *data, uint32_t num)
 Pointer to ARM_SAI_Send : Start sending data to SAI Interface.
 
int32_t(* Receive )(void *data, uint32_t num)
 Pointer to ARM_SAI_Receive : Start receiving data from SAI Interface.
 
uint32_t(* GetTxCount )(void)
 Pointer to ARM_SAI_GetTxCount : Get transmitted data count.
 
uint32_t(* GetRxCount )(void)
 Pointer to ARM_SAI_GetRxCount : Get received data count.
 
int32_t(* Control )(uint32_t control, uint32_t arg1, uint32_t arg2)
 Pointer to ARM_SAI_Control : Control SAI Interface.
 
ARM_SAI_STATUS(* GetStatus )(void)
 Pointer to ARM_SAI_GetStatus : Get SAI status.
 

Field Documentation

int32_t(* Control)(uint32_t control, uint32_t arg1, uint32_t arg2)

Pointer to ARM_SAI_Control : Control SAI Interface.

ARM_SAI_CAPABILITIES(* GetCapabilities)(void)

Pointer to ARM_SAI_GetCapabilities : Get driver capabilities.

uint32_t(* GetRxCount)(void)

Pointer to ARM_SAI_GetRxCount : Get received data count.

ARM_SAI_STATUS(* GetStatus)(void)

Pointer to ARM_SAI_GetStatus : Get SAI status.

uint32_t(* GetTxCount)(void)

Pointer to ARM_SAI_GetTxCount : Get transmitted data count.

ARM_DRIVER_VERSION(* GetVersion)(void)

Pointer to ARM_SAI_GetVersion : Get driver version.

int32_t(* Initialize)(ARM_SAI_SignalEvent_t cb_event)

Pointer to ARM_SAI_Initialize : Initialize SAI Interface.

int32_t(* PowerControl)(ARM_POWER_STATE state)

Pointer to ARM_SAI_PowerControl : Control SAI Interface Power.

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

Pointer to ARM_SAI_Receive : Start receiving data from SAI Interface.

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

Pointer to ARM_SAI_Send : Start sending data to SAI Interface.

int32_t(* Uninitialize)(void)

Pointer to ARM_SAI_Uninitialize : De-initialize SAI Interface.

struct ARM_SAI_CAPABILITIES

SAI Driver Capabilities.

An SAI driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.

Returned by:

Data Fields
uint32_t asynchronous: 1 supports asynchronous Transmit/Receive
uint32_t companding: 1 supports Companding
uint32_t event_frame_error: 1 supports Frame error event: ARM_SAI_EVENT_FRAME_ERROR
uint32_t mclk_pin: 1 supports MCLK (Master Clock) pin
uint32_t mono_mode: 1 supports Mono mode
uint32_t protocol_ac97: 1 supports AC'97 Protocol
uint32_t protocol_i2s: 1 supports I2S Protocol
uint32_t protocol_justified: 1 supports MSB/LSB justified Protocol
uint32_t protocol_pcm: 1 supports PCM short/long frame Protocol
uint32_t protocol_user: 1 supports user defined Protocol
uint32_t synchronous: 1 supports synchronous Transmit/Receive
struct ARM_SAI_STATUS

SAI Status.

Structure with information about the status of the SAI. The bitfields encode busy flags and error flags.

Returned by:

Data Fields
uint32_t frame_error: 1 Sync Frame error detected (cleared on start of next send/receive operation)
uint32_t rx_busy: 1 Receiver busy flag.
uint32_t rx_overflow: 1 Receive data overflow detected (cleared on start of next receive operation)
uint32_t tx_busy: 1 Transmitter busy flag.
uint32_t tx_underflow: 1 Transmit data underflow detected (cleared on start of next send operation)

Typedef Documentation

ARM_SAI_SignalEvent_t

Pointer to ARM_SAI_SignalEvent : Signal SAI Event.

Provides the typedef for the callback function ARM_SAI_SignalEvent.

Parameter for:

Function Documentation

int32_t ARM_SAI_Control ( uint32_t  control,
uint32_t  arg1,
uint32_t  arg2 
)

Control SAI Interface.

Parameters
[in]controlOperation
[in]arg1Argument 1 of operation (optional)
[in]arg2Argument 2 of operation (optional)
Returns
common Status Error Codes and driver specific Status Error Codes

The function ARM_SAI_Control controls the SAI interface settings and executes various operations.

The parameter control specifies the operation (see table below).

Depending on the control, the parameters arg1 and arg2 provide additional information.

Example

extern ARM_DRIVER_SAI Driver_SAI0;
// configure Transmitter to Asynchronous Slave: I2S Protocol, 16-bit data, 16kHz Audio frequency
status = Driver_SAI0.Control(ARM_SAI_CONFIGURE_TX |
ARM_SAI_DATA_SIZE(16), 0, 16000);
// configure Receiver identical with above settings (default settings removed)
// configure Receiver to Asynchronous Slave: I2S Protocol, 16-bit data, 16kHz Audio frequency
status = Driver_SAI0.Control(ARM_SAI_CONFIGURE_RX | ARM_SAI_PROTOCOL_I2S, ARM_SAI_DATA_SIZE(16), 0, 16000);
// enable Transmitter
status = Driver_SAI0.Control(ARM_SAI_CONTROL_TX, 1);
// enable Receiver
status = Driver_SAI0.Control(ARM_SAI_CONTROL_RX, 1);

Controls execute various operations:

Controls Description
ARM_SAI_CONFIGURE_TX Configure transmitter (see below)
ARM_SAI_CONFIGURE_RX Configure receiver (see below)
ARM_SAI_CONTROL_TX Enable or disable transmitter and control mute; arg1.0 : 0=disabled; 1=enabled; arg1.1 : mute (see also: ARM_SAI_Send)
ARM_SAI_CONTROL_RX Enable or disable receiver; arg1.0 : 0=disabled; 1=enabled (see also: ARM_SAI_Receive)
ARM_SAI_MASK_SLOTS_TX Mask transmitter slots; arg1 = mask (bit: 0=active, 1=inactive); all configured slots are active by default
ARM_SAI_MASK_SLOTS_RX Mask receiver slots; arg1 = mask (bit: 0=active, 1=inactive); all configured slots are active by default
ARM_SAI_ABORT_SEND Abort send operation (see also: ARM_SAI_Send)
ARM_SAI_ABORT_RECEIVE Abort receive operation (see also: ARM_SAI_Receive)

Configuration parameters are combined with the ARM_SAI_CONFIGURE_x control:

  • ARM_SAI_MODE_xxx control bits specify the SAI mode.
Configuration parameters: Mode Description
ARM_SAI_MODE_MASTER Master mode. arg2 specifies audio frequency.
ARM_SAI_MODE_SLAVE Slave mode (default).
  • ARM_SAI_ASYNCHRONOUS and ARM_SAI_SYNCHRONOUS control bits specify the SAI synchronization.
Configuration parameters: Synchronization Description
ARM_SAI_ASYNCHRONOUS Asynchronous operation using own clock and sync signal (default).
ARM_SAI_SYNCHRONOUS Synchronous operation using clock and sync signal from other transmitter/receiver.
  • ARM_SAI_PROTOCOL_xxx control bits specify the SAI protocol.
Configuration parameters: Protocol Description
ARM_SAI_PROTOCOL_USER User defined protocol (default).
ARM_SAI_PROTOCOL_I2S I2S protocol.
ARM_SAI_PROTOCOL_MSB_JUSTIFIED MSB (left) justified protocol.
ARM_SAI_PROTOCOL_LSB_JUSTIFIED LSB (right) justified protocol.
ARM_SAI_PROTOCOL_PCM_SHORT PCM with short frame protocol.
ARM_SAI_PROTOCOL_PCM_LONG PCM with long frame protocol.
ARM_SAI_PROTOCOL_AC97 AC'97 protocol.
Configuration Parameters: Data Size Description
ARM_SAI_DATA_SIZE(n) Data size in bits; the possible range for n is 8..32.
  • ARM_SAI_MSB_FIRST and ARM_SAI_LSB_FIRST control bits specify the bit order.
Configuration parameters: Bit Order Description
ARM_SAI_MSB_FIRST Data is transferred with MSB first (default).
ARM_SAI_LSB_FIRST Data is transferred with LSB first (User protocol only, ignored otherwise).
  • ARM_SAI_MONO_MODE control bit specifies mono mode.
Configuration parameters: Mono Mode Description
ARM_SAI_MONO_MODE Mono Mode (only for I2S, MSB/LSB justified).
  • ARM_SAI_COMPANDING_xxx control bits specify the companding mode.
Configuration parameters: Companding Description
ARM_SAI_COMPANDING_NONE No companding (default).
ARM_SAI_COMPANDING_A_LAW A-Law companding (8-bit data).
ARM_SAI_COMPANDING_U_LAW u-Law companding (8-bit data).
  • ARM_SAI_CLOCK_POLARITY_xxx control bits specify the clock polarity.
Configuration parameters: Clock Polarity Description
ARM_SAI_CLOCK_POLARITY_0 Drive on falling edge, capture on rising edge (default).
ARM_SAI_CLOCK_POLARITY_1 Drive on rising edge, capture on falling edge.
  • ARM_SAI_MCLK_PIN_xxx control bits specify the Master Clock (MCLK) pin function.
Configuration parameters: MCLK Pin Description
ARM_SAI_MCLK_PIN_INACTIVE MCLK not used (default).
ARM_SAI_MCLK_PIN_OUTPUT MCLK is output (Master mode only).
ARM_SAI_MCLK_PIN_INPUT MCLK is input (Master mode only).

Configuration parameters specified in arg1:

Configuration Parameters: Frame Length Description
ARM_SAI_FRAME_LENGTH(n) Frame length in bits; the possible range for n is 8..1024; default depends on protocol and data.
Configuration Parameters: Frame Sync Width Description
ARM_SAI_FRAME_SYNC_WIDTH(n) Frame Sync width in bits; the possible range for n is 1..256; default=1; User protocol only, ignored otherwise.
  • ARM_SAI_FRAME_SYNC_POLARITY_xxx control bits specify the frame sync polarity.
Configuration parameters: Frame Sync Polarity Description
ARM_SAI_FRAME_SYNC_POLARITY_HIGH Frame Sync is active high (default).
ARM_SAI_FRAME_SYNC_POLARITY_LOW Frame Sync is active low (User protocol only, ignored otherwise).
  • ARM_SAI_FRAME_SYNC_EARLY control bit specifies early frame sync.
Configuration parameters: Frame Sync Early Description
ARM_SAI_FRAME_SYNC_EARLY Frame Sync one bit before the first bit of the frame (User protocol only, ignored otherwise).
Configuration Parameters: Slot Count Description
ARM_SAI_SLOT_COUNT(n) Number of slots in frame; the possible range for n is 1..32; default=1; User protocol only, ignored otherwise.
  • ARM_SAI_SLOT_SIZE_xxx control bits specify the slot size.
Configuration Parameters: Slot Size Description
ARM_SAI_SLOT_SIZE_DEFAULT Slot size is equal to data size (default).
ARM_SAI_SLOT_SIZE_16 Slot size is 16 bits (User protocol only, ignored otherwise).
ARM_SAI_SLOT_SIZE_32 Slot size is 32 bits (User protocol only, ignored otherwise).
Configuration Parameters: Slot Offset Description
ARM_SAI_SLOT_OFFSET(n) Offset of first data bit in slot; the possible range for n is 0..31; default=0; User protocol only, ignored otherwise.

Configuration parameters specified in arg2:

Configuration Parameters: MCLK Prescaler Description
ARM_SAI_MCLK_PRESCALER(n) MCLK prescaler; Audio_frequency = MCLK/n; the possible range for n is 1..4096; default=1.
ARM_USART_CAPABILITIES ARM_SAI_GetCapabilities ( void  )

Get driver capabilities.

Returns
ARM_SAI_CAPABILITIES

The function ARM_SAI_GetCapabilities retrieves information about the capabilities in this driver implementation. The bitfield members of the struct ARM_SAI_CAPABILITIES encode various capabilities, for example supported protocols, or if a hardware is capable to create signal events using the ARM_SAI_SignalEvent callback function.

Example:

extern ARM_DRIVER_SAI Driver_SAI0;
ARM_DRIVER_SAI *drv_info;
void read_capabilities (void) {
ARM_SAI_CAPABILITIES drv_capabilities;
drv_info = &Driver_SAI0;
drv_capabilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
uint32_t ARM_SAI_GetRxCount ( void  )

Get received data count.

Returns
number of data items received

The function ARM_SAI_GetRxCount returns the number of the currently received data items during an ARM_SAI_Receive operation.

ARM_SAI_STATUS ARM_SAI_GetStatus ( void  )

Get SAI status.

Returns
SAI status ARM_SAI_STATUS

The function ARM_SAI_GetStatus retrieves the current SAI interface status.

uint32_t ARM_SAI_GetTxCount ( void  )

Get transmitted data count.

Returns
number of data items transmitted

The function ARM_SAI_GetTxCount returns the number of the currently transmitted data items during an ARM_SAI_Send operation.

ARM_DRIVER_VERSION ARM_SAI_GetVersion ( void  )

Get driver version.

Returns
ARM_DRIVER_VERSION

The function ARM_SAI_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_SAI Driver_SAI0;
ARM_DRIVER_SAI *drv_info;
void setup_sai (void) {
drv_info = &Driver_SAI0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
int32_t ARM_SAI_Initialize ( ARM_SAI_SignalEvent_t  cb_event)

Initialize SAI Interface.

Parameters
[in]cb_eventPointer to ARM_SAI_SignalEvent
Returns
Status Error Codes

The function ARM_SAI_Initialize initializes the SAI interface. It is called when the middleware component starts operation.

The function performs the following operations:

  • Initializes the required resources of the SAI interface.
  • Registers the ARM_SAI_SignalEvent callback function.

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

int32_t ARM_SAI_PowerControl ( ARM_POWER_STATE  state)

Control SAI Interface Power.

Parameters
[in]statePower state
Returns
Status Error Codes

The function ARM_SAI_PowerControl allows you to control the power modes of the SAI interface.

int32_t ARM_SAI_Receive ( void *  data,
uint32_t  num 
)

Start receiving data from SAI receiver.

Parameters
[out]dataPointer to buffer for data to receive from SAI receiver
[in]numNumber of data items to receive
Returns
Status Error Codes

The function ARM_SAI_Receive is used to receive data from the SAI receiver. The function parameters specify the buffer for data and the number num 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 8 data bits
  • uint16_t when configured for 9..16 data bits
  • uint32_t when configured for 17..32 data bits

The receiver is enabled by calling ARM_SAI_Control with ARM_SAI_CONTROL_RX as the control parameter and 1 as an argument. This starts the receive engine which generates a clock and frame sync signal in master mode and receives data. In slave mode, clock and frame sync are generated by the external master.

Calling the function ARM_SAI_Receive only starts the receive operation. The function is non-blocking and returns as soon as the driver has started the operation (the driver typically configures DMA or the interrupt system for continuous transfer). During the operation, it is not allowed to call this function again. The data buffer must also stay allocated. When receive operation is completed (the requested number of items have been received), the ARM_SAI_EVENT_RECEIVE_COMPLETE event is generated. Progress of the receive operation can also be monitored by reading the number of items already received by calling ARM_SAI_GetRxCount.

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

When the receiver is enabled and data is received but the receive operation has not been started yet, then the ARM_SAI_EVENT_RX_OVERFLOW event is generated.

If an invalid synchronization frame is detected in slave mode, the ARM_SAI_EVENT_FRAME_ERROR event is generated (if supported and reported by event_frame_error in ARM_SAI_CAPABILITIES).

The receive operation can be aborted by calling ARM_SAI_Control with ARM_SAI_ABORT_RECEIVE as the control parameter.

int32_t ARM_SAI_Send ( const void *  data,
uint32_t  num 
)

Start sending data to SAI transmitter.

Parameters
[in]dataPointer to buffer with data to send to SAI transmitter
[in]numNumber of data items to send
Returns
Status Error Codes

The function ARM_SAI_Send sends data to the SAI transmitter.

The function parameters specify the buffer with data and the number num 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 8 data bits
  • uint16_t when configured for 9..16 data bits
  • uint32_t when configured for 17..32 data bits

Transmitter is enabled by calling ARM_SAI_Control with ARM_SAI_CONTROL_TX as the control parameter and 1 as an argument. This starts the transmit engine which generates a clock and frame sync signal in master mode and transmits the data. In slave mode, clock and frame sync are generated by the external master. When mute is active, data is discarded and zero values are transmitted.

Calling the function ARM_SAI_Send only starts the send operation. The function is non-blocking and returns as soon as the driver has started the operation (the driver typically configures DMA or the interrupt system for continuous transfer). During the operation it is not allowed to call this function again. Also, the data buffer must stay allocated and the contents of unsent data must not be modified. When the send operation is completed (requested number of items have been sent), the ARM_SAI_EVENT_SEND_COMPLETE event is generated. Progress of the send operation can be monitored by reading the number of already sent items by calling ARM_SAI_GetTxCount.

The status of the transmitter can also be monitored by calling the ARM_SAI_GetStatus and checking the tx_busy flag which indicates if a transmission is still in progress.

When the transmitter is enabled and data is to be sent but the send operation has not been started yet, then the ARM_SAI_EVENT_TX_UNDERFLOW event is generated.

If an invalid synchronization frame is detected in slave mode, then the ARM_SAI_EVENT_FRAME_ERROR event is generated (if supported and reported by event_frame_error in ARM_SAI_CAPABILITIES).

The send operation can be aborted by calling ARM_SAI_Control with ARM_SAI_ABORT_SEND as the control parameter.

void ARM_SAI_SignalEvent ( uint32_t  event)

Signal SAI Events.

Parameters
[in]eventSAI Events notification mask
Returns
none

The function ARM_SAI_SignalEvent notifies the application of the SAI Events and it is registered by the function ARM_SAI_Initialize. The function ARM_SAI_GetCapabilities returns information about the implemented optional events in a driver.

The parameter event represents the notification mask of the events. Each event is coded in a separate bit and therefore it is possible to signal multiple events in the event call back function. The following call back notifications are generated:

BitEvent Description
0 ARM_SAI_EVENT_SEND_COMPLETE Occurs after call to ARM_SAI_Send to indicate that all the data has been sent (or queued in transmit buffers). The driver is ready for the next call to ARM_SAI_Send.
1 ARM_SAI_EVENT_RECEIVE_COMPLETE Occurs after call to ARM_SAI_Receive to indicate that all the data has been received. The driver is ready for the next call to ARM_SAI_Receive.
2 ARM_SAI_EVENT_TX_UNDERFLOW Occurs when data is to be sent but send operation has not been started.
3 ARM_SAI_EVENT_RX_OVERFLOW Occurs when data is received but receive operation has not been started.
4 ARM_SAI_EVENT_FRAME_ERROR Occurs in slave mode when invalid synchronization frame is detected.
int32_t ARM_SAI_Uninitialize ( void  )

De-initialize SAI Interface.

Returns
Status Error Codes

The function ARM_SAI_Uninitialize de-initializes the resources of SAI interface.

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