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