drivers/staging/unisys/Documentation/overview.txt

1. Overview
-----------

This document describes the driver set for Unisys Secure Partitioning
(s-Par(R)).

s-Par is firmware that provides hardware partitioning capabilities for
splitting large-scale Intel x86 servers into multiple isolated
partitions. s-Par provides a set of para-virtualized device drivers to
allow guest partitions on the same server to share devices that would
normally be unsharable, specifically:

* visornic - network interface
* visorhba - scsi disk adapter
* visorinput - keyboard and mouse

These drivers conform to the standard Linux bus/device model described
within Documentation/driver-api/driver-model/, and utilize a driver named
visorbus to present the virtual busses involved. Drivers in the 'visor*'
driver set are commonly referred to as "guest drivers" or "client drivers".
All drivers except visorbus expose a device of a specific usable class to the
Linux guest environment (e.g., block, network, or input), and are collectively
referred to as "function drivers".

The back-end for each device is owned and managed by a small,
single-purpose service partition in the s-Par firmware, which communicates
with each guest partition sharing that device through an area of shared memory
called a "channel". In s-Par nomenclature, the back-end is often referred to
as the "service partition", "IO partition" (for virtual network and scsi disk
devices), or "console partition" (for virtual keyboard and mouse devices).

Each virtual device requires exactly 1 dedicated channel, which the guest
driver and back-end use to communicate.  The hypervisor need not intervene
(other than normal interrupt handling) in the interactions that occur across
this channel.

NOT covered in this document:

* s-Par also supports sharing physical PCI adapters via SR-IOV, but
  because this requires no specific support in the guest partitions, it will
  not be discussed in this document.  Shared SR-IOV devices should be used
  wherever possible for highest performance.

* Because the s-Par back-end provides a standard EFI framebuffer to each
  guest, the already-existing efifb Linux driver is used to provide guest
  video access. Thus, the only s-Par-unique support that is necessary to
  provide a guest graphics console are for keyboard and mouse (via visorinput).


2. Driver Descriptions
----------------------

2.1. visorbus
-------------

2.1.1. Overview
---------------

The visorbus driver handles the virtual busses on which all of the virtual
devices reside. It provides a registration function named
visorbus_register_visor_driver() that is called by each of the function
drivers at initialization time, which the function driver uses to tell
visorbus about the device classes (via specifying a list of device type
GUIDs) it wants to handle. For use by function drivers, visorbus provides
implementation for struct visor_driver and struct visor_device, as well
as utility functions for communicating with the back-end.

visorbus is associated with ACPI id "PNP0A07" in modules.alias, so if built
as a module it will typically be loaded automatically via standard udev or
systemd (God help us) configurations.

visorbus can similarly force auto-loading of function drivers for virtual
devices it discovers, as it includes a MODALIAS environment variable of this
form in the hotplug uevent environment when each virtual device is
discovered:

    visorbus:<device type GUID>

visorbus notifies each function driver when a device of its registered class
arrives and departs, by calling the function driver's probe() and remove()
methods.

The actual struct device objects that correspond to each virtual bus and
each virtual device are created and owned by visorbus.  These device objects
are created in response to messages from the s-Par back-end received on a
special control channel called the "controlvm channel" (each guest partition
has access to exactly 1 controlvm channel), and have a lifetime that is
independent of the function drivers that control them.

2.1.2. "struct visor device" Function Driver Interfaces
-------------------------------------------------------

The interface between visorbus and its function drivers is defined in
visorbus.h, and described below.

When a visor function driver loads, it calls visorbus_register_visor_driver()
to register itself with visorbus. The significant information passed in this
exchange is as follows:

* the GUID(s) of the channel type(s) that are handled by this driver, as
  well as a "friendly name" identifying each (this will be published under
  /sys/devices/visorbus<x>/dev<y>)

* the addresses of callback functions to be called whenever a virtual
  device/channel with the appropriate channel-type GUID(s) appears or
  disappears

* the address of a "channel_interrupt" function, which will be automatically
  called at specific intervals to enable the driver to poll the device
  channel for activity

The following functions implemented within each function driver will be
called automatically by the visorbus driver at appropriate times:

* The probe() function notifies about the creation of each new virtual
  device/channel instance.

