Loading...
Searching...
No Matches
L4virtio::Svr::Console::Device Class Referenceabstract

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.
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.
virtual void | process_port_open (l4_uint32_t id, l4_uint16_t value)
| 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 | port_name (unsigned idx, char const *name)
| Send a PORT_NAME message to announce the port name.
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< No_custom_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

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

## Additional Inherited Members

Protected Attributes inherited from L4virtio::Svr::Device_t< No_custom_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, ...);
L4Re::Util::Object_registry
A registry that manages server objects and their attached IPC gates for a single server loop for a sp...
Definition object_registry:44
L4Re::Util::Object_registry::register_irq_obj
L4::Cap< L4::Irq > register_irq_obj(L4::Epiface *o) override
Register a handler for an interrupt.
Definition object_registry:227
L4virtio::Svr::Console::Device
Base class implementing a virtio console device with L4Re-based notification handling.
Definition virtio-console-device:120
L4virtio::Svr::Console::Device::tx_space_available
virtual void tx_space_available(unsigned port)=0
Callback to notify that data can be written to port.
L4virtio::Svr::Console::Device::port
Port * port(unsigned idx) override
Return the specified port.
Definition virtio-console-device:450
L4virtio::Svr::Console::Device::Device
Device(unsigned vq_max)
Create a new console device.
Definition virtio-console-device:145
L4virtio::Svr::Console::Device::rx_data_available
virtual void rx_data_available(unsigned port)=0
Callback to notify that new data is available to be read from port.
L4virtio::Svr::Device_t< No_custom_data >::init_mem_info
void init_mem_info(unsigned num)
Definition l4virtio:1012
L4Re::chkcap
T chkcap(T &&cap, char const *extra="", long err=-L4_ENOMEM)
Check for valid capability or raise C++ exception.
Definition error_helper:149
L4virtio
L4-VIRTIO Transport C++ API.
Definition l4virtio:26
L4::Epiface_t
Epiface implementation for Kobject-based interface implementations.
Definition ipc_epiface:504

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

Definition at line 118 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 145 of file virtio-console-device.

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

Here is the call graph for this function:

## 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 163 of file virtio-console-device.

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

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 182 of file virtio-console-device.

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

Here is the call graph for this function:

## Member Function Documentation

## 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 202 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 450 of file virtio-console-device.

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

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 272 of file virtio-console-device.

References L4virtio::Svr::Data_buffer::copy_to(), L4virtio::Svr::Device_t< No_custom_data >::device_error(), L4virtio::Svr::Virtqueue::finish(), L4virtio::Svr::Data_buffer::left, L4virtio::Svr::Device_t< No_custom_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, L4virtio::Svr::Console::Port::tx_ready(), and L4virtio::Svr::Virtqueue::Head_desc::valid().

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 341 of file virtio-console-device.

References L4virtio::Svr::Data_buffer::copy_to(), L4virtio::Svr::Device_t< No_custom_data >::device_error(), L4virtio::Svr::Virtqueue::finish(), L4virtio::Svr::Data_buffer::left, L4virtio::Svr::Device_t< No_custom_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. It is then your responsibility to inform the driver about usable ports, see port_add().

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

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

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

Here is the call graph for this function:

## process_port_open()

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

inlinevirtual

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.

The default implementation does nothing. Override it to implement some custom logic to respond to open/close events of the driver.

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

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

## 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 opens the port if the driver is ready. Otherwise, the port is removed 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 connected or unusable ports. See port_open() and port_remove().

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

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

References port(), L4virtio::Svr::Console::Port::Port_failed, L4virtio::Svr::Console::Virtio_con::port_open(), L4virtio::Svr::Console::Port::Port_ready, 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