Base class implementing a virtio console device with L4Re-based notification handling. More...

#include <virtio-console-device>

Inheritance diagram for L4virtio::Svr::Console::Device:

Collaboration diagram for L4virtio::Svr::Console::Device:

Public Member Functions
	Device (unsigned vq_max)
	Create a new console device.

	Device (unsigned vq_max, unsigned ports)
	Create a new console device.

	Device (cxx::static_vector< unsigned > const &vq_max_nums)
	Create a new console Device.

void	register_single_driver_irq () override
	callback for registering a single guest IRQ for all queues (old-style)

L4::Cap< L4::Irq >	device_notify_irq () const override
	callback to gather the device notification IRQ (old-style)

void	notify_queue (Virtqueue *queue) override
	Notify queue of available data.

virtual void	rx_data_available (unsigned port)=0
	Callback to notify that new data is available to be read from port.

virtual void	tx_space_available (unsigned port)=0
	Callback to notify that data can be written to port.

virtual bool	queues_stopped ()
	Return true, if the queues should not be processed further.

void	trigger_driver_config_irq () override
	callback for triggering configuration change notification IRQ

unsigned	port_read (char *buf, unsigned len, unsigned port=0)
	Read data from port.

unsigned	port_write (char const *buf, unsigned len, unsigned port=0)
	Write data to port.

int	do_control_work ()
	Receive new control messages and resend stalled ones.

void	process_device_ready (l4_uint16_t value) override
	Callback called on DEVICE_READY event.

void	process_port_ready (l4_uint32_t id, l4_uint16_t value) override
	Callback called on PORT_READY event.

void	process_port_open (l4_uint32_t id, l4_uint16_t value) override
	Callback called on PORT_OPEN event.

Public Member Functions inherited from L4virtio::Svr::Console::Virtio_con
	Virtio_con (unsigned max_ports, bool enable_multiport)
	Create a new multiport console device.

int	reconfig_queue (unsigned index) override
	callback for client queue-config request

bool	multiport_enabled () const
	Return true if the multiport feature is enabled and control queues are available.

bool	check_features (void) override
	callback for checking the subset of accepted features

bool	check_queues () override
	callback for checking if the queues at DRIVER_OK transition

int	port_add (unsigned idx)
	Send a DEVICE_ADD message and update the internal state.

int	port_remove (unsigned idx)
	Send a DEVICE_REMOVE message and update the internal state.

int	port_open (unsigned idx, bool open)
	Send a PORT_OPEN message and update the internal state.

int	send_control_message (l4_uint32_t idx, l4_uint16_t event, l4_uint16_t value=0, const char *name=0)
	Send control message to driver.

int	handle_control_message ()
	Handle control message received from the driver.

void	reset () override
	reset callback, called for doing a device reset

virtual void	reset_device ()
	Reset the state of the actual console device.

Public Member Functions inherited from L4virtio::Svr::Device_t< DATA >
virtual void	cfg_changed (unsigned)
	callback for client device configuration changes

virtual void	register_driver_irq (unsigned idx)
	Callback for registering an notification IRQ (multi IRQ).

virtual L4::Cap< L4::Irq >	device_notify_irq (unsigned idx)
	Callback to gather the device notification IRQ (multi IRQ).

virtual unsigned	num_events_supported () const
	Return the highest notification index supported.

	Device_t (Dev_config *dev_config)
	Make a device for the given config.

Mem_list const *	mem_info () const
	Get the memory region list used for this device.

void	reset_queue_config (unsigned idx, unsigned num_max, bool inc_generation=false)
	Trigger reset for the configuration space for queue idx.

void	init_mem_info (unsigned num)
	Initialize the memory region list to the given maximum.

void	device_error ()
	Transition device into DEVICE_NEEDS_RESET state.

bool	setup_queue (Virtqueue *q, unsigned qn, unsigned num_max)
	Enable/disable the specified queue.

bool	handle_mem_cmd_write ()
	Check for a value in the `cmd` register and handle a write.

void	enable_trusted_ds_validation ()
	Enable trusted dataspace validation.

void	add_trusted_dataspaces (std::shared_ptr< Ds_vector const > ds)
	Provide a list of trusted dataspaces that can be used for validation.

Protected Member Functions
void	resend_stalled_control_messages ()
	Try to resend a stalled control message and update the port and global state accordingly.

Port *	port (unsigned idx) override
	Return the specified port.

Additional Inherited Members
Protected Attributes inherited from L4virtio::Svr::Device_t< DATA >
Mem_list	_mem_info
	Memory region list.

Detailed Description

Base class implementing a virtio console device with L4Re-based notification handling.

This console device is derived from Virtio_con and already includes functionality to handle interrupts and notify drivers. If an interrupt is received, all the necessary interaction with the virtqueues is performed and only the actual data processing has to be done by the derived class. By default all available ports are added and an "open"-request of a port by the driver is automatically acknowledged. The derived class can optionally change this behaviour by overriding process_device_ready(), process_port_ready() and process_port_open().

