L4Re Operating System Framework
Interface and Usage Documentation
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::Irqdevice_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::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.
 

Protected Member Functions

void resend_stalled_control_messages ()
 Try to resend a stalled control message and update the port and global state accordingly.
 
Portport (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.
 

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 L4::Epiface_t<My_console, L4virtio::Device>
{
public:
: 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, ...);
A registry that manages server objects and their attached IPC gates for a single server loop for a sp...
L4::Cap< L4::Irq > register_irq_obj(L4::Epiface *o) override
Register a handler for an interrupt.
Base class implementing a virtio console device with L4Re-based notification handling.
T chkcap(T &&cap, char const *extra="", long err=-L4_ENOMEM)
Check for valid capability or raise C++ exception.
Definition error_helper:145
L4-VIRTIO Transport C++ API.
Definition l4virtio:26
Epiface implementation for Kobject-based interface implementations.
Definition ipc_epiface:515

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.

Constructor & Destructor Documentation

◆ Device() [1/3]

L4virtio::Svr::Console::Device::Device ( unsigned  vq_max)
inlineexplicit

Create a new console device.

Parameters
vq_maxMaximum 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.

◆ Device() [2/3]

L4virtio::Svr::Console::Device::Device ( unsigned  vq_max,
unsigned  ports 
)
inlineexplicit

Create a new console device.

Parameters
vq_maxMaximum number of buffers in data queues.
portsNumber 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.

+ 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_numsMaximum 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.

+ Here is the call graph for this function:

Member Function Documentation

◆ do_control_work()

int L4virtio::Svr::Console::Device::do_control_work ( )
inline

Receive new control messages and resend stalled ones.

Return values
seehandle_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().

+ Here is the call graph for this function:

◆ notify_queue()

void L4virtio::Svr::Console::Device::notify_queue ( Virtqueue queue)
inlineoverridevirtual

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.

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().

+ Here is the call graph for this function:

◆ port()

Port * L4virtio::Svr::Console::Device::port ( unsigned  port)
inlineoverrideprotectedvirtual

Return the specified port.

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

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().

+ 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
bufThe destination buffer
lenSize of the buffer
portPort index to read data from
Returns
Number of bytes read

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().

+ 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
bufThe souce buffer
lenSize of the buffer
portPort index to write data to
Returns
Number of bytes written

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().

+ 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
valueThe 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().

+ Here is the call graph for this function:

◆ process_port_open()

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

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.

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().

+ Here is the call graph for this function:

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

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.

+ Here is the call graph for this function:

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