gem5  v21.1.0.2
Classes | Public Member Functions | Private Types | Private Member Functions | Private Attributes | List of all members
gem5::DmaReadFifo Class Reference

Buffered DMA engine helper class. More...

#include <dma_device.hh>

Inheritance diagram for gem5::DmaReadFifo:
gem5::Drainable gem5::Serializable gem5::HDLcd::DmaEngine

Classes

class  DmaDoneEvent
 

Public Member Functions

 DmaReadFifo (DmaPort &port, size_t size, unsigned max_req_size, unsigned max_pending, Request::Flags flags=0)
 
 ~DmaReadFifo ()
 
void serialize (CheckpointOut &cp) const override
 Serialize an object. More...
 
void unserialize (CheckpointIn &cp) override
 Unserialize an object. More...
 
DrainState drain () override
 Draining is the process of clearing out the states of SimObjects.These are the SimObjects that are partially executed or are partially in flight. More...
 
FIFO access
bool tryGet (uint8_t *dst, size_t len)
 Try to read data from the FIFO. More...
 
template<typename T >
bool tryGet (T &value)
 
void get (uint8_t *dst, size_t len)
 Read data from the FIFO and panic on failure. More...
 
template<typename T >
get ()
 
size_t size () const
 Get the amount of data stored in the FIFO. More...
 
void flush ()
 Flush the FIFO. More...
 
FIFO fill control
void startFill (Addr start, size_t size)
 Start filling the FIFO. More...
 
void stopFill ()
 Stop the DMA engine. More...
 
bool atEndOfBlock () const
 Has the DMA engine sent out the last request for the active block? More...
 
bool isActive () const
 Is the DMA engine active (i.e., are there still in-flight accesses)? More...
 
- Public Member Functions inherited from gem5::Drainable
DrainState drainState () const
 Return the current drain state of an object. More...
 
virtual void notifyFork ()
 Notify a child process of a fork. More...
 
- Public Member Functions inherited from gem5::Serializable
 Serializable ()
 
virtual ~Serializable ()
 
void serializeSection (CheckpointOut &cp, const char *name) const
 Serialize an object into a new section. More...
 
void serializeSection (CheckpointOut &cp, const std::string &name) const
 
void unserializeSection (CheckpointIn &cp, const char *name)
 Unserialize an a child object. More...
 
void unserializeSection (CheckpointIn &cp, const std::string &name)
 

Protected Member Functions

Callbacks
virtual void onEndOfBlock ()
 End of block callback. More...
 
virtual void onIdle ()
 Last response received callback. More...
 
- Protected Member Functions inherited from gem5::Drainable
 Drainable ()
 
virtual ~Drainable ()
 
virtual void drainResume ()
 Resume execution after a successful drain. More...
 
void signalDrainDone () const
 Signal that an object is drained. More...
 

Private Types

typedef std::unique_ptr< DmaDoneEventDmaDoneEventUPtr
 

Private Member Functions

void dmaDone ()
 DMA request done, handle incoming data and issue new request. More...
 
void handlePending ()
 Handle pending requests that have been flagged as done. More...
 
void resumeFill ()
 Try to issue new DMA requests or bypass DMA requests. More...
 
void resumeFillTiming ()
 Try to issue new DMA requests during normal execution. More...
 
void resumeFillBypass ()
 Try to bypass DMA requests in non-caching mode. More...
 

Private Attributes

const Addr maxReqSize
 Maximum request size in bytes. More...
 
const size_t fifoSize
 Maximum FIFO size in bytes. More...
 
const Request::Flags reqFlags
 Request flags. More...
 
DmaPortport
 
const int cacheLineSize
 
Fifo< uint8_t > buffer
 
Addr nextAddr = 0
 
Addr endAddr = 0
 
std::deque< DmaDoneEventUPtrpendingRequests
 
std::deque< DmaDoneEventUPtrfreeRequests
 

Additional Inherited Members

- Static Public Member Functions inherited from gem5::Serializable
static const std::string & currentSection ()
 Gets the fully-qualified name of the active section. More...
 
