L4Re Operating System Framework
Interface and Usage Documentation
|
Base class implementing a virtio console device with L4Re-based notification handling. More...
#include <virtio-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. | |
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:
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.
|
inlineexplicit |
Create a new console device.
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.
|
inlineexplicit |
Create a new console device.
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.
|
inlineexplicit |
Create a new console Device.
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.
|
inline |
Receive new control messages and resend stalled ones.
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().
|
inlineoverridevirtual |
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.
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().
|
inlineoverrideprotectedvirtual |
Return the specified port.
port | Port number. |
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().
|
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.
buf | The destination buffer |
len | Size of the buffer |
port | Port index to read data from |
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().
|
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.
buf | The souce buffer |
len | Size of the buffer |
port | Port index to write data to |
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().
|
inlineoverridevirtual |
Callback called on DEVICE_READY event.
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().
|
inlineoverridevirtual |
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. |
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().
|
inlineoverridevirtual |
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. |
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.