Base wrapper around a virtqueue. More...

#include <base.hh>

Inheritance diagram for VirtQueue:

Classes
class	VirtRing
	VirtIO ring buffer wrapper. More...

Public Member Functions
virtual	~VirtQueue ()

Checkpointing Interface
void	serialize (CheckpointOut &cp) const override
	Serialize an object. More...

void	unserialize (CheckpointIn &cp) override
	Unserialize an object. More...

Low-level Device Interface
void	reset ()
	Reset cached state in this queue and in the associated ring buffers. More...

void	setAddress (Addr address)
	Set the base address of this queue. More...

Addr	getAddress () const
	Get the guest physical address of this queue. More...

uint16_t	getSize () const
	Get the number of descriptors available in this queue. More...

VirtDescriptor *	getDescriptor (VirtDescriptor::Index index)
	Get a pointer to a specific descriptor in the queue. More...

Device Model Interfaces
VirtDescriptor *	consumeDescriptor ()
	Get an incoming descriptor chain from the queue. More...

void	produceDescriptor (VirtDescriptor *desc, uint32_t len)
	Send a descriptor chain to the guest. More...

Device Model Callbacks
virtual void	onNotify ()
	Notify queue of pending events. More...

virtual void	onNotifyDescriptor (VirtDescriptor *desc)
	Notify queue of pending incoming descriptor. More...

Debug interfaces
void	dump () const
	Dump the contents of a queue. 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)

Static Public Attributes

static const Addr	ALIGN_BITS = 12
	Page size used by VirtIO. It's hard-coded to 4096 bytes in the spec for historical reasons. More...

static const Addr	ALIGN_SIZE = 1 << ALIGN_BITS

Protected Member Functions
	VirtQueue (PortProxy &proxy, ByteOrder bo, uint16_t size)
	Instantiate a new virtqueue. More...

Protected Attributes
ByteOrder	byteOrder
	Byte order in this queue. More...

Private Member Functions
	VirtQueue ()

Private Attributes
const uint16_t	_size
	Queue size in terms of number of descriptors. More...

Addr	_address
	Base address of the queue. More...

PortProxy &	memProxy
	Guest physical memory proxy. More...

VirtRing< VirtDescriptor::Index >	avail
	Ring of available (incoming) descriptors. More...

VirtRing< struct vring_used_elem >	used
	Ring of used (outgoing) descriptors. More...

uint16_t	_last_avail
	Offset of last consumed descriptor in the VirtQueue::avail ring. More...

std::vector< VirtDescriptor >	descriptors
	Vector of pre-created descriptors indexed by their index into the queue. More...

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

Base wrapper around a virtqueue.

VirtIO device models typically need to extend this class to implement their own device queues.

Note: Queues must be registered with VirtIODeviceBase::registerQueue() to be active.

Definition at line 295 of file base.hh.

Constructor & Destructor Documentation

◆ ~VirtQueue()

virtual VirtQueue::~VirtQueue ( )

inlinevirtual

Definition at line 297 of file base.hh.

◆ VirtQueue() [1/2]

VirtQueue::VirtQueue	(	PortProxy &	proxy,
		ByteOrder	bo,
		uint16_t	size
	)

protected

Instantiate a new virtqueue.

Instantiate a virtqueue with a fixed size. The size is specified in descriptors which are defined as 4096 bytes each.

Parameters

proxy	Proxy to the guest physical memory.
size	Size in descriptors/pages.

Definition at line 228 of file base.cc.

References _size, PowerISA::bo, descriptors, and ArmISA::i.

◆ VirtQueue() [2/2]

VirtQueue::VirtQueue ( )

private

Member Function Documentation

◆ consumeDescriptor()

VirtDescriptor * VirtQueue::consumeDescriptor ( )

Get an incoming descriptor chain from the queue.

Returns: Pointer to descriptor on success, NULL if no pending descriptors are available.

