L4Re Operating System Framework
Interface and Usage Documentation
Loading...
Searching...
No Matches
L4virtio::Svr::Console::Virtio_con Class Referenceabstract

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 Portport (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::Irqdevice_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::Irqdevice_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:

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_portsMaximum number of ports the device should be able to handle (ignored when enable_multiport is false).
enable_multiportEnable 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_EOKMessage has been handled.
-L4_ENODEVControl queue is not ready.
-L4_EBUSYCurrently no descriptor available in the control queue.
-L4_EINVALReceived 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.

References L4virtio::Svr::Virtqueue::consumed(), L4virtio::Svr::Console::Control_message::Device_ready, L4virtio::Svr::Console::Control_message::event, L4virtio::Svr::Console::Control_message::id, L4_EINVAL, L4_ENODEV, L4_EOK, L4virtio::Svr::Console::Control_request::len, L4virtio::Svr::Console::Control_request::msg, L4virtio::Svr::Virtqueue::next_avail(), port(), L4virtio::Svr::Console::Port::Port_added, L4virtio::Svr::Console::Port::Port_disabled, L4virtio::Svr::Console::Control_message::Port_open, L4virtio::Svr::Console::Port::Port_open, L4virtio::Svr::Console::Control_message::Port_ready, L4virtio::Svr::Console::Port::Port_ready, process_device_ready(), process_port_open(), process_port_ready(), L4virtio::Virtqueue::ready(), L4virtio::Svr::Request_processor::start(), L4virtio::Svr::Console::Port::status, L4virtio::Svr::Console::Port::tx, and L4virtio::Svr::Console::Control_message::value.

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
queueVirtqueue 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
portPort 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
idxPort that should be added.
Return values
L4_EOKMessage has been sent.
-L4_EPERMControl 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
idxPort that should be opened or closed.
openOpen or close port.
Return values
L4_EOKMessage has been sent.
-L4_EPERMControl 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
idxPort that should be removed.
Return values
L4_EOKMessage has been sent.
-L4_EPERMControl 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
valueThe 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
idThe id field of the control message, i.e. the port number.
valueThe 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
idThe id field of the control message, i.e. the port number.
valueThe 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
idxPort number.
eventKind of control event.
valueExtra information for the event.
nameName to be used for Port_name message
Return values
L4_EOKMessage has been sent.
-L4_ENODEVControl queue is not ready.
-L4_EBUSYCurrently no descriptor available in the control queue.
-L4_ENOMEMClient-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: