dma_device.hh

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2013, 2015, 2017, 2019 ARM Limited
 * All rights reserved.
 *
 * The license below extends only to copyright in the software and shall
 * not be construed as granting a license to any other intellectual
 * property including but not limited to intellectual property relating
 * to a hardware implementation of the functionality of the software
 * licensed hereunder.  You may use the software subject to the license
 * terms below provided that you ensure that this notice is replicated
 * unmodified and in its entirety in all distributions of the software,
 * modified or unmodified, in source code or in binary form.
 *
 * Copyright (c) 2004-2005 The Regents of The University of Michigan
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met: redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer;
 * 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;
 * neither the name of the copyright holders 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
 * OWNER 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 __DEV_DMA_DEVICE_HH__
#define __DEV_DMA_DEVICE_HH__
 
#include <deque>
#include <optional>
#include <memory>
 
#include "base/addr_range_map.hh"
#include "base/chunk_generator.hh"
#include "base/circlebuf.hh"
#include "dev/io_device.hh"
#include "mem/backdoor.hh"
#include "params/DmaDevice.hh"
#include "sim/drain.hh"
#include "sim/system.hh"
 
namespace gem5
{
 
class ClockedObject;
 
class DmaPort : public RequestPort, public Drainable
{
  private:
    AddrRangeMap<MemBackdoorPtr, 1> memBackdoors;

    void trySendTimingReq();

    void sendDma();
 
    struct DmaReqState : public Packet::SenderState
    {
        Event *completionEvent;

        Event *abortEvent;

        bool aborted = false;

        const Addr totBytes;

        Addr numBytes = 0;

        const Tick delay;

        ChunkGenerator gen;

        uint8_t *const data = nullptr;

        const Request::Flags flags;

        const RequestorID id;

        const std::optional<uint32_t> sid;
        const std::optional<uint32_t> ssid;

        const Packet::Command cmd;
 
        DmaReqState(Packet::Command _cmd, Addr addr, Addr chunk_sz, Addr tb,
                    uint8_t *_data, Request::Flags _flags, RequestorID _id,
                    std::optional<uint32_t> _sid, std::optional<uint32_t> _ssid,
                    Event *ce, Tick _delay, Event *ae=nullptr)
            : completionEvent(ce), abortEvent(ae), totBytes(tb), delay(_delay),
              gen(addr, tb, chunk_sz), data(_data), flags(_flags), id(_id),
              sid(_sid), ssid(_ssid), cmd(_cmd)
        {}
 
        PacketPtr createPacket();
    };

    bool sendAtomicReq(DmaReqState *state);
    bool sendAtomicBdReq(DmaReqState *state);

    void handleRespPacket(PacketPtr pkt, Tick delay=0);
    void handleResp(DmaReqState *state, Addr addr, Addr size, Tick delay=0);
 
  public:
    ClockedObject *const device;

    System *const sys;

    const RequestorID requestorId;
 
  protected:
    std::deque<DmaReqState *> transmitList;

    EventFunctionWrapper sendEvent;

    uint32_t pendingCount = 0;

    PacketPtr inRetry = nullptr;
    bool retryPending = false;

    const std::optional<uint32_t> defaultSid;

    const std::optional<uint32_t> defaultSSid;
 
    const Addr cacheLineSize;
 
  protected:
 
    bool recvTimingResp(PacketPtr pkt) override;
    void recvReqRetry() override;
 
  public:
 
    DmaPort(ClockedObject *dev, System *s, std::optional<uint32_t> sid=0,
            std::optional<uint32_t> ssid=0);
 
    void
    dmaAction(Packet::Command cmd, Addr addr, int size, Event *event,
              uint8_t *data, Tick delay, Request::Flags flag=0);
 
    void
    dmaAction(Packet::Command cmd, Addr addr, int size, Event *event,
              uint8_t *data, std::optional<uint32_t> sid,
              std::optional<uint32_t> ssid, Tick delay, Request::Flags flag=0);
 
    // Abort and remove any pending DMA transmissions.
    void abortPending();
 
    bool dmaPending() const { return pendingCount > 0; }
 
    DrainState drain() override;
};
 
class DmaDevice : public PioDevice
{
   protected:
    DmaPort dmaPort;
 
  public:
    typedef DmaDeviceParams Params;
    DmaDevice(const Params &p);
    virtual ~DmaDevice() = default;
 
    void
    dmaWrite(Addr addr, int size, Event *event, uint8_t *data,
             std::optional<uint32_t> sid, std::optional<uint32_t> ssid,
             Tick delay=0)
    {
        dmaPort.dmaAction(MemCmd::WriteReq, addr, size, event, data,
                          sid, ssid, delay);
    }
 
