gem5  v21.1.0.2
Public Types | Private Member Functions | Private Attributes | List of all members
gem5::VirtDescriptor Class Reference

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
 
VirtDescriptoroperator= (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...
 
VirtDescriptornext () 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

PortProxymemProxy
 Pointer to memory proxy. More...
 
VirtQueuequeue
 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 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
memProxyProxy to the guest physical memory.
queueQueue owning this descriptor.
indexIndex 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
offsetOffset into the chain (in bytes).
dstPointer to destination buffer.
sizeSize (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::VirtIOConsole::TermTransQueue::onNotifyDescriptor(), gem5::VirtIO9PBase::FSQueue::onNotifyDescriptor(), gem5::VirtIOBlock::RequestQueue::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::VirtIOConsole::TermTransQueue::onNotifyDescriptor(), and gem5::VirtIOBlock::RequestQueue::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
offsetOffset into the chain (in bytes).
srcPointer to source buffer.
sizeSize (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
offsetOffset into the descriptor.
dstDestination buffer.
sizeAmount 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::VirtIOConsole::TermTransQueue::onNotifyDescriptor(), gem5::VirtIO9PBase::FSQueue::onNotifyDescriptor(), gem5::VirtIOBlock::RequestQueue::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
offsetOffset into the descriptor.
srcSource buffer.
sizeAmount 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:

Generated on Tue Sep 21 2021 12:28:20 for gem5 by doxygen 1.8.17