spi.h

Go to the documentation of this file.

/******************************************************************************
 *  Filename:       spi.h
 *
 *  Description:    Defines and prototypes for the Serial Peripheral Interface (SPI).
 *
 *  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 __SPI_H__
#define __SPI_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_ints.h"
#include "../inc/hw_memmap.h"
#include "../inc/hw_types.h"
#include "../inc/hw_spi.h"
#include "debug.h"
#include "interrupt.h"

//*****************************************************************************
//
// Values that can be passed to SPIEnableInt(), SPIDisableInt(), and SPIClearInt()
// as the intFlags parameter, and returned by SPIIntStatus().
//
//*****************************************************************************
#define SPI_DMA_DONE_TX SPI_IMASK_DMATX   
#define SPI_DMA_DONE_RX SPI_IMASK_DMARX   
#define SPI_IDLE        SPI_IMASK_IDLE    
#define SPI_TXEMPTY     SPI_IMASK_TXEMPTY 
#define SPI_TX          SPI_IMASK_TX      
#define SPI_RX \
    SPI_IMASK_RX 
#define SPI_RTOUT      SPI_IMASK_RTOUT 
#define SPI_PER        SPI_IMASK_PER   
#define SPI_RXFIFO_OVF SPI_IMASK_RXOVF 

//*****************************************************************************
//
// Values that are returned from SPIStatus
//
//*****************************************************************************
#define SPI_BUSY        SPI_STA_BUSY_ACTIVE  
#define SPI_RX_NOT_FULL SPI_STA_RNF_NOT_FULL 
#define SPI_RX_EMPTY    SPI_STA_RFE_EMPTY    
#define SPI_TX_NOT_FULL SPI_STA_TNF_NOT_FULL 
#define SPI_TX_EMPTY    SPI_STA_TFE_EMPTY    
#define SPI_STATUS_MASK 0x0000001F           

//*****************************************************************************
//
// Values that can be passed to SPIConfigSetExpClk
//
//*****************************************************************************
#define SPI_FRF_MOTO_MODE_0 (SPI_CTL0_FRF_MOTOROLA_3WIRE | SPI_CTL0_SPO_LO | SPI_CTL0_SPH_FIRST)
#define SPI_FRF_MOTO_MODE_1 (SPI_CTL0_FRF_MOTOROLA_3WIRE | SPI_CTL0_SPO_LO | SPI_CTL0_SPH_SECOND)
#define SPI_FRF_MOTO_MODE_2 (SPI_CTL0_FRF_MOTOROLA_3WIRE | SPI_CTL0_SPO_HI | SPI_CTL0_SPH_FIRST)
#define SPI_FRF_MOTO_MODE_3 (SPI_CTL0_FRF_MOTOROLA_3WIRE | SPI_CTL0_SPO_HI | SPI_CTL0_SPH_SECOND)
#define SPI_FRF_MOTO_MODE_4 (SPI_CTL0_FRF_MOTOROLA_4WIRE | SPI_CTL0_SPO_LO | SPI_CTL0_SPH_FIRST)
#define SPI_FRF_MOTO_MODE_5 (SPI_CTL0_FRF_MOTOROLA_4WIRE | SPI_CTL0_SPO_LO | SPI_CTL0_SPH_SECOND)
#define SPI_FRF_MOTO_MODE_6 (SPI_CTL0_FRF_MOTOROLA_4WIRE | SPI_CTL0_SPO_HI | SPI_CTL0_SPH_FIRST)
#define SPI_FRF_MOTO_MODE_7 (SPI_CTL0_FRF_MOTOROLA_4WIRE | SPI_CTL0_SPO_HI | SPI_CTL0_SPH_SECOND)

#define SPI_FRF_TI  SPI_CTL0_FRF_TI_SYNC   
#define SPI_FRF_NMW SPI_CTL0_FRF_MIRCOWIRE 

#define SPI_MODE_CONTROLLER SPI_CTL1_MS_CONTROLLER 
#define SPI_MODE_PERIPHERAL SPI_CTL1_MS_PERIPHERAL 
#define SPI_MODE_PERIPHERAL_OD \
    SPI_CTL1_SOD_ENABLE 

//*****************************************************************************
//
// Values that can be passed to SPIEnableDMA() and SPIDisableDMA()
//
//*****************************************************************************
#define SPI_DMA_TX SPI_DMACR_TXEN 
#define SPI_DMA_RX SPI_DMACR_RXEN 

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

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

//*****************************************************************************
//
//
//*****************************************************************************
extern void SPIConfigSetExpClk(uint32_t base,
                               uint32_t spiClk,
                               uint32_t protocol,
                               uint32_t mode,
                               uint32_t bitRate,
                               uint32_t dataWidth);

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void SPIEnable(uint32_t base)
{
    // Check the arguments
    ASSERT(SPIBaseValid(base));

    // Read-modify-write the enable bit
    HWREG(base + SPI_O_CTL1) |= SPI_CTL1_EN_EN;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void SPIDisable(uint32_t base)
{
    // Check the arguments
    ASSERT(SPIBaseValid(base));

    // Read-modify-write the enable bit
    HWREG(base + SPI_O_CTL1) &= ~SPI_CTL1_EN_EN;
}

//*****************************************************************************
//
//
//*****************************************************************************
extern void SPIPutData(uint32_t base, uint32_t data);

//*****************************************************************************
//
//
//*****************************************************************************
extern int32_t SPIPutDataNonBlocking(uint32_t base, uint32_t data);

//*****************************************************************************
//
//
//*****************************************************************************
extern void SPIGetData(uint32_t base, uint32_t *data);

//*****************************************************************************
//
//
//*****************************************************************************
extern int32_t SPIGetDataNonBlocking(uint32_t base, uint32_t *data);

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE bool SPIBusy(uint32_t base)
{
    // Check the arguments
    ASSERT(SPIBaseValid(base));

    /* Determine if the SPI is busy. */
    return ((HWREG(base + SPI_O_STA) & SPI_STA_BUSY) ? true : false);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE uint32_t SPIStatus(uint32_t base)
{
    // Check the arguments
    ASSERT(SPIBaseValid(base));

    // Return the status
    return (HWREG(base + SPI_O_STA) & SPI_STATUS_MASK);
}

