staging: unisys: documentation and TODO tweaks

Update documentation (including TODO) to reflect the current state of
the drivers.

Signed-off-by: Tim Sell <Timothy.Sell@unisys.com>
Signed-off-by: Benjamin Romer <benjamin.romer@unisys.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset

@@ -1,3 +1,5 @@
+This file describes sysfs entries beneath /devices/platform/visorchipset.
+
 What:		install/error
 Date:		7/18/2014
 KernelVersion: 	TBD

drivers/staging/unisys/Documentation/overview.txt

@@ -1,76 +1,282 @@
+1. Overview
+-----------
 
-Overview
-
-This document describes the driver set for Unisys Secure Partitioning (s-Par®).
+This document describes the driver set for Unisys Secure Partitioning
+(s-Par(R)).
 
 s-Par is firmware that provides hardware partitioning capabilities for
 splitting large-scale Intel x86 servers into multiple isolated
 partitions. s-Par provides a set of para-virtualized device drivers to
 allow guest partitions on the same server to share devices that would
-normally be unsharable; specifically, PCI network interfaces and host
-bus adapters that do not support shared access via SR-IOV. The shared
-device is owned and managed by a small, single-purpose service
-partition, which communicates with each guest partition sharing that
-device through an area of shared memory called a channel. Additional
-drivers provide support interfaces for communicating with s-Par
-services, logging and diagnostics, and accessing the Linux console
-from the s-Par user interface.
-
-The driver stack consists of a set of support modules, a set of bus
-modules, and a set of device driver modules. The support modules
-handle a number of common functions across each of the other
-drivers. The bus modules provide organization for the device driver
-modules, which provide the shared device functionality.
-
-These drivers are for the Unisys virtual PCI hardware model where the
-hypervisor need not intervene (other than normal interrupt handling)
-in the interactions between the client drivers and the virtual adapter
-firmware in the adapter service partition.
-
-Driver Descriptions
-
-Device Modules
-
-The modules in this section handle shared devices and the virtual
-buses required to support them. These modules use functions in and
-depend on the modules described in the support modules section.
-
-visorchipset
-
-The visorchipset module receives device creation and destruction
-events from the Command service partition of s-Par, as well as
-controlling registration of shared device drivers with the s-Par
-driver core. The events received are used to populate other s-Par
-modules with their assigned shared devices. Visorchipset is required
-for shared device drivers to function properly. Visorchipset also
-stores information for handling dump disk device creation during
-kdump.
-
-In operation, the visorchipset module processes device creation and
-destruction messages sent by s-Par's Command service partition through
-a channel. These messages result in creation (or destruction) of each
-virtual bus and virtual device. Each bus and device is also associated
-with a communication channel, which is used to communicate with one or
-more IO service partitions to perform device IO on behalf of the
-guest.
-
-virthba
-
-The virthba module provides access to a shared SCSI host bus adapter
-and one or more disk devices, by proxying SCSI commands between the
-guest and the service partition that owns the shared SCSI adapter,
-using a channel between the guest and the service partition. The disks
-that appear on the shared bus are defined by the s-Par configuration
-and enforced by the service partition, while the guest driver handles
-sending commands and handling responses. Each disk is shared as a
-whole to a guest. Sharing the bus adapter in this way provides
-resiliency; should the device encounter an error, only the service
+normally be unsharable, specifically:
+
+* visornic - network interface
+* visorhba - scsi disk adapter
+* visorhid - keyboard and mouse
+
+These drivers conform to the standard Linux bus/device model described
+within Documentation/driver-model/, and utilize a driver named visorbus to
+present the virtual busses involved. Drivers in the 'visor*' driver set are
+commonly referred to as "guest drivers" or "client drivers".  All drivers
+except visorbus expose a device of a specific usable class to the Linux guest
+environment (e.g., block, network, or input), and are collectively referred
+to as "function drivers".
+
+The back-end for each device is owned and managed by a small,
+single-purpose service partition in the s-Par firmware, which communicates
+with each guest partition sharing that device through an area of shared memory
+called a "channel". In s-Par nomenclature, the back-end is often referred to
+as the "service partition", "IO partition" (for virtual network and scsi disk
+devices), or "console partition" (for virtual keyboard and mouse devices).
+
+Each virtual device requires exactly 1 dedicated channel, which the guest
+driver and back-end use to communicate.  The hypervisor need not intervene
+(other than normal interrupt handling) in the interactions that occur across
+this channel.
+
+NOT covered in this document:
+
+* s-Par also supports sharing physical PCI adapters via SR-IOV, but
+  because this requires no specific support in the guest partitions, it will
+  not be discussed in this document.  Shared SR-IOV devices should be used
+  wherever possible for highest performance.
+
+* Because the s-Par back-end provides a standard EFI framebuffer to each
+  guest, the already-existing efifb Linux driver is used to provide guest
+  video access. Thus, the only s-Par-unique support that is necessary to
+  provide a guest graphics console are for keyboard and mouse (via visorhid).
+
+
+2. Driver Descriptions
+----------------------
+
+2.1. visorbus
+-------------
+
+2.1.1. Overview
+---------------
+
+The visorbus driver handles the virtual busses on which all of the virtual
+devices reside. It provides a registration function named
+visorbus_register_visor_driver() that is called by each of the function
+drivers at initialization time, which the function driver uses to tell
+visorbus about the device classes (via specifying a list of device type
+GUIDs) it wants to handle. For use by function drivers, visorbus provides
+implementation for struct visor_driver and struct visor_device, as well
+as utility functions for communicating with the back-end.
+
+visorbus is associated with ACPI id "PNP0A07" in modules.alias, so if built
+as a module it will typically be loaded automatically via standard udev or
+systemd (God help us) configurations.
+
+visorbus can similarly force auto-loading of function drivers for virtual
+devices it discovers, as it includes a MODALIAS environment variable of this
+form in the hotplug uevent environment when each virtual device is
+discovered:
+
+    visorbus:<device type GUID>
+
+visorbus notifies each function driver when a device of its registered class
+arrives and departs, by calling the function driver's probe() and remove()
+methods.
+
+The actual struct device objects that correspond to each virtual bus and
+each virtual device are created and owned by visorbus.  These device objects
+are created in response to messages from the s-Par back-end received on a
+special control channel called the "controlvm channel" (each guest partition
+has access to exactly 1 controlvm channel), and have a lifetime that is
+independent of the function drivers that control them.
+
+2.1.2. "struct visor device" Function Driver Interfaces
+-------------------------------------------------------
+
+The interface between visorbus and its function drivers is defined in
+visorbus.h, and described below.
+
+When a visor function driver loads, it calls visorbus_register_visor_driver()
+to register itself with visorbus. The significant information passed in this
+exchange is as follows:
+
+* the GUID(s) of the channel type(s) that are handled by this driver, as
+  well as a "friendly name" identifying each (this will be published under
+  /sys/devices/visorbus<x>/dev<y>)
+
+* the addresses of callback functions to be called whenever a virtual
+  device/channel with the appropriate channel-type GUID(s) appears or
+  disappears
+
+* the address of a "channel_interrupt" function, which will be automatically
+  called at specific intervals to enable the driver to poll the device
+  channel for activity
+
+The following functions implemented within each function driver will be
+called automatically by the visorbus driver at appropriate times:
+
+* The probe() function notifies about the creation of each new virtual
+  device/channel instance.
+
+* The remove() function notifies about the destruction of a virtual
+  device/channel instance.
+
+* The channel_interrupt() function is called at frequent intervals to
+  give the function driver an opportunity to poll the virtual device channel
+  for requests.  Information is passed to this function to enable the
+  function driver to use the visorchannel_signalinsert() and
+  visorchannel_signalremove() functions to respond to and initiate activity
+  over the channel.  (Note that since it is the visorbus driver that
+  determines when this is called, it is very easy to switch to
+  interrupt-driven mechanisms when available for particular virtual device
+  types.)
+
+* The pause() function is called should it ever be necessary to direct the
+  function driver to temporarily stop accessing the device channel.  An
+  example of when this is needed is when the service partition implementing
+  the back-end of the virtual device needs to be recovered.  After a
+  successful return of pause(), the function driver must not access the
+  device channel until a subsequent resume() occurs.
+
+* The resume() function is the "book-end" to pause(), and is described above.
+
+If/when a function driver creates a Linux device (that needs to be accessed
+from usermode), it calls visorbus_registerdevnode(), passing the major and
+minor number of the device.  (Of course not all function drivers will need
+to do this.)  This simply creates the appropriate "devmajorminor" sysfs entry
+described below, so that a hotplug script can use it to create a device node.
+
+2.1.3. sysfs Advertised Information
+-----------------------------------
+
+Because visorbus is a standard Linux bus driver in the model described in
+Documentation/driver-model/, the hierarchy of s-Par virtual devices is
+published in the sysfs tree beneath /bus/visorbus/, e.g.,
+/sys/bus/visorbus/devices/ might look like:
+
+    vbus1:dev1 -> ../../../devices/visorbus1/vbus1:dev1
+    vbus1:dev2 -> ../../../devices/visorbus1/vbus1:dev2
+    vbus1:dev3 -> ../../../devices/visorbus1/vbus1:dev3
+    vbus2:dev0 -> ../../../devices/visorbus2/vbus2:dev0
+    vbus2:dev1 -> ../../../devices/visorbus2/vbus2:dev1
+    vbus2:dev2 -> ../../../devices/visorbus2/vbus2:dev2
+    visorbus1 -> ../../../devices/visorbus1
+    visorbus2 -> ../../../devices/visorbus2
+
+visor_device notes:
+
+* Each visorbus<n> entry denotes the existence of a struct visor_device
+  denoting virtual bus #<n>.  A unique s-Par channel exists for each such
+  virtual bus.
+
+* Virtual bus numbers uniquely identify s-Par back-end service partitions.
+  In this example, bus 1 corresponds to the s-Par console partition
+  (controls keyboard, video, and mouse), whereas bus 2 corresponds to the
+  s-Par IO partition (controls network and disk).
+
+* Each vbus<x>:dev<y> entry denotes the existence of a struct visor_device
+  denoting virtual device #<y> outboard of virtual bus #<x>.  A unique s-Par
+  channel exists for each such virtual device.
+
+* If a function driver has loaded and claimed a particular device, the
+  bus/visorbus/devices/vbus<x>:dev<y>/driver symlink will indicate that
+  function driver.
+
+Every active visorbus device will have a sysfs subtree under:
+
+    /sys/devices/visorbus<x>/vbus<x>:dev<y>/
+
+The following files exist under /sys/devices/visorbus<x>/vbus<x>:dev<y>:
+
+    subsystem                 link to sysfs tree that describes the
+                              visorbus bus type; e.g.:
+                                  ../../../bus/visorbus
+
+    driver                    link to sysfs tree that describes the
+                              function driver controlling this device;
+                              e.g.:
+                                  ../../../bus/visorbus/drivers/visorhba
+                              Note that this "driver" link will not exist
+                              if the appropriate function driver has not
+                              been loaded yet.
+
+    devmajorminor
+
+        <devname>             if applicable, each file here identifies (via
+        ...                   its file contents) the
+                              "<major>:<minor>" needed for a device node to
+                              enable access from usermode.  There is exactly
+                              one file here for each different device node
+                              that can be accessed (from usermode).  Note
+                              that this info is provided by a particular
+                              function driver, so these will not exist
+                              until AFTER the appropriate function driver
+                              controlling this device class is loaded.
+
+    channel                   properties of the device channel (all in
+                              ascii text format)
+
+        clientpartition       handle identifying the guest (client) side
+                              of this channel, e.g. 0x10000000.
+
+        nbytes                total size of this channel in bytes
+
+        physaddr              the guest physical address for the base of
+                              the channel
+
+        typeguid              a GUID identifying the channel type, in
+                              xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation
+
+        typename              a "friendly name" for this channel type, e.g.,
+                              "keyboard".  Note that this name is provided by
+                              a particular function driver, so "typename"
+                              will return an empty string until AFTER the
+                              appropriate function driver controlling this
+                              channel type is loaded
+
+        zoneguid              a GUID identifying the channel zone, in
+                              xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation
+
+
+2.2. visorhba
+-------------
+
+The visorhba driver registers with visorbus as the function driver to
+handle virtual scsi disk devices, specified using the
+SPAR_VHBA_CHANNEL_PROTOCOL_UUID type in the visorbus_register_visor_driver()
+call. visorhba uses scsi_add_host() to expose a Linux block device
+(e.g., /sys/block/) in the guest environment for each s-Par virtual device.
+
+visorhba provides access to a shared SCSI host bus adapter and one or more
+disk devices, by proxying SCSI commands between the guest and the service
+partition that owns the shared SCSI adapter, using a channel between the
+guest and the service partition. The disks that appear on the shared bus
+are defined by the s-Par configuration and enforced by the service partition,
+while the guest driver handles sending commands and handling responses. Each
+disk is shared as a whole to a guest. Sharing the bus adapter in this way
+provides resiliency; should the device encounter an error, only the service
 partition is rebooted, and the device is reinitialized. This allows
 guests to continue running and to recover from the error.
 
