From abed632efd87a655eb7e9e84d889161a1600b7d3 Mon Sep 17 00:00:00 2001 From: Ken Cox Date: Tue, 4 Mar 2014 07:58:12 -0600 Subject: [PATCH] staging: s-Par driver documentation Documentation for the set of s-Par drivers Signed-off-by: Ken Cox Cc: Ben Romer Signed-off-by: Greg Kroah-Hartman --- .../staging/unisys/Documentation/overview.txt | 174 ++++++++++++++++++ .../unisys/Documentation/proc-entries.txt | 93 ++++++++++ drivers/staging/unisys/MAINTAINERS | 6 + drivers/staging/unisys/TODO | 20 ++ 4 files changed, 293 insertions(+) create mode 100644 drivers/staging/unisys/Documentation/overview.txt create mode 100644 drivers/staging/unisys/Documentation/proc-entries.txt create mode 100644 drivers/staging/unisys/MAINTAINERS create mode 100644 drivers/staging/unisys/TODO diff --git a/drivers/staging/unisys/Documentation/overview.txt b/drivers/staging/unisys/Documentation/overview.txt new file mode 100644 index 000000000000..8d078e4de3b8 --- /dev/null +++ b/drivers/staging/unisys/Documentation/overview.txt @@ -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. diff --git a/drivers/staging/unisys/Documentation/proc-entries.txt b/drivers/staging/unisys/Documentation/proc-entries.txt new file mode 100644 index 000000000000..426f92b1c577 --- /dev/null +++ b/drivers/staging/unisys/Documentation/proc-entries.txt @@ -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. diff --git a/drivers/staging/unisys/MAINTAINERS b/drivers/staging/unisys/MAINTAINERS new file mode 100644 index 000000000000..c9cef0b91531 --- /dev/null +++ b/drivers/staging/unisys/MAINTAINERS @@ -0,0 +1,6 @@ +Unisys s-Par drivers +M: Ben Romer +S: Maintained +F: Documentation/s-Par/overview.txt +F: Documentation/s-Par/proc-entries.txt +F: drivers/staging/unisys/ diff --git a/drivers/staging/unisys/TODO b/drivers/staging/unisys/TODO new file mode 100644 index 000000000000..c4265a2e73d9 --- /dev/null +++ b/drivers/staging/unisys/TODO @@ -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 + Ben Romer