udma.h

Go to the documentation of this file.

/******************************************************************************
 *  Filename:       udma.h
 *
 *  Description:    Defines and prototypes for the uDMA controller.
 *
 *  Copyright (c) 2022-2024 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 __UDMA_H__
#define __UDMA_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_dma.h"
#include "debug.h"
#include "interrupt.h"

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    volatile void *pSrcEndAddr; 
    volatile void *pDstEndAddr; 
    volatile uint32_t control;  
    volatile uint32_t spare;    
} uDMAControlTableEntry;

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

//
//*****************************************************************************
#define uDMATaskStructEntry(transferCount, itemSize, srcIncrement, pSrcAddr, dstIncrement, pDstAddr, arbSize, mode) \
    {                                                                                                               \
        (((srcIncrement) == UDMA_SRC_INC_NONE)                                                                      \
             ? (pSrcAddr)                                                                                           \
             : ((void *)(&((uint8_t *)(pSrcAddr))[((transferCount) << ((srcIncrement) >> 26)) - 1]))),              \
            (((dstIncrement) == UDMA_DST_INC_NONE)                                                                  \
                 ? (pDstAddr)                                                                                       \
                 : ((void *)(&((uint8_t *)(pDstAddr))[((transferCount) << ((dstIncrement) >> 30)) - 1]))),          \
            (srcIncrement) | (dstIncrement) | (itemSize) | (arbSize) | (((transferCount)-1) << 4) |                 \
                ((((mode) == UDMA_MODE_MEM_SCATTER_GATHER) || ((mode) == UDMA_MODE_PER_SCATTER_GATHER))             \
                     ? (mode) | UDMA_MODE_ALT_SELECT                                                                \
                     : (mode)),                                                                                     \
            0                                                                                                       \
    }

//*****************************************************************************
//
// The hardware configured number of uDMA channels.
//
//*****************************************************************************
#define UDMA_NUM_CHANNELS 8

//*****************************************************************************
//
// The level of priority for the uDMA channels
//
//*****************************************************************************
#define UDMA_PRIORITY_LOW  0x00000000
#define UDMA_PRIORITY_HIGH 0x00000001

//*****************************************************************************
//
// Flags that can be passed to uDMAEnableChannelAttribute(),
// uDMADisableChannelAttribute(), and returned from uDMAGetChannelAttribute().
//
//*****************************************************************************
#define UDMA_ATTR_USEBURST      0x00000001
#define UDMA_ATTR_ALTSELECT     0x00000002
#define UDMA_ATTR_HIGH_PRIORITY 0x00000004
#define UDMA_ATTR_REQMASK       0x00000008
#define UDMA_ATTR_ALL           0x0000000F

//*****************************************************************************
//
// DMA control modes that can be passed to uDMASetChannelTransfer() and returned
// from uDMAGetChannelMode().
//
//*****************************************************************************
#define UDMA_MODE_STOP               0x00000000
#define UDMA_MODE_BASIC              0x00000001
#define UDMA_MODE_AUTO               0x00000002
#define UDMA_MODE_PINGPONG           0x00000003
#define UDMA_MODE_MEM_SCATTER_GATHER 0x00000004
#define UDMA_MODE_PER_SCATTER_GATHER 0x00000006
#define UDMA_MODE_M                  0x00000007 // uDMA Transfer Mode
#define UDMA_MODE_ALT_SELECT         0x00000001

//*****************************************************************************
//
// Channel configuration values that can be passed to uDMASetChannelControl().
//
//*****************************************************************************
#define UDMA_DST_INC_8     0x00000000
#define UDMA_DST_INC_16    0x40000000
#define UDMA_DST_INC_32    0x80000000
#define UDMA_DST_INC_NONE  0xC0000000
#define UDMA_DST_INC_M     0xC0000000 // Destination Address Increment
#define UDMA_DST_INC_S     30
#define UDMA_SRC_INC_8     0x00000000
#define UDMA_SRC_INC_16    0x04000000
#define UDMA_SRC_INC_32    0x08000000
#define UDMA_SRC_INC_NONE  0x0c000000
#define UDMA_SRC_INC_M     0x0C000000 // Source Address Increment
#define UDMA_SRC_INC_S     26
#define UDMA_SIZE_8        0x00000000
#define UDMA_SIZE_16       0x11000000
#define UDMA_SIZE_32       0x22000000
#define UDMA_SIZE_M        0x33000000 // Data Size
#define UDMA_SIZE_S        24
#define UDMA_ARB_1         0x00000000
#define UDMA_ARB_2         0x00004000
#define UDMA_ARB_4         0x00008000
#define UDMA_ARB_8         0x0000c000
#define UDMA_ARB_16        0x00010000
#define UDMA_ARB_32        0x00014000
#define UDMA_ARB_64        0x00018000
#define UDMA_ARB_128       0x0001c000
#define UDMA_ARB_256       0x00020000
#define UDMA_ARB_512       0x00024000
#define UDMA_ARB_1024      0x00028000
#define UDMA_ARB_M         0x0003C000 // Arbitration Size
#define UDMA_ARB_S         14
#define UDMA_NEXT_USEBURST 0x00000008
#define UDMA_XFER_SIZE_MAX 1024
#define UDMA_XFER_SIZE_M   0x00003FF0 // Transfer size
#define UDMA_XFER_SIZE_S   4

//*****************************************************************************
//
// Channel numbers to be passed to API functions that require a channel number
// ID. On CC27xx each uDMA channel is multiplexed between two different
// peripherals. The 1-to-1 mapping between UDMA channel and peripheral must be
// decided by the user and set in the event fabric registers EVTSVT.DMACH[x]SEL.
// The two valid peripherals for each channel are listed next to each channel's
// mask definition.
//
//*****************************************************************************
#define UDMA_CHANNEL_0_M  0x001 
#define UDMA_CHANNEL_1_M  0x002 
#define UDMA_CHANNEL_2_M  0x004 
#define UDMA_CHANNEL_3_M  0x008 
#define UDMA_CHANNEL_4_M  0x010 
#define UDMA_CHANNEL_5_M  0x020 
#define UDMA_CHANNEL_6_M  0x040 
#define UDMA_CHANNEL_7_M  0x080 
#define UDMA_CHANNEL_8_M  0x100 
#define UDMA_CHANNEL_9_M  0x200 
#define UDMA_CHANNEL_10_M 0x400 
#define UDMA_CHANNEL_11_M 0x800 

//*****************************************************************************
//
// Flags to be OR'd with the channel ID to indicate if the primary or alternate
// control structure should be used.
//
//*****************************************************************************
#define UDMA_PRI_SELECT 0x00000000
#define UDMA_ALT_SELECT 0x00000010

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

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMAEnable(void)
{
    // Set the master enable bit in the config register.
    HWREG(DMA_BASE + DMA_O_CFG) = DMA_CFG_MASTERENABLE;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMADisable(void)
{
    // Clear the master enable bit in the config register.
    HWREG(DMA_BASE + DMA_O_CFG) = 0;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE uint32_t uDMAGetErrorStatus(void)
{
    // Return the uDMA error status.
    return (HWREG(DMA_BASE + DMA_O_ERROR));
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMAClearErrorStatus(void)
{
    // Clear the uDMA error interrupt.
    HWREG(DMA_BASE + DMA_O_ERROR) = DMA_ERROR_STATUS;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMAEnableChannel(uint32_t channelBitMask)
{
    HWREG(DMA_BASE + DMA_O_SETCHANNELEN) = channelBitMask;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMADisableChannel(uint32_t channelBitMask)
{
    HWREG(DMA_BASE + DMA_O_CLEARCHANNELEN) = channelBitMask;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE bool uDMAIsChannelEnabled(uint32_t channelBitMask)
{
    return ((HWREG(DMA_BASE + DMA_O_SETCHANNELEN) & (channelBitMask)) ? true : false);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMASetControlBase(void *pControlTable)
{
    // Check the arguments.
    ASSERT(((uint32_t)pControlTable & ~0x3FF) == (uint32_t)pControlTable);
    ASSERT((uint32_t)pControlTable >= SRAM_BASE);

    // Program the base address into the register.
    HWREG(DMA_BASE + DMA_O_CTRL) = (uint32_t)pControlTable;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void *uDMAGetControlBase(void)
{
    // Read the current value of the control base register, and return it to
    // the caller.
    return ((void *)HWREG(DMA_BASE + DMA_O_CTRL));
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void *uDMAGetControlAlternateBase(void)
{
    // Read the current value of the control base register, and return it to
    // the caller.
    return ((void *)HWREG(DMA_BASE + DMA_O_ALTCTRL));
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMARequestChannel(uint32_t channelBitMask)
{
    // Set the bit for this channel in the software uDMA request register.
    HWREG(DMA_BASE + DMA_O_SOFTREQ) = channelBitMask;
}

//*****************************************************************************
//
//
//*****************************************************************************
extern void uDMAEnableChannelAttribute(uint32_t channelBitMask, uint32_t attr);

//*****************************************************************************
//
//
//*****************************************************************************
extern void uDMADisableChannelAttribute(uint32_t channelBitMask, uint32_t attr);

//*****************************************************************************
//
//
//*****************************************************************************
extern uint32_t uDMAGetChannelAttribute(uint32_t channelBitMask);

//*****************************************************************************
//
//
//*****************************************************************************
extern void uDMASetChannelControl(volatile uDMAControlTableEntry *pChannelControlStruct, uint32_t control);

//*****************************************************************************
//
//
//*****************************************************************************
extern void uDMASetChannelTransfer(volatile uDMAControlTableEntry *pChannelControlStruct,
                                   uint32_t mode,
                                   void *pSrcAddr,
                                   void *pDstAddr,
                                   uint32_t transferSize);

//*****************************************************************************
//
//
//*****************************************************************************
extern uint32_t uDMAGetChannelSize(volatile uDMAControlTableEntry const *pChannelControlStruct);

//*****************************************************************************
//
//
//*****************************************************************************
extern uint32_t uDMAGetChannelMode(volatile uDMAControlTableEntry const *pChannelControlStruct);

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMARegisterInt(uint32_t intChannel, void (*pfnHandler)(void))
{
    // Check the arguments.
    ASSERT(pfnHandler);
    ASSERT(intChannel == INT_DMA_DONE_COMB);

    // Register the interrupt handler.
    IntRegister(intChannel, pfnHandler);

    // Enable the memory management fault.
    IntEnable(intChannel);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMAUnregisterInt(uint32_t intChannel)
{
    // Check the arguments.
    ASSERT(intChannel == INT_DMA_DONE_COMB);

    // Disable the interrupt.
    IntDisable(intChannel);

    // Unregister the interrupt handler.
    IntUnregister(intChannel);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMAClearInt(uint32_t channelBitMask)
{
    // Clear the requested bits in the uDMA interrupt status register.
    HWREG(DMA_BASE + DMA_O_REQDONE) = channelBitMask;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE uint32_t uDMAIntStatus(void)
{
    // Return the uDMA interrupt status register.
    return (HWREG(DMA_BASE + DMA_O_REQDONE));
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMAEnableSwEventInt(uint32_t intChannel)
{
    // Check the arguments.
    ASSERT(intChannel < UDMA_NUM_CHANNELS);

    // Enable the channel.
    HWREG(DMA_BASE + DMA_O_DONEMASK) |= intChannel;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMADisableSwEventInt(uint32_t intChannel)
{
    // Check the arguments.
    ASSERT(intChannel < UDMA_NUM_CHANNELS);

    // Disable the SW channel.
    HWREG(DMA_BASE + DMA_O_DONEMASK) &= ~intChannel;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE uint32_t uDMAGetStatus(void)
{
    // Read and return the status register.
    return HWREG(DMA_BASE + DMA_O_STATUS);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMASetChannelPriority(uint32_t channelBitMask)
{
    // Set the channel priority to high.
    HWREG(DMA_BASE + DMA_O_SETCHNLPRIORITY) = channelBitMask;
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE bool uDMAGetChannelPriority(uint32_t channelBitMask)
{
    // Return the channel priority.
    return (HWREG(DMA_BASE + DMA_O_SETCHNLPRIORITY) & (channelBitMask) ? UDMA_PRIORITY_HIGH : UDMA_PRIORITY_LOW);
}

//*****************************************************************************
//
//
//*****************************************************************************
__STATIC_INLINE void uDMAClearChannelPriority(uint32_t channelBitMask)
{
    // Clear the channel priority.
    HWREG(DMA_BASE + DMA_O_CLEARCHNLPRIORITY) = channelBitMask;
}

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

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

#endif //  __UDMA_H__