* The remove() function notifies about the destruction of a virtual
  device/channel instance.

* The channel_interrupt() function is called at frequent intervals to
  give the function driver an opportunity to poll the virtual device channel
  for requests.  Information is passed to this function to enable the
  function driver to use the visorchannel_signalinsert() and
  visorchannel_signalremove() functions to respond to and initiate activity
  over the channel.  (Note that since it is the visorbus driver that
  determines when this is called, it is very easy to switch to
  interrupt-driven mechanisms when available for particular virtual device
  types.)

* The pause() function is called should it ever be necessary to direct the
  function driver to temporarily stop accessing the device channel.  An
  example of when this is needed is when the service partition implementing
  the back-end of the virtual device needs to be recovered.  After a
  successful return of pause(), the function driver must not access the
  device channel until a subsequent resume() occurs.

* The resume() function is the "book-end" to pause(), and is described above.

2.1.3. sysfs Advertised Information
-----------------------------------

Because visorbus is a standard Linux bus driver in the model described in
Documentation/driver-api/driver-model/, the hierarchy of s-Par virtual devices is
published in the sysfs tree beneath /bus/visorbus/, e.g.,
/sys/bus/visorbus/devices/ might look like:

    vbus1:dev1 -> ../../../devices/visorbus1/vbus1:dev1
    vbus1:dev2 -> ../../../devices/visorbus1/vbus1:dev2
    vbus1:dev3 -> ../../../devices/visorbus1/vbus1:dev3
    vbus2:dev0 -> ../../../devices/visorbus2/vbus2:dev0
    vbus2:dev1 -> ../../../devices/visorbus2/vbus2:dev1
    vbus2:dev2 -> ../../../devices/visorbus2/vbus2:dev2
    visorbus1 -> ../../../devices/visorbus1
    visorbus2 -> ../../../devices/visorbus2

visor_device notes:

* Each visorbus<n> entry denotes the existence of a struct visor_device
  denoting virtual bus #<n>.  A unique s-Par channel exists for each such
  virtual bus.

* Virtual bus numbers uniquely identify s-Par back-end service partitions.
  In this example, bus 1 corresponds to the s-Par console partition
  (controls keyboard, video, and mouse), whereas bus 2 corresponds to the
  s-Par IO partition (controls network and disk).

* Each vbus<x>:dev<y> entry denotes the existence of a struct visor_device
  denoting virtual device #<y> outboard of virtual bus #<x>.  A unique s-Par
  channel exists for each such virtual device.

* If a function driver has loaded and claimed a particular device, the
  bus/visorbus/devices/vbus<x>:dev<y>/driver symlink will indicate that
  function driver.

Every active visorbus device will have a sysfs subtree under:

    /sys/devices/visorbus<x>/vbus<x>:dev<y>/

The following files exist under /sys/devices/visorbus<x>/vbus<x>:dev<y>:

    subsystem                 link to sysfs tree that describes the
                              visorbus bus type; e.g.:
                                  ../../../bus/visorbus

    driver                    link to sysfs tree that describes the
                              function driver controlling this device;
                              e.g.:
                                  ../../../bus/visorbus/drivers/visorhba
                              Note that this "driver" link will not exist
                              if the appropriate function driver has not
                              been loaded yet.

    channel                   properties of the device channel (all in
                              ascii text format)

        clientpartition       handle identifying the guest (client) side
                              of this channel, e.g. 0x10000000.

        nbytes                total size of this channel in bytes

        physaddr              the guest physical address for the base of
                              the channel

        typeguid              a GUID identifying the channel type, in
                              xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation

        typename              a "friendly name" for this channel type, e.g.,
                              "keyboard".  Note that this name is provided by
                              a particular function driver, so "typename"
                              will return an empty string until AFTER the
                              appropriate function driver controlling this
                              channel type is loaded

        zoneguid              a GUID identifying the channel zone, in
                              xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation


2.2. visorhba
-------------

The visorhba driver registers with visorbus as the function driver to
handle virtual scsi disk devices, specified using the
VISOR_VHBA_CHANNEL_GUID type in the visorbus_register_visor_driver()
call. visorhba uses scsi_add_host() to expose a Linux block device
(e.g., /sys/block/) in the guest environment for each s-Par virtual device.

