| /****************************************************************************** |
| * Filename: i2s_doc.h |
| * Revised: $$ |
| * Revision: $$ |
| * |
| * Copyright (c) 2015 - 2017, Texas Instruments Incorporated |
| * 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 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 the ORGANIZATION nor the names of its contributors may |
| * be used to endorse or promote products derived from this software without |
| * specific prior written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 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. |
| * |
| ******************************************************************************/ |
| //! \addtogroup i2s_api |
| //! @{ |
| //! \section sec_i2s Introduction |
| //! |
| //! The I2S API provides a set of functions for using the I2S module. |
| //! This module provides a standardized serial interface to transfer |
| //! audio samples from and to external audio devices such as a codec, |
| //! DAC, or ADC. |
| //! |
| //! The I2S module has the following features: |
| //! - Audio clock signals are internally generated by the PRCM module |
| //! or externally by another device. |
| //! - One or two data pins, which can be configured independently as |
| //! input or output |
| //! - Various data formats according to the settings of the module |
| //! - Up to two channels per data pin for dual phase formats and up |
| //! to eight channels per data pin for single phase formats |
| //! - DMA with double-buffered pointers |
| //! - Error detection for DMA and audio clock signal integrity |
| //! - A Samplestamp generator that allows maintaining of constant |
| //! audio latency |
| //! |
| //! The I2S module is configured through the functions \ref I2SFormatConfigure(), |
| //! \ref I2SFrameConfigure() and \ref I2SWclkConfigure(). |
| //! Transfers are enabled using \ref I2SStart(). Transfers are disabled using |
| //! \ref I2SStop(). Please note that a specific procedure exists in order |
| //! to disable transfers without losing data (refer to \ref I2SStop()). |
| //! |
| //! Data are transmitted using the two double-buffered pointers. |
| //! For each interface, two registers are set with the address of the data to |
| //! transfer. These registers are named INPTR and INPTRNEXT for the input |
| //! interface and OUTPTR and OUTPTRNEXT for the output. When PTR is consumed, |
| //! the hardware copies the content of PTRNEXT into PTR and the next transfer |
| //! begins. |
| //! The address of the next value to write or to read in memory (i.e. to receive |
| //! or to send out) is set using \ref I2SInPointerSet() and \ref I2SOutPointerSet(). |
| //! The values contented by INPTRNEXT, OUTPTRNEXT, INPTR and OUTPTR can be read using |
| //! \ref I2SInPointerNextGet(), \ref I2SOutPointerNextGet(), \ref I2SInPointerGet() and |
| //! \ref I2SOutPointerGet() functions. |
| //! |
| //! Interrupts can help the user to refresh pointers on time. Interrupts can also |
| //! be used to detect I2S errors. \ref I2SIntEnable() and \ref I2SIntDisable() |
| //! activate and deactivate interrupt(s). Interrupt status can be read through |
| //! \ref I2SIntStatus() and a pending interrupt can be acquitted by |
| //! \ref I2SIntClear() function. |
| //! |
| //! The sample stamps generator can be configured to slightly delay the |
| //! emission or the reception of the data (based on the number of WCLK |
| //! cycles) using \ref I2SSampleStampInConfigure(), \ref I2SSampleStampOutConfigure(), |
| //! \ref I2SWclkCounterReset() and \ref I2SWclkCounterConfigure(). The current sample stamp |
| //! can be computed using \ref I2SSampleStampGet(). |
| //! To finish, the sample stamps generator can be enable and disable using |
| //! the following functions: \ref I2SSampleStampEnable() and |
| //! \ref I2SSampleStampDisable(). |
| //! The sample stamps generator must be enabled prior to any transfer. |
| //! |
| //! Note: Other functions contained in the PRCM API are required to handle I2S. |
| //! |
| //! \section sec_i2s_api API |
| //! |
| //! Two APIs are coexisting. |
| //! It is recommended to only use the new API as the old one is deprecated and |
| //! will be removed soon. |
| //! |
| //! New API: |
| //! Functions to perform I2S configuration: |
| //! - \ref I2SStart() |
| //! - \ref I2SStop() |
| //! - \ref I2SFormatConfigure() |
| //! - \ref I2SFrameConfigure() |
| //! - \ref I2SWclkConfigure() |
| //! |
| //! Functions to perform transfers: |
| //! - \ref I2SInPointerSet() |
| //! - \ref I2SOutPointerSet() |
| //! - \ref I2SInPointerGet() |
| //! - \ref I2SOutPointerGet() |
| //! - \ref I2SInPointerNextGet() |
| //! - \ref I2SOutPointerNextGet() |
| //! |
| //! Functions to handle interruptions: |
| //! - \ref I2SIntEnable() |
| //! - \ref I2SIntDisable() |
| //! - \ref I2SIntStatus() |
| //! - \ref I2SIntClear() |
| //! |
| //! Functions to handle sample stamps |
| //! - \ref I2SSampleStampEnable() |
| //! - \ref I2SSampleStampDisable() |
| //! - \ref I2SSampleStampInConfigure() |
| //! - \ref I2SSampleStampOutConfigure() |
| //! - \ref I2SSampleStampGet() |
| //! - \ref I2SWclkCounterConfigure() |
| //! - \ref I2SWclkCounterReset() |
| //! |
| //! Old API: |
| //! \ref I2SEnable(), \ref I2SDisable(), \ref I2SAudioFormatConfigure(), |
| //! \ref I2SChannelConfigure(), \ref I2SClockConfigure(), |
| //! \ref I2SBufferConfig(), \ref I2SIntEnable(), \ref I2SIntDisable(), |
| //! \ref I2SIntStatus(), \ref I2SIntClear(), \ref I2SSampleStampEnable(), |
| //! \ref I2SSampleStampDisable(), \ref I2SSampleStampGet(), |
| //! \ref I2SPointerSet (), \ref I2SPointerUpdate(), |
| //! \ref I2SSampleStampConfigure(), \ref I2SIntRegister(), |
| //! \ref I2SIntUnregister() |
| //! |
| //! @} |