staging: s-Par driver documentation

Documentation for the set of s-Par drivers

Signed-off-by: Ken Cox <jkc@redhat.com>
Cc: Ben Romer <sparmaintainer@unisys.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Ken Cox 2014-03-04 07:58:12 -06:00 committed by Greg Kroah-Hartman
parent dc95086172
commit abed632efd
4 changed files with 293 additions and 0 deletions

View file

@ -0,0 +1,174 @@
Overview
This document describes the driver set for Unisys Secure Partitioning (s-Par®).
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
partition is rebooted, and the device is reinitialized. This allows
guests to continue running and to recover from the error.
virtnic
The virtnic module 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.
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.
sparstop
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.
visordiag
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
The modules described in this section provide functions and
abstractions to support the modules described in the previous
sections, to avoid having duplicated functionality.
visornoop
The visornoop module is a placeholder that responds to device
create/destroy messages that are currently not in use by linux guests.
visoruislib
The visoruislib module is a support library, used to handle requests
from virtpci.
visorchannelstub
The visorchannelstub module provides support routines for storing and
retrieving data from a channel.
visorchannel
The visorchannel module is a support library that abstracts reading
and writing a channel in memory.
visorutil
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.
Minimum Required Driver Set
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.

View file

@ -0,0 +1,93 @@
s-Par Proc Entries
This document describes the proc entries created by the Unisys s-Par modules.
Support Module Entries
These entries are provided primarily for debugging.
/proc/uislib/info: This entry contains debugging information for the
uislib module, including bus information and memory usage.
/proc/visorchipset/controlvm: This directory contains debugging
entries for the controlvm channel used by visorchipset.
/proc/uislib/platform: This entry is used to display the platform
number this node is in the system. For some guests, this may be
invalid.
/proc/visorchipset/chipsetready: This entry is written to by scripts
to signify that any user level activity has been completed before the
guest can be considered running and is shown as running in the s-Par
UI.
Device Entries
These entries provide status of the devices shared by a service partition.
/proc/uislib/vbus: this is a directory containing entries for each
virtual bus. Each numbered sub-directory contains an info entry, which
describes the devices that appear on that bus.
/proc/uislib/cycles_before_wait: This entry is used to tune
performance, by setting the number of cycles we wait before going idle
when in polling mode. A longer time will reduce message latency but
spend more processing time polling.
/proc/uislib/smart_wakeup: This entry is used to tune performance, by
enabling or disabling smart wakeup.
/proc/virthba/info: This entry contains debugging information for the
virthba module, including interrupt information and memory usage.
/proc/virthba/enable_ints: This entry controls interrupt use by the
virthba module. Writing a 0 to this entry will disable interrupts.
/proc/virtnic/info: This entry contains debugging information for the
virtnic module, including interrupt information, send and receive
counts, and other device information.
/proc/virtnic/ethX: This is a directory containing entries for each
virtual NIC. Each named subdirectory contains two entries,
clientstring and zone.
/proc/virtpci/info: This entry contains debugging information for the
virtpci module, including virtual PCI bus information and device
locations.
/proc/virtnic/enable_ints: This entry controls interrupt use by the
virtnic module. Writing a 0 to this entry will disable interrupts.
Visorconinclient, visordiag, visornoop, visorserialclient, and
visorvideoclient Entries
The entries in proc for these modules all follow the same
pattern. Each module has its own proc directory with the same name,
e.g. visordiag presents a /proc/visordiag directory. Inside of the
module's directory are a device directory, which contains one numbered
directory for each device provided by that module. Each device has a
diag entry that presents the device number and visorbus name for that
device. The module directory also has a driver/diag entry, which
reports the corresponding s-Par version number of the driver.
Automated Installation Entries
These entries are used to pass information between the s-Par platform
and the Linux-based installation and recovery tool. These values are
read/write, however, the guest can only reset them to 0, or report an
error status through the installer entry. The values are only set via
s-Par's firmware interface, to help prevent accidentally booting into
the tool.
/proc/visorchipset/boottotool: This entry instructs s-Par that the
next reboot will launch the installation and recovery tool. If set to
0, the next boot will happen according to the UEFI boot manager
settings.
/proc/visorchipset/toolaction: This entry indicates the installation
and recovery tool mode requested for the next boot.
/proc/visorchipset/installer: this entry is used by the installation
and recovery tool to pass status and result information back to the
s-Par firmware.
/proc/visorchipset/partition: This directory contains the guest
partition configuration data for each virtual bus, for use during
installation and at runtime for s-Par service partitions.

View file

@ -0,0 +1,6 @@
Unisys s-Par drivers
M: Ben Romer <sparmaintainer@unisys.com>
S: Maintained
F: Documentation/s-Par/overview.txt
F: Documentation/s-Par/proc-entries.txt
F: drivers/staging/unisys/

View file

@ -0,0 +1,20 @@
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
Patches to:
Ken Cox <jkc@redhat.com>
Ben Romer <sparmaintainer@unisys.com>