diff options
Diffstat (limited to 'drivers/staging/unisys/Documentation')
3 files changed, 368 insertions, 0 deletions
diff --git a/drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset b/drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset new file mode 100644 index 000000000..28f8f1233 --- /dev/null +++ b/drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset @@ -0,0 +1,101 @@ +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: guest/chipsetready +Date: 7/18/2014 +KernelVersion: TBD +Contact: sparmaintainer@unisys.com +Description: This entry is used by Unisys application software on the guest + to acknowledge completion of specific events for integration + purposes, but these acknowledgements are not required for the + guest to operate correctly. The interface accepts one of two + strings: MODULES_LOADED to indicate that the s-Par driver + modules have been loaded successfully, or CALLHOMEDISK_MOUNTED, + which indicates that the disk used to support call home services + has been successfully mounted. +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 new file mode 100644 index 000000000..8d078e4de --- /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 000000000..426f92b1c --- /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. |