-virtnic
+When compiled as a module, visorhba can be autoloaded by visorbus in
+standard udev/systemd environments, as it includes the modules.alias
+definition:
+
+    "visorbus:"+SPAR_VHBA_CHANNEL_PROTOCOL_UUID_STR
+
+i.e.:
+
+    alias visorbus:414815ed-c58c-11da-95a9-00e08161165f visorhba
+
 
-The virtnic module provides a paravirtualized network interface to a
+2.3. visornic
+-------------
+
+The visornic driver registers with visorbus as the function driver to
+handle virtual network devices, specified using the
+SPAR_VNIC_CHANNEL_PROTOCOL_UUID type in the visorbus_register_visor_driver()
+call. visornic uses register_netdev() to expose a Linux device of class net
+(e.g., /sys/class/net/) in the guest environment for each s-Par virtual
+device.
+
+visornic provides a paravirtualized network interface to a
 guest by proxying buffer information between the guest and the service
 partition that owns the shared network interface, using a channel
 between the guest and the service partition. The connectivity of this
@@ -79,96 +285,72 @@ partitions is defined by the s-Par configuration and enforced by the
 service partition; the guest driver handles communication and link
 status.
 
-visorserial
-
-The visorserial module allows the console of the linux guest to be
-accessed via the s-Par console serial channel. It creates devices in
-/dev/visorserialclientX which behave like a serial terminal and are
-connected to the diagnostics system in s-Par. By assigning a getty to
-the terminal in the guest, a user could log into and access the guest
-from the s-Par diagnostics SWITCH RUN terminal.
-
-visorbus
-
-The visorbus module handles the bus functions for most functional
-drivers except visorserial, visordiag, virthba, and virtnic. It
-maintains the sysfs subtree /sys/devices/visorbus*/. It is responsible
-for device creation and destruction of the devices on its bus.
-
-visorclientbus
-
-The visorclientbus module forwards the bus functions for virthba, and
-virtnic to the virtpci driver.
-
-virtpci
-
-The virtpci module handles the bus functions for virthba, and virtnic.
-
-s-Par Integration Modules
-
-The modules in this section provide integration with s-Par guest
-partition services like diagnostics and remote desktop. These modules
-depend on functions in the modules described in the support modules
-section.
-
-visorvideoclient
-
-The visorvideoclient module provides functionality for video support
-for the Unisys s-Par Partition Desktop application. The guest OS must
-also have the UEFI GOP protocol enabled for the partition desktop to
-function.  visorconinclient The visorconinclient module provides
-keyboard and mouse support for the Unisys s-Par Partition Desktop
-application.
+When compiled as a module, visornic can be autoloaded by visorbus in
+standard udev/systemd environments, as it includes the modules.alias
+definition:
 
