Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-12-11 05:33:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

staging: unisys: documentation and TODO tweaks

Browse Source 
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>
This commit is contained in:
Tim Sell 2015-09-04 12:25:49 -04:00 committed by Greg Kroah-Hartman
parent 2b922cbef1
commit 4629385e6a
3 changed files with 322 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset
View File

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

438
drivers/staging/unisys/Documentation/overview.txt
View File

@ -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.
normally be unsharable, specifically:
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.
* visornic - network interface
* visorhba - scsi disk adapter
* visorhid - keyboard and mouse
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.
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".
Driver Descriptions
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).
Device Modules
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.
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.
NOT covered in this document:
visorchipset
* 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.
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.
* 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).
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
2. Driver Descriptions
----------------------
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
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:
The virtnic module provides a paravirtualized network interface to a
"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
@ -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
When compiled as a module, visornic can be autoloaded by visorbus in
standard udev/systemd environments, as it includes the modules.alias
definition:
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:"+SPAR_VNIC_CHANNEL_PROTOCOL_UUID_STR
visorbus
i.e.:
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.
alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic
visorclientbus
The visorclientbus module forwards the bus functions for virthba, and
virtnic to the virtpci driver.
2.4. visorhid
-------------
virtpci
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".
The virtpci module handles the bus functions for virthba, and virtnic.
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().
s-Par Integration Modules
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.
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.
When compiled as a module, visorhid can be autoloaded by visorbus in
standard udev/systemd environments, as it includes the modules.alias
definition:
visorvideoclient
"visorbus:"+SPAR_MOUSE_CHANNEL_PROTOCOL_UUID_STR
"visorbus:"+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID_STR
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.
i.e.:
sparstop
alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorhid
alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorhid
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
3. Minimum Required Driver Set
------------------------------
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.
visorbus is required for every Linux guest running under s-Par.
Support Modules
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.
The modules described in this section provide functions and
abstractions to support the modules described in the previous
sections, to avoid having duplicated functionality.
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.
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.
visorhid is only required for a Linux guest running under s-Par if you
require graphics-mode access to your guest console.

25
drivers/staging/unisys/TODO
View File

@ -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>