[PATCH 3/5] Documentation: Move visorbus documentation from staging to Documentation/
From: David Kershner
Date: Tue May 17 2016 - 03:35:44 EST
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@xxxxxxxxxx>
---
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@xxxxxxxxxx
+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@xxxxxxxxxx
+
+What: install/remainingsteps
+Date: 7/18/2014
+KernelVersion: TBD
+Contact: sparmaintainer@xxxxxxxxxx
+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@xxxxxxxxxx
+
+What: install/textid
+Date: 7/18/2014
+KernelVersion: TBD
+Contact: sparmaintainer@xxxxxxxxxx
+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@xxxxxxxxxx
+
+What: install/boottotool
+Date: 7/18/2014
+KernelVersion: TBD
+Contact: sparmaintainer@xxxxxxxxxx
+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@xxxxxxxxxx
+
+What: install/toolaction
+Date: 7/18/2014
+KernelVersion: TBD
+Contact: sparmaintainer@xxxxxxxxxx
+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@xxxxxxxxxx
+
+What: parahotplug/deviceenabled
+Date: 7/18/2014
+KernelVersion: TBD
+Contact: sparmaintainer@xxxxxxxxxx
+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@xxxxxxxxxx
+
+What: parahotplug/devicedisabled
+Date: 7/18/2014
+KernelVersion: TBD
+Contact: sparmaintainer@xxxxxxxxxx
+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@xxxxxxxxxx
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@xxxxxxxxxx
-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@xxxxxxxxxx
-
-What: install/remainingsteps
-Date: 7/18/2014
-KernelVersion: TBD
-Contact: sparmaintainer@xxxxxxxxxx
-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@xxxxxxxxxx
-
-What: install/textid
-Date: 7/18/2014
-KernelVersion: TBD
-Contact: sparmaintainer@xxxxxxxxxx
-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@xxxxxxxxxx
-
-What: install/boottotool
-Date: 7/18/2014
-KernelVersion: TBD
-Contact: sparmaintainer@xxxxxxxxxx
-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@xxxxxxxxxx
-
-What: install/toolaction
-Date: 7/18/2014
-KernelVersion: TBD
-Contact: sparmaintainer@xxxxxxxxxx
-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@xxxxxxxxxx
-
-What: parahotplug/deviceenabled
-Date: 7/18/2014
-KernelVersion: TBD
-Contact: sparmaintainer@xxxxxxxxxx
-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@xxxxxxxxxx
-
-What: parahotplug/devicedisabled
-Date: 7/18/2014
-KernelVersion: TBD
-Contact: sparmaintainer@xxxxxxxxxx
-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@xxxxxxxxxx
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