Definition at line 282 of file base.cc.

References _last_avail, avail, ArmISA::d, descriptors, DPRINTF, VirtQueue::VirtRing< T >::header, MipsISA::index, VirtQueue::VirtRing< T >::read(), VirtQueue::VirtRing< T >::ring, and used.

Referenced by onNotify(), and VirtIOConsole::TermRecvQueue::trySend().

◆ dump()

void VirtQueue::dump ( ) const

Dump the contents of a queue.

Definition at line 315 of file base.cc.

References ArmISA::d, descriptors, and DTRACE.

◆ getAddress()

Addr VirtQueue::getAddress ( ) const

inline

Get the guest physical address of this queue.

Returns: Physical address in guest where this queue resides.

Definition at line 327 of file base.hh.

References _address.

Referenced by VirtDescriptor::update().

◆ getDescriptor()

VirtDescriptor* VirtQueue::getDescriptor ( VirtDescriptor::Index index )

inline

Get a pointer to a specific descriptor in the queue.

Note: This interfaces is normally only used by VirtDescriptor to follow descriptor chains. Device models typically don't need to use it.

Returns: Pointer to a VirtDescriptor.

Definition at line 345 of file base.hh.

References descriptors, and MipsISA::index.

Referenced by VirtDescriptor::next().

◆ getSize()

uint16_t VirtQueue::getSize ( ) const

inline

Get the number of descriptors available in this queue.

Returns: Size of queue in descriptors.

Definition at line 334 of file base.hh.

References _size.

Referenced by VirtIODeviceBase::getQueueSize().

◆ onNotify()

void VirtQueue::onNotify ( )

virtual

Notify queue of pending events.

This method is called by VirtIODeviceBase::onNotify() to notify the device model of pending data in a virtqueue. The default implementation of this method iterates over the available descriptor chains and calls onNotifyDescriptor() for every new incoming chain.

Device models should normally overload one of onNotify() and onNotifyDescriptor().

Reimplemented in VirtIOConsole::TermRecvQueue.

Definition at line 325 of file base.cc.

References consumeDescriptor(), ArmISA::d, DPRINTF, and onNotifyDescriptor().

◆ onNotifyDescriptor()

virtual void VirtQueue::onNotifyDescriptor ( VirtDescriptor * desc )

inlinevirtual

Notify queue of pending incoming descriptor.

This method is called by the default implementation of onNotify() to notify the device model of pending data in a descriptor chain.

Device models should normally overload one of onNotify() and onNotifyDescriptor().

Reimplemented in VirtIOBlock::RequestQueue, VirtIO9PBase::FSQueue, and VirtIOConsole::TermTransQueue.

Definition at line 407 of file base.hh.

Referenced by onNotify().

◆ produceDescriptor()

void VirtQueue::produceDescriptor	(	VirtDescriptor *	desc,
		uint32_t	len
	)

Send a descriptor chain to the guest.

This method posts a descriptor chain to the guest after a device model has finished processing it. The device model typically needs to call VirtIODeviceBase::kick() to deliver notify tell the guest that the queue has been updated.

Note: The desc parameter must refer to the first descriptor in a chain that has been retrieved using consumeDescriptor().; The len parameter specified the amount of data produced by the device model. It seems to be ignored by Linux and it is not well defined.

Parameters

desc	Start of descriptor chain.
len	Length of the produced data.

Definition at line 301 of file base.cc.

References DPRINTF, ArmISA::e, VirtQueue::VirtRing< T >::header, VirtDescriptor::index(), ArmISA::len, VirtQueue::VirtRing< T >::readHeader(), VirtQueue::VirtRing< T >::ring, used, and VirtQueue::VirtRing< T >::write().

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

◆ reset()

void VirtQueue::reset ( )

Reset cached state in this queue and in the associated ring buffers.

A client of this method should be the VirtIODeviceBase::reset.

Definition at line 259 of file base.cc.

