mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-23 01:10:04 +00:00
![Mauro Carvalho Chehab](/assets/img/avatar_default.png)
The audience for the Kernel driver-model is clearly Kernel hackers. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com> # ice driver changes
337 lines
15 KiB
Text
337 lines
15 KiB
Text
1. Overview
|
|
-----------
|
|
|
|
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:
|
|
|
|
* visornic - network interface
|
|
* visorhba - scsi disk adapter
|
|
* visorinput - keyboard and mouse
|
|
|
|
These drivers conform to the standard Linux bus/device model described
|
|
within Documentation/driver-api/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 visorinput).
|
|
|
|
|
|
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.
|
|
|
|
2.1.3. sysfs Advertised Information
|
|
-----------------------------------
|
|
|
|
Because visorbus is a standard Linux bus driver in the model described in
|
|
Documentation/driver-api/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.
|
|
|
|
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
|
|
VISOR_VHBA_CHANNEL_GUID 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.
|
|
|
|
When compiled as a module, visorhba can be autoloaded by visorbus in
|
|
standard udev/systemd environments, as it includes the modules.alias
|
|
definition:
|
|
|
|
"visorbus:"+VISOR_VHBA_CHANNEL_GUID_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
|
|
VISOR_VNIC_CHANNEL_GUID 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
|
|
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.
|
|
|
|
When compiled as a module, visornic can be autoloaded by visorbus in
|
|
standard udev/systemd environments, as it includes the modules.alias
|
|
definition:
|
|
|
|
"visorbus:"+VISOR_VNIC_CHANNEL_GUID_STR
|
|
|
|
i.e.:
|
|
|
|
alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic
|
|
|
|
|
|
2.4. visorinput
|
|
---------------
|
|
|
|
The visorinput driver registers with visorbus as the function driver to
|
|
handle human input devices, specified using the
|
|
VISOR_KEYBOARD_CHANNEL_GUID and VISOR_MOUSE_CHANNEL_GUID
|
|
types in the visorbus_register_visor_driver() call. visorinput 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".
|
|
|
|
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 visorinput driver delivers the activity to the
|
|
Linux environment by calling input_report_key() and input_report_abs().
|
|
|
|
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.
|
|
|
|
When compiled as a module, visorinput can be autoloaded by visorbus in
|
|
standard udev/systemd environments, as it includes the modules.alias
|
|
definition:
|
|
|
|
"visorbus:"+VISOR_MOUSE_CHANNEL_GUID_STR
|
|
"visorbus:"+VISOR_KEYBOARD_CHANNEL_GUID_STR
|
|
|
|
i.e.:
|
|
|
|
alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorinput
|
|
alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorinput
|
|
|
|
|
|
3. Minimum Required Driver Set
|
|
------------------------------
|
|
|
|
visorbus is required for every Linux guest running under s-Par.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
visorinput is only required for a Linux guest running under s-Par if you
|
|
require graphics-mode access to your guest console.
|