static void generateCheckpointOut (const std::string &cpt_dir, std::ofstream &outstream)
 Generate a checkpoint file so that the serialization can be routed to it. More...
 

Detailed Description

Buffered DMA engine helper class.

This class implements a simple DMA engine that feeds a FIFO buffer. The size of the buffer, the maximum number of pending requests and the maximum request size are all set when the engine is instantiated.

An asynchronous transfer of a block of data (designated by a start address and a size) is started by calling the startFill() method. The DMA engine will aggressively try to keep the internal FIFO full. As soon as there is room in the FIFO for more data and there are free request slots, a new fill will be started.

Data in the FIFO can be read back using the get() and tryGet() methods. Both request a block of data from the FIFO. However, get() panics if the block cannot be satisfied, while tryGet() simply returns false. The latter call makes it possible to implement custom buffer underrun handling.

A simple use case would be something like this:

// Create a DMA engine with a 1KiB buffer. Issue up to 8 concurrent
// uncacheable 64 byte (maximum) requests.
DmaReadFifo *dma = new DmaReadFifo(port, 1024, 64, 8,
// Start copying 4KiB data from 0xFF000000
dma->startFill(0xFF000000, 0x1000);
// Some time later when there is data in the FIFO.
uint8_t data[8];
dma->get(data, sizeof(data))

The DMA engine allows new blocks to be requested as soon as the last request for a block has been sent (i.e., there is no need to wait for pending requests to complete). This can be queried with the atEndOfBlock() method and more advanced implementations may override the onEndOfBlock() callback.

Definition at line 364 of file dma_device.hh.

Member Typedef Documentation

◆ DmaDoneEventUPtr

typedef std::unique_ptr<DmaDoneEvent> gem5::DmaReadFifo::DmaDoneEventUPtr
private

Definition at line 541 of file dma_device.hh.

Constructor & Destructor Documentation

◆ DmaReadFifo()

gem5::DmaReadFifo::DmaReadFifo ( DmaPort port,
size_t  size,
unsigned  max_req_size,
unsigned  max_pending,
Request::Flags  flags = 0 
)

Definition at line 371 of file dma_device.cc.

References gem5::ArmISA::e, and freeRequests.

◆ ~DmaReadFifo()

gem5::DmaReadFifo::~DmaReadFifo ( )

Definition at line 385 of file dma_device.cc.

References gem5::ArmISA::e, gem5::MipsISA::p, and pendingRequests.

Member Function Documentation

◆ atEndOfBlock()

bool gem5::DmaReadFifo::atEndOfBlock ( ) const
inline

Has the DMA engine sent out the last request for the active block?

Definition at line 463 of file dma_device.hh.

References endAddr, and nextAddr.

Referenced by isActive(), resumeFill(), resumeFillTiming(), and startFill().

◆ dmaDone()

void gem5::DmaReadFifo::dmaDone ( )
private

DMA request done, handle incoming data and issue new request.

Definition at line 528 of file dma_device.cc.

References handlePending(), isActive(), onIdle(), and resumeFill().

◆ drain()

DrainState gem5::DmaReadFifo::drain ( )
overridevirtual

Draining is the process of clearing out the states of SimObjects.These are the SimObjects that are partially executed or are partially in flight.

Draining is mostly used before forking and creating a check point.

This function notifies an object that it needs to drain its state.

If the object does not need further simulation to drain internal buffers, it returns DrainState::Drained and automatically switches to the Drained state. If the object needs more simulation, it returns DrainState::Draining and automatically enters the Draining state. Other return values are invalid.

Note
An object that has entered the Drained state can be disturbed by other objects in the system and consequently stop being drained. These perturbations are not visible in the drain state. The simulator therefore repeats the draining process until all objects return DrainState::Drained on the first call to drain().
Returns
DrainState::Drained if the object is drained at this point in time, DrainState::Draining if it needs further simulation.

Implements gem5::Drainable.

Definition at line 559 of file dma_device.cc.

References gem5::Drained, gem5::Draining, and pendingRequests.

◆ flush()

void gem5::DmaReadFifo::flush ( )
inline

Flush the FIFO.

Definition at line 429 of file dma_device.hh.

References buffer, and gem5::Fifo< T >::flush().

◆ get() [1/2]

template<typename T >
T gem5::DmaReadFifo::get ( )
inline

Definition at line 419 of file dma_device.hh.

◆ get() [2/2]

void gem5::DmaReadFifo::get ( uint8_t *  dst,
size_t  len 
)

Read data from the FIFO and panic on failure.

See also
tryGet()
Parameters
dstPointer to a destination buffer
lenAmount of data to read.

Definition at line 432 of file dma_device.cc.

References gem5::ArmISA::len, panic_if, and tryGet().

◆ handlePending()

void gem5::DmaReadFifo::handlePending ( )
private

Handle pending requests that have been flagged as done.

Definition at line 540 of file dma_device.cc.

References buffer, gem5::MipsISA::event, freeRequests, pendingRequests, gem5::Drainable::signalDrainDone(), and gem5::Fifo< T >::write().

Referenced by dmaDone().

◆ isActive()

bool gem5::DmaReadFifo::isActive ( ) const
inline

Is the DMA engine active (i.e., are there still in-flight accesses)?

Definition at line 470 of file dma_device.hh.

References atEndOfBlock(), and pendingRequests.

Referenced by dmaDone().

◆ onEndOfBlock()

virtual void gem5::DmaReadFifo::onEndOfBlock ( )
inlineprotectedvirtual

End of block callback.

This callback is called once after the last access in a block has been sent. It is legal for a derived class to call startFill() from this method to initiate a transfer.

Reimplemented in gem5::HDLcd::DmaEngine.

Definition at line 488 of file dma_device.hh.

Referenced by resumeFill().

◆ onIdle()

virtual void gem5::DmaReadFifo::onIdle ( )
inlineprotectedvirtual

Last response received callback.

This callback is called when the DMA engine becomes idle (i.e., there are no pending requests).

It is possible for a DMA engine to reach the end of block and become idle at the same tick. In such a case, the onEndOfBlock() callback will be called first. This callback will NOT be called if that callback initiates a new DMA transfer.

Reimplemented in gem5::HDLcd::DmaEngine.

Definition at line 501 of file dma_device.hh.

Referenced by dmaDone().

◆ resumeFill()

void gem5::DmaReadFifo::resumeFill ( )
private

Try to issue new DMA requests or bypass DMA requests.

Definition at line 461 of file dma_device.cc.

References atEndOfBlock(), gem5::System::bypassCaches(), gem5::Draining, gem5::Drainable::drainState(), onEndOfBlock(), port, resumeFillBypass(), resumeFillTiming(), and gem5::DmaPort::sys.

Referenced by dmaDone(), startFill(), and tryGet().

◆ resumeFillBypass()

void gem5::DmaReadFifo::resumeFillBypass ( )
private

◆ resumeFillTiming()

void gem5::DmaReadFifo::resumeFillTiming ( )
private

◆ serialize()

void gem5::DmaReadFifo::serialize ( CheckpointOut cp) const
overridevirtual

Serialize an object.

Output an object's state into the current checkpoint section.

Parameters
cpCheckpoint state

Implements gem5::Serializable.

Definition at line 402 of file dma_device.cc.

References buffer, endAddr, nextAddr, pendingRequests, SERIALIZE_CONTAINER, and SERIALIZE_SCALAR.

Referenced by gem5::HDLcd::DmaEngine::serialize().

◆ size()

size_t gem5::DmaReadFifo::size ( ) const
inline

Get the amount of data stored in the FIFO.

Definition at line 427 of file dma_device.hh.

References buffer, and gem5::Fifo< T >::size().

Referenced by gem5::DmaReadFifo::DmaDoneEvent::reset(), and startFill().

◆ startFill()

void gem5::DmaReadFifo::startFill ( Addr  start,
size_t  size 
)

Start filling the FIFO.

@warn It's considered an error to call start on an active DMA engine unless the last request from the active block has been sent (i.e., atEndOfBlock() is true).

Parameters
startPhysical address to copy from.
sizeSize of the block to copy.

Definition at line 438 of file dma_device.cc.

References atEndOfBlock(), endAddr, nextAddr, resumeFill(), and size().

◆ stopFill()

void gem5::DmaReadFifo::stopFill ( )

Stop the DMA engine.

Stop filling the FIFO and ignore incoming responses for pending requests. The onEndOfBlock() callback will not be called after this method has been invoked. However, once the last response has been received, the onIdle() callback will still be called.

Definition at line 448 of file dma_device.cc.

References endAddr, nextAddr, gem5::MipsISA::p, and pendingRequests.

◆ tryGet() [1/2]

template<typename T >
bool gem5::DmaReadFifo::tryGet ( T &  value)
inline

Definition at line 402 of file dma_device.hh.

References tryGet().

◆ tryGet() [2/2]

bool gem5::DmaReadFifo::tryGet ( uint8_t *  dst,
size_t  len 
)

Try to read data from the FIFO.

This method reads len bytes of data from the FIFO and stores them in the memory location pointed to by dst. The method fails, and no data is written to the buffer, if the FIFO doesn't contain enough data to satisfy the request.

Parameters
dstPointer to a destination buffer
lenAmount of data to read.
Returns
true on success, false otherwise.

Definition at line 420 of file dma_device.cc.

References buffer, gem5::ArmISA::len, gem5::Fifo< T >::read(), resumeFill(), and gem5::Fifo< T >::size().

Referenced by get(), and tryGet().

◆ unserialize()

void gem5::DmaReadFifo::unserialize ( CheckpointIn cp)
overridevirtual

Unserialize an object.

Read an object's state from the current checkpoint section.

Parameters
cpCheckpoint state

Implements gem5::Serializable.

Definition at line 412 of file dma_device.cc.

References buffer, endAddr, nextAddr, UNSERIALIZE_CONTAINER, and UNSERIALIZE_SCALAR.

Referenced by gem5::HDLcd::DmaEngine::unserialize().

Member Data Documentation

◆ buffer

Fifo<uint8_t> gem5::DmaReadFifo::buffer
private

◆ cacheLineSize

const int gem5::DmaReadFifo::cacheLineSize
private

Definition at line 514 of file dma_device.hh.

Referenced by resumeFillBypass().

◆ endAddr

Addr gem5::DmaReadFifo::endAddr = 0
private

◆ fifoSize

const size_t gem5::DmaReadFifo::fifoSize
private

Maximum FIFO size in bytes.

Definition at line 508 of file dma_device.hh.

Referenced by resumeFillTiming().

◆ freeRequests

std::deque<DmaDoneEventUPtr> gem5::DmaReadFifo::freeRequests
private

Definition at line 568 of file dma_device.hh.

Referenced by DmaReadFifo(), handlePending(), and resumeFillTiming().

◆ maxReqSize

const Addr gem5::DmaReadFifo::maxReqSize
private

Maximum request size in bytes.

Definition at line 501 of file dma_device.hh.

Referenced by resumeFillTiming().

◆ nextAddr

Addr gem5::DmaReadFifo::nextAddr = 0
private

◆ pendingRequests

std::deque<DmaDoneEventUPtr> gem5::DmaReadFifo::pendingRequests
private

◆ port

DmaPort& gem5::DmaReadFifo::port
private

Definition at line 512 of file dma_device.hh.

Referenced by resumeFill(), resumeFillBypass(), and resumeFillTiming().

◆ reqFlags

const Request::Flags gem5::DmaReadFifo::reqFlags
private

Request flags.

Definition at line 510 of file dma_device.hh.

Referenced by resumeFillBypass(), and resumeFillTiming().


The documentation for this class was generated from the following files:
data
const char data[]
Definition: circlebuf.test.cc:48
gem5::DmaReadFifo::port
DmaPort & port
Definition: dma_device.hh:512
gem5::Request::UNCACHEABLE
@ UNCACHEABLE
The request is to an uncacheable address.
Definition: request.hh:125
gem5::DmaReadFifo::DmaReadFifo
DmaReadFifo(DmaPort &port, size_t size, unsigned max_req_size, unsigned max_pending, Request::Flags flags=0)
Definition: dma_device.cc:371

Generated on Tue Sep 21 2021 12:27:30 for gem5 by doxygen 1.8.17