VirtIO descriptor (chain) wrapper. More...

#include <base.hh>

Public Types
typedef uint16_t	Index
	Descriptor index in virtqueue. More...

Public Member Functions
VirtIO Descriptor <-> Queue Interface
	VirtDescriptor (PortProxy &memProxy, VirtQueue &queue, Index index)
	Create a descriptor wrapper. More...

	VirtDescriptor (VirtDescriptor &&other) noexcept

	~VirtDescriptor () noexcept

VirtDescriptor &	operator= (VirtDescriptor &&rhs) noexcept

Index	index () const
	Get the descriptor's index into the virtqueue. More...

void	update ()
	Populate this descriptor with data from the guest. More...

void	updateChain ()
	Populate this descriptor chain with data from the guest. More...

Debug interfaces
void	dump () const
	Dump the contents of a descriptor. More...

void	dumpChain () const
	Dump the contents of a descriptor chain starting at this descriptor. More...

Device Model Interfaces
void	read (size_t offset, uint8_t *dst, size_t size) const
	Read the contents of a descriptor. More...

void	write (size_t offset, const uint8_t *src, size_t size)
	Write to the contents of a descriptor. More...

size_t	size () const
	Retrieve the size of this descriptor. More...

bool	hasNext () const
	Is this descriptor chained to another descriptor? More...

VirtDescriptor *	next () const
	Get the pointer to the next descriptor in a chain. More...

bool	isIncoming () const
	Check if this is a read-only descriptor (incoming data). More...

bool	isOutgoing () const
	Check if this is a write-only descriptor (outgoing data). More...

void	chainRead (size_t offset, uint8_t *dst, size_t size) const
	Read the contents of a descriptor chain. More...

void	chainWrite (size_t offset, const uint8_t *src, size_t size)
	Write to a descriptor chain. More...

size_t	chainSize () const
	Retrieve the size of this descriptor chain. More...

Private Member Functions
	VirtDescriptor ()

	VirtDescriptor (const VirtDescriptor &other)

Private Attributes
PortProxy *	memProxy
	Pointer to memory proxy. More...

VirtQueue *	queue
	Pointer to virtqueue owning this descriptor. More...

Index	_index
	Index in virtqueue. More...

vring_desc	desc
	Underlying descriptor. More...

Detailed Description

VirtIO descriptor (chain) wrapper.

Communication in VirtIO takes place by sending and receiving chains of so called descriptors using device queues. The queue is responsible for sending a descriptor chain from the guest to the host and later sending it back to the guest. The descriptor chain itself can be thought of as a linked list of buffers (descriptors) that are read only (isIncoming() is true) or write only (isOutgoing() is true). A single chain may contain any mix of input and output buffers.

The descriptor wrapper is normally only instantiated by the virtqueue wrapper (VirtQueue) and should never be instantiated in device models. The VirtQueue also ensures that the descriptor wrapper is re-populated with new data from the guest by calling updateChain() whenever a new descriptor chain is passed to the host (VirtQueue::consumeDescriptor()). The updateChain() method automatically does some sanity checks on the descriptor chain to detect loops.

Definition at line 136 of file base.hh.

Member Typedef Documentation

typedef uint16_t VirtDescriptor::Index

Descriptor index in virtqueue.

Definition at line 140 of file base.hh.

Constructor & Destructor Documentation

VirtDescriptor::VirtDescriptor	(	PortProxy &	memProxy,
		VirtQueue &	queue,
		Index	index
	)

Create a descriptor wrapper.

Parameters

memProxy	Proxy to the guest physical memory.
queue	Queue owning this descriptor.
index	Index within the queue.

Definition at line 46 of file base.cc.

VirtDescriptor::VirtDescriptor ( VirtDescriptor && other )

noexcept

Definition at line 53 of file base.cc.

VirtDescriptor::~VirtDescriptor ( )

noexcept

Definition at line 58 of file base.cc.

VirtDescriptor::VirtDescriptor ( )

private

VirtDescriptor::VirtDescriptor ( const VirtDescriptor & other )

private

Member Function Documentation

void VirtDescriptor::chainRead	(	size_t	offset,
		uint8_t *	dst,
		size_t	size
	)		const

Read the contents of a descriptor chain.

This method reads the specified number of bytes from a descriptor chain starting at the this descriptor plus an offset in bytes. The method automatically follows the links in the descriptor chain.

Parameters

offset	Offset into the chain (in bytes).
dst	Pointer to destination buffer.
size	Size (in bytes).

Definition at line 168 of file base.cc.

References chainSize(), desc, isIncoming(), next(), ArmISA::offset, panic, read(), and size().

Referenced by VirtIOConsole::TermTransQueue::onNotifyDescriptor(), VirtIO9PBase::FSQueue::onNotifyDescriptor(), VirtIOBlock::RequestQueue::onNotifyDescriptor(), and VirtIOBlock::write().

size_t VirtDescriptor::chainSize ( ) const

Retrieve the size of this descriptor chain.

This method gets the size of a descriptor chain starting at this descriptor.

Returns: Size of descriptor chain in bytes.

Definition at line 214 of file base.cc.

References desc, next(), and size().

Referenced by chainRead(), chainWrite(), VirtIOConsole::TermTransQueue::onNotifyDescriptor(), and VirtIOBlock::RequestQueue::onNotifyDescriptor().

