i2s.h

Go to the documentation of this file.

/******************************************************************************
 *  Filename:       i2s.h
 *
 *  Description:    Prototypes and defines for the I2S API.
 *
 *  Copyright (c) 2025 Texas Instruments Incorporated
 *
 *  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 copyright holder 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.
 *
 ******************************************************************************/

#ifndef __I2S_H__
#define __I2S_H__

//****************************************************************************
//
//
//****************************************************************************

//*****************************************************************************
//
// If building with a C++ compiler, make all of the definitions in this header
// have a C binding.
//
//*****************************************************************************
#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stdint.h>
#include "../inc/hw_types.h"
#include "../inc/hw_ints.h"
#include "../inc/hw_memmap.h"
#include "../inc/hw_i2s.h"
#include "debug.h"
#include "interrupt.h"

//*****************************************************************************
//
// Defines for selecting I2S module clock source
//
//*****************************************************************************
#define I2S_CLK_SRC_SOC_CLK     I2S_CLKCFG_CLKSEL_SEL_1 
#define I2S_CLK_SRC_SOC_PLL_CLK I2S_CLKCFG_CLKSEL_SEL_2 
#define I2S_CLK_SRC_HFXT_CLK    I2S_CLKCFG_CLKSEL_SEL_3 

//*****************************************************************************
//
// Defines for selecting data pin usage.
//
//*****************************************************************************
#define I2S_SD0_DIS I2S_AIFDIRCFG_AD0_DIS 
#define I2S_SD0_IN  I2S_AIFDIRCFG_AD0_IN  
#define I2S_SD0_OUT I2S_AIFDIRCFG_AD0_OUT 
#define I2S_SD1_DIS I2S_AIFDIRCFG_AD1_DIS 
#define I2S_SD1_IN  I2S_AIFDIRCFG_AD1_IN  
#define I2S_SD1_OUT I2S_AIFDIRCFG_AD1_OUT 

//*****************************************************************************
//
// Defines for activating an audio channel.
//
//*****************************************************************************
#define I2S_CHAN0_MASK 0x00000001
#define I2S_CHAN1_MASK 0x00000002
#define I2S_CHAN2_MASK 0x00000004
#define I2S_CHAN3_MASK 0x00000008
#define I2S_CHAN4_MASK 0x00000010
#define I2S_CHAN5_MASK 0x00000020
#define I2S_CHAN6_MASK 0x00000040
#define I2S_CHAN7_MASK 0x00000080

//*****************************************************************************
//
// Defines for the audio format configuration
//
//*****************************************************************************
#define I2S_MEM_LENGTH_16 I2S_AIFFMTCFG_LEN32__16BIT 
#define I2S_MEM_LENGTH_32 I2S_AIFFMTCFG_LEN32__32BIT 
#define I2S_POS_EDGE      I2S_AIFFMTCFG_SMPLEDGE_POS 
#define I2S_NEG_EDGE      I2S_AIFFMTCFG_SMPLEDGE_NEG 

//*****************************************************************************
//
// Defines for the sample stamp counters
//
//*****************************************************************************
#define I2S_STMP_SATURATION 0x0000FFFF 

//*****************************************************************************
//
// Defines for the interrupt
//
//*****************************************************************************
#define I2S_INT_XCNT_CAPTURE I2S_IRQFLAGS_XCNTCPT   
#define I2S_INT_DMA_IN       I2S_IRQFLAGS_AIFDMAIN  
#define I2S_INT_DMA_OUT      I2S_IRQFLAGS_AIFDMAOUT 
#define I2S_INT_TIMEOUT      I2S_IRQFLAGS_WCLKTOUT  
#define I2S_INT_BUS_ERR      I2S_IRQFLAGS_BUSERR    
#define I2S_INT_WCLK_ERR     I2S_IRQFLAGS_WCLKERR   
#define I2S_INT_PTR_ERR      I2S_IRQFLAGS_PTRERR    
#define I2S_INT_ALL                                                                                                   \
    (I2S_INT_XCNT_CAPTURE | I2S_INT_DMA_IN | I2S_INT_DMA_OUT | I2S_INT_TIMEOUT | I2S_INT_BUS_ERR | I2S_INT_WCLK_ERR | \
     I2S_INT_PTR_ERR) 

//*****************************************************************************
//
// API Functions and prototypes
//
//*****************************************************************************