This class provides a stream-based interface to access the port data with edge-triggered notification callbacks. If a port receives data from the driver the derived class is notified with the rx_data_available() callback. The actual data can be retrieved by port_read(). If there was not enough data to be read, the call will return the available partial data. Only then will the rx_data_available() callback be triggered again.

Data on a port may be transmitted by port_write(). If there were not enough buffers available, only a part of the data will be transmitted. Once there are new buffers available, the tx_space_available() callback will be invoked. This callback will be called again only after a previous port_write() was not able to send all requested data.

Use this class as a base to provide your own high-level console device. You must derive from this class as well as L4::Epiface_t<..., L4virtio::Device>. For a working device the irq_iface() must be registered too. A typical implementation might look like the following:

class My_console
: public L4virtio::Svr::Console::Device,
  public L4::Epiface_t<My_console, L4virtio::Device>
{
public:
  My_console(L4Re::Util::Object_registry *r)
  : L4virtio::Svr::Console::Device(0x100)
  {
    init_mem_info(4);
    L4Re::chkcap(r->register_irq_obj(irq_iface()), "virtio notification IRQ");
  }
 
  void rx_data_available(unsigned port) override
  {
    // call port_read() to fetch available data
  }
 
  void tx_space_available(unsigned port) override
  {
    // can call port_write() to send (pending) data
  }
};
 
My_console console(registry);
registry->register_obj(&console, ...);

The maximum number of memory regions (init_mem_info()) should correlate with the number of supported ports.

Definition at line 116 of file virtio-console-device.

Constructor & Destructor Documentation

◆ Device() [1/3]

L4virtio::Svr::Console::Device::Device ( unsigned vq_max )

inlineexplicit

Create a new console device.

Parameters

vq_max Maximum number of buffers in data queues.

Create a console device with no multiport support, i.e. control queues are disabled.

Definition at line 143 of file virtio-console-device.

◆ Device() [2/3]

L4virtio::Svr::Console::Device::Device	(	unsigned	vq_max,
		unsigned	ports
	)

inlineexplicit

Create a new console device.

Parameters

vq_max	Maximum number of buffers in data queues.
ports	Number of ports (maximum 32).

Create a console device with multiport support, i.e. control queues are enabled.

Definition at line 162 of file virtio-console-device.

References L4Re::chksys(), and L4_ENOMEM.

Here is the call graph for this function:

◆ Device() [3/3]

L4virtio::Svr::Console::Device::Device ( cxx::static_vector< unsigned > const & vq_max_nums )

inlineexplicit

Create a new console Device.

Parameters

vq_max_nums Maximum number of buffers in data queues, given as a cxx::static_vector with one entry per port.

Create a console device with multiport support, i.e. control queues are enabled.

Definition at line 184 of file virtio-console-device.

References L4Re::chksys(), and L4_ENOMEM.

Here is the call graph for this function:

Member Function Documentation

◆ do_control_work()

int L4virtio::Svr::Console::Device::do_control_work ( )

inline

Receive new control messages and resend stalled ones.

Return values

see	`handle_control_message()`

As it may happen that the driver is not able to receive a control message, there may be some stalled control message. This function checks if such messages exist and tries to resend them once more. Afterwards it checks for new messages from the driver, see handle_control_message().

Definition at line 400 of file virtio-console-device.

References L4virtio::Svr::Console::Virtio_con::handle_control_message(), and resend_stalled_control_messages().

Here is the call graph for this function:

◆ notify_queue()

void L4virtio::Svr::Console::Device::notify_queue ( Virtqueue * queue )

inlineoverridevirtual

Notify queue of available data.

Parameters

queue Virtqueue to notify.

This callback is called whenever data is sent to queue. It is the responsibility of the derived class to perform all necessary notification actions, e.g. triggering guest interrupts.

Implements L4virtio::Svr::Console::Virtio_con.

Definition at line 208 of file virtio-console-device.

References L4VIRTIO_IRQ_STATUS_VRING, and L4virtio::Virtqueue::no_notify_guest().

Here is the call graph for this function:

◆ port()

Port * L4virtio::Svr::Console::Device::port ( unsigned port )

inlineoverrideprotectedvirtual

Return the specified port.

Parameters

port	Port number.

Precondition: Port number must be lower than the configured maximum number of ports.

Implements L4virtio::Svr::Console::Virtio_con.

Definition at line 505 of file virtio-console-device.

Referenced by port_read(), port_write(), and process_port_ready().

Here is the caller graph for this function:

◆ port_read()

unsigned L4virtio::Svr::Console::Device::port_read	(	char *	buf,
		unsigned	len,
		unsigned	port = `0`
	)

inline

Read data from port.

