diff options
Diffstat (limited to 'drivers/staging/unisys/Documentation/overview.txt')
-rw-r--r-- | drivers/staging/unisys/Documentation/overview.txt | 337 |
1 files changed, 0 insertions, 337 deletions
diff --git a/drivers/staging/unisys/Documentation/overview.txt b/drivers/staging/unisys/Documentation/overview.txt deleted file mode 100644 index cf29f884cbe0..000000000000 --- a/drivers/staging/unisys/Documentation/overview.txt +++ /dev/null @@ -1,337 +0,0 @@ -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. |