Buffered DMA engine helper class. More...

#include <dma_device.hh>

Inheritance diagram for 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. 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 >
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 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 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 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< DmaDoneEvent >	DmaDoneEventUPtr

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	resumeFillFunctional ()
	Try to bypass DMA requests in KVM execution 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...

DmaPort &	port

Fifo< uint8_t >	buffer

Addr	nextAddr

Addr	endAddr

std::deque< DmaDoneEventUPtr >	pendingRequests

std::deque< DmaDoneEventUPtr >	freeRequests

Additional Inherited Members
Static Public Member Functions inherited from Serializable
static const std::string &	currentSection ()
	Gets the fully-qualified name of the active section. More...

static void	serializeAll (const std::string &cpt_dir)
	Serializes all the SimObjects. More...

static void	unserializeGlobals (CheckpointIn &cp)

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 325 of file dma_device.hh.

Member Typedef Documentation

◆ DmaDoneEventUPtr

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

private

Definition at line 496 of file dma_device.hh.

Constructor & Destructor Documentation

◆ DmaReadFifo()

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

Definition at line 285 of file dma_device.cc.

References ArmISA::e, and freeRequests.

◆ ~DmaReadFifo()

DmaReadFifo::~DmaReadFifo ( )

Definition at line 300 of file dma_device.cc.

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

Member Function Documentation

◆ atEndOfBlock()

bool DmaReadFifo::atEndOfBlock ( ) const

inline

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

Definition at line 420 of file dma_device.hh.

References endAddr, and nextAddr.

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

◆ dmaDone()

void DmaReadFifo::dmaDone ( )

private

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

Definition at line 443 of file dma_device.cc.

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

◆ drain()

DrainState 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 Drainable.

Definition at line 474 of file dma_device.cc.

References Drained, Draining, and pendingRequests.

◆ flush()

void DmaReadFifo::flush ( )

inline

Flush the FIFO.

Definition at line 386 of file dma_device.hh.

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

◆ get() [1/2]

template<typename T >

T DmaReadFifo::get ( )

inline

Definition at line 377 of file dma_device.hh.

◆ get() [2/2]

void 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 347 of file dma_device.cc.

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

◆ handlePending()

void DmaReadFifo::handlePending ( )

private

Handle pending requests that have been flagged as done.

Definition at line 455 of file dma_device.cc.

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

Referenced by dmaDone().

◆ isActive()

bool DmaReadFifo::isActive ( ) const

inline

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

Definition at line 428 of file dma_device.hh.

References atEndOfBlock(), and pendingRequests.

Referenced by dmaDone().

◆ onEndOfBlock()

virtual void 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 HDLcd::DmaEngine.

Definition at line 445 of file dma_device.hh.

Referenced by resumeFill().

◆ onIdle()

virtual void 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 HDLcd::DmaEngine.

Definition at line 458 of file dma_device.hh.

Referenced by dmaDone().

◆ resumeFill()

void DmaReadFifo::resumeFill ( )

private

Try to issue new DMA requests or bypass DMA requests.

Definition at line 377 of file dma_device.cc.

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

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

◆ resumeFillFunctional()

void DmaReadFifo::resumeFillFunctional ( )

private

Try to bypass DMA requests in KVM execution mode.

Definition at line 396 of file dma_device.cc.

References buffer, System::cacheLineSize(), Fifo< T >::capacity(), ContextSwitchTaskId::DMA, DPRINTF, endAddr, nextAddr, pendingRequests, System::physProxy, port, PortProxy::readBlob(), Fifo< T >::size(), DmaPort::sys, and Fifo< T >::write().

Referenced by resumeFill().

◆ resumeFillTiming()

void DmaReadFifo::resumeFillTiming ( )

private

Try to issue new DMA requests during normal execution.

Definition at line 417 of file dma_device.cc.

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

Referenced by resumeFill().

◆ serialize()

void DmaReadFifo::serialize ( CheckpointOut & cp ) const

overridevirtual

Serialize an object.

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

Parameters

cp	Checkpoint state

Implements Serializable.

Definition at line 317 of file dma_device.cc.

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

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

◆ size()

size_t DmaReadFifo::size ( ) const

inline

Get the amount of data stored in the FIFO.

Definition at line 384 of file dma_device.hh.

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

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

◆ startFill()

void 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 354 of file dma_device.cc.

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

◆ stopFill()

void 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 364 of file dma_device.cc.

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

◆ tryGet() [1/2]

template<typename T >

bool DmaReadFifo::tryGet ( T & value )

inline

Definition at line 362 of file dma_device.hh.

References tryGet().

◆ tryGet() [2/2]

bool 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 335 of file dma_device.cc.

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

Referenced by get(), and tryGet().

◆ unserialize()

void DmaReadFifo::unserialize ( CheckpointIn & cp )

overridevirtual

Unserialize an object.

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

Parameters

cp	Checkpoint state

Implements Serializable.

Definition at line 327 of file dma_device.cc.

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

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

Member Data Documentation

◆ buffer

Fifo<uint8_t> DmaReadFifo::buffer

private

Definition at line 517 of file dma_device.hh.

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

◆ endAddr

Addr DmaReadFifo::endAddr

private

Definition at line 520 of file dma_device.hh.

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

◆ fifoSize

const size_t DmaReadFifo::fifoSize

private

Maximum FIFO size in bytes.

Definition at line 465 of file dma_device.hh.

Referenced by resumeFillTiming().

◆ freeRequests

std::deque<DmaDoneEventUPtr> DmaReadFifo::freeRequests

private

Definition at line 523 of file dma_device.hh.

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

◆ maxReqSize

const Addr DmaReadFifo::maxReqSize

private

Maximum request size in bytes.

Definition at line 458 of file dma_device.hh.

Referenced by resumeFillTiming().

◆ nextAddr

Addr DmaReadFifo::nextAddr

private

Definition at line 519 of file dma_device.hh.

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

◆ pendingRequests

std::deque<DmaDoneEventUPtr> DmaReadFifo::pendingRequests

private

Definition at line 522 of file dma_device.hh.

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

◆ port

DmaPort& DmaReadFifo::port

private

Definition at line 469 of file dma_device.hh.

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

◆ reqFlags

const Request::Flags DmaReadFifo::reqFlags

private

Request flags.

Definition at line 467 of file dma_device.hh.

Referenced by resumeFillTiming().

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

dev/dma_device.hh
dev/dma_device.cc

Classes

Public Member Functions

Protected Member Functions

Private Types

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ DmaDoneEventUPtr

Constructor & Destructor Documentation

◆ DmaReadFifo()

◆ ~DmaReadFifo()

Member Function Documentation

◆ atEndOfBlock()

◆ dmaDone()

◆ drain()

◆ flush()

◆ get() [1/2]

◆ get() [2/2]

◆ handlePending()

◆ isActive()

◆ onEndOfBlock()

◆ onIdle()

◆ resumeFill()

◆ resumeFillFunctional()

◆ resumeFillTiming()

◆ serialize()

◆ size()

◆ startFill()

◆ stopFill()

◆ tryGet() [1/2]

◆ tryGet() [2/2]

◆ unserialize()

Member Data Documentation

◆ buffer

◆ endAddr

◆ fifoSize

◆ freeRequests

◆ maxReqSize

◆ nextAddr

◆ pendingRequests

◆ port

◆ reqFlags