text: /**
   * Copyright (c) 2015 - 2019, 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; ///< Pointer to the buffer for received data.
      uint32_t const * p_tx_buffer; ///< Pointer to the buffer with data to be sent.
  } 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 must provide buffers that are to be used in the next
       *   part of the transfer. A call to @ref nrfx_i2s_next_buffers_set must
       *   be done before the currently used buffers are completely processed
       *   (that is, 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 the 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 (that is, buffers pointers)
   *       must 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 accessed 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 the initial configuration.
   * @param[in] handler  Data handler provided by the user. Must not be NULL.
   *
   * @retval NRFX_SUCCESS             Initialization was successful.
   * @retval NRFX_ERROR_INVALID_STATE The driver was already initialized.
   * @retval NRFX_ERROR_INVALID_PARAM 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
   * is to 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             The operation was successful.
   * @retval NRFX_ERROR_INVALID_STATE Transfer was already started or
   *                                  the driver has not been initialized.
   * @retval NRFX_ERROR_INVALID_ADDR  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 must 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__
  
  