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

   1 1. Overview
   2 -----------
   3
   4 This document describes the driver set for Unisys Secure Partitioning
   5 (s-Par(R)).
   6
   7 s-Par is firmware that provides hardware partitioning capabilities for
   8 splitting large-scale Intel x86 servers into multiple isolated
   9 partitions. s-Par provides a set of para-virtualized device drivers to
  10 allow guest partitions on the same server to share devices that would
  11 normally be unsharable, specifically:
  12
  13 * visornic - network interface
  14 * visorhba - scsi disk adapter
  15 * visorinput - keyboard and mouse
  16
  17 These drivers conform to the standard Linux bus/device model described
  18 within Documentation/driver-model/, and utilize a driver named visorbus to
  19 present the virtual busses involved. Drivers in the 'visor*' driver set are
  20 commonly referred to as "guest drivers" or "client drivers".  All drivers
  21 except visorbus expose a device of a specific usable class to the Linux guest
  22 environment (e.g., block, network, or input), and are collectively referred
  23 to as "function drivers".
  24
  25 The back-end for each device is owned and managed by a small,
  26 single-purpose service partition in the s-Par firmware, which communicates
  27 with each guest partition sharing that device through an area of shared memory
  28 called a "channel". In s-Par nomenclature, the back-end is often referred to
  29 as the "service partition", "IO partition" (for virtual network and scsi disk
  30 devices), or "console partition" (for virtual keyboard and mouse devices).
  31
  32 Each virtual device requires exactly 1 dedicated channel, which the guest
  33 driver and back-end use to communicate.  The hypervisor need not intervene
  34 (other than normal interrupt handling) in the interactions that occur across
  35 this channel.
  36
  37 NOT covered in this document:
  38
  39 * s-Par also supports sharing physical PCI adapters via SR-IOV, but
  40   because this requires no specific support in the guest partitions, it will
  41   not be discussed in this document.  Shared SR-IOV devices should be used
  42   wherever possible for highest performance.
  43
  44 * Because the s-Par back-end provides a standard EFI framebuffer to each
  45   guest, the already-existing efifb Linux driver is used to provide guest
  46   video access. Thus, the only s-Par-unique support that is necessary to
  47   provide a guest graphics console are for keyboard and mouse (via visorinput).
  48
  49
  50 2. Driver Descriptions
  51 ----------------------
  52
  53 2.1. visorbus
  54 -------------
  55
  56 2.1.1. Overview
  57 ---------------
  58
  59 The visorbus driver handles the virtual busses on which all of the virtual
  60 devices reside. It provides a registration function named
  61 visorbus_register_visor_driver() that is called by each of the function
  62 drivers at initialization time, which the function driver uses to tell
  63 visorbus about the device classes (via specifying a list of device type
  64 GUIDs) it wants to handle. For use by function drivers, visorbus provides
  65 implementation for struct visor_driver and struct visor_device, as well
  66 as utility functions for communicating with the back-end.
  67
  68 visorbus is associated with ACPI id "PNP0A07" in modules.alias, so if built
  69 as a module it will typically be loaded automatically via standard udev or
  70 systemd (God help us) configurations.
  71
  72 visorbus can similarly force auto-loading of function drivers for virtual
  73 devices it discovers, as it includes a MODALIAS environment variable of this
  74 form in the hotplug uevent environment when each virtual device is
  75 discovered:
  76
  77     visorbus:<device type GUID>
  78
  79 visorbus notifies each function driver when a device of its registered class
  80 arrives and departs, by calling the function driver's probe() and remove()
  81 methods.
  82
  83 The actual struct device objects that correspond to each virtual bus and
  84 each virtual device are created and owned by visorbus.  These device objects
  85 are created in response to messages from the s-Par back-end received on a
  86 special control channel called the "controlvm channel" (each guest partition
  87 has access to exactly 1 controlvm channel), and have a lifetime that is
  88 independent of the function drivers that control them.
  89
  90 2.1.2. "struct visor device" Function Driver Interfaces
  91 -------------------------------------------------------
  92
  93 The interface between visorbus and its function drivers is defined in
  94 visorbus.h, and described below.
  95
  96 When a visor function driver loads, it calls visorbus_register_visor_driver()
  97 to register itself with visorbus. The significant information passed in this
  98 exchange is as follows:
  99
 100 * the GUID(s) of the channel type(s) that are handled by this driver, as
 101   well as a "friendly name" identifying each (this will be published under
 102   /sys/devices/visorbus<x>/dev<y>)
 103
 104 * the addresses of callback functions to be called whenever a virtual
 105   device/channel with the appropriate channel-type GUID(s) appears or
 106   disappears
 107
 108 * the address of a "channel_interrupt" function, which will be automatically
 109   called at specific intervals to enable the driver to poll the device
 110   channel for activity
 111
 112 The following functions implemented within each function driver will be
 113 called automatically by the visorbus driver at appropriate times:
 114
 115 * The probe() function notifies about the creation of each new virtual
 116   device/channel instance.
 117
 118 * The remove() function notifies about the destruction of a virtual
 119   device/channel instance.
 120
 121 * The channel_interrupt() function is called at frequent intervals to
 122   give the function driver an opportunity to poll the virtual device channel
 123   for requests.  Information is passed to this function to enable the
 124   function driver to use the visorchannel_signalinsert() and
 125   visorchannel_signalremove() functions to respond to and initiate activity
 126   over the channel.  (Note that since it is the visorbus driver that
 127   determines when this is called, it is very easy to switch to
 128   interrupt-driven mechanisms when available for particular virtual device
 129   types.)
 130
 131 * The pause() function is called should it ever be necessary to direct the
 132   function driver to temporarily stop accessing the device channel.  An
 133   example of when this is needed is when the service partition implementing
 134   the back-end of the virtual device needs to be recovered.  After a
 135   successful return of pause(), the function driver must not access the
 136   device channel until a subsequent resume() occurs.
 137
 138 * The resume() function is the "book-end" to pause(), and is described above.
 139
 140 If/when a function driver creates a Linux device (that needs to be accessed
 141 from usermode), it calls visorbus_registerdevnode(), passing the major and
 142 minor number of the device.  (Of course not all function drivers will need
 143 to do this.)  This simply creates the appropriate "devmajorminor" sysfs entry
 144 described below, so that a hotplug script can use it to create a device node.
 145
 146 2.1.3. sysfs Advertised Information
 147 -----------------------------------
 148
 149 Because visorbus is a standard Linux bus driver in the model described in
 150 Documentation/driver-model/, the hierarchy of s-Par virtual devices is
 151 published in the sysfs tree beneath /bus/visorbus/, e.g.,
 152 /sys/bus/visorbus/devices/ might look like:
 153
 154     vbus1:dev1 -> ../../../devices/visorbus1/vbus1:dev1
 155     vbus1:dev2 -> ../../../devices/visorbus1/vbus1:dev2
 156     vbus1:dev3 -> ../../../devices/visorbus1/vbus1:dev3
 157     vbus2:dev0 -> ../../../devices/visorbus2/vbus2:dev0
 158     vbus2:dev1 -> ../../../devices/visorbus2/vbus2:dev1
 159     vbus2:dev2 -> ../../../devices/visorbus2/vbus2:dev2
 160     visorbus1 -> ../../../devices/visorbus1
 161     visorbus2 -> ../../../devices/visorbus2
 162
 163 visor_device notes:
 164
 165 * Each visorbus<n> entry denotes the existence of a struct visor_device
 166   denoting virtual bus #<n>.  A unique s-Par channel exists for each such
 167   virtual bus.
 168
 169 * Virtual bus numbers uniquely identify s-Par back-end service partitions.
 170   In this example, bus 1 corresponds to the s-Par console partition
 171   (controls keyboard, video, and mouse), whereas bus 2 corresponds to the
 172   s-Par IO partition (controls network and disk).
 173
 174 * Each vbus<x>:dev<y> entry denotes the existence of a struct visor_device
 175   denoting virtual device #<y> outboard of virtual bus #<x>.  A unique s-Par
 176   channel exists for each such virtual device.
 177
 178 * If a function driver has loaded and claimed a particular device, the
 179   bus/visorbus/devices/vbus<x>:dev<y>/driver symlink will indicate that
 180   function driver.
 181
 182 Every active visorbus device will have a sysfs subtree under:
 183
 184     /sys/devices/visorbus<x>/vbus<x>:dev<y>/
 185
 186 The following files exist under /sys/devices/visorbus<x>/vbus<x>:dev<y>:
 187
 188     subsystem                 link to sysfs tree that describes the
 189                               visorbus bus type; e.g.:
 190                                   ../../../bus/visorbus
 191
 192     driver                    link to sysfs tree that describes the
 193                               function driver controlling this device;
 194                               e.g.:
 195                                   ../../../bus/visorbus/drivers/visorhba
 196                               Note that this "driver" link will not exist
 197                               if the appropriate function driver has not
 198                               been loaded yet.
 199
 200     devmajorminor
 201
 202         <devname>             if applicable, each file here identifies (via
 203         ...                   its file contents) the
 204                               "<major>:<minor>" needed for a device node to
 205                               enable access from usermode.  There is exactly
 206                               one file here for each different device node
 207                               that can be accessed (from usermode).  Note
 208                               that this info is provided by a particular
 209                               function driver, so these will not exist
 210                               until AFTER the appropriate function driver
 211                               controlling this device class is loaded.
 212
 213     channel                   properties of the device channel (all in
 214                               ascii text format)
 215
 216         clientpartition       handle identifying the guest (client) side
 217                               of this channel, e.g. 0x10000000.
 218
 219         nbytes                total size of this channel in bytes
 220
 221         physaddr              the guest physical address for the base of
 222                               the channel
 223
 224         typeguid              a GUID identifying the channel type, in
 225                               xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation
 226
 227         typename              a "friendly name" for this channel type, e.g.,
 228                               "keyboard".  Note that this name is provided by
 229                               a particular function driver, so "typename"
 230                               will return an empty string until AFTER the
 231                               appropriate function driver controlling this
 232                               channel type is loaded
 233
 234         zoneguid              a GUID identifying the channel zone, in
 235                               xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation
 236
 237
 238 2.2. visorhba
 239 -------------
 240
 241 The visorhba driver registers with visorbus as the function driver to
 242 handle virtual scsi disk devices, specified using the
 243 SPAR_VHBA_CHANNEL_PROTOCOL_UUID type in the visorbus_register_visor_driver()
 244 call. visorhba uses scsi_add_host() to expose a Linux block device
 245 (e.g., /sys/block/) in the guest environment for each s-Par virtual device.
 246
 247 visorhba provides access to a shared SCSI host bus adapter and one or more
 248 disk devices, by proxying SCSI commands between the guest and the service
 249 partition that owns the shared SCSI adapter, using a channel between the
 250 guest and the service partition. The disks that appear on the shared bus
 251 are defined by the s-Par configuration and enforced by the service partition,
 252 while the guest driver handles sending commands and handling responses. Each
 253 disk is shared as a whole to a guest. Sharing the bus adapter in this way
 254 provides resiliency; should the device encounter an error, only the service
 255 partition is rebooted, and the device is reinitialized. This allows
 256 guests to continue running and to recover from the error.
 257
 258 When compiled as a module, visorhba can be autoloaded by visorbus in
 259 standard udev/systemd environments, as it includes the modules.alias
 260 definition:
 261
 262     "visorbus:"+SPAR_VHBA_CHANNEL_PROTOCOL_UUID_STR
 263
 264 i.e.:
 265
 266     alias visorbus:414815ed-c58c-11da-95a9-00e08161165f visorhba
 267
 268
 269 2.3. visornic
 270 -------------
 271
 272 The visornic driver registers with visorbus as the function driver to
 273 handle virtual network devices, specified using the
 274 SPAR_VNIC_CHANNEL_PROTOCOL_UUID type in the visorbus_register_visor_driver()
 275 call. visornic uses register_netdev() to expose a Linux device of class net
 276 (e.g., /sys/class/net/) in the guest environment for each s-Par virtual
 277 device.
 278
 279 visornic provides a paravirtualized network interface to a
 280 guest by proxying buffer information between the guest and the service
 281 partition that owns the shared network interface, using a channel
 282 between the guest and the service partition. The connectivity of this
 283 interface with the shared interface and possibly other guest
 284 partitions is defined by the s-Par configuration and enforced by the
 285 service partition; the guest driver handles communication and link
 286 status.
 287
 288 When compiled as a module, visornic can be autoloaded by visorbus in
 289 standard udev/systemd environments, as it includes the modules.alias
 290 definition:
 291
 292     "visorbus:"+SPAR_VNIC_CHANNEL_PROTOCOL_UUID_STR
 293
 294 i.e.:
 295
 296     alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic
 297
 298
 299 2.4. visorinput
 300 ---------------
 301
 302 The visorinput driver registers with visorbus as the function driver to
 303 handle human input devices, specified using the
 304 SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID and SPAR_MOUSE_CHANNEL_PROTOCOL_UUID
 305 types in the visorbus_register_visor_driver() call. visorinput uses
 306 input_register_device() to expose devices of class input
 307 (e.g., /sys/class/input/) for virtual keyboard and virtual mouse devices.
 308 A s-Par virtual keyboard device maps 1-to-1 with a Linux input device
 309 named "visor Keyboard", while a s-Par virtual mouse device has 2 Linux input
 310 devices created for it: 1 named "visor Wheel", and 1 named "visor Mouse".
 311
 312 By registering as input class devices, modern versions of X will
 313 automatically find and properly use s-Par virtual keyboard and mouse devices.
 314 As the s-Par back-end reports keyboard and mouse activity via events on the
 315 virtual device channel, the visorinput driver delivers the activity to the
 316 Linux environment by calling input_report_key() and input_report_abs().
 317
 318 You can interact with the guest console using the usyscon Partition Desktop
 319 (a.k.a., "pd") application, provided as part of s-Par.  After installing the
 320 usyscon Partition Desktop into a Linux environment via the
 321 usyscon_partitiondesktop-*.rpm, or into a Windows environment via
 322 PartitionDesktop.msi, you will be able to launch a console for your guest
 323 Linux environment by clicking the console icon in the s-Par web UI.
 324
 325 When compiled as a module, visorinput can be autoloaded by visorbus in
 326 standard udev/systemd environments, as it includes the modules.alias
 327 definition:
 328
 329     "visorbus:"+SPAR_MOUSE_CHANNEL_PROTOCOL_UUID_STR
 330     "visorbus:"+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID_STR
 331
 332 i.e.:
 333
 334     alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorinput
 335     alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorinput
 336
 337
 338 3. Minimum Required Driver Set
 339 ------------------------------
 340
 341 visorbus is required for every Linux guest running under s-Par.
 342
 343 visorhba is typically required for a Linux guest running under s-Par, as it
 344 is required if your guest boot disk is a virtual device provided by the s-Par
 345 back-end, which is the default configuration.  However, for advanced
 346 configurations where the Linux guest boots via an SR-IOV-provided HBA or
 347 SAN disk for example, visorhba is not technically required.
 348
 349 visornic is typically required for a Linux guest running under s-Par, as it
 350 is required if your guest network interface is a virtual device provided by
 351 the s-Par back-end, which is the default configuration.  However, for
 352 configurations where the Linux guest is provided with an SR-IOV NIC
 353 for example, visornic is not technically required.
 354
 355 visorinput is only required for a Linux guest running under s-Par if you
 356 require graphics-mode access to your guest console.