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
	Notify an object that it needs to drain its state. 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 ()
	Get the fully-qualified name of the active section. More...

static void	serializeAll (const std::string &cpt_dir)

static void	unserializeGlobals (CheckpointIn &cp)

Static Public Attributes inherited from Serializable
static int	ckptCount = 0

static int	ckptMaxCount = 0

static int	ckptPrevCount = -1

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

Member Typedef Documentation

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

private

Definition at line 486 of file dma_device.hh.

Constructor & Destructor Documentation

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

Definition at line 275 of file dma_device.cc.

References ArmISA::e, and freeRequests.

DmaReadFifo::~DmaReadFifo ( )

Definition at line 290 of file dma_device.cc.

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

Member Function Documentation

bool DmaReadFifo::atEndOfBlock ( ) const

inline

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

Definition at line 410 of file dma_device.hh.

References endAddr, and nextAddr.

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

void DmaReadFifo::dmaDone ( )

private

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

Definition at line 433 of file dma_device.cc.

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

DrainState DmaReadFifo::drain ( )

overridevirtual

Notify 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 464 of file dma_device.cc.

References Drained, Draining, and pendingRequests.

void DmaReadFifo::flush ( )

inline

Flush the FIFO.

Definition at line 376 of file dma_device.hh.

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

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

References panic_if(), and tryGet().

template<typename T >

T DmaReadFifo::get ( )

inline

Definition at line 367 of file dma_device.hh.

void DmaReadFifo::handlePending ( )

private

Handle pending requests that have been flagged as done.

Definition at line 445 of file dma_device.cc.

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

Referenced by dmaDone().

bool DmaReadFifo::isActive ( ) const

inline

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

Definition at line 418 of file dma_device.hh.

References atEndOfBlock(), and pendingRequests.

Referenced by dmaDone().

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

Referenced by resumeFill().

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

Referenced by dmaDone().

void DmaReadFifo::resumeFill ( )

private

Try to issue new DMA requests or bypass DMA requests.

Definition at line 367 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().

void DmaReadFifo::resumeFillFunctional ( )

private

Try to bypass DMA requests in KVM execution mode.

Definition at line 386 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().

void DmaReadFifo::resumeFillTiming ( )

private

Try to issue new DMA requests during normal execution.

Definition at line 407 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().

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

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

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

size_t DmaReadFifo::size ( ) const

inline

Get the amount of data stored in the FIFO.

Definition at line 374 of file dma_device.hh.

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

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

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

Start filling the FIFO.

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

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

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

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

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