src/dev/dma_device.hh

   1 /*
   2  * Copyright (c) 2012-2013, 2015, 2017, 2019 ARM Limited
   3  * All rights reserved.
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Copyright (c) 2004-2005 The Regents of The University of Michigan
  15  * All rights reserved.
  16  *
  17  * Redistribution and use in source and binary forms, with or without
  18  * modification, are permitted provided that the following conditions are
  19  * met: redistributions of source code must retain the above copyright
  20  * notice, this list of conditions and the following disclaimer;
  21  * redistributions in binary form must reproduce the above copyright
  22  * notice, this list of conditions and the following disclaimer in the
  23  * documentation and/or other materials provided with the distribution;
  24  * neither the name of the copyright holders nor the names of its
  25  * contributors may be used to endorse or promote products derived from
  26  * this software without specific prior written permission.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  29  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  30  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  31  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  32  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  33  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  34  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  38  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39  */
  40
  41 #ifndef __DEV_DMA_DEVICE_HH__
  42 #define __DEV_DMA_DEVICE_HH__
  43
  44 #include <deque>
  45 #include <memory>
  46
  47 #include "base/circlebuf.hh"
  48 #include "dev/io_device.hh"
  49 #include "params/DmaDevice.hh"
  50 #include "sim/drain.hh"
  51 #include "sim/system.hh"
  52
  53 class ClockedObject;
  54
  55 class DmaPort : public RequestPort, public Drainable
  56 {
  57   private:
  58
  59     /**
  60      * Take the first packet of the transmit list and attempt to send
  61      * it as a timing request. If it is successful, schedule the
  62      * sending of the next packet, otherwise remember that we are
  63      * waiting for a retry.
  64      */
  65     void trySendTimingReq();
  66
  67     /**
  68      * For timing, attempt to send the first item on the transmit
  69      * list, and if it is successful and there are more packets
  70      * waiting, then schedule the sending of the next packet. For
  71      * atomic, simply send and process everything on the transmit
  72      * list.
  73      */
  74     void sendDma();
  75
  76     /**
  77      * Handle a response packet by updating the corresponding DMA
  78      * request state to reflect the bytes received, and also update
  79      * the pending request counter. If the DMA request that this
  80      * packet is part of is complete, then signal the completion event
  81      * if present, potentially with a delay added to it.
  82      *
  83      * @param pkt Response packet to handler
  84      * @param delay Additional delay for scheduling the completion event
  85      */
  86     void handleResp(PacketPtr pkt, Tick delay = 0);
  87
  88     struct DmaReqState : public Packet::SenderState
  89     {
  90         /** Event to call on the device when this transaction (all packets)
  91          * complete. */
  92         Event *completionEvent;
  93
  94         /** Total number of bytes that this transaction involves. */
  95         const Addr totBytes;
  96
  97         /** Number of bytes that have been acked for this transaction. */
  98         Addr numBytes;
  99
 100         /** Amount to delay completion of dma by */
 101         const Tick delay;
 102
 103         DmaReqState(Event *ce, Addr tb, Tick _delay)
 104             : completionEvent(ce), totBytes(tb), numBytes(0), delay(_delay)
 105         {}
 106     };
 107
 108   public:
 109     /** The device that owns this port. */
 110     ClockedObject *const device;
 111
 112     /** The system that device/port are in. This is used to select which mode
 113      * we are currently operating in. */
 114     System *const sys;
 115
 116     /** Id for all requests */
 117     const RequestorID requestorId;
 118
 119   protected:
 120     /** Use a deque as we never do any insertion or removal in the middle */
 121     std::deque<PacketPtr> transmitList;
 122
 123     /** Event used to schedule a future sending from the transmit list. */
 124     EventFunctionWrapper sendEvent;
 125
 126     /** Number of outstanding packets the dma port has. */
 127     uint32_t pendingCount;
 128
 129     /** If the port is currently waiting for a retry before it can
 130      * send whatever it is that it's sending. */
 131     bool inRetry;
 132
 133     /** Default streamId */
 134     const uint32_t defaultSid;
 135
 136     /** Default substreamId */
 137     const uint32_t defaultSSid;
 138
 139   protected:
 140
 141     bool recvTimingResp(PacketPtr pkt) override;
 142     void recvReqRetry() override;
 143
 144     void queueDma(PacketPtr pkt);
 145
 146   public:
 147
 148     DmaPort(ClockedObject *dev, System *s,
 149             uint32_t sid = 0, uint32_t ssid = 0);
 150
 151     RequestPtr
 152     dmaAction(Packet::Command cmd, Addr addr, int size, Event *event,
 153               uint8_t *data, Tick delay, Request::Flags flag = 0);
 154
 155     RequestPtr
 156     dmaAction(Packet::Command cmd, Addr addr, int size, Event *event,
 157               uint8_t *data, uint32_t sid, uint32_t ssid, Tick delay,
 158               Request::Flags flag = 0);
 159
 160     bool dmaPending() const { return pendingCount > 0; }
 161
 162     DrainState drain() override;
 163 };
 164
 165 class DmaDevice : public PioDevice
 166 {
 167    protected:
 168     DmaPort dmaPort;
 169
 170   public:
 171     typedef DmaDeviceParams Params;
 172     DmaDevice(const Params *p);
 173     virtual ~DmaDevice() { }
 174
 175     void dmaWrite(Addr addr, int size, Event *event, uint8_t *data,
 176                   uint32_t sid, uint32_t ssid, Tick delay = 0)
 177     {
 178         dmaPort.dmaAction(MemCmd::WriteReq, addr, size, event, data,
 179                           sid, ssid, delay);
 180     }
 181
 182     void dmaWrite(Addr addr, int size, Event *event, uint8_t *data,
 183                   Tick delay = 0)
 184     {
 185         dmaPort.dmaAction(MemCmd::WriteReq, addr, size, event, data, delay);
 186     }
 187
 188     void dmaRead(Addr addr, int size, Event *event, uint8_t *data,
 189                  uint32_t sid, uint32_t ssid, Tick delay = 0)
 190     {
 191         dmaPort.dmaAction(MemCmd::ReadReq, addr, size, event, data,
 192                           sid, ssid, delay);
 193     }
 194
 195     void dmaRead(Addr addr, int size, Event *event, uint8_t *data,
 196                  Tick delay = 0)
 197     {
 198         dmaPort.dmaAction(MemCmd::ReadReq, addr, size, event, data, delay);
 199     }
 200
 201     bool dmaPending() const { return dmaPort.dmaPending(); }
 202
 203     void init() override;
 204
 205     unsigned int cacheBlockSize() const { return sys->cacheLineSize(); }
 206
 207     Port &getPort(const std::string &if_name,
 208                   PortID idx=InvalidPortID) override;
 209
 210 };
 211
 212 /**
 213  * DMA callback class.
 214  *
 215  * Allows one to register for a callback event after a sequence of (potentially
 216  * non-contiguous) DMA transfers on a DmaPort completes.  Derived classes must
 217  * implement the process() method and use getChunkEvent() to allocate a
 218  * callback event for each participating DMA.
 219  */
 220 class DmaCallback : public Drainable
 221 {
 222   public:
 223     virtual const std::string name() const { return "DmaCallback"; }
 224
 225     /**
 226      * DmaPort ensures that all oustanding DMA accesses have completed before
 227      * it finishes draining.  However, DmaChunkEvents scheduled with a delay
 228      * might still be sitting on the event queue.  Therefore, draining is not
 229      * complete until count is 0, which ensures that all outstanding
 230      * DmaChunkEvents associated with this DmaCallback have fired.
 231      */
 232     DrainState drain() override
 233     {
 234         return count ? DrainState::Draining : DrainState::Drained;
 235     }
 236
 237   protected:
 238     int count;
 239
 240     DmaCallback()
 241         : count(0)
 242     { }
 243
 244     virtual ~DmaCallback() { }
 245
 246     /**
 247      * Callback function invoked on completion of all chunks.
 248      */
 249     virtual void process() = 0;
 250
 251   private:
 252     /**
 253      * Called by DMA engine completion event on each chunk completion.
 254      * Since the object may delete itself here, callers should not use
 255      * the object pointer after calling this function.
 256      */
 257     void chunkComplete()
 258     {
 259         if (--count == 0) {
 260             process();
 261             // Need to notify DrainManager that this object is finished
 262             // draining, even though it is immediately deleted.
 263             signalDrainDone();
 264             delete this;
 265         }
 266     }
 267
 268   public:
 269
 270     /**
 271      * Request a chunk event.  Chunks events should be provided to each DMA
 272      * request that wishes to participate in this DmaCallback.
 273      */
 274     Event *getChunkEvent()
 275     {
 276         ++count;
 277         return new EventFunctionWrapper([this]{ chunkComplete(); }, name(),
 278                                         true);
 279     }
 280 };
 281
 282 /**
 283  * Buffered DMA engine helper class
 284  *
 285  * This class implements a simple DMA engine that feeds a FIFO
 286  * buffer. The size of the buffer, the maximum number of pending
 287  * requests and the maximum request size are all set when the engine
 288  * is instantiated.
 289  *
 290  * An <i>asynchronous</i> transfer of a <i>block</i> of data
 291  * (designated by a start address and a size) is started by calling
 292  * the startFill() method. The DMA engine will aggressively try to
 293  * keep the internal FIFO full. As soon as there is room in the FIFO
 294  * for more data <i>and</i> there are free request slots, a new fill
 295  * will be started.
 296  *
 297  * Data in the FIFO can be read back using the get() and tryGet()
 298  * methods. Both request a block of data from the FIFO. However, get()
 299  * panics if the block cannot be satisfied, while tryGet() simply
 300  * returns false. The latter call makes it possible to implement
 301  * custom buffer underrun handling.
 302  *
 303  * A simple use case would be something like this:
 304  * \code{.cpp}
 305  *     // Create a DMA engine with a 1KiB buffer. Issue up to 8 concurrent
 306  *     // uncacheable 64 byte (maximum) requests.
 307  *     DmaReadFifo *dma = new DmaReadFifo(port, 1024, 64, 8,
 308  *                                        Request::UNCACHEABLE);
 309  *
 310  *     // Start copying 4KiB data from 0xFF000000
 311  *     dma->startFill(0xFF000000, 0x1000);
 312  *
 313  *     // Some time later when there is data in the FIFO.
 314  *     uint8_t data[8];
 315  *     dma->get(data, sizeof(data))
 316  * \endcode
 317  *
 318  *
 319  * The DMA engine allows new blocks to be requested as soon as the
 320  * last request for a block has been sent (i.e., there is no need to
 321  * wait for pending requests to complete). This can be queried with
 322  * the atEndOfBlock() method and more advanced implementations may
 323  * override the onEndOfBlock() callback.
 324  */
 325 class DmaReadFifo : public Drainable, public Serializable
 326 {
 327   public:
 328     DmaReadFifo(DmaPort &port, size_t size,
 329                 unsigned max_req_size,
 330                 unsigned max_pending,
 331                 Request::Flags flags = 0);
 332
 333     ~DmaReadFifo();
 334
 335   public: // Serializable
 336     void serialize(CheckpointOut &cp) const override;
 337     void unserialize(CheckpointIn &cp) override;
 338
 339   public: // Drainable
 340     DrainState drain() override;
 341
 342   public: // FIFO access
 343     /**
 344      * @{
 345      * @name FIFO access
 346      */
 347     /**
 348      * Try to read data from the FIFO.
 349      *
 350      * This method reads len bytes of data from the FIFO and stores
 351      * them in the memory location pointed to by dst. The method
 352      * fails, and no data is written to the buffer, if the FIFO
 353      * doesn't contain enough data to satisfy the request.
 354      *
 355      * @param dst Pointer to a destination buffer
 356      * @param len Amount of data to read.
 357      * @return true on success, false otherwise.
 358      */
 359     bool tryGet(uint8_t *dst, size_t len);
 360
 361     template<typename T>
 362     bool tryGet(T &value) {
 363         return tryGet(static_cast<T *>(&value), sizeof(T));
 364     };
 365
 366     /**
 367      * Read data from the FIFO and panic on failure.
 368      *
 369      * @see tryGet()
 370      *
 371      * @param dst Pointer to a destination buffer
 372      * @param len Amount of data to read.
 373      */
 374     void get(uint8_t *dst, size_t len);
 375
 376     template<typename T>
 377     T get() {
 378         T value;
 379         get(static_cast<uint8_t *>(&value), sizeof(T));
 380         return value;
 381     };
 382
 383     /** Get the amount of data stored in the FIFO */
 384     size_t size() const { return buffer.size(); }
 385     /** Flush the FIFO */
 386     void flush() { buffer.flush(); }
 387
 388     /** @} */
 389   public: // FIFO fill control
 390     /**
 391      * @{
 392      * @name FIFO fill control
 393      */
 394     /**
 395      * Start filling the FIFO.
 396      *
 397      * @warn It's considered an error to call start on an active DMA
 398      * engine unless the last request from the active block has been
 399      * sent (i.e., atEndOfBlock() is true).
 400      *
 401      * @param start Physical address to copy from.
 402      * @param size Size of the block to copy.
 403      */
 404     void startFill(Addr start, size_t size);
 405
 406     /**
 407      * Stop the DMA engine.
 408      *
 409      * Stop filling the FIFO and ignore incoming responses for pending
 410      * requests. The onEndOfBlock() callback will not be called after
 411      * this method has been invoked. However, once the last response
 412      * has been received, the onIdle() callback will still be called.
 413      */
 414     void stopFill();
 415
 416     /**
 417      * Has the DMA engine sent out the last request for the active
 418      * block?
 419      */
 420     bool atEndOfBlock() const {
 421         return nextAddr == endAddr;
 422     }
 423
 424     /**
 425      * Is the DMA engine active (i.e., are there still in-flight
 426      * accesses)?
 427      */
 428     bool isActive() const {
 429         return !(pendingRequests.empty() && atEndOfBlock());
 430     }
 431
 432     /** @} */
 433   protected: // Callbacks
 434     /**
 435      * @{
 436      * @name Callbacks
 437      */
 438     /**
 439      * End of block callback
 440      *
 441      * This callback is called <i>once</i> after the last access in a
 442      * block has been sent. It is legal for a derived class to call
 443      * startFill() from this method to initiate a transfer.
 444      */
 445     virtual void onEndOfBlock() {};
 446
 447     /**
 448      * Last response received callback
 449      *
 450      * This callback is called when the DMA engine becomes idle (i.e.,
 451      * there are no pending requests).
 452      *
 453      * It is possible for a DMA engine to reach the end of block and
 454      * become idle at the same tick. In such a case, the
 455      * onEndOfBlock() callback will be called first. This callback
 456      * will <i>NOT</i> be called if that callback initiates a new DMA transfer.
 457      */
 458     virtual void onIdle() {};
 459
 460     /** @} */
 461   private: // Configuration
 462     /** Maximum request size in bytes */
 463     const Addr maxReqSize;
 464     /** Maximum FIFO size in bytes */
 465     const size_t fifoSize;
 466     /** Request flags */
 467     const Request::Flags reqFlags;
 468
 469     DmaPort &port;
 470
 471   private:
 472     class DmaDoneEvent : public Event
 473     {
 474       public:
 475         DmaDoneEvent(DmaReadFifo *_parent, size_t max_size);
 476
 477         void kill();
 478         void cancel();
 479         bool canceled() const { return _canceled; }
 480         void reset(size_t size);
 481         void process();
 482
 483         bool done() const { return _done; }
 484         size_t requestSize() const { return _requestSize; }
 485         const uint8_t *data() const { return _data.data(); }
 486         uint8_t *data() { return _data.data(); }
 487
 488       private:
 489         DmaReadFifo *parent;
 490         bool _done;
 491         bool _canceled;
 492         size_t _requestSize;
 493         std::vector<uint8_t> _data;
 494     };
 495
 496     typedef std::unique_ptr<DmaDoneEvent> DmaDoneEventUPtr;
 497
 498     /**
 499      * DMA request done, handle incoming data and issue new
 500      * request.
 501      */
 502     void dmaDone();
 503
 504     /** Handle pending requests that have been flagged as done. */
 505     void handlePending();
 506
 507     /** Try to issue new DMA requests or bypass DMA requests*/
 508     void resumeFill();
 509
 510     /** Try to issue new DMA requests during normal execution*/
 511     void resumeFillTiming();
 512
 513     /** Try to bypass DMA requests in KVM execution mode */
 514     void resumeFillFunctional();
 515
 516   private: // Internal state
 517     Fifo<uint8_t> buffer;
 518
 519     Addr nextAddr;
 520     Addr endAddr;
 521
 522     std::deque<DmaDoneEventUPtr> pendingRequests;
 523     std::deque<DmaDoneEventUPtr> freeRequests;
 524 };
 525
 526 #endif // __DEV_DMA_DEVICE_HH__