Will read up to len bytes from port into buf. Returns the number of bytes read, which may be less if not enough data was available. If all data was read, the rx_data_available() callback will be invoked the next time the driver queues new data for the port. The callback won't be called again until all data was consumed again.

Parameters

buf	The destination buffer
len	Size of the buffer
port	Port index to read data from

Returns: Number of bytes read

Definition at line 278 of file virtio-console-device.

References L4virtio::Svr::Virtqueue::finish(), L4virtio::Svr::Data_buffer::left, L4virtio::Svr::Device_t< DATA >::mem_info(), L4virtio::Svr::Request_processor::next(), L4virtio::Svr::Virtqueue::next_avail(), port(), L4virtio::Svr::Data_buffer::pos, L4virtio::Svr::Console::Device_port::request, L4virtio::Svr::Console::Device_port::rp, L4virtio::Svr::Console::Device_port::src, L4virtio::Svr::Request_processor::start(), L4virtio::Svr::Console::Port::tx, and L4virtio::Svr::Console::Port::tx_ready().

Here is the call graph for this function:

◆ port_write()

unsigned L4virtio::Svr::Console::Device::port_write	(	char const *	buf,
		unsigned	len,
		unsigned	port = `0`
	)

inline

Write data to port.

Will write up to len bytes to port from buf. Returns the number of bytes written, which may be less if not enough virtio buffers were available. If not all data could be written, the tx_space_available() callback will be invoked the next time the driver queues new receive buffers for the port. The callback won't be called again until all receive buffers were filled again.

Parameters

buf	The souce buffer
len	Size of the buffer
port	Port index to write data to

Returns: Number of bytes written

Definition at line 345 of file virtio-console-device.

References L4virtio::Svr::Data_buffer::copy_to(), L4virtio::Svr::Virtqueue::finish(), L4virtio::Svr::Data_buffer::left, L4virtio::Svr::Device_t< DATA >::mem_info(), L4virtio::Svr::Request_processor::next(), L4virtio::Svr::Virtqueue::next_avail(), port(), L4virtio::Svr::Data_buffer::pos, L4virtio::Svr::Console::Port::rx, L4virtio::Svr::Console::Port::rx_ready(), and L4virtio::Svr::Request_processor::start().

Here is the call graph for this function:

◆ process_device_ready()

void L4virtio::Svr::Console::Device::process_device_ready ( l4_uint16_t value )

inlineoverridevirtual

Callback called on DEVICE_READY event.

Parameters

value The value field of the control message, indicating if the initialization was successful.

By default, this function adds all ports if the driver indicates successful initialization. Override this function to perform custom actions for a DEVICE_READY event, after the generic management of the base class. It is then your responsibility to inform the driver about usable ports, see port_add().

Implements L4virtio::Svr::Console::Virtio_con.

Definition at line 426 of file virtio-console-device.

References L4virtio::Svr::Console::Virtio_con::port_add().

Here is the call graph for this function:

◆ process_port_open()

void L4virtio::Svr::Console::Device::process_port_open	(	l4_uint32_t	id,
		l4_uint16_t	value
	)

inlineoverridevirtual

Callback called on PORT_OPEN event.

Parameters

id	The id field of the control message, i.e. the port number.
value	The value field of the control message, indicating if the port was opened or closed.

By default, this function acknowledges the message from the driver by sending back the same message. Override this function to perform custom actions for a PORT_OPEN event, after the generic management of the base class. It is then your responsibility to update the internal port state and answer the driver's messages, see port_open().

Implements L4virtio::Svr::Console::Virtio_con.

Definition at line 470 of file virtio-console-device.

References L4virtio::Svr::Console::Virtio_con::port_open().

Here is the call graph for this function:

◆ process_port_ready()

void L4virtio::Svr::Console::Device::process_port_ready	(	l4_uint32_t	id,
		l4_uint16_t	value
	)

inlineoverridevirtual

Callback called on PORT_READY event.

Parameters

id	The id field of the control message, i.e. the port number.
value	The value field of the control message, indicating if the initialization was successful.

By default, this function removes the port, if the driver failed to set it up correctly. Override this function to perform custom actions for a PORT_READY event, after the generic management of the base class. It is then your responsibility to inform the driver about unusable ports, see port_remove().

Reimplemented from L4virtio::Svr::Console::Virtio_con.

Definition at line 448 of file virtio-console-device.

References port(), L4virtio::Svr::Console::Port::Port_failed, L4virtio::Svr::Console::Virtio_con::port_remove(), L4virtio::Svr::Console::Virtio_con::process_port_ready(), and L4virtio::Svr::Console::Port::status.

Here is the call graph for this function:

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

l4/l4virtio/server/virtio-console-device

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Device() [1/3]

◆ Device() [2/3]

◆ Device() [3/3]

Member Function Documentation

◆ do_control_work()

◆ notify_queue()

◆ port()

◆ port_read()

◆ port_write()

◆ process_device_ready()

◆ process_port_open()

◆ process_port_ready()