#ifdef DRIVERLIB_DEBUG
//*****************************************************************************
//
//
//*****************************************************************************
static bool I2SBaseValid(uint32_t base)
{
    return (base == I2S_BASE);
}
#endif

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SEnableInt(uint32_t base, uint32_t intFlags)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Enable the specified interrupts
    HWREG(I2S_BASE + I2S_O_IRQMASK) |= intFlags;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SDisableInt(uint32_t base, uint32_t intFlags)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Disable the specified interrupts
    HWREG(I2S_BASE + I2S_O_IRQMASK) &= ~intFlags;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE uint32_t I2SIntStatus(uint32_t base, bool masked)
{
    uint32_t status;

    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Read the raw status
    status = HWREG(I2S_BASE + I2S_O_IRQFLAGS);

    // If the masked status is requested, mask the raw status with the interrupt
    // mask.
    if (masked)
    {
        status &= HWREG(I2S_BASE + I2S_O_IRQMASK);
    }

    return status;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SClearInt(uint32_t base, uint32_t intFlags)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Clear the requested interrupt sources
    HWREG(I2S_BASE + I2S_O_IRQCLR) = intFlags;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SEnableSampleStamp(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Set the enable bit
    HWREG(I2S_BASE + I2S_O_STMPCTL) |= I2S_STMPCTL_STMPEN_M;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SDisableSampleStamp(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Clear the enable bit
    HWREG(I2S_BASE + I2S_O_STMPCTL) &= ~I2S_STMPCTL_STMPEN_M;
}

//*****************************************************************************
//
//
//*****************************************************************************
extern uint32_t I2SGetSampleStamp(uint32_t base, uint32_t channel);

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SStart(uint32_t base, uint16_t dmaLength)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));
    ASSERT(dmaLength <= 256);
    ASSERT(dmaLength >= 2);

    // Enable the I2S module, by writting a non-zero value to AIFDMACFG.
    // AIFDMACFG expects the end frame index to be written, and the end index is
    // one less than the length.
    HWREG(I2S_BASE + I2S_O_AIFDMACFG) = (dmaLength - 1) & I2S_AIFDMACFG_ENDFRAMIDX_M;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SStop(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Disable the I2S module
    HWREG(I2S_BASE + I2S_O_AIFDMACFG) = 0x00;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SConfigureFormat(uint32_t base,
                                        uint8_t dataDelay,
                                        uint32_t memoryLength,
                                        uint32_t samplingEdge,
                                        bool dualPhase,
                                        uint8_t bitsPerSample)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));
    ASSERT(bitsPerSample <= 24); // Max. I2S_AIFFMTCFG_WORD_LEN
    ASSERT(bitsPerSample >= 8);  // Min. I2S_AIFFMTCFG_WORD_LEN

    // Setup register AIFFMTCFG Source
    HWREGH(I2S_BASE + I2S_O_AIFFMTCFG) = (dataDelay << I2S_AIFFMTCFG_DATADELAY_S) | (memoryLength) | (samplingEdge) |
                                         (dualPhase << I2S_AIFFMTCFG_DUALPHASE_S) |
                                         (bitsPerSample << I2S_AIFFMTCFG_WORDLEN_S);
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE void I2SConfigureFrame(uint32_t base,
                                       uint8_t sd0Usage,
                                       uint8_t sd0Channels,
                                       uint8_t sd1Usage,
                                       uint8_t sd1Channels)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Configure input/output channels
    HWREGB(I2S_BASE + I2S_O_AIFDIRCFG) = (sd0Usage | sd1Usage);

    // Configure the valid channel mask
    HWREGB(I2S_BASE + I2S_O_AIFWMASK0) = sd0Channels;
    HWREGB(I2S_BASE + I2S_O_AIFWMASK1) = sd1Channels;
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE void I2SConfigureClocks(uint32_t base,
                                        bool isController,
                                        bool invertWclk,
                                        bool dualPhase,
                                        uint32_t cclkDiv,
                                        uint32_t wclkDiv,
                                        uint32_t bclkDiv)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));
    ASSERT(cclkDiv <= 1024);
    ASSERT(cclkDiv >= 2);
    ASSERT(wclkDiv <= 1023);
    ASSERT(wclkDiv >= 1);
    ASSERT(bclkDiv <= 1024);
    ASSERT(bclkDiv >= 2);

    // Setup register WCLK and BCLK Source
    HWREGB(I2S_BASE + I2S_O_AIFWCLKSRC) = ((isController ? I2S_AIFWCLKSRC_WBCLKSRC_INT : I2S_AIFWCLKSRC_WBCLKSRC_EXT) |
                                           (invertWclk ? I2S_AIFWCLKSRC_WCLKINV : 0));

    // Configure internal clocks, if internal clocks are to be used
    if (isController)
    {

        // Make sure to compensate the WCLK division factor if using single
        // phase format.
        if (dualPhase == false)
        {
            wclkDiv -= 1;
        }

        // Write the clock division factors.
        // A value of 0 is interpreted as 1024 for CCLK and BCLK.
        HWREG(I2S_BASE + I2S_O_AIFMCLKDIV) = (cclkDiv == 1024 ? 0 : cclkDiv);
        HWREG(I2S_BASE + I2S_O_AIFWCLKDIV) = wclkDiv;
        HWREG(I2S_BASE + I2S_O_AIFBCLKDIV) = (bclkDiv == 1024 ? 0 : bclkDiv);

        // Configure the WCLK format and disable CCLK, WCLK and BCLK
        HWREG(I2S_BASE + I2S_O_AIFCLKCTL) = (dualPhase ? (1 << I2S_AIFCLKCTL_WCLKPHASE_S)
                                                       : (0 << I2S_AIFCLKCTL_WCLKPHASE_S));
    }
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SEnableControllerClocks(uint32_t base)
{
    // Enable CCLK, WCLK and BCLK
    HWREG(I2S_BASE + I2S_O_AIFCLKCTL) |= I2S_AIFCLKCTL_MEN | I2S_AIFCLKCTL_WBEN;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SDisableControllerClocks(uint32_t base)
{
    // Disable CCLK, WCLK and BCLK
    HWREG(I2S_BASE + I2S_O_AIFCLKCTL) &= ~(I2S_AIFCLKCTL_MEN | I2S_AIFCLKCTL_WBEN);
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE void I2SSetInPointer(uint32_t base, uint32_t nextPointer)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREG(I2S_BASE + I2S_O_AIFINPTNXT) = nextPointer;
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE void I2SSetOutPointer(uint32_t base, uint32_t nextPointer)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREG(I2S_BASE + I2S_O_AIFOPTNXT) = nextPointer;
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE uint32_t I2SGetInPointerNext(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    return (HWREG(I2S_BASE + I2S_O_AIFINPTNXT));
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE uint32_t I2SGetOutPointerNext(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    return (HWREG(I2S_BASE + I2S_O_AIFOPTNXT));
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE uint32_t I2SGetInPointer(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    return (HWREG(I2S_BASE + I2S_O_AIFINPTR));
}

//****************************************************************************
//
//
//****************************************************************************
__STATIC_INLINE uint32_t I2SGetOutPointer(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    return (HWREG(I2S_BASE + I2S_O_AIFOUTPTR));
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SConfigureInSampleStampTrigger(uint32_t base, uint16_t trigValue)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Setup the sample stamp trigger for input streams
    HWREGH(I2S_BASE + I2S_O_STMPINTRIG) = trigValue;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SConfigureOutSampleStampTrigger(uint32_t base, uint16_t trigValue)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Setup the sample stamp trigger for output streams
    HWREGH(I2S_BASE + I2S_O_STMPOTRIG) = trigValue;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SConfigureWclkCounterPeriod(uint32_t base, uint16_t period)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    // Configure the WCLK counter period
    HWREGH(I2S_BASE + I2S_O_STMPWPER) = period;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SConfigureWclkCounter(uint32_t base, int16_t value)
{
    uint16_t minusValue;

    // Check the arguments
    ASSERT(I2SBaseValid(base));

    if (value >= 0)
    {
        HWREGH(I2S_BASE + I2S_O_STMPWADD) = value;
    }
    else
    {
        minusValue                        = (uint16_t)(-value);
        HWREGH(I2S_BASE + I2S_O_STMPWADD) = HWREGH(I2S_BASE + I2S_O_STMPWPER) - minusValue;
    }
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SResetWclkCounter(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREGH(I2S_BASE + I2S_O_STMPWSET) = 0;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SEnableClk(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREG(I2S_BASE + I2S_O_CLKCFG) |= (I2S_CLKCFG_EN_M);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SDisableClk(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREG(I2S_BASE + I2S_O_CLKCFG) &= ~I2S_CLKCFG_EN_M;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SEnableAdfs(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREG(I2S_BASE + I2S_O_CLKCFG) |= (I2S_CLKCFG_ADFSEN_M);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SSelectAdfsInputClk(uint32_t base, uint32_t source)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    uint32_t temp = HWREG(I2S_BASE + I2S_O_CLKCFG);
    temp &= ~I2S_CLKCFG_CLKSEL_M;
    temp |= (source & I2S_CLKCFG_CLKSEL_M);
    HWREG(I2S_BASE + I2S_O_CLKCFG) = temp;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SConfigureAdfs(uint32_t base, uint32_t tref, uint32_t delta, uint32_t deltaSign, uint32_t div)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREG(I2S_BASE + I2S_O_ADFSCTRL1) = (tref & I2S_ADFSCTRL1_TREF_M);
    HWREG(I2S_BASE + I2S_O_ADFSCTRL2) = ((delta & I2S_ADFSCTRL2_DELTA_M) |
                                         ((deltaSign << I2S_ADFSCTRL2_DELTASIGN_S) & I2S_ADFSCTRL2_DELTASIGN_M) |
                                         ((div << I2S_ADFSCTRL2_DIV_S) & I2S_ADFSCTRL2_DIV_M));
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void I2SDisableAdfs(uint32_t base)
{
    // Check the arguments
    ASSERT(I2SBaseValid(base));

    HWREG(I2S_BASE + I2S_O_CLKCFG) &= ~(I2S_CLKCFG_ADFSEN_M);
}

//*****************************************************************************
//
// Mark the end of the C bindings section for C++ compilers.
//
//*****************************************************************************
#ifdef __cplusplus
}
#endif
//****************************************************************************
//
//
//****************************************************************************

#endif //  __I2S_H__