VirtIO descriptor (chain) wrapper. More...

#include <base.hh>

Public Types
typedef uint16_t	Index
	Descriptor index in virtqueue.

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

	VirtDescriptor (VirtDescriptor &&other) noexcept

	~VirtDescriptor () noexcept

VirtDescriptor &	operator= (VirtDescriptor &&rhs) noexcept

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Private Member Functions
	VirtDescriptor ()

	VirtDescriptor (const VirtDescriptor &other)

Private Attributes
PortProxy *	memProxy
	Pointer to memory proxy.

VirtQueue *	queue
	Pointer to virtqueue owning this descriptor.

ByteOrder	byteOrder
	The byte order the descriptor is stored in.

Index	_index
	Index in virtqueue.

vring_desc	desc
	Underlying descriptor.

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

Member Typedef Documentation

◆ Index

typedef uint16_t gem5::VirtDescriptor::Index

Descriptor index in virtqueue.

Definition at line 121 of file base.hh.

Constructor & Destructor Documentation

◆ VirtDescriptor() [1/4]

gem5::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 49 of file base.cc.

◆ VirtDescriptor() [2/4]

gem5::VirtDescriptor::VirtDescriptor ( VirtDescriptor && other )

noexcept

Definition at line 56 of file base.cc.

◆ ~VirtDescriptor()

gem5::VirtDescriptor::~VirtDescriptor ( )

noexcept

Definition at line 61 of file base.cc.

◆ VirtDescriptor() [3/4]

gem5::VirtDescriptor::VirtDescriptor ( )

private

◆ VirtDescriptor() [4/4]

gem5::VirtDescriptor::VirtDescriptor ( const VirtDescriptor & other )

private

Member Function Documentation

◆ chainRead()

void gem5::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 172 of file base.cc.

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

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

◆ chainSize()

size_t gem5::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 218 of file base.cc.

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

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

◆ chainWrite()

void gem5::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 195 of file base.cc.

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

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

◆ dump()

void gem5::VirtDescriptor::dump ( ) const

Dump the contents of a descriptor.

Definition at line 109 of file base.cc.

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

◆ dumpChain()

void gem5::VirtDescriptor::dumpChain ( ) const

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

Definition at line 126 of file base.cc.

References desc, and vring_desc::next.

◆ hasNext()

bool gem5::VirtDescriptor::hasNext ( ) const

inline

Is this descriptor chained to another descriptor?

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

Definition at line 220 of file base.hh.

References desc, vring_desc::flags, and VRING_DESC_F_NEXT.

Referenced by next().

◆ index()

Index gem5::VirtDescriptor::index ( ) const

inline

Get the descriptor's index into the virtqueue.

Definition at line 144 of file base.hh.

References _index.

Referenced by gem5::VirtQueue::produceDescriptor().

◆ isIncoming()

bool gem5::VirtDescriptor::isIncoming ( ) const

inline

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

Definition at line 230 of file base.hh.

References isOutgoing().

Referenced by dump(), and read().

◆ isOutgoing()

bool gem5::VirtDescriptor::isOutgoing ( ) const

inline

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

Definition at line 232 of file base.hh.

References desc, vring_desc::flags, and VRING_DESC_F_WRITE.

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

◆ next()

VirtDescriptor * gem5::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 138 of file base.cc.

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

Referenced by gem5::VirtIO9PBase::sendRMsg().

◆ operator=()

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

noexcept

Definition at line 66 of file base.cc.

References gem5::ArmISA::byteOrder().

◆ read()

void gem5::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 148 of file base.cc.

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

Referenced by dump().

◆ size()

size_t gem5::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 213 of file base.hh.

References desc, and vring_desc::len.

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

◆ update()

void gem5::VirtDescriptor::update ( )

Populate this descriptor with data from the guest.

Definition at line 78 of file base.cc.

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

◆ updateChain()

void gem5::VirtDescriptor::updateChain ( )

Populate this descriptor chain with data from the guest.

Definition at line 97 of file base.cc.

References desc, vring_desc::next, and panic.

◆ write()

void gem5::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 160 of file base.cc.

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

Member Data Documentation

◆ _index

Index gem5::VirtDescriptor::_index

private

Index in virtqueue.

Definition at line 287 of file base.hh.

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

◆ byteOrder

ByteOrder gem5::VirtDescriptor::byteOrder

private

The byte order the descriptor is stored in.

Definition at line 284 of file base.hh.

Referenced by update().

◆ desc

vring_desc gem5::VirtDescriptor::desc

private

Underlying descriptor.

Definition at line 290 of file base.hh.

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

◆ memProxy

PortProxy* gem5::VirtDescriptor::memProxy

private

Pointer to memory proxy.

Definition at line 279 of file base.hh.

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

◆ queue

VirtQueue* gem5::VirtDescriptor::queue

private

Pointer to virtqueue owning this descriptor.

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