[PATCH 3/5] Documentation: Move visorbus documentation from staging to Documentation/

[David Kershner <david.kershner@unisys.com>]

This patch simple does a git mv of the
drivers/staging/unisys/Documentation directory to Documentation. Renames
overview.txt to visorbus.txt and renames sysfs-platform-visorchipset to
the correct name sysfs-bus-visorbus.

Signed-off-by: David Kershner <david.kershner@unisys.com>
---
 Documentation/ABI/stable/sysfs-bus-visorbus        |  89 ++++++
 Documentation/visorbus.txt                         | 337 +++++++++++++++++++++
 .../Documentation/ABI/sysfs-platform-visorchipset  |  89 ------
 drivers/staging/unisys/Documentation/overview.txt  | 337 ---------------------
 4 files changed, 426 insertions(+), 426 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-bus-visorbus
 create mode 100644 Documentation/visorbus.txt
 delete mode 100644 drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset
 delete mode 100644 drivers/staging/unisys/Documentation/overview.txt

diff --git a/Documentation/ABI/stable/sysfs-bus-visorbus b/Documentation/ABI/stable/sysfs-bus-visorbus
new file mode 100644
index 0000000..c2359de
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-visorbus
@@ -0,0 +1,89 @@
+This file describes sysfs entries beneath /devices/platform/visorchipset.
+
+What:		install/error
+Date:		7/18/2014
+KernelVersion: 	TBD
+Contact:	sparmaintainer@unisys.com
+Description:	used to send the ID of a string that should be displayed on
+		s-Par's automatic installation progress screen when an error
+		is encountered during installation. This field has no effect
+		if not in installation mode.
+Users:		sparmaintainer@unisys.com
+
+What:		install/remainingsteps
+Date:		7/18/2014
+KernelVersion: 	TBD
+Contact:	sparmaintainer@unisys.com
+Description:	used to set the value of the progress bar on the s-Par automatic
+		installation progress screen. This field has no effect if not in
+		installation mode.
+Users:		sparmaintainer@unisys.com
+
+What:		install/textid
+Date:		7/18/2014
+KernelVersion: 	TBD
+Contact:	sparmaintainer@unisys.com
+Description:	used to send the ID of a string that should be displayed on
+		s-Par's automatic installation progress screen. Setting this
+		field when not in installation mode (boottotool was set on
+		the previous guest boot) has no effect.
+Users:		sparmaintainer@unisys.com
+
+What:		install/boottotool
+Date:		7/18/2014
+KernelVersion: 	TBD
+Contact:	sparmaintainer@unisys.com
+Description:	The boottotool flag controls s-Par behavior on the next boot of
+		this guest. Setting the flag will cause the guest to boot from
+		the utility and installation image, which will use the value in
+		the toolaction field to determine what operation is being
+		requested.
+Users:		sparmaintainer@unisys.com
+
+What:		install/toolaction
+Date:		7/18/2014
+KernelVersion: 	TBD
+Contact:	sparmaintainer@unisys.com
+Description:	This field is used to tell s-Par which type of recovery tool
+		action to perform on the next guest boot-up. The meaning of the
+		value is dependent on the type of installation software used to
+		commission the guest.
+Users:		sparmaintainer@unisys.com
+
+What:		parahotplug/deviceenabled
+Date:		7/18/2014
+KernelVersion: 	TBD
+Contact:	sparmaintainer@unisys.com
+Description:	This entry is used by a Unisys support script installed on the
+		guest, and triggered by a udev event. The support script is
+		responsible for enabling and disabling SR-IOV devices when the
+		PF device is being recovered in another guest.
+
+		Some SR-IOV devices have problems when the PF is reset without
+		first disabling all VFs attached to that PF. s-Par handles this
+		situation by sending a message to guests using these VFs, and
+		the script will disable the device. When the PF is recovered,
+		another message is sent to the guests to re-enable the VFs.
+
+		The parahotplug/deviceenabled interface is used to acknowledge
+		the recovery message.
+Users:		sparmaintainer@unisys.com
+
+What:		parahotplug/devicedisabled
+Date:		7/18/2014
+KernelVersion: 	TBD
+Contact:	sparmaintainer@unisys.com
+Description:	This entry is used by a Unisys support script installed on the
+		guest, and triggered by a udev event. The support script is
+		responsible for enabling and disabling SR-IOV devices when the
+		PF device is being recovered in another guest.
+
+		Some SR-IOV devices have problems when the PF is reset without
+		first disabling all VFs attached to that PF. s-Par handles this
+		situation by sending a message to guests using these VFs, and
+		the script will disable the device. When the PF is recovered,
+		another message is sent to the guests to re-enable the VFs.
+
+		The parahotplug/devicedisaabled interface is used to acknowledge
+		the initial recovery message.
+Users:		sparmaintainer@unisys.com
diff --git a/Documentation/visorbus.txt b/Documentation/visorbus.txt
new file mode 100644
index 0000000..1146c1c
--- /dev/null
+++ b/Documentation/visorbus.txt
@@ -0,0 +1,337 @@
+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-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-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
+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.
+
+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
+
+
+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
+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:"+SPAR_VNIC_CHANNEL_PROTOCOL_UUID_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
+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID and SPAR_MOUSE_CHANNEL_PROTOCOL_UUID
+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:"+SPAR_MOUSE_CHANNEL_PROTOCOL_UUID_STR
+    "visorbus:"+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID_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.
diff --git a/drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset b/drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset
deleted file mode 100644
index c2359de..0000000
--- a/drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset
+++ /dev/null
@@ -1,89 +0,0 @@
-This file describes sysfs entries beneath /devices/platform/visorchipset.
-
-What:		install/error
-Date:		7/18/2014
-KernelVersion: 	TBD
-Contact:	sparmaintainer@unisys.com
-Description:	used to send the ID of a string that should be displayed on
-		s-Par's automatic installation progress screen when an error
-		is encountered during installation. This field has no effect
-		if not in installation mode.
-Users:		sparmaintainer@unisys.com
-
-What:		install/remainingsteps
-Date:		7/18/2014
-KernelVersion: 	TBD
-Contact:	sparmaintainer@unisys.com
-Description:	used to set the value of the progress bar on the s-Par automatic
-		installation progress screen. This field has no effect if not in
-		installation mode.
-Users:		sparmaintainer@unisys.com
-
-What:		install/textid
-Date:		7/18/2014
-KernelVersion: 	TBD
-Contact:	sparmaintainer@unisys.com
-Description:	used to send the ID of a string that should be displayed on
-		s-Par's automatic installation progress screen. Setting this
-		field when not in installation mode (boottotool was set on
-		the previous guest boot) has no effect.
-Users:		sparmaintainer@unisys.com
-
-What:		install/boottotool
-Date:		7/18/2014
-KernelVersion: 	TBD
-Contact:	sparmaintainer@unisys.com
-Description:	The boottotool flag controls s-Par behavior on the next boot of
-		this guest. Setting the flag will cause the guest to boot from
-		the utility and installation image, which will use the value in
-		the toolaction field to determine what operation is being
-		requested.
-Users:		sparmaintainer@unisys.com
-
-What:		install/toolaction
-Date:		7/18/2014
-KernelVersion: 	TBD
-Contact:	sparmaintainer@unisys.com
-Description:	This field is used to tell s-Par which type of recovery tool
-		action to perform on the next guest boot-up. The meaning of the
-		value is dependent on the type of installation software used to
-		commission the guest.
-Users:		sparmaintainer@unisys.com
-
-What:		parahotplug/deviceenabled
-Date:		7/18/2014
-KernelVersion: 	TBD
-Contact:	sparmaintainer@unisys.com
-Description:	This entry is used by a Unisys support script installed on the
-		guest, and triggered by a udev event. The support script is
-		responsible for enabling and disabling SR-IOV devices when the
-		PF device is being recovered in another guest.
-
-		Some SR-IOV devices have problems when the PF is reset without
-		first disabling all VFs attached to that PF. s-Par handles this
-		situation by sending a message to guests using these VFs, and
-		the script will disable the device. When the PF is recovered,
-		another message is sent to the guests to re-enable the VFs.
-
-		The parahotplug/deviceenabled interface is used to acknowledge
-		the recovery message.
-Users:		sparmaintainer@unisys.com
-
-What:		parahotplug/devicedisabled
-Date:		7/18/2014
-KernelVersion: 	TBD
-Contact:	sparmaintainer@unisys.com
-Description:	This entry is used by a Unisys support script installed on the
-		guest, and triggered by a udev event. The support script is
-		responsible for enabling and disabling SR-IOV devices when the
-		PF device is being recovered in another guest.
-
-		Some SR-IOV devices have problems when the PF is reset without
-		first disabling all VFs attached to that PF. s-Par handles this
-		situation by sending a message to guests using these VFs, and
-		the script will disable the device. When the PF is recovered,
-		another message is sent to the guests to re-enable the VFs.
-
-		The parahotplug/devicedisaabled interface is used to acknowledge
-		the initial recovery message.
-Users:		sparmaintainer@unisys.com
diff --git a/drivers/staging/unisys/Documentation/overview.txt b/drivers/staging/unisys/Documentation/overview.txt
deleted file mode 100644
index 1146c1c..0000000
--- 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-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-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
-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.
-
-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
-
-
-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
-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:"+SPAR_VNIC_CHANNEL_PROTOCOL_UUID_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
-SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID and SPAR_MOUSE_CHANNEL_PROTOCOL_UUID
-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:"+SPAR_MOUSE_CHANNEL_PROTOCOL_UUID_STR
-    "visorbus:"+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID_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.
-- 
1.9.1