DMA.h

Go to the documentation of this file.

/* Copyright (c) 2025 Skyward Experimental Rocketry
 * Author: Alberto Nidasio, Fabrizio Monti
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
 
#pragma once
 
#include <kernel/scheduler/scheduler.h>
#include <kernel/sync.h>
 
#include <chrono>
#include <functional>
#include <map>
 
#include "DMADefs.h"
 
namespace Boardcore
{
 
enum class DMAErrors : uint8_t
{
    NO_ERRORS          = 0,
    TIMEOUT            = 1,  // The timeout expired
    FIFO_ERROR         = 2,  // The fifo error flag was raised
    TRANSFER_ERROR     = 3,  // The transfer error flag was raised
    DIRECT_MODE_ERROR  = 4,  // The direct mode error flag was raised
    END_OF_BASE_ERRORS = 5   // Used to extend this enum
};
 
struct DMATransaction
{
    enum class Direction : uint16_t
    {
        MEM_TO_MEM = DMA_SxCR_DIR_1,
        MEM_TO_PER = DMA_SxCR_DIR_0,
        PER_TO_MEM = 0,
    };
 
    enum class Priority : uint32_t
    {
        VERY_HIGH = DMA_SxCR_PL,
        HIGH      = DMA_SxCR_PL_1,
        MEDIUM    = DMA_SxCR_PL_0,
        LOW       = 0,
    };
 
    enum class DataSize : uint8_t
    {
        BITS_8 = 0,
        BITS_16,
        BITS_32,
    };
 
    Direction direction                = Direction::MEM_TO_MEM;
    Priority priority                  = Priority::LOW;
    DataSize srcSize                   = DataSize::BITS_32;
    DataSize dstSize                   = DataSize::BITS_32;
    volatile void* srcAddress          = nullptr;
    volatile void* dstAddress          = nullptr;
    volatile void* secondMemoryAddress = nullptr;
    uint16_t numberOfDataItems         = 0;
    bool srcIncrement                  = false;
    bool dstIncrement                  = false;
 
    bool circularMode = false;
 
    bool doubleBufferMode                = false;
    bool enableTransferCompleteInterrupt = false;
 
    bool enableHalfTransferInterrupt = false;
 
    bool enableTransferErrorInterrupt = false;
 
    bool enableFifoErrorInterrupt = false;
 
    bool enableDirectModeErrorInterrupt = false;
};
 
// Forward declaration
class DMAStream;
class DMAStreamGuard;
 
class DMADriver
{
public:
    // cppcheck-suppress  noExplicitConstructor
 
    void IRQhandleInterrupt(DMADefs::DMAStreamId id);
 
    static DMADriver& instance();
 
    bool tryStream(DMADefs::DMAStreamId id);
 
    DMAStreamGuard acquireStream(
        DMADefs::DMAStreamId id, DMADefs::Channel channel,
        std::chrono::nanoseconds timeout = std::chrono::nanoseconds::zero());
 
    DMAStreamGuard acquireStreamForPeripheral(
        DMADefs::Peripherals peripheral,
        std::chrono::nanoseconds timeout = std::chrono::nanoseconds::zero());
 
    void releaseStream(DMADefs::DMAStreamId id);
 
private:
    DMADriver();
 
    void IRQwakeupThread(DMAStream& stream);
 
    miosix::FastMutex mutex;
    miosix::ConditionVariable cv;
    std::map<DMADefs::DMAStreamId, DMAStream> streams;
 
public:
    DMADriver(const DMADriver&)            = delete;
    DMADriver& operator=(const DMADriver&) = delete;
};
 
class DMAStream
{
    friend DMADriver;
 
public:
    // cppcheck-suppress  noExplicitConstructor
 
    void setup(DMATransaction& transaction);
 
    void enable();
 
    void disable();
 
    void waitForHalfTransfer();
 
    void waitForTransferComplete();
 
    bool timedWaitForHalfTransfer(std::chrono::nanoseconds timeout_ns);
 
    bool timedWaitForTransferComplete(std::chrono::nanoseconds timeout_ns);
 
    void setHalfTransferCallback(std::function<void()> callback);
 
    void resetHalfTransferCallback();
 
    void setTransferCompleteCallback(std::function<void()> callback);
 
    void resetTransferCompleteCallback();
 
    void setErrorCallback(std::function<void()> callback);
 
    void resetErrorCallback();
 
    void readFlags();
 
    bool setNumberOfDataItems(const uint16_t nBytes);
 
    void setChannel(const DMADefs::Channel channel);
 
    inline bool getHalfTransferFlagStatus() { return halfTransferFlag; }
 
    inline bool getTransferCompleteFlagStatus() { return transferCompleteFlag; }
 
    inline bool getTransferErrorFlagStatus() { return transferErrorFlag; }
 
    inline bool getFifoErrorFlagStatus() { return fifoErrorFlag; }
 
    inline bool getDirectModeErrorFlagStatus() { return directModeErrorFlag; }
 
    int getCurrentBufferNumber();
 
    inline DMADefs::DMAStreamId getStreamId() { return id; }
 
    inline DMADefs::Channel getCurrentChannel() { return currentChannel; }
 
    inline void clearHalfTransferFlag()
    {
        *IFCR |= DMA_LIFCR_CHTIF0 << IFindex;
    }
 
    inline void clearTransferCompleteFlag()
    {
        *IFCR |= DMA_LIFCR_CTCIF0 << IFindex;
    }
 
    inline void clearTransferErrorFlag()
    {
        *IFCR |= DMA_LIFCR_CTEIF0 << IFindex;
    }
 
    inline void clearFifoErrorFlag() { *IFCR |= DMA_LIFCR_CFEIF0 << IFindex; }
 
    inline void clearDirectModeErrorFlag()
    {
        *IFCR |= DMA_LIFCR_CDMEIF0 << IFindex;
    }
 
    inline void clearAllFlags()
    {
        *IFCR |= (DMA_LIFCR_CHTIF0 | DMA_LIFCR_CTCIF0 | DMA_LIFCR_CTEIF0 |
                  DMA_LIFCR_CFEIF0 | DMA_LIFCR_CDMEIF0)
                 << IFindex;
    }
 
private:
    DMAStream(DMADefs::DMAStreamId id, DMADefs::Channel channel);
 
    DMATransaction currentSetup;
 
    miosix::Thread* waitingThread = nullptr;
 
    // These flags are set by the interrupt routine and tells the user
    // which event were triggered
    bool halfTransferFlag     = false;
    bool transferCompleteFlag = false;
    bool transferErrorFlag    = false;
    bool fifoErrorFlag        = false;
    bool directModeErrorFlag  = false;
 
    std::function<void()> halfTransferCallback;
    std::function<void()> transferCompleteCallback;
    std::function<void()> errorCallback;
 
    const DMADefs::DMAStreamId id;
    DMADefs::Channel currentChannel;
    DMA_Stream_TypeDef* registers;
 
    volatile uint32_t* ISR;   
    volatile uint32_t* IFCR;  
    int IFindex;              
 
    inline bool waitForInterruptEventImpl(
        bool isInterruptEnabled, std::function<bool()> getEventStatus,
        std::function<void()> clearEventStatus, bool& eventTriggered,
        long long timeout_ns)
    {
        // Return value: true if the event was triggered, false if the timeout
        // expired
        bool result = false;
 
        // If the interrupt is enabled we can just pause and wait for it.
        // Otherwise we need to pool the flag.
        if (isInterruptEnabled)
        {
            // Here we have 2 cases:
            // - This function has been called after the interrupt fired. In
            // this case the interrupt saves the flags status and we check them
            // - The interrupt has not yet fired. We pause the thread and the
            // interrupt will wake us up
 
            if (eventTriggered)
            {
                result = true;
            }
            else
            {
                // Save the current thread pointer
                waitingThread = miosix::Thread::getCurrentThread();
 
                // Wait until the thread is woken up and the pointer is cleared
                miosix::FastInterruptDisableLock dLock;
                if (timeout_ns > 0)
                {
                    do
                    {
                        if (miosix::Thread::IRQenableIrqAndTimedWait(
                                dLock, timeout_ns + miosix::IRQgetTime()) ==
                            miosix::TimedWaitResult::Timeout)
                        {
                            result = false;
 
                            // If the timeout expired we clear the thread
                            // pointer so that the interrupt, if it will occur,
                            // will not wake up the thread (and we can exit the
                            // while loop)
                            waitingThread = nullptr;
                        }
                        else
                        {
                            result = true;
                        }
                    } while (waitingThread);
                }
                else
                {
                    do
                    {
                        miosix::Thread::IRQenableIrqAndWait(dLock);
                    } while (waitingThread);
                    result = true;
                }
            }
 
            // Before returning we need to clear the flags otherwise we could
            // get misfires
            eventTriggered = false;
        }
        else
        {
            // Pool the flag if the user did not enable the interrupt
            if (timeout_ns > 0)
            {
                const long long start = miosix::getTime();
 
                do
                {
                    readFlags();
                } while (!getEventStatus() &&
                         miosix::getTime() - start < timeout_ns);
 
                result = getEventStatus();
            }
            else
            {
                while (!getEventStatus())
                    readFlags();
                result = true;
            }
 
            if (result)
            {
                // Clear the flag
                clearEventStatus();
            }
        }
 
        return result;
    }
 
#ifdef STM32F767xx
    void invalidateCache();
#endif  // STM32F767xx
 
public:
    DMAStream(const DMAStream&)            = delete;
    DMAStream& operator=(const DMAStream&) = delete;
 
    DMAStream(DMAStream&&) noexcept            = default;
    DMAStream& operator=(DMAStream&&) noexcept = default;
};
 
class DMAStreamGuard
{
public:
    // cppcheck-suppress  noExplicitConstructor
    DMAStreamGuard(DMAStream* ptr) : pStream(ptr) {}
 
    ~DMAStreamGuard()
    {
        if (pStream != nullptr)
            DMADriver::instance().releaseStream(pStream->getStreamId());
    }
 
    DMAStreamGuard(const DMAStreamGuard&)            = delete;
    DMAStreamGuard& operator=(const DMAStreamGuard&) = delete;
 
    DMAStreamGuard(DMAStreamGuard&&) noexcept            = default;
    DMAStreamGuard& operator=(DMAStreamGuard&&) noexcept = default;
 
    DMAStream* operator->();
 
    inline bool isValid() { return pStream != nullptr; }
 
private:
    DMAStream* const pStream;
};
 
}  // namespace Boardcore