src/dev/dma_device.hh

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