| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Functions
I2S driver
I2S HAL and driver

nRF52 only: Inter-IC Sound (I2S) interface driver. More...

## Modules
| I2S peripheral driver configuration

## Data Structures
struct | nrf_drv_i2s_config_t
| I2S driver configuration structure. More...

## Macros
#define | NRF_DRV_I2S_PIN_NOT_USED 0xFF
| This value can be provided instead of a pin number for the signals SDOUT, SDIN, and MCK to specify that a given signal is not used and therefore does not need to be connected to a pin.
#define | NRF_DRV_I2S_FLAG_SYNCHRONIZED_MODE 0x01
| Flag indicating that calls to the data handler for RX and TX should be synchronized, thus always combined into one call. More...
#define | NRF_DRV_I2S_DEFAULT_CONFIG
| I2S driver default configuration. More...

## Typedefs
typedef void(* | nrf_drv_i2s_data_handler_t )(uint32_t const *p_data_received, uint32_t *p_data_to_send, uint16_t number_of_words)
| I2S driver data handler type. More...

## Functions
ret_code_t | nrf_drv_i2s_init (nrf_drv_i2s_config_t const *p_config, nrf_drv_i2s_data_handler_t handler)
| Function for initializing the I2S driver. More...
void | nrf_drv_i2s_uninit (void)
| Function for uninitializing the I2S driver.
ret_code_t | nrf_drv_i2s_start (uint32_t *p_rx_buffer, uint32_t *p_tx_buffer, uint16_t buffer_size, uint8_t flags)
| Function for starting the continuous I2S transfer. More...
void | nrf_drv_i2s_stop (void)
| Function for stopping the I2S transfer.

## Detailed Description

nRF52 only: Inter-IC Sound (I2S) interface driver.

## Macro Definition Documentation

#define NRF_DRV_I2S_DEFAULT_CONFIG

Value:
{ \
.sck_pin = I2S_CONFIG_SCK_PIN, \
.lrck_pin = I2S_CONFIG_LRCK_PIN, \
.mck_pin = I2S_CONFIG_MCK_PIN, \
.sdout_pin = I2S_CONFIG_SDOUT_PIN, \
.sdin_pin = I2S_CONFIG_SDIN_PIN, \
.irq_priority = I2S_CONFIG_IRQ_PRIORITY, \
.mode = (nrf_i2s_mode_t)I2S_CONFIG_MASTER, \
.format = (nrf_i2s_format_t)I2S_CONFIG_FORMAT, \
.alignment = (nrf_i2s_align_t)I2S_CONFIG_ALIGN, \
.sample_width = (nrf_i2s_swidth_t)I2S_CONFIG_SWIDTH, \
.channels = (nrf_i2s_channels_t)I2S_CONFIG_CHANNELS, \
.mck_setup = (nrf_i2s_mck_t)I2S_CONFIG_MCK_SETUP, \
.ratio = (nrf_i2s_ratio_t)I2S_CONFIG_RATIO, \
}

I2S driver default configuration.

#define NRF_DRV_I2S_FLAG_SYNCHRONIZED_MODE 0x01

Flag indicating that calls to the data handler for RX and TX should be synchronized, thus always combined into one call.

Use this flag when calling nrf_drv_i2s_start to force a common call to the data handler for RX and TX data. This is useful, for example, when received data should be processed and then be sent back. Obviously, this flag is only applicable when both directions (RX and TX) are enabled.

## Typedef Documentation

typedef void(* nrf_drv_i2s_data_handler_t)(uint32_t const *p_data_received, uint32_t *p_data_to_send, uint16_t number_of_words)

I2S driver data handler type.

A data handling function of this type must be specified during initialization of the driver. The driver will call this function when a new portion of data is received or a new portion of data should be prepared for transmission. The first case is indicated by a non-NULL value in the `p_data_received` parameter (which points to the memory containing the received data). Similarly, the second case is indicated by a non-NULL value in the `p_data_to_send` parameter (which points to where the data to be transmitted should be placed).

Note
  The two cases mentioned above may be indicated separately or combined into one call (depending on the environment in which the driver is used). Therefore, both parameters should be checked and handled properly in every call. Synchronized mode can be used to always combine these indications.

Parameters

  [in] | p_data_received | Pointer to the buffer with received data, or NULL if the handler is called to prepare transmission only.
  [out] | p_data_to_send | Pointer to the buffer where data to be sent should be written, or NULL if the handler is called for received data only.
  [in] | number_of_words | Length of data received and/or to be written (in 32-bit words). This value is always equal to half the size of the buffers set by the call to the nrf_drv_i2s_start function.

## Function Documentation

ret_code_t nrf_drv_i2s_init | ( | nrf_drv_i2s_config_t const * | p_config,
|  | nrf_drv_i2s_data_handler_t | handler
| ) |  |

Function for initializing the I2S driver.

Parameters

  [in] | p_config | Pointer to the structure with initial configuration. If NULL, the default configuration is used.
  [in] | handler | Data handler provided by the user. Must not be NULL.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_INVALID_STATE | If the driver was already initialized.
  NRF_ERROR_INVALID_PARAM | If the requested combination of configuration options is not allowed by the I2S peripheral.

ret_code_t nrf_drv_i2s_start | ( | uint32_t * | p_rx_buffer,
|  | uint32_t * | p_tx_buffer,
|  | uint16_t | buffer_size,
|  | uint8_t | flags
| ) |  |

Function for starting the continuous I2S transfer.

The I2S data transfer can be performed in one of three modes: RX (reception) only, TX (transmission) only, or in both directions simultaneously. The mode is selected by specifying a proper buffer for a given direction in the call to this function or by passing NULL instead if this direction should be disabled.

The length of the buffer (which is a common value for RX and TX if both directions are enabled) is specified in 32-bit words. One 32-bit memory word can either contain four 8-bit samples, two 16-bit samples, or one right-aligned 24-bit sample sign-extended to a 32-bit value. For a detailed memory mapping for different supported configurations, see the Product Specification.

The provided buffers are logically divided into two parts of equal size. One of them is in use by the peripheral (for storing received data or for getting data to be transmitted, respectively). The other part is provided to the application via a call to the defined data handling function, so that the application can process the received data or prepare the next portion of data to be sent. The two parts are swapped every time `buffer_size/2` data words are received or transmitted.

Additional options are provided using the `flags` parameter:

- NRF_DRV_I2S_FLAG_SYNCHRONIZED_MODE - the calls to data handler should be done in a synchronized manner (one common call for TX and RX). Applicable only when both RX and TX are enabled.

Attention
  All data exchange is done in the data handler only. In particular, no data should be written to the transmit buffer before calling this function (a proper call to the data handler to get the first portion of data to be sent will be done before the actual transfer starts).

Note
  Peripherals using EasyDMA (like I2S) require the transfer buffers to be placed in the Data RAM region. If this condition is not met, this function will fail with the error code NRF_ERROR_INVALID_ADDR.

Parameters

  [in] | p_rx_buffer | Pointer to the receive buffer. Pass NULL if reception is not required.
  [in] | p_tx_buffer | Pointer to the transmit buffer. Pass NULL if transmission is not required.
  [in] | buffer_size | Size of the buffers (in 32-bit words). The size must be an even number greater than 0.
  [in] | flags | Transfer options (0 for default settings).

Return values

  NRF_SUCCESS | If the operation was successful.
  NRF_ERROR_INVALID_STATE | If a transfer was already started or the driver has not been initialized.
  NRF_ERROR_INVALID_ADDR | If the provided buffers are not placed in the Data RAM region.