![]() |
CMSIS-Driver
Version 2.02
Peripheral Interface for Middleware and Application Code
|
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. | |
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 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
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:
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. | |
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:
ARM_SAI_SignalEvent_t |
Pointer to ARM_SAI_SignalEvent : Signal SAI Event.
Provides the typedef for the callback function ARM_SAI_SignalEvent.
Parameter for:
int32_t ARM_SAI_Control | ( | uint32_t | control, |
uint32_t | arg1, | ||
uint32_t | arg2 | ||
) |
Control SAI Interface.
[in] | control | Operation |
[in] | arg1 | Argument 1 of operation (optional) |
[in] | arg2 | Argument 2 of operation (optional) |
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
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:
Configuration parameters: Mode | Description |
---|---|
ARM_SAI_MODE_MASTER | Master mode. arg2 specifies audio frequency. |
ARM_SAI_MODE_SLAVE | Slave mode (default). |
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. |
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. |
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). |
Configuration parameters: Mono Mode | Description |
---|---|
ARM_SAI_MONO_MODE | Mono Mode (only for I2S, MSB/LSB justified). |
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). |
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. |
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. |
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). |
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. |
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.
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:
uint32_t ARM_SAI_GetRxCount | ( | void | ) |
Get received data count.
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.
The function ARM_SAI_GetStatus retrieves the current SAI interface status.
uint32_t ARM_SAI_GetTxCount | ( | void | ) |
Get transmitted data count.
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.
The function ARM_SAI_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
int32_t ARM_SAI_Initialize | ( | ARM_SAI_SignalEvent_t | cb_event | ) |
Initialize SAI Interface.
[in] | cb_event | Pointer to ARM_SAI_SignalEvent |
The function ARM_SAI_Initialize initializes the SAI interface. It is called when the middleware component starts operation.
The function performs the following operations:
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.
[in] | state | Power state |
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.
[out] | data | Pointer to buffer for data to receive from SAI receiver |
[in] | num | Number of data items to receive |
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:
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.
[in] | data | Pointer to buffer with data to send to SAI transmitter |
[in] | num | Number of data items to send |
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:
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.
[in] | event | SAI Events notification mask |
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:
Bit | Event | 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.
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.