-sparstop
+    "visorbus:"+SPAR_VNIC_CHANNEL_PROTOCOL_UUID_STR
 
-The sparstop module handles requests from the Unisys s-Par platform to
-shutdown the linux guest. It allows a program on the guest to perform
-clean-up functions on the guest before the guest is shut down or
-rebooted using ACPI.
+i.e.:
 
-visordiag
+    alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic
 
-This driver provides the ability for the guest to write information
-into the s-Par diagnostics subsystem. It creates a set of devices
-named /dev/visordiag.X which can be written to by the guest to add
-text to the s-Par system log.
 
-Support Modules
+2.4. visorhid
+-------------
 
-The modules described in this section provide functions and
-abstractions to support the modules described in the previous
-sections, to avoid having duplicated functionality.
+The visorhid driver registers with visorbus as the function driver to
+handle human input devices, specified using the
+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID and SPAR_MOUSE_CHANNEL_PROTOCOL_UUID
+types in the visorbus_register_visor_driver() call. visorhid uses
+input_register_device() to expose devices of class input
+(e.g., /sys/class/input/) for virtual keyboard and virtual mouse devices.
+A s-Par virtual keyboard device maps 1-to-1 with a Linux input device
+named "visor Keyboard", while a s-Par virtual mouse device has 2 Linux input
+devices created for it: 1 named "visor Wheel", and 1 named "visor Mouse".
 
