gem5::DmaReadFifo Class Reference

Buffered DMA engine helper class. More...

#include <dma_device.hh>

Inheritance diagram for gem5::DmaReadFifo:

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.
void	unserialize (CheckpointIn &cp) override
	Unserialize an object.
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.
FIFO access
bool	tryGet (uint8_t *dst, size_t len)
	Try to read data from the FIFO.
template<typename T >
bool	tryGet (T &value)
void	get (uint8_t *dst, size_t len)
	Read data from the FIFO and panic on failure.
template<typename T >
T	get ()
size_t	size () const
	Get the amount of data stored in the FIFO.
void	flush ()
	Flush the FIFO.
FIFO fill control
void	startFill (Addr start, size_t size)
	Start filling the FIFO.
void	stopFill ()
	Stop the DMA engine.
bool	atEndOfBlock () const
	Has the DMA engine sent out the last request for the active block?
bool	isActive () const
	Is the DMA engine active (i.e., are there still in-flight accesses)?
Public Member Functions inherited from gem5::Drainable
DrainState	drainState () const
	Return the current drain state of an object.
virtual void	notifyFork ()
	Notify a child process of a fork.
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.
void	serializeSection (CheckpointOut &cp, const std::string &name) const
void	unserializeSection (CheckpointIn &cp, const char *name)
	Unserialize an a child object.
void	unserializeSection (CheckpointIn &cp, const std::string &name)

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

Private Types
typedef std::unique_ptr< DmaDoneEvent >	DmaDoneEventUPtr

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

Private Attributes
const Addr	maxReqSize
	Maximum request size in bytes.
const size_t	fifoSize
	Maximum FIFO size in bytes.
const Request::Flags	reqFlags
	Request flags.
DmaPort &	port
const Addr	cacheLineSize
Fifo< uint8_t >	buffer
Addr	nextAddr = 0
Addr	endAddr = 0
std::deque< DmaDoneEventUPtr >	pendingRequests
std::deque< DmaDoneEventUPtr >	freeRequests

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.
static void	generateCheckpointOut (const std::string &cpt_dir, std::ofstream &outstream)
	Generate a checkpoint file so that the serialization can be routed to it.

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,
                                   Request::UNCACHEABLE);
 
// 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 379 of file dma_device.hh.

Member Typedef Documentation

DmaDoneEventUPtr

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

private

Definition at line 556 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 426 of file dma_device.cc.

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

~DmaReadFifo()

gem5::DmaReadFifo::~DmaReadFifo

(

)

Definition at line 440 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 478 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 583 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 614 of file dma_device.cc.

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

flush()

void gem5::DmaReadFifo::flush ( )

inline

Flush the FIFO.

Definition at line 444 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 434 of file dma_device.hh.

References get().

Referenced by get().

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

dst	Pointer to a destination buffer
len	Amount of data to read.

Definition at line 487 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 595 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 485 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 503 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 516 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 516 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

Try to bypass DMA requests in non-caching mode.

Definition at line 535 of file dma_device.cc.

References buffer, cacheLineSize, gem5::Fifo< T >::capacity(), gem5::DmaPort::dmaAction(), DPRINTF, endAddr, nextAddr, pendingRequests, port, gem5::MemCmd::ReadReq, reqFlags, gem5::Fifo< T >::size(), and gem5::Fifo< T >::write().

Referenced by resumeFill().

resumeFillTiming()

void gem5::DmaReadFifo::resumeFillTiming ( )

private

Try to issue new DMA requests during normal execution.

Definition at line 557 of file dma_device.cc.

References atEndOfBlock(), buffer, gem5::DmaPort::dmaAction(), gem5::ArmISA::e, endAddr, gem5::MipsISA::event, fifoSize, freeRequests, maxReqSize, nextAddr, pendingRequests, port, gem5::MemCmd::ReadReq, reqFlags, and gem5::Fifo< T >::size().

Referenced by resumeFill().

serialize()

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

overridevirtual

Serialize an object.

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

Parameters

cp	Checkpoint state

Implements gem5::Serializable.

Definition at line 457 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 442 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

start	Physical address to copy from.
size	Size of the block to copy.

Definition at line 493 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 503 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 417 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

dst	Pointer to a destination buffer
len	Amount of data to read.

Returns

true on success, false otherwise.

Definition at line 475 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

cp	Checkpoint state

Implements gem5::Serializable.

Definition at line 467 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

Definition at line 577 of file dma_device.hh.

Referenced by flush(), handlePending(), resumeFillBypass(), resumeFillTiming(), serialize(), size(), tryGet(), and unserialize().

cacheLineSize

const Addr gem5::DmaReadFifo::cacheLineSize

private

Definition at line 529 of file dma_device.hh.

Referenced by resumeFillBypass().

endAddr

Addr gem5::DmaReadFifo::endAddr = 0

private

Definition at line 580 of file dma_device.hh.

Referenced by atEndOfBlock(), resumeFillBypass(), resumeFillTiming(), serialize(), startFill(), stopFill(), and unserialize().

fifoSize

const size_t gem5::DmaReadFifo::fifoSize

private

Maximum FIFO size in bytes.

Definition at line 523 of file dma_device.hh.

Referenced by resumeFillTiming().

freeRequests

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

private

Definition at line 583 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 521 of file dma_device.hh.

Referenced by resumeFillTiming().

nextAddr

Addr gem5::DmaReadFifo::nextAddr = 0

private

Definition at line 579 of file dma_device.hh.

Referenced by atEndOfBlock(), resumeFillBypass(), resumeFillTiming(), serialize(), startFill(), stopFill(), and unserialize().

pendingRequests

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

private

Definition at line 582 of file dma_device.hh.

Referenced by drain(), handlePending(), isActive(), resumeFillBypass(), resumeFillTiming(), serialize(), stopFill(), and ~DmaReadFifo().

port

DmaPort& gem5::DmaReadFifo::port

private

Definition at line 527 of file dma_device.hh.

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

reqFlags

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

private

Request flags.

Definition at line 525 of file dma_device.hh.

Referenced by resumeFillBypass(), and resumeFillTiming().

---

The documentation for this class was generated from the following files:

• dev/dma_device.hh
• dev/dma_device.cc