Base class implementing a virtio console functionality. More...

#include <virtio-console>

Inheritance diagram for L4virtio::Svr::Console::Virtio_con:

Collaboration diagram for L4virtio::Svr::Console::Virtio_con:

Public Member Functions
	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.

virtual void	notify_queue (Virtqueue *queue)=0
	Notify queue of available data.

virtual Port *	port (unsigned port)=0
	Return the specified port.

virtual void	process_device_ready (l4_uint16_t value)=0
	Callback called on DEVICE_READY event.

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

virtual void	process_port_open (l4_uint32_t id, l4_uint16_t value)=0
	Callback called on PORT_OPEN event.

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

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

virtual void	trigger_driver_config_irq ()=0
	callback for triggering configuration change notification IRQ

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

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.

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 functionality.

It is possible to activate the MULTIPORT feature, in which case incoming control messages need to be dispatched by calling handle_control_message(). The derived class must additionally override process_device_ready(), process_port_ready() and process_port_open() to implement the actual behaviour. The derived class has the following responsibilities:

inform the driver about usable ports once the device is ready as signaled in process_device_ready(), see the wrapper port_add().
inform the driver about unusable ports, see the wrapper port_remove().
react to open/close events, see the wrapper port_open().

This implementation provides no means to handle interrupts or notify guests, therefore derived classes have to provide this functionality, see notify_queue() and handle_control_message(). Similarly, all interaction with data queues has to be implemented. Memory for port structures must be managed by the implementor as well.

Use this class as a base to implement your own specific console device.

Definition at line 185 of file virtio-console.

Constructor & Destructor Documentation

◆ Virtio_con()

L4virtio::Svr::Console::Virtio_con::Virtio_con	(	unsigned	max_ports,
		bool	enable_multiport
	)

inlineexplicit

Create a new multiport console device.

Parameters

max_ports	Maximum number of ports the device should be able to handle (ignored when `enable_multiport` is false).
enable_multiport	Enable the control queue for dynamic handling of ports.

Definition at line 211 of file virtio-console.

References L4Re::chksys(), L4virtio::Svr::Console::Features::console_multiport(), L4_EINVAL, and L4virtio::Svr::Dev_features::raw.

Here is the call graph for this function:

Member Function Documentation

◆ handle_control_message()

int L4virtio::Svr::Console::Virtio_con::handle_control_message ( )

inline

Handle control message received from the driver.

Return values

L4_EOK	Message has been handled.
-L4_ENODEV	Control queue is not ready.
-L4_EBUSY	Currently no descriptor available in the control queue.
-L4_EINVAL	Received an unexpected control event.

This function performs the basic handling of control messages from the driver. It does all necessary work with the control queues and performs some sanity checks. All other work is deferred to the derived class, see process_device_ready(), process_port_ready() and process_port_open().

Definition at line 443 of file virtio-console.

Referenced by L4virtio::Svr::Console::Device::do_control_work().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ notify_queue()

virtual void L4virtio::Svr::Console::Virtio_con::notify_queue ( Virtqueue * queue )

pure virtual

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.

Implemented in L4virtio::Svr::Console::Device.

◆ port()

virtual Port * L4virtio::Svr::Console::Virtio_con::port ( unsigned port )

pure virtual

Return the specified port.

Parameters

port	Port number.

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

Implemented in L4virtio::Svr::Console::Device.

Referenced by check_queues(), handle_control_message(), port_add(), port_open(), port_remove(), process_port_ready(), and reset().

Here is the caller graph for this function:

◆ port_add()

int L4virtio::Svr::Console::Virtio_con::port_add ( unsigned idx )

inline

Send a DEVICE_ADD message and update the internal state.

Parameters

idx	Port that should be added.

Return values

L4_EOK	Message has been sent.
-L4_EPERM	Control message is not allowed in the current state.

Returns: Errors from send_control_message()

Precondition: port must be smaller than the configured number of ports.; Port must not already exist.

Definition at line 298 of file virtio-console.

References L4virtio::Svr::Console::Control_message::Device_add, L4_EOK, L4_EPERM, port(), L4virtio::Svr::Console::Port::Port_added, L4virtio::Svr::Console::Port::Port_disabled, send_control_message(), and L4virtio::Svr::Console::Port::status.

Referenced by L4virtio::Svr::Console::Device::process_device_ready(), and L4virtio::Svr::Console::Device::resend_stalled_control_messages().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ port_open()

int L4virtio::Svr::Console::Virtio_con::port_open	(	unsigned	idx,
		bool	open
	)

inline

Send a PORT_OPEN message and update the internal state.

Parameters

idx	Port that should be opened or closed.
open	Open or close port.

Return values

L4_EOK	Message has been sent.
-L4_EPERM	Control message is not allowed in the current state.

Returns: Errors from send_control_message()

Precondition: port must be smaller than the configured number of ports.; Port must already exist.

Definition at line 355 of file virtio-console.

