1 /******************************************************************************
2 *  Filename:       i2s_doc.h
3 *
4 *  Copyright (c) 2015 - 2022, Texas Instruments Incorporated
5 *  All rights reserved.
6 *
7 *  Redistribution and use in source and binary forms, with or without
8 *  modification, are permitted provided that the following conditions are met:
9 *
10 *  1) Redistributions of source code must retain the above copyright notice,
11 *     this list of conditions and the following disclaimer.
12 *
13 *  2) Redistributions in binary form must reproduce the above copyright notice,
14 *     this list of conditions and the following disclaimer in the documentation
15 *     and/or other materials provided with the distribution.
16 *
17 *  3) Neither the name of the ORGANIZATION nor the names of its contributors may
18 *     be used to endorse or promote products derived from this software without
19 *     specific prior written permission.
20 *
21 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
25 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 *  POSSIBILITY OF SUCH DAMAGE.
32 *
33 ******************************************************************************/
34 //! \addtogroup i2s_api
35 //! @{
36 //! \section sec_i2s Introduction
37 //!
38 //! The I2S API provides a set of functions for using the I2S module.
39 //! This module provides a standardized serial interface to transfer
40 //! audio samples from and to external audio devices such as a codec,
41 //! DAC, or ADC.
42 //!
43 //! The I2S module has the following features:
44 //!  - Audio clock signals are internally generated by the PRCM module
45 //!    or externally by another device.
46 //!  - One or two data pins, which can be configured independently as
47 //!    input or output
48 //!  - Various data formats according to the settings of the module
49 //!  - Up to two channels per data pin for dual phase formats and up
50 //!    to eight channels per data pin for single phase formats
51 //!  - DMA with double-buffered pointers
52 //!  - Error detection for DMA and audio clock signal integrity
53 //!  - A Samplestamp generator that allows maintaining of constant
54 //!    audio latency
55 //!
56 //! The I2S module is configured through the functions \ref I2SFormatConfigure(),
57 //! \ref I2SFrameConfigure() and \ref I2SWclkConfigure().
58 //! Transfers are enabled using \ref I2SStart(). Transfers are disabled  using
59 //! \ref I2SStop(). Please note that a specific procedure exists in order
60 //! to disable transfers without losing data (refer to \ref I2SStop()).
61 //!
62 //! Data are transmitted using the two double-buffered pointers.
63 //! For each interface, two registers are set with the address of the data to
64 //! transfer. These registers are named INPTR and INPTRNEXT for the input
65 //! interface and OUTPTR and OUTPTRNEXT for the output. When PTR is consumed,
66 //! the hardware copies the content of PTRNEXT into PTR and the next transfer
67 //! begins.
68 //! The address of the next value to write or to read in memory (i.e. to receive
69 //! or to send out) is set using \ref I2SInPointerSet() and \ref I2SOutPointerSet().
70 //! The values contented by INPTRNEXT, OUTPTRNEXT, INPTR and OUTPTR can be read using
71 //! \ref I2SInPointerNextGet(), \ref I2SOutPointerNextGet(), \ref I2SInPointerGet() and
72 //! \ref I2SOutPointerGet() functions.
73 //!
74 //! Interrupts can help the user to refresh pointers on time. Interrupts can also
75 //! be used to detect I2S errors. \ref I2SIntEnable() and \ref I2SIntDisable()
76 //! activate and deactivate interrupt(s). Interrupt status can be read through
77 //! \ref I2SIntStatus() and a pending interrupt can be acquitted by
78 //! \ref I2SIntClear() function.
79 //!
80 //! The sample stamps generator can be configured to slightly delay the
81 //! emission or the reception of the data (based on the number of WCLK
82 //! cycles) using \ref I2SSampleStampInConfigure(), \ref I2SSampleStampOutConfigure(),
83 //! \ref I2SWclkCounterReset() and \ref I2SWclkCounterConfigure(). The current sample stamp
84 //! can be computed using \ref I2SSampleStampGet().
85 //! To finish, the sample stamps generator can be enable and disable using
86 //! the following functions: \ref I2SSampleStampEnable() and
87 //! \ref I2SSampleStampDisable().
88 //! The sample stamps generator must be enabled prior to any transfer.
89 //!
90 //! Note: Other functions contained in the PRCM API are required to handle I2S.
91 //!
92 //! \section sec_i2s_api API
93 //!
94 //! Two APIs are coexisting.
95 //! It is recommended to only use the new API as the old one is deprecated and
96 //! will be removed soon.
97 //!
98 //! New API:
99 //!   Functions to perform I2S configuration:
100 //!   - \ref I2SStart()
101 //!   - \ref I2SStop()
102 //!   - \ref I2SFormatConfigure()
103 //!   - \ref I2SFrameConfigure()
104 //!   - \ref I2SWclkConfigure()
105 //!
106 //!   Functions to perform transfers:
107 //!   - \ref I2SInPointerSet()
108 //!   - \ref I2SOutPointerSet()
109 //!   - \ref I2SInPointerGet()
110 //!   - \ref I2SOutPointerGet()
111 //!   - \ref I2SInPointerNextGet()
112 //!   - \ref I2SOutPointerNextGet()
113 //!
114 //!   Functions to handle interruptions:
115 //!   - \ref I2SIntEnable()
116 //!   - \ref I2SIntDisable()
117 //!   - \ref I2SIntStatus()
118 //!   - \ref I2SIntClear()
119 //!
120 //!   Functions to handle sample stamps
121 //!   - \ref I2SSampleStampEnable()
122 //!   - \ref I2SSampleStampDisable()
123 //!   - \ref I2SSampleStampInConfigure()
124 //!   - \ref I2SSampleStampOutConfigure()
125 //!   - \ref I2SSampleStampGet()
126 //!   - \ref I2SWclkCounterConfigure()
127 //!   - \ref I2SWclkCounterReset()
128 //!
129 //! Old API:
130 //!   \ref I2SEnable(), \ref I2SDisable(), \ref I2SAudioFormatConfigure(),
131 //!   \ref I2SChannelConfigure(), \ref I2SClockConfigure(),
132 //!   \ref I2SBufferConfig(), \ref I2SIntEnable(), \ref I2SIntDisable(),
133 //!   \ref I2SIntStatus(), \ref I2SIntClear(), \ref I2SSampleStampEnable(),
134 //!   \ref I2SSampleStampDisable(), \ref I2SSampleStampGet(),
135 //!   \ref I2SPointerSet (), \ref I2SPointerUpdate(),
136 //!   \ref I2SSampleStampConfigure(), \ref I2SIntRegister(),
137 //!   \ref I2SIntUnregister()
138 //!
139 //! @}
140