diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/modules/nrfx/drivers/include/nrfx_i2s.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/modules/nrfx/drivers/include/nrfx_i2s.h | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/modules/nrfx/drivers/include/nrfx_i2s.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/modules/nrfx/drivers/include/nrfx_i2s.h new file mode 100644 index 0000000..f64fa21 --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/modules/nrfx/drivers/include/nrfx_i2s.h @@ -0,0 +1,254 @@ +/** + * Copyright (c) 2015 - 2018, 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. + * + */ + +#ifndef NRFX_I2S_H__ +#define NRFX_I2S_H__ + +#include <nrfx.h> +#include <hal/nrf_i2s.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup nrfx_i2s I2S driver + * @{ + * @ingroup nrf_i2s + * @brief Inter-IC Sound (I2S) peripheral driver. + */ + + +/** + * @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 NRFX_I2S_PIN_NOT_USED 0xFF + +/** @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 NRFX_I2S_PIN_NOT_USED + * if this signal is not needed. */ + uint8_t sdout_pin; ///< SDOUT pin number. + /**< Optional. Use @ref NRFX_I2S_PIN_NOT_USED + * if this signal is not needed. */ + uint8_t sdin_pin; ///< SDIN pin number. + /**< Optional. Use @ref NRFX_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. +} nrfx_i2s_config_t; + +/** @brief I2S driver buffers structure. */ +typedef struct +{ + uint32_t * p_rx_buffer; + uint32_t const * p_tx_buffer; +} nrfx_i2s_buffers_t; + +/** + * @brief I2S driver default configuration. + */ +#define NRFX_I2S_DEFAULT_CONFIG \ +{ \ + .sck_pin = NRFX_I2S_CONFIG_SCK_PIN, \ + .lrck_pin = NRFX_I2S_CONFIG_LRCK_PIN, \ + .mck_pin = NRFX_I2S_CONFIG_MCK_PIN, \ + .sdout_pin = NRFX_I2S_CONFIG_SDOUT_PIN, \ + .sdin_pin = NRFX_I2S_CONFIG_SDIN_PIN, \ + .irq_priority = NRFX_I2S_CONFIG_IRQ_PRIORITY, \ + .mode = (nrf_i2s_mode_t)NRFX_I2S_CONFIG_MASTER, \ + .format = (nrf_i2s_format_t)NRFX_I2S_CONFIG_FORMAT, \ + .alignment = (nrf_i2s_align_t)NRFX_I2S_CONFIG_ALIGN, \ + .sample_width = (nrf_i2s_swidth_t)NRFX_I2S_CONFIG_SWIDTH, \ + .channels = (nrf_i2s_channels_t)NRFX_I2S_CONFIG_CHANNELS, \ + .mck_setup = (nrf_i2s_mck_t)NRFX_I2S_CONFIG_MCK_SETUP, \ + .ratio = (nrf_i2s_ratio_t)NRFX_I2S_CONFIG_RATIO, \ +} + + +#define NRFX_I2S_STATUS_NEXT_BUFFERS_NEEDED (1UL << 0) + /**< The application should provide buffers that are to be used in the next + * part of the transfer. A call to @ref nrfx_i2s_next_buffers_set should + * be done before the currently used buffers are completely processed + * (i.e. the time remaining for supplying the next buffers depends on + * the used size of the buffers). */ + +/** + * @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 it finishes using + * buffers passed to it by the application, and when it needs to be provided + * with buffers for the next part of the transfer. + * + * @note The @c p_released pointer passed to this function is temporary and + * will be invalid after the function returns, hence it cannot be stored + * and used later. If needed, the pointed content (i.e. buffers pointers) + * should be copied instead. + * + * @param[in] p_released Pointer to a structure with pointers to buffers + * passed previously to the driver that will no longer + * be access by it (they can be now safely released or + * used for another purpose, in particular for a next + * part of the transfer). + * This pointer will be NULL if the application did not + * supply the buffers for the next part of the transfer + * (via a call to @ref nrfx_i2s_next_buffers_set) since + * the previous time the data handler signaled such need. + * This means that data corruption occurred (the previous + * buffers are used for the second time) and no buffers + * can be released at the moment. + * Both pointers in this structure are NULL when the + * handler is called for the first time after a transfer + * is started, because no data has been transferred yet + * at this point. In all successive calls the pointers + * specify what has been sent (TX) and what has been + * received (RX) in the part of transfer that has just + * been completed (provided that a given direction is + * enabled, see @ref nrfx_i2s_start). + * @param[in] status Bit field describing the current status of the transfer. + * It can be 0 or a combination of the following flags: + * - @ref NRFX_I2S_STATUS_NEXT_BUFFERS_NEEDED + */ +typedef void (* nrfx_i2s_data_handler_t)(nrfx_i2s_buffers_t const * p_released, + uint32_t status); + + +/** + * @brief Function for initializing the I2S driver. + * + * @param[in] p_config Pointer to the structure with initial configuration. + * @param[in] handler Data handler provided by the user. Must not be NULL. + * + * @retval NRFX_SUCCESS If initialization was successful. + * @retval NRFX_ERROR_INVALID_STATE If the driver was already initialized. + * @retval NRFX_ERROR_INVALID_PARAM If the requested combination of configuration + * options is not allowed by the I2S peripheral. + */ +nrfx_err_t nrfx_i2s_init(nrfx_i2s_config_t const * p_config, + nrfx_i2s_data_handler_t handler); + +/** @brief Function for uninitializing the I2S driver. */ +void nrfx_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. + * + * @note Peripherals using EasyDMA (including 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 NRFX_ERROR_INVALID_ADDR. + * + * @param[in] p_initial_buffers Pointer to a structure specifying the buffers + * to be used in the initial part of the transfer + * (buffers for all consecutive parts are provided + * through the data handler). + * @param[in] buffer_size Size of the buffers (in 32-bit words). + * Must not be 0. + * @param[in] flags Transfer options (0 for default settings). + * Currently, no additional flags are available. + * + * @retval NRFX_SUCCESS If the operation was successful. + * @retval NRFX_ERROR_INVALID_STATE If a transfer was already started or + * the driver has not been initialized. + * @retval NRFX_ERROR_INVALID_ADDR If the provided buffers are not placed + * in the Data RAM region. + */ +nrfx_err_t nrfx_i2s_start(nrfx_i2s_buffers_t const * p_initial_buffers, + uint16_t buffer_size, + uint8_t flags); + +/** + * @brief Function for supplying the buffers to be used in the next part of + * the transfer. + * + * The application should call this function when the data handler receives + * @ref NRFX_I2S_STATUS_NEXT_BUFFERS_NEEDED in the @c status parameter. + * The call can be done immediately from the data handler function or later, + * but it has to be done before the I2S peripheral finishes processing the + * buffers supplied previously. Otherwise, data corruption will occur. + * + * @sa nrfx_i2s_data_handler_t + * + * @retval NRFX_SUCCESS If the operation was successful. + * @retval NRFX_ERROR_INVALID_STATE If the buffers were already supplied or + * the peripheral is currently being stopped. + */ +nrfx_err_t nrfx_i2s_next_buffers_set(nrfx_i2s_buffers_t const * p_buffers); + +/** @brief Function for stopping the I2S transfer. */ +void nrfx_i2s_stop(void); + +/** @} */ + + +void nrfx_i2s_irq_handler(void); + + +#ifdef __cplusplus +} +#endif + +#endif // NRFX_I2S_H__ |