+1. Overview
+-----------
-Overview
-
-This document describes the driver set for Unisys Secure Partitioning (s-Par®).
+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, PCI network interfaces and host
-bus adapters that do not support shared access via SR-IOV. The shared
-device is owned and managed by a small, single-purpose service
-partition, which communicates with each guest partition sharing that
-device through an area of shared memory called a channel. Additional
-drivers provide support interfaces for communicating with s-Par
-services, logging and diagnostics, and accessing the Linux console
-from the s-Par user interface.
-
-The driver stack consists of a set of support modules, a set of bus
-modules, and a set of device driver modules. The support modules
-handle a number of common functions across each of the other
-drivers. The bus modules provide organization for the device driver
-modules, which provide the shared device functionality.
-
-These drivers are for the Unisys virtual PCI hardware model where the
-hypervisor need not intervene (other than normal interrupt handling)
-in the interactions between the client drivers and the virtual adapter
-firmware in the adapter service partition.
-
-Driver Descriptions
-
-Device Modules
-
-The modules in this section handle shared devices and the virtual
-buses required to support them. These modules use functions in and
-depend on the modules described in the support modules section.
-
-visorchipset
-
-The visorchipset module receives device creation and destruction
-events from the Command service partition of s-Par, as well as
-controlling registration of shared device drivers with the s-Par
-driver core. The events received are used to populate other s-Par
-modules with their assigned shared devices. Visorchipset is required
-for shared device drivers to function properly. Visorchipset also
-stores information for handling dump disk device creation during
-kdump.
-
-In operation, the visorchipset module processes device creation and
-destruction messages sent by s-Par's Command service partition through
-a channel. These messages result in creation (or destruction) of each
-virtual bus and virtual device. Each bus and device is also associated
-with a communication channel, which is used to communicate with one or
-more IO service partitions to perform device IO on behalf of the
-guest.
-
-virthba
-
-The virthba module 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
+normally be unsharable, specifically:
+
+* visornic - network interface
+* visorhba - scsi disk adapter
+* visorhid - keyboard and mouse
+
+These drivers conform to the standard Linux bus/device model described
+within Documentation/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 visorhid).
+
+
+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.
+
+If/when a function driver creates a Linux device (that needs to be accessed
+from usermode), it calls visorbus_registerdevnode(), passing the major and
+minor number of the device. (Of course not all function drivers will need
+to do this.) This simply creates the appropriate "devmajorminor" sysfs entry
+described below, so that a hotplug script can use it to create a device node.
+
+2.1.3. sysfs Advertised Information
+-----------------------------------
+
+Because visorbus is a standard Linux bus driver in the model described in
+Documentation/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.
+
+ devmajorminor
+
+ <devname> if applicable, each file here identifies (via
+ ... its file contents) the
+ "<major>:<minor>" needed for a device node to
+ enable access from usermode. There is exactly
+ one file here for each different device node
+ that can be accessed (from usermode). Note
+ that this info is provided by a particular
+ function driver, so these will not exist
+ until AFTER the appropriate function driver
+ controlling this device class is loaded.
+
+ 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
+SPAR_VHBA_CHANNEL_PROTOCOL_UUID 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.
-virtnic
+When compiled as a module, visorhba can be autoloaded by visorbus in
+standard udev/systemd environments, as it includes the modules.alias
+definition:
+
+ "visorbus:"+SPAR_VHBA_CHANNEL_PROTOCOL_UUID_STR
+
+i.e.:
+
+ alias visorbus:414815ed-c58c-11da-95a9-00e08161165f visorhba
+
-The virtnic module provides a paravirtualized network interface to a
+2.3. visornic
+-------------
+
+The visornic driver registers with visorbus as the function driver to
+handle virtual network devices, specified using the
+SPAR_VNIC_CHANNEL_PROTOCOL_UUID 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
service partition; the guest driver handles communication and link
status.
-visorserial
-
-The visorserial module allows the console of the linux guest to be
-accessed via the s-Par console serial channel. It creates devices in
-/dev/visorserialclientX which behave like a serial terminal and are
-connected to the diagnostics system in s-Par. By assigning a getty to
-the terminal in the guest, a user could log into and access the guest
-from the s-Par diagnostics SWITCH RUN terminal.
-
-visorbus
-
-The visorbus module handles the bus functions for most functional
-drivers except visorserial, visordiag, virthba, and virtnic. It
-maintains the sysfs subtree /sys/devices/visorbus*/. It is responsible
-for device creation and destruction of the devices on its bus.
-
-visorclientbus
-
-The visorclientbus module forwards the bus functions for virthba, and
-virtnic to the virtpci driver.
-
-virtpci
-
-The virtpci module handles the bus functions for virthba, and virtnic.
-
-s-Par Integration Modules
-
-The modules in this section provide integration with s-Par guest
-partition services like diagnostics and remote desktop. These modules
-depend on functions in the modules described in the support modules
-section.
-
-visorvideoclient
-
-The visorvideoclient module provides functionality for video support
-for the Unisys s-Par Partition Desktop application. The guest OS must
-also have the UEFI GOP protocol enabled for the partition desktop to
-function. visorconinclient The visorconinclient module provides
-keyboard and mouse support for the Unisys s-Par Partition Desktop
-application.
+When compiled as a module, visornic can be autoloaded by visorbus in
+standard udev/systemd environments, as it includes the modules.alias
+definition:
-sparstop
+ "visorbus:"+SPAR_VNIC_CHANNEL_PROTOCOL_UUID_STR
-The sparstop module handles requests from the Unisys s-Par platform to
-shutdown the linux guest. It allows a program on the guest to perform
-clean-up functions on the guest before the guest is shut down or
-rebooted using ACPI.
+i.e.:
-visordiag
+ alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic
-This driver provides the ability for the guest to write information
-into the s-Par diagnostics subsystem. It creates a set of devices
-named /dev/visordiag.X which can be written to by the guest to add
-text to the s-Par system log.
-Support Modules
+2.4. visorhid
+-------------
-The modules described in this section provide functions and
-abstractions to support the modules described in the previous
-sections, to avoid having duplicated functionality.
+The visorhid driver registers with visorbus as the function driver to
+handle human input devices, specified using the
+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID and SPAR_MOUSE_CHANNEL_PROTOCOL_UUID
+types in the visorbus_register_visor_driver() call. visorhid 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".
-visornoop
+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 visorhid driver delivers the activity to the
+Linux environment by calling input_report_key() and input_report_abs().
-The visornoop module is a placeholder that responds to device
-create/destroy messages that are currently not in use by linux guests.
+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.
-visoruislib
+When compiled as a module, visorhid can be autoloaded by visorbus in
+standard udev/systemd environments, as it includes the modules.alias
+definition:
-The visoruislib module is a support library, used to handle requests
-from virtpci.
+ "visorbus:"+SPAR_MOUSE_CHANNEL_PROTOCOL_UUID_STR
+ "visorbus:"+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID_STR
-visorchannelstub
+i.e.:
-The visorchannelstub module provides support routines for storing and
-retrieving data from a channel.
+ alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorhid
+ alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorhid
-visorchannel
-The visorchannel module is a support library that abstracts reading
-and writing a channel in memory.
+3. Minimum Required Driver Set
+------------------------------
-visorutil
+visorbus is required for every Linux guest running under s-Par.
-The visorutil module is a support library required by all other s-Par
-driver modules. Among its features it abstracts reading, writing, and
-manipulating a block of memory.
+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.
-Minimum Required Driver Set
+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.
-The drivers required to boot a Linux guest are visorchipset, visorbus,
-visorvideoclient, visorconinclient, visoruislib, visorchannelstub,
-visorchannel, and visorutil. The other drivers are required by the
-product configurations that are currently being marketed.
+visorhid is only required for a Linux guest running under s-Par if you
+require graphics-mode access to your guest console.
projects / linux-beck.git / commitdiff