References L4_EOK, L4_EPERM, port(), L4virtio::Svr::Console::Control_message::Port_open, L4virtio::Svr::Console::Port::Port_open, L4virtio::Svr::Console::Port::Port_ready, send_control_message(), and L4virtio::Svr::Console::Port::status.

Referenced by L4virtio::Svr::Console::Device::process_port_open(), and L4virtio::Svr::Console::Device::resend_stalled_control_messages().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ port_remove()

int L4virtio::Svr::Console::Virtio_con::port_remove ( unsigned idx )

inline

Send a DEVICE_REMOVE message and update the internal state.

Parameters

idx	Port that should be removed.

Return values

L4_EOK	Message has been sent.
-L4_EPERM	Control message is not allowed in the current state.

Returns: Errors from send_control_message()

Precondition: port must be smaller than the configured number of ports.; Port must already exist.

Definition at line 325 of file virtio-console.

References L4virtio::Svr::Console::Control_message::Device_remove, L4_EOK, L4_EPERM, port(), L4virtio::Svr::Console::Port::Port_failed, L4virtio::Svr::Console::Port::Port_open, L4virtio::Svr::Console::Port::Port_ready, L4virtio::Svr::Console::Port::reset(), send_control_message(), and L4virtio::Svr::Console::Port::status.

Referenced by L4virtio::Svr::Console::Device::process_port_ready(), and L4virtio::Svr::Console::Device::resend_stalled_control_messages().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ process_device_ready()

virtual void L4virtio::Svr::Console::Virtio_con::process_device_ready ( l4_uint16_t value )

pure virtual

Callback called on DEVICE_READY event.

Parameters

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

Needs to be overridden by the derived class if the MULTIPORT feature is enabled. Control messages may be sent only after the driver has successfully initialized the device.

Implemented in L4virtio::Svr::Console::Device.

Referenced by handle_control_message().

Here is the caller graph for this function:

◆ process_port_open()

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

pure virtual

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.

Needs to be overridden by the derived class if the MULTIPORT feature is enabled. The device must acknowledge the message by calling port_open().

Implemented in L4virtio::Svr::Console::Device.

Referenced by handle_control_message().

Here is the caller graph for this function:

◆ process_port_ready()

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

inlinevirtual

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.

May be overridden by the derived class if the MULTIPORT feature is enabled. This default implementation just sets the status of the port according to the driver message.

Reimplemented in L4virtio::Svr::Console::Device.

Definition at line 606 of file virtio-console.

References port(), L4virtio::Svr::Console::Port::Port_added, L4virtio::Svr::Console::Port::Port_failed, L4virtio::Svr::Console::Port::Port_open, L4virtio::Svr::Console::Port::Port_ready, and L4virtio::Svr::Console::Port::status.

Referenced by handle_control_message(), and L4virtio::Svr::Console::Device::process_port_ready().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reset_device()

virtual void L4virtio::Svr::Console::Virtio_con::reset_device ( )

inlinevirtual

Reset the state of the actual console device.

This callback is called at the end of reset(), allowing the derived class to reset internal state.

Definition at line 560 of file virtio-console.

Referenced by reset().

Here is the caller graph for this function:

◆ send_control_message()

int L4virtio::Svr::Console::Virtio_con::send_control_message	(	l4_uint32_t	idx,
		l4_uint16_t	event,
		l4_uint16_t	value = `0`,
		const char *	name = `0`
	)

inline

Send control message to driver.

Parameters

idx	Port number.
event	Kind of control event.
value	Extra information for the event.
name	Name to be used for Port_name message

Return values

L4_EOK	Message has been sent.
-L4_ENODEV	Control queue is not ready.
-L4_EBUSY	Currently no descriptor available in the control queue.
-L4_ENOMEM	Client-issued descriptor too small. Device will be set to failed state.

Precondition: port must be smaller than the configured number of ports.

The convenience functions port_add(), port_remove() and port_open() should cover the most use cases and are the preferred way of communication with the driver. If you use this function directly, it is your responsibility to guarantee no invalid control messages are sent to the driver.

Definition at line 393 of file virtio-console.

References L4virtio::Svr::Virtqueue::finish(), L4_EBUSY, L4_ENODEV, L4_ENOMEM, L4_EOK, L4virtio::Svr::Console::Control_request::len, L4virtio::Svr::Console::Control_request::msg, L4virtio::Svr::Virtqueue::next_avail(), L4virtio::Svr::Console::Control_message::Port_name, L4virtio::Virtqueue::ready(), L4virtio::Svr::Console::Port::rx, and L4virtio::Svr::Request_processor::start().

Referenced by port_add(), port_open(), and port_remove().

Here is the call graph for this function:

Here is the caller graph for this function:

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

l4/l4virtio/server/virtio-console

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Virtio_con()

Member Function Documentation

◆ handle_control_message()

◆ notify_queue()

◆ port()

◆ port_add()

◆ port_open()

◆ port_remove()

◆ process_device_ready()

◆ process_port_open()

◆ process_port_ready()

◆ reset_device()

◆ send_control_message()