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, ByteOrder bo, 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...

ByteOrder	byteOrder
	The byte order the descriptor is stored in. 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 106 of file base.hh.

Member Typedef Documentation

◆ Index

typedef uint16_t VirtDescriptor::Index

Descriptor index in virtqueue.

Definition at line 110 of file base.hh.

Constructor & Destructor Documentation

◆ VirtDescriptor() [1/4]

VirtDescriptor::VirtDescriptor	(	PortProxy &	memProxy,
		ByteOrder	bo,
		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 45 of file base.cc.

◆ VirtDescriptor() [2/4]

VirtDescriptor::VirtDescriptor ( VirtDescriptor && other )

noexcept

Definition at line 52 of file base.cc.

◆ ~VirtDescriptor()

VirtDescriptor::~VirtDescriptor ( )

noexcept

Definition at line 57 of file base.cc.

◆ VirtDescriptor() [3/4]

VirtDescriptor::VirtDescriptor ( )

private

◆ VirtDescriptor() [4/4]

VirtDescriptor::VirtDescriptor ( const VirtDescriptor & other )

private

Member Function Documentation

◆ chainRead()

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, vring_desc::next, ArmISA::offset, panic, and size().

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

◆ chainSize()

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, vring_desc::next, and size().

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

◆ chainWrite()

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, vring_desc::next, ArmISA::offset, panic, and size().

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

◆ dump()

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().

◆ 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, and vring_desc::next.

◆ hasNext()

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 209 of file base.hh.

References desc, vring_desc::flags, and VRING_DESC_F_NEXT.

Referenced by next().

◆ index()

Index VirtDescriptor::index ( ) const

inline

Get the descriptor's index into the virtqueue.

Definition at line 133 of file base.hh.

References _index.

Referenced by VirtQueue::produceDescriptor().

◆ isIncoming()

bool VirtDescriptor::isIncoming ( ) const

inline

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

Definition at line 219 of file base.hh.

References isOutgoing().

Referenced by dump(), and read().

◆ isOutgoing()

bool VirtDescriptor::isOutgoing ( ) const

inline

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

Definition at line 221 of file base.hh.

References desc, vring_desc::flags, and VRING_DESC_F_WRITE.

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

◆ next()

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 VirtIO9PBase::sendRMsg().

◆ operator=()

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

noexcept

Definition at line 62 of file base.cc.

References ArmISA::byteOrder().

◆ read()

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, ArmISA::offset, panic, PortProxy::readBlob(), and size().

Referenced by dump().

◆ size()

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 202 of file base.hh.

References desc, and vring_desc::len.

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

◆ update()

void VirtDescriptor::update ( )

Populate this descriptor with data from the guest.

Definition at line 74 of file base.cc.

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

◆ updateChain()

void VirtDescriptor::updateChain ( )

Populate this descriptor chain with data from the guest.

Definition at line 93 of file base.cc.

References desc, vring_desc::next, and panic.

◆ write()

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.

See also: chainWrite

Parameters

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

Definition at line 156 of file base.cc.

References vring_desc::addr, desc, DPRINTF, isOutgoing(), vring_desc::len, memProxy, ArmISA::offset, panic, size(), and PortProxy::writeBlob().

Member Data Documentation

◆ _index

Index VirtDescriptor::_index

private

Index in virtqueue.

Definition at line 276 of file base.hh.

Referenced by dump(), index(), and update().

◆ byteOrder

ByteOrder VirtDescriptor::byteOrder

private

The byte order the descriptor is stored in.

Definition at line 273 of file base.hh.

Referenced by update().

◆ desc

vring_desc VirtDescriptor::desc

private

Underlying descriptor.

Definition at line 279 of file base.hh.

Referenced by chainRead(), chainSize(), chainWrite(), dump(), dumpChain(), hasNext(), isOutgoing(), next(), read(), size(), update(), updateChain(), and write().

◆ memProxy

PortProxy* VirtDescriptor::memProxy

private

Pointer to memory proxy.

Definition at line 268 of file base.hh.

Referenced by read(), update(), and write().

◆ queue

VirtQueue* VirtDescriptor::queue

private

Pointer to virtqueue owning this descriptor.

Definition at line 270 of file base.hh.

Referenced by next(), and update().

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

dev/virtio/base.hh
dev/virtio/base.cc

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Index

Constructor & Destructor Documentation

◆ VirtDescriptor() [1/4]

◆ VirtDescriptor() [2/4]

◆ ~VirtDescriptor()

◆ VirtDescriptor() [3/4]

◆ VirtDescriptor() [4/4]

Member Function Documentation

◆ chainRead()

◆ chainSize()

◆ chainWrite()

◆ dump()

◆ dumpChain()

◆ hasNext()

◆ index()

◆ isIncoming()

◆ isOutgoing()

◆ next()

◆ operator=()

◆ read()

◆ size()

◆ update()

◆ updateChain()

◆ write()

Member Data Documentation

◆ _index

◆ byteOrder

◆ desc

◆ memProxy

◆ queue