    void
    dmaWrite(Addr addr, int size, Event *event, uint8_t *data, Tick delay=0)
    {
        dmaPort.dmaAction(MemCmd::WriteReq, addr, size, event, data, delay);
    }
 
    void
    dmaRead(Addr addr, int size, Event *event, uint8_t *data,
            std::optional<uint32_t> sid, std::optional<uint32_t> ssid,
            Tick delay=0)
    {
        dmaPort.dmaAction(MemCmd::ReadReq, addr, size, event, data,
                          sid, ssid, delay);
    }
 
    void
    dmaRead(Addr addr, int size, Event *event, uint8_t *data, Tick delay=0)
    {
        dmaPort.dmaAction(MemCmd::ReadReq, addr, size, event, data, delay);
    }
 
    bool dmaPending() const { return dmaPort.dmaPending(); }
 
    void init() override;
 
    Addr cacheBlockSize() const { return sys->cacheLineSize(); }
 
    Port &getPort(const std::string &if_name,
                  PortID idx=InvalidPortID) override;
 
};

class DmaCallback : public Drainable
{
  public:
    virtual const std::string name() const { return "DmaCallback"; }

    DrainState
    drain() override
    {
        return count ? DrainState::Draining : DrainState::Drained;
    }
 
  protected:
    int count = 0;
 
    virtual ~DmaCallback() = default;

    virtual void process() = 0;
 
  private:
    void
    chunkComplete()
    {
        if (--count == 0) {
            process();
            // Need to notify DrainManager that this object is finished
            // draining, even though it is immediately deleted.
            signalDrainDone();
            delete this;
        }
    }
 
  public:

    Event *
    getChunkEvent()
    {
        ++count;
        return new EventFunctionWrapper([this]{ chunkComplete(); }, name(),
                                        true);
    }
};

class DmaReadFifo : public Drainable, public Serializable
{
  public:
    DmaReadFifo(DmaPort &port, size_t size,
                unsigned max_req_size,
                unsigned max_pending,
                Request::Flags flags=0);
 
    ~DmaReadFifo();
 
  public: // Serializable
    void serialize(CheckpointOut &cp) const override;
    void unserialize(CheckpointIn &cp) override;
 
  public: // Drainable
    DrainState drain() override;
 
  public: // FIFO access
    bool tryGet(uint8_t *dst, size_t len);
 
    template<typename T>
    bool
    tryGet(T &value)
    {
        return tryGet(static_cast<T *>(&value), sizeof(T));
    };

    void get(uint8_t *dst, size_t len);
 
    template<typename T>
    T
    get()
    {
        T value;
        get(static_cast<uint8_t *>(&value), sizeof(T));
        return value;
    };

    size_t size() const { return buffer.size(); }
    void flush() { buffer.flush(); }

  public: // FIFO fill control
    void startFill(Addr start, size_t size);

    void stopFill();

    bool atEndOfBlock() const { return nextAddr == endAddr; }

    bool
    isActive() const
    {
        return !(pendingRequests.empty() && atEndOfBlock());
    }

  protected: // Callbacks
    virtual void onEndOfBlock() {};

    virtual void onIdle() {};

  private: // Configuration
    const Addr maxReqSize;
    const size_t fifoSize;
    const Request::Flags reqFlags;
 
    DmaPort &port;
 
    const Addr cacheLineSize;
 
  private:
    class DmaDoneEvent : public Event
    {
      public:
        DmaDoneEvent(DmaReadFifo *_parent, size_t max_size);
 
        void kill();
        void cancel();
        bool canceled() const { return _canceled; }
        void reset(size_t size);
        void process();
 
        bool done() const { return _done; }
        size_t requestSize() const { return _requestSize; }
        const uint8_t *data() const { return _data.data(); }
        uint8_t *data() { return _data.data(); }
 
      private:
        DmaReadFifo *parent;
        bool _done = false;
        bool _canceled = false;
        size_t _requestSize;
        std::vector<uint8_t> _data;
    };
 
    typedef std::unique_ptr<DmaDoneEvent> DmaDoneEventUPtr;

    void dmaDone();

    void handlePending();

    void resumeFill();

    void resumeFillTiming();

    void resumeFillBypass();
 
  private: // Internal state
    Fifo<uint8_t> buffer;
 
    Addr nextAddr = 0;
    Addr endAddr = 0;
 
    std::deque<DmaDoneEventUPtr> pendingRequests;
    std::deque<DmaDoneEventUPtr> freeRequests;
};
 
} // namespace gem5
 
#endif // __DEV_DMA_DEVICE_HH__