/** * Copyright (c) 2015 - 2017, Nordic Semiconductor ASA * * All rights reserved. * * Redistribution and use in source and binary forms, with or without modification, * are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, this * list of conditions and the following disclaimer. * * 2. Redistributions in binary form, except as embedded into a Nordic * Semiconductor ASA integrated circuit in a product or a software update for * such product, must reproduce the above copyright notice, this list of * conditions and the following disclaimer in the documentation and/or other * materials provided with the distribution. * * 3. Neither the name of Nordic Semiconductor ASA nor the names of its * contributors may be used to endorse or promote products derived from this * software without specific prior written permission. * * 4. This software, with or without modification, must only be used with a * Nordic Semiconductor ASA integrated circuit. * * 5. Any software provided in binary form under this license must not be reverse * engineered, decompiled, modified and/or disassembled. * * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */ /**@file * @addtogroup nrf_i2s I2S HAL and driver * @ingroup nrf_drivers * @brief @tagAPI52 Inter-IC Sound (I2S) interface APIs. * * @defgroup nrf_drv_i2s I2S driver * @{ * @ingroup nrf_i2s * @brief @tagAPI52 Inter-IC Sound (I2S) interface driver. */ #ifndef NRF_DRV_I2S_H__ #define NRF_DRV_I2S_H__ #include "nordic_common.h" #include "sdk_config.h" #include "nrf_i2s.h" #include "sdk_errors.h" #ifdef __cplusplus extern "C" { #endif /** * @brief 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_PIN_NOT_USED 0xFF /** * @brief 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 @ref nrf_drv_i2s_start to force a common call * to the @ref nrf_drv_i2s_data_handler_t "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. */ #define NRF_DRV_I2S_FLAG_SYNCHRONIZED_MODE 0x01 /** * @brief I2S driver configuration structure. */ typedef struct { uint8_t sck_pin; ///< SCK pin number. uint8_t lrck_pin; ///< LRCK pin number. uint8_t mck_pin; ///< MCK pin number. /**< Optional. Use @ref NRF_DRV_I2S_PIN_NOT_USED * if this signal is not needed. */ uint8_t sdout_pin; ///< SDOUT pin number. /**< Optional. Use @ref NRF_DRV_I2S_PIN_NOT_USED * if this signal is not needed. */ uint8_t sdin_pin; ///< SDIN pin number. /**< Optional. Use @ref NRF_DRV_I2S_PIN_NOT_USED * if this signal is not needed. */ uint8_t irq_priority; ///< Interrupt priority. nrf_i2s_mode_t mode; ///< Mode of operation. nrf_i2s_format_t format; ///< Frame format. nrf_i2s_align_t alignment; ///< Alignment of sample within a frame. nrf_i2s_swidth_t sample_width; ///< Sample width. nrf_i2s_channels_t channels; ///< Enabled channels. nrf_i2s_mck_t mck_setup; ///< Master clock setup. nrf_i2s_ratio_t ratio; ///< MCK/LRCK ratio. } nrf_drv_i2s_config_t; /** * @brief I2S driver default configuration. */ #define NRF_DRV_I2S_DEFAULT_CONFIG \ { \ .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, \ } /** * @brief 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 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 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. @ref NRF_DRV_I2S_FLAG_SYNCHRONIZED_MODE * "Synchronized mode" can be used to always combine these indications. * * @param[in] p_data_received Pointer to the buffer with received data, * or NULL if the handler is called to prepare * transmission only. * @param[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. * @param[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 @ref nrf_drv_i2s_start function. */ 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); /** * @brief Function for initializing the I2S driver. * * @param[in] p_config Pointer to the structure with initial configuration. * If NULL, the default configuration is used. * @param[in] handler Data handler provided by the user. Must not be NULL. * * @retval NRF_SUCCESS If initialization was successful. * @retval NRF_ERROR_INVALID_STATE If the driver was already initialized. * @retval NRF_ERROR_INVALID_PARAM If the requested combination of configuration * options is not allowed by the I2S peripheral. */ ret_code_t nrf_drv_i2s_init(nrf_drv_i2s_config_t const * p_config, nrf_drv_i2s_data_handler_t handler); /** * @brief Function for uninitializing the I2S driver. */ void nrf_drv_i2s_uninit(void); /** * @brief 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 @linkProductSpecification52. * * 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 @ref nrf_drv_i2s_data_handler_t * "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 @p buffer_size/2 data words are received or transmitted. * * Additional options are provided using the @p flags parameter: * - @ref 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. * * @param[in] p_rx_buffer Pointer to the receive buffer. * Pass NULL if reception is not required. * @param[in] p_tx_buffer Pointer to the transmit buffer. * Pass NULL if transmission is not required. * @param[in] buffer_size Size of the buffers (in 32-bit words). * The size must be an even number greater than 0. * @param[in] flags Transfer options (0 for default settings). * * @retval NRF_SUCCESS If the operation was successful. * @retval NRF_ERROR_INVALID_STATE If a transfer was already started or * the driver has not been initialized. * @retval NRF_ERROR_INVALID_ADDR If the provided buffers are not placed * in the Data RAM region. */ ret_code_t nrf_drv_i2s_start(uint32_t * p_rx_buffer, uint32_t * p_tx_buffer, uint16_t buffer_size, uint8_t flags); /** * @brief Function for stopping the I2S transfer. */ void nrf_drv_i2s_stop(void); #ifdef __cplusplus } #endif #endif // NRF_DRV_I2S_H__ /** @} */