-visornoop
+By registering as input class devices, modern versions of X will
+automatically find and properly use s-Par virtual keyboard and mouse devices.
+As the s-Par back-end reports keyboard and mouse activity via events on the
+virtual device channel, the visorhid driver delivers the activity to the
+Linux environment by calling input_report_key() and input_report_abs().
 
-The visornoop module is a placeholder that responds to device
-create/destroy messages that are currently not in use by linux guests.
+You can interact with the guest console using the usyscon Partition Desktop
+(a.k.a., "pd") application, provided as part of s-Par.  After installing the
+usyscon Partition Desktop into a Linux environment via the
+usyscon_partitiondesktop-*.rpm, or into a Windows environment via
+PartitionDesktop.msi, you will be able to launch a console for your guest
+Linux environment by clicking the console icon in the s-Par web UI.
 
-visoruislib
+When compiled as a module, visorhid can be autoloaded by visorbus in
+standard udev/systemd environments, as it includes the modules.alias
+definition:
 
-The visoruislib module is a support library, used to handle requests
-from virtpci.
+    "visorbus:"+SPAR_MOUSE_CHANNEL_PROTOCOL_UUID_STR
+    "visorbus:"+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID_STR
 
-visorchannelstub
+i.e.:
 
-The visorchannelstub module provides support routines for storing and
-retrieving data from a channel.
+    alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorhid
+    alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorhid
 
