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 | 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.
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< No_custom_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< No_custom_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:

- inform the driver about usable ports once the device is ready as signaled in process_device_ready(), see the wrapper port_add().
- inform the driver about unusable ports, see the wrapper port_remove().
- react to open/close events, see the wrapper 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 267 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_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 293 of file virtio-console.

References L4Re::chksys(), L4virtio::Svr::Console::Features::console_multiport(), L4_EINVAL, L4VIRTIO_ID_CONSOLE, and L4virtio::Svr::Dev_features::raw.

Referenced by L4virtio::Svr::Console::Device::Device(), L4virtio::Svr::Console::Device::Device(), and L4virtio::Svr::Console::Device::Device().

Here is the call graph for this function:
Here is the caller 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_EOK | Message has been handled.
  -L4_ENODEV | Control queue is not ready.
  -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 536 of file virtio-console.

References L4virtio::Svr::Console::Control_message::Device_ready, L4virtio::Svr::Console::Control_message::event, L4virtio::Svr::Virtqueue::finish(), 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(), 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, process_device_ready(), process_port_open(), process_port_ready(), L4virtio::Virtqueue::ready(), L4virtio::Svr::Request_processor::start(), and L4virtio::Svr::Console::Control_message::value.

Here is the call 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

  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.

## port()

virtual Port * L4virtio::Svr::Console::Virtio_con::port | ( | unsigned | port | ) |

pure virtual

Return the specified port.

Parameters

  port | Port number.

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

Implemented in L4virtio::Svr::Console::Device.

References port().

Referenced by check_queues(), port(), port_add(), port_name(), port_open(), port_remove(), process_port_ready(), and reset().

Here is the call graph for this function:
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

  idx | Port that should be added.

Return values

  L4_EOK | Message has been sent.
  -L4_EPERM | Invalid state transition.

Precondition
  idx must be smaller than the configured number of ports.
  Port must not already exist.

Definition at line 379 of file virtio-console.

References L4_EOK, L4_EPERM, port(), L4virtio::Svr::Console::Port::Port_added, L4virtio::Svr::Console::Port::Port_disabled, and L4virtio::Svr::Console::Port::status.

Referenced by L4virtio::Svr::Console::Device::process_device_ready().

Here is the call graph for this function:
Here is the caller graph for this function:

## port_name()

int L4virtio::Svr::Console::Virtio_con::port_name | ( | unsigned | idx,
|  | char const * | name )

inline

Send a PORT_NAME message to announce the port name.

Parameters

  idx | Port that should be opened or closed.
  name | The port name

Return values

  L4_EOK | Message has been sent.
  -L4_EPERM | Control message is not allowed in the current state.

Returns
  Errors from send_control_message()

Precondition
  idx must be smaller than the configured number of ports.
  Port must already exist.

Definition at line 455 of file virtio-console.

References L4_EPERM, port(), L4virtio::Svr::Console::Port::Port_disabled, L4virtio::Svr::Console::Control_message::Port_name, send_control_message(), and L4virtio::Svr::Console::Port::status.

Here is the call 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

  idx | Port that should be opened or closed.
  open | Open or close port.

Return values

  L4_EOK | Message has been sent.
  -L4_EPERM | Invalid state transition.

Precondition
  idx must be smaller than the configured number of ports.
  Port must be ready when opening or open when closing.

Definition at line 428 of file virtio-console.

References L4_EOK, L4_EPERM, port(), L4virtio::Svr::Console::Port::Port_open, L4virtio::Svr::Console::Port::Port_ready, and L4virtio::Svr::Console::Port::status.

Referenced by L4virtio::Svr::Console::Device::process_port_ready().

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

  idx | Port that should be removed.

Return values

  L4_EOK | Message has been sent.
  -L4_EPERM | Invalid state transition.

Precondition
  idx must be smaller than the configured number of ports.
  Port must already exist.

Definition at line 403 of file virtio-console.

References L4_EOK, L4_EPERM, port(), L4virtio::Svr::Console::Port::Port_disabled, and L4virtio::Svr::Console::Port::status.

Referenced by L4virtio::Svr::Console::Device::process_port_ready().

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

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

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

  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.

Signal that an application has opened the port. Can to be overridden by the derived class if the MULTIPORT feature is enabled.

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

  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 698 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 652 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

  idx | Port number.
  event | Kind of control event.
  value | Extra information for the event.
  name | Name to be used for Port_name message

Return values

  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.

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 487 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(), and L4virtio::Svr::Request_processor::start().

Referenced by port_name().

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:

- l4/l4virtio/server/virtio-console