L4Re Operating System Framework
Interface and Usage Documentation
|
Base class implementing a virtio console functionality. More...
#include <virtio-console>
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. | |
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:
port_add()
.port_remove()
.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.
|
inlineexplicit |
Create a new multiport console device.
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.
|
inline |
Handle control message received from the driver.
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.
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().
|
pure virtual |
Notify queue of available data.
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.
|
pure virtual |
Return the specified port.
port | Port number. |
Implemented in L4virtio::Svr::Console::Device.
Referenced by check_queues(), handle_control_message(), port_add(), port_open(), port_remove(), process_port_ready(), and reset().
|
inline |
Send a DEVICE_ADD message and update the internal state.
idx | Port that should be added. |
L4_EOK | Message has been sent. |
-L4_EPERM | Control message is not allowed in the current state. |
port
must be smaller than the configured number of ports. 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().
|
inline |
Send a PORT_OPEN message and update the internal state.
idx | Port that should be opened or closed. |
open | Open or close port. |
L4_EOK | Message has been sent. |
-L4_EPERM | Control message is not allowed in the current state. |
port
must be smaller than the configured number of ports. 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().
|
inline |
Send a DEVICE_REMOVE message and update the internal state.
idx | Port that should be removed. |
L4_EOK | Message has been sent. |
-L4_EPERM | Control message is not allowed in the current state. |
port
must be smaller than the configured number of ports. 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().
|
pure virtual |
Callback called on DEVICE_READY event.
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().
|
pure virtual |
Callback called on PORT_OPEN event.
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().
|
inlinevirtual |
Callback called on PORT_READY event.
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().
|
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().
|
inline |
Send control message to driver.
idx | Port number. |
event | Kind of control event. |
value | Extra information for the event. |
name | Name to be used for Port_name message |
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. |
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().