-visorchannel
 
-The visorchannel module is a support library that abstracts reading
-and writing a channel in memory.
+3. Minimum Required Driver Set
+------------------------------
 
-visorutil
+visorbus is required for every Linux guest running under s-Par.
 
-The visorutil module is a support library required by all other s-Par
-driver modules. Among its features it abstracts reading, writing, and
-manipulating a block of memory.
+visorhba is typically required for a Linux guest running under s-Par, as it
+is required if your guest boot disk is a virtual device provided by the s-Par
+back-end, which is the default configuration.  However, for advanced
+configurations where the Linux guest boots via an SR-IOV-provided HBA or
+SAN disk for example, visorhba is not technically required.
 
-Minimum Required Driver Set
+visornic is typically required for a Linux guest running under s-Par, as it
+is required if your guest network interface is a virtual device provided by
+the s-Par back-end, which is the default configuration.  However, for
+configurations where the Linux guest is provided with an SR-IOV NIC
+for example, visornic is not technically required.
 
-The drivers required to boot a Linux guest are visorchipset, visorbus,
-visorvideoclient, visorconinclient, visoruislib, visorchannelstub,
-visorchannel, and visorutil. The other drivers are required by the
-product configurations that are currently being marketed.
+visorhid is only required for a Linux guest running under s-Par if you
+require graphics-mode access to your guest console.

drivers/staging/unisys/TODO

@@ -1,19 +1,14 @@
 TODO:
-	-checkpatch warnings
-	-move /proc entries to /sys
-	-proper major number(s)
-	-add other drivers needed for full functionality:
-		-visorclientbus
-		-visorbus
-		-visordiag
-		-virtnic
-		-visornoop
-		-visorserial
-		-visorvideoclient
-		-visorconinclient
-		-sparstop
-	-move individual drivers into proper driver subsystems
-		
+	- enhance visornic to use channel_interrupt() hook instead of a
+	  kernel thread
+	- enhance visorhba to use channel_interrupt() hook instead of a
+	  kernel thread
+	- teach visorbus to handle virtual interrupts triggered by s-Par
+	  back-end, and call function driver's channel_interrupt() function
+	  when they occur
+	- enhance debugfs interfaces (e.g., per device, etc.)
+	- upgrade/remove deprecated workqueue operations
+	- move individual drivers into proper driver subsystems
 
 Patches to:
 	Greg Kroah-Hartman <gregkh@linuxfoundation.org>