void VirtDescriptor::chainWrite	(	size_t	offset,
		const uint8_t *	src,
		size_t	size
	)

Write to a descriptor chain.

This method writes the specified number of bytes to a descriptor chain starting at the this descriptor plus an offset in bytes. The method automatically follows the links in the descriptor chain.

Parameters

offset	Offset into the chain (in bytes).
src	Pointer to source buffer.
size	Size (in bytes).

Definition at line 191 of file base.cc.

References chainSize(), desc, next(), ArmISA::offset, panic, size(), and write().

Referenced by VirtIOBlock::RequestQueue::onNotifyDescriptor(), VirtIOBlock::read(), VirtIO9PBase::sendRMsg(), and VirtIOConsole::TermRecvQueue::trySend().

void VirtDescriptor::dump ( ) const

Dump the contents of a descriptor.

Definition at line 105 of file base.cc.

References _index, vring_desc::addr, data, DDUMP, desc, DPRINTF, DTRACE, vring_desc::flags, isIncoming(), vring_desc::len, vring_desc::next, and read().

Referenced by dumpChain().

void VirtDescriptor::dumpChain ( ) const

Dump the contents of a descriptor chain starting at this descriptor.

Definition at line 122 of file base.cc.

References desc, DTRACE, dump(), and next().

bool VirtDescriptor::hasNext ( ) const

inline

Is this descriptor chained to another descriptor?

Returns: true if there is a next pointer, false otherwise.

Definition at line 238 of file base.hh.

References desc, vring_desc::flags, and VRING_DESC_F_NEXT.

Referenced by next().

Index VirtDescriptor::index ( ) const

inline

Get the descriptor's index into the virtqueue.

Definition at line 162 of file base.hh.

References _index.

Referenced by VirtQueue::produceDescriptor().

bool VirtDescriptor::isIncoming ( ) const

inline

Check if this is a read-only descriptor (incoming data).

Definition at line 248 of file base.hh.

References isOutgoing().

Referenced by chainRead(), dump(), and read().

bool VirtDescriptor::isOutgoing ( ) const

inline

Check if this is a write-only descriptor (outgoing data).

Definition at line 250 of file base.hh.

References desc, vring_desc::flags, and VRING_DESC_F_WRITE.

Referenced by isIncoming(), VirtIO9PBase::sendRMsg(), and write().

VirtDescriptor * VirtDescriptor::next ( ) const

Get the pointer to the next descriptor in a chain.

Returns: Pointer to the next descriptor or NULL if this is the last element in a chain.

Definition at line 134 of file base.cc.

References desc, VirtQueue::getDescriptor(), hasNext(), vring_desc::next, and queue.

Referenced by chainRead(), chainSize(), chainWrite(), dumpChain(), VirtIO9PBase::sendRMsg(), and updateChain().

VirtDescriptor & VirtDescriptor::operator= ( VirtDescriptor && rhs )

noexcept

Definition at line 63 of file base.cc.

References _index, desc, memProxy, and queue.

void VirtDescriptor::read	(	size_t	offset,
		uint8_t *	dst,
		size_t	size
	)		const

Read the contents of a descriptor.

This method copies the contents of a descriptor into a buffer within gem5. Devices should typically use chainRead() instead as it automatically follows the descriptor chain to read the desired number of bytes.

See Also: chainRead

Parameters

offset	Offset into the descriptor.
dst	Destination buffer.
size	Amount of data to read (in bytes).

Definition at line 144 of file base.cc.

References vring_desc::addr, desc, DPRINTF, isIncoming(), vring_desc::len, memProxy, panic, and PortProxy::readBlob().

Referenced by chainRead(), and dump().

size_t VirtDescriptor::size ( ) const

inline

Retrieve the size of this descriptor.

This method gets the size of a single descriptor. For incoming data, it corresponds to the amount of data that can be read from the descriptor. For outgoing data, it corresponds to the amount of data that can be written to it.

See Also: chainSize

Returns: Size of descriptor in bytes.

Definition at line 231 of file base.hh.

References desc, and vring_desc::len.

Referenced by chainRead(), chainSize(), chainWrite(), VirtIOConsole::TermTransQueue::onNotifyDescriptor(), VirtIO9PBase::FSQueue::onNotifyDescriptor(), VirtIOBlock::RequestQueue::onNotifyDescriptor(), and VirtIOConsole::TermRecvQueue::trySend().

void VirtDescriptor::update ( )

Populate this descriptor with data from the guest.

Definition at line 74 of file base.cc.

References _index, vring_desc::addr, desc, DPRINTF, vring_desc::flags, VirtQueue::getAddress(), vring_desc::len, memProxy, vring_desc::next, queue, PortProxy::readBlob(), and vtoh_legacy().

Referenced by updateChain().

void VirtDescriptor::updateChain ( )

Populate this descriptor chain with data from the guest.

Definition at line 93 of file base.cc.

References desc, next(), panic, and update().

Referenced by VirtQueue::consumeDescriptor().

void VirtDescriptor::write	(	size_t	offset,
		const uint8_t *	src,
		size_t	size
	)

Write to the contents of a descriptor.

This method copies the contents of a descriptor into a buffer within gem5. Devices should typically use chainWrite() instead as it automatically follows the descriptor chain to read the desired number of bytes.