//*****************************************************************************
//
//
//*****************************************************************************
extern void SPIRegisterInt(uint32_t base, void (*pfnHandler)(void));

//*****************************************************************************
//
//
//*****************************************************************************
extern void SPIUnregisterInt(uint32_t base);

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

    // Enable the specified interrupts
    HWREG(base + SPI_O_IMASK) |= intFlags;
}

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

    // Disable the specified interrupts
    HWREG(base + SPI_O_IMASK) &= ~intFlags;
}

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

    // Clear the requested interrupt sources
    HWREG(base + SPI_O_ICLR) = intFlags;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE uint32_t SPIIntStatus(uint32_t base, bool isMasked)
{
    // Check the arguments
    ASSERT(SPIBaseValid(base));

    /* Return either the interrupt status or the raw interrupt status as
    requested. */
    if (isMasked)
    {
        return (HWREG(base + SPI_O_MIS));
    }
    else
    {
        return (HWREG(base + SPI_O_RIS));
    }
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void SPIEnableDMA(uint32_t base, uint32_t dmaFlags)
{
    // Check the arguments
    ASSERT(SPIBaseValid(base));

    // Set the requested bits in the SPI DMA control register
    HWREG(base + SPI_O_DMACR) |= dmaFlags;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void SPIDisableDMA(uint32_t base, uint32_t dmaFlags)
{
    // Check the arguments
    ASSERT(SPIBaseValid(base));

    // Clear the requested bits in the SPI DMA control register
    HWREG(base + SPI_O_DMACR) &= ~dmaFlags;
}

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

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

#endif // __SPI_H__