visorhba provides access to a shared SCSI host bus adapter and one or more
disk devices, by proxying SCSI commands between the guest and the service
partition that owns the shared SCSI adapter, using a channel between the
guest and the service partition. The disks that appear on the shared bus
are defined by the s-Par configuration and enforced by the service partition,
while the guest driver handles sending commands and handling responses. Each
disk is shared as a whole to a guest. Sharing the bus adapter in this way
provides resiliency; should the device encounter an error, only the service
partition is rebooted, and the device is reinitialized. This allows
guests to continue running and to recover from the error.

When compiled as a module, visorhba can be autoloaded by visorbus in
standard udev/systemd environments, as it includes the modules.alias
definition:

    "visorbus:"+VISOR_VHBA_CHANNEL_GUID_STR

i.e.:

    alias visorbus:414815ed-c58c-11da-95a9-00e08161165f visorhba


2.3. visornic
-------------

The visornic driver registers with visorbus as the function driver to
handle virtual network devices, specified using the
VISOR_VNIC_CHANNEL_GUID type in the visorbus_register_visor_driver()
call. visornic uses register_netdev() to expose a Linux device of class net
(e.g., /sys/class/net/) in the guest environment for each s-Par virtual
device.

visornic provides a paravirtualized network interface to a
guest by proxying buffer information between the guest and the service
partition that owns the shared network interface, using a channel
between the guest and the service partition. The connectivity of this
interface with the shared interface and possibly other guest
partitions is defined by the s-Par configuration and enforced by the
service partition; the guest driver handles communication and link
status.

When compiled as a module, visornic can be autoloaded by visorbus in
standard udev/systemd environments, as it includes the modules.alias
definition:

    "visorbus:"+VISOR_VNIC_CHANNEL_GUID_STR

i.e.:

    alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic


2.4. visorinput
---------------

The visorinput driver registers with visorbus as the function driver to
handle human input devices, specified using the
VISOR_KEYBOARD_CHANNEL_GUID and VISOR_MOUSE_CHANNEL_GUID
types in the visorbus_register_visor_driver() call. visorinput uses
input_register_device() to expose devices of class input
(e.g., /sys/class/input/) for virtual keyboard and virtual mouse devices.
A s-Par virtual keyboard device maps 1-to-1 with a Linux input device
named "visor Keyboard", while a s-Par virtual mouse device has 2 Linux input
devices created for it: 1 named "visor Wheel", and 1 named "visor Mouse".

By registering as input class devices, modern versions of X will
automatically find and properly use s-Par virtual keyboard and mouse devices.
As the s-Par back-end reports keyboard and mouse activity via events on the
virtual device channel, the visorinput driver delivers the activity to the
Linux environment by calling input_report_key() and input_report_abs().

You can interact with the guest console using the usyscon Partition Desktop
(a.k.a., "pd") application, provided as part of s-Par.  After installing the
usyscon Partition Desktop into a Linux environment via the
usyscon_partitiondesktop-*.rpm, or into a Windows environment via
PartitionDesktop.msi, you will be able to launch a console for your guest
Linux environment by clicking the console icon in the s-Par web UI.

When compiled as a module, visorinput can be autoloaded by visorbus in
standard udev/systemd environments, as it includes the modules.alias
definition:

    "visorbus:"+VISOR_MOUSE_CHANNEL_GUID_STR
    "visorbus:"+VISOR_KEYBOARD_CHANNEL_GUID_STR

i.e.:

    alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorinput
    alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorinput


3. Minimum Required Driver Set
------------------------------

visorbus is required for every Linux guest running under s-Par.

visorhba is typically required for a Linux guest running under s-Par, as it
is required if your guest boot disk is a virtual device provided by the s-Par
back-end, which is the default configuration.  However, for advanced
configurations where the Linux guest boots via an SR-IOV-provided HBA or
SAN disk for example, visorhba is not technically required.

visornic is typically required for a Linux guest running under s-Par, as it
is required if your guest network interface is a virtual device provided by
the s-Par back-end, which is the default configuration.  However, for
configurations where the Linux guest is provided with an SR-IOV NIC
for example, visornic is not technically required.

visorinput is only required for a Linux guest running under s-Par if you
require graphics-mode access to your guest console.