References _address, _last_avail, avail, VirtQueue::VirtRing< T >::reset(), and used.

◆ serialize()

void VirtQueue::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 239 of file base.cc.

References _address, _last_avail, and SERIALIZE_SCALAR.

◆ setAddress()

void VirtQueue::setAddress ( Addr address )

Set the base address of this queue.

Parameters

address Guest physical base address of the queue.

Definition at line 269 of file base.cc.

References _address, _size, ALIGN_SIZE, avail, VirtQueue::VirtRing< T >::setAddress(), and used.

Referenced by VirtIODeviceBase::setQueueAddress(), and unserialize().

◆ unserialize()

void VirtQueue::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 246 of file base.cc.

References _last_avail, paramIn(), setAddress(), and UNSERIALIZE_SCALAR.

Member Data Documentation

◆ _address

Addr VirtQueue::_address

private

Base address of the queue.

Definition at line 447 of file base.hh.

Referenced by getAddress(), reset(), serialize(), and setAddress().

◆ _last_avail

uint16_t VirtQueue::_last_avail

private

Offset of last consumed descriptor in the VirtQueue::avail ring.

Definition at line 561 of file base.hh.

Referenced by consumeDescriptor(), reset(), serialize(), and unserialize().

◆ _size

const uint16_t VirtQueue::_size

private

Queue size in terms of number of descriptors.

Definition at line 445 of file base.hh.

Referenced by getSize(), setAddress(), and VirtQueue().

◆ ALIGN_BITS

const Addr VirtQueue::ALIGN_BITS = 12

static

Page size used by VirtIO. It's hard-coded to 4096 bytes in the spec for historical reasons.

Definition at line 422 of file base.hh.

Referenced by VirtIODeviceBase::getQueueAddress().

◆ ALIGN_SIZE

const Addr VirtQueue::ALIGN_SIZE = 1 << ALIGN_BITS

static

Definition at line 423 of file base.hh.

Referenced by MmioVirtIO::read(), setAddress(), VirtIODeviceBase::setQueueAddress(), and MmioVirtIO::write().

◆ avail

VirtRing<VirtDescriptor::Index> VirtQueue::avail

private

Ring of available (incoming) descriptors.

Definition at line 555 of file base.hh.

Referenced by consumeDescriptor(), reset(), and setAddress().

◆ byteOrder

ByteOrder VirtQueue::byteOrder

protected

Byte order in this queue.

Definition at line 439 of file base.hh.

Referenced by VirtIOBlock::RequestQueue::onNotifyDescriptor().

◆ descriptors

std::vector<VirtDescriptor> VirtQueue::descriptors

private

Vector of pre-created descriptors indexed by their index into the queue.

Definition at line 565 of file base.hh.

Referenced by consumeDescriptor(), dump(), getDescriptor(), and VirtQueue().

◆ memProxy

PortProxy& VirtQueue::memProxy

private

Guest physical memory proxy.

Definition at line 449 of file base.hh.

◆ used

VirtRing<struct vring_used_elem> VirtQueue::used

private

Ring of used (outgoing) descriptors.

Definition at line 557 of file base.hh.

Referenced by consumeDescriptor(), produceDescriptor(), reset(), and setAddress().

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

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

Classes

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~VirtQueue()

◆ VirtQueue() [1/2]

◆ VirtQueue() [2/2]

Member Function Documentation

◆ consumeDescriptor()

◆ dump()

◆ getAddress()

◆ getDescriptor()

◆ getSize()

◆ onNotify()

◆ onNotifyDescriptor()

◆ produceDescriptor()

◆ reset()

◆ serialize()

◆ setAddress()

◆ unserialize()

Member Data Documentation

◆ _address

◆ _last_avail

◆ _size

◆ ALIGN_BITS

◆ ALIGN_SIZE

◆ avail

◆ byteOrder

◆ descriptors

◆ memProxy

◆ used