kernel/drivers/staging/unisys/Documentation/overview.txt

   1
   2 Overview
   3
   4 This document describes the driver set for Unisys Secure Partitioning (s-Par®).
   5
   6 s-Par is firmware that provides hardware partitioning capabilities for
   7 splitting large-scale Intel x86 servers into multiple isolated
   8 partitions. s-Par provides a set of para-virtualized device drivers to
   9 allow guest partitions on the same server to share devices that would
  10 normally be unsharable; specifically, PCI network interfaces and host
  11 bus adapters that do not support shared access via SR-IOV. The shared
  12 device is owned and managed by a small, single-purpose service
  13 partition, which communicates with each guest partition sharing that
  14 device through an area of shared memory called a channel. Additional
  15 drivers provide support interfaces for communicating with s-Par
  16 services, logging and diagnostics, and accessing the Linux console
  17 from the s-Par user interface.
  18
  19 The driver stack consists of a set of support modules, a set of bus
  20 modules, and a set of device driver modules. The support modules
  21 handle a number of common functions across each of the other
  22 drivers. The bus modules provide organization for the device driver
  23 modules, which provide the shared device functionality.
  24
  25 These drivers are for the Unisys virtual PCI hardware model where the
  26 hypervisor need not intervene (other than normal interrupt handling)
  27 in the interactions between the client drivers and the virtual adapter
  28 firmware in the adapter service partition.
  29
  30 Driver Descriptions
  31
  32 Device Modules
  33
  34 The modules in this section handle shared devices and the virtual
  35 buses required to support them. These modules use functions in and
  36 depend on the modules described in the support modules section.
  37
  38 visorchipset
  39
  40 The visorchipset module receives device creation and destruction
  41 events from the Command service partition of s-Par, as well as
  42 controlling registration of shared device drivers with the s-Par
  43 driver core. The events received are used to populate other s-Par
  44 modules with their assigned shared devices. Visorchipset is required
  45 for shared device drivers to function properly. Visorchipset also
  46 stores information for handling dump disk device creation during
  47 kdump.
  48
  49 In operation, the visorchipset module processes device creation and
  50 destruction messages sent by s-Par's Command service partition through
  51 a channel. These messages result in creation (or destruction) of each
  52 virtual bus and virtual device. Each bus and device is also associated
  53 with a communication channel, which is used to communicate with one or
  54 more IO service partitions to perform device IO on behalf of the
  55 guest.
  56
  57 virthba
  58
  59 The virthba module provides access to a shared SCSI host bus adapter
  60 and one or more disk devices, by proxying SCSI commands between the
  61 guest and the service partition that owns the shared SCSI adapter,
  62 using a channel between the guest and the service partition. The disks
  63 that appear on the shared bus are defined by the s-Par configuration
  64 and enforced by the service partition, while the guest driver handles
  65 sending commands and handling responses. Each disk is shared as a
  66 whole to a guest. Sharing the bus adapter in this way provides
  67 resiliency; should the device encounter an error, only the service
  68 partition is rebooted, and the device is reinitialized. This allows
  69 guests to continue running and to recover from the error.
  70
  71 virtnic
  72
  73 The virtnic module provides a paravirtualized network interface to a
  74 guest by proxying buffer information between the guest and the service
  75 partition that owns the shared network interface, using a channel
  76 between the guest and the service partition. The connectivity of this
  77 interface with the shared interface and possibly other guest
  78 partitions is defined by the s-Par configuration and enforced by the
  79 service partition; the guest driver handles communication and link
  80 status.
  81
  82 visorserial
  83
  84 The visorserial module allows the console of the linux guest to be
  85 accessed via the s-Par console serial channel. It creates devices in
  86 /dev/visorserialclientX which behave like a serial terminal and are
  87 connected to the diagnostics system in s-Par. By assigning a getty to
  88 the terminal in the guest, a user could log into and access the guest
  89 from the s-Par diagnostics SWITCH RUN terminal.
  90
  91 visorbus
  92
  93 The visorbus module handles the bus functions for most functional
  94 drivers except visorserial, visordiag, virthba, and virtnic. It
  95 maintains the sysfs subtree /sys/devices/visorbus*/. It is responsible
  96 for device creation and destruction of the devices on its bus.
  97
  98 visorclientbus
  99
 100 The visorclientbus module forwards the bus functions for virthba, and
 101 virtnic to the virtpci driver.
 102
 103 virtpci
 104
 105 The virtpci module handles the bus functions for virthba, and virtnic.
 106
 107 s-Par Integration Modules
 108
 109 The modules in this section provide integration with s-Par guest
 110 partition services like diagnostics and remote desktop. These modules
 111 depend on functions in the modules described in the support modules
 112 section.
 113
 114 visorvideoclient
 115
 116 The visorvideoclient module provides functionality for video support
 117 for the Unisys s-Par Partition Desktop application. The guest OS must
 118 also have the UEFI GOP protocol enabled for the partition desktop to
 119 function.  visorconinclient The visorconinclient module provides
 120 keyboard and mouse support for the Unisys s-Par Partition Desktop
 121 application.
 122
 123 sparstop
 124
 125 The sparstop module handles requests from the Unisys s-Par platform to
 126 shutdown the linux guest. It allows a program on the guest to perform
 127 clean-up functions on the guest before the guest is shut down or
 128 rebooted using ACPI.
 129
 130 visordiag
 131
 132 This driver provides the ability for the guest to write information
 133 into the s-Par diagnostics subsystem. It creates a set of devices
 134 named /dev/visordiag.X which can be written to by the guest to add
 135 text to the s-Par system log.
 136
 137 Support Modules
 138
 139 The modules described in this section provide functions and
 140 abstractions to support the modules described in the previous
 141 sections, to avoid having duplicated functionality.
 142
 143 visornoop
 144
 145 The visornoop module is a placeholder that responds to device
 146 create/destroy messages that are currently not in use by linux guests.
 147
 148 visoruislib
 149
 150 The visoruislib module is a support library, used to handle requests
 151 from virtpci.
 152
 153 visorchannelstub
 154
 155 The visorchannelstub module provides support routines for storing and
 156 retrieving data from a channel.
 157
 158 visorchannel
 159
 160 The visorchannel module is a support library that abstracts reading
 161 and writing a channel in memory.
 162
 163 visorutil
 164
 165 The visorutil module is a support library required by all other s-Par
 166 driver modules. Among its features it abstracts reading, writing, and
 167 manipulating a block of memory.
 168
 169 Minimum Required Driver Set
 170
 171 The drivers required to boot a Linux guest are visorchipset, visorbus,
 172 visorvideoclient, visorconinclient, visoruislib, visorchannelstub,
 173 visorchannel, and visorutil. The other drivers are required by the
 174 product configurations that are currently being marketed.