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: 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/dev) * 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 entry denotes the existence of a struct visor_device denoting virtual bus #. 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:dev entry denotes the existence of a struct visor_device denoting virtual device # outboard of virtual bus #. 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:dev/driver symlink will indicate that function driver. Every active visorbus device will have a sysfs subtree under: /sys/devices/visorbus/vbus:dev/ The following files exist under /sys/devices/visorbus/vbus:dev: 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.