11. Overview 2----------- 3 4This document describes the driver set for Unisys Secure Partitioning 5(s-Par(R)). 6 7s-Par is firmware that provides hardware partitioning capabilities for 8splitting large-scale Intel x86 servers into multiple isolated 9partitions. s-Par provides a set of para-virtualized device drivers to 10allow guest partitions on the same server to share devices that would 11normally be unsharable, specifically: 12 13* visornic - network interface 14* visorhba - scsi disk adapter 15* visorinput - keyboard and mouse 16 17These drivers conform to the standard Linux bus/device model described 18within Documentation/driver-model/, and utilize a driver named visorbus to 19present the virtual busses involved. Drivers in the 'visor*' driver set are 20commonly referred to as "guest drivers" or "client drivers". All drivers 21except visorbus expose a device of a specific usable class to the Linux guest 22environment (e.g., block, network, or input), and are collectively referred 23to as "function drivers". 24 25The back-end for each device is owned and managed by a small, 26single-purpose service partition in the s-Par firmware, which communicates 27with each guest partition sharing that device through an area of shared memory 28called a "channel". In s-Par nomenclature, the back-end is often referred to 29as the "service partition", "IO partition" (for virtual network and scsi disk 30devices), or "console partition" (for virtual keyboard and mouse devices). 31 32Each virtual device requires exactly 1 dedicated channel, which the guest 33driver and back-end use to communicate. The hypervisor need not intervene 34(other than normal interrupt handling) in the interactions that occur across 35this channel. 36 37NOT 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 502. Driver Descriptions 51---------------------- 52 532.1. visorbus 54------------- 55 562.1.1. Overview 57--------------- 58 59The visorbus driver handles the virtual busses on which all of the virtual 60devices reside. It provides a registration function named 61visorbus_register_visor_driver() that is called by each of the function 62drivers at initialization time, which the function driver uses to tell 63visorbus about the device classes (via specifying a list of device type 64GUIDs) it wants to handle. For use by function drivers, visorbus provides 65implementation for struct visor_driver and struct visor_device, as well 66as utility functions for communicating with the back-end. 67 68visorbus is associated with ACPI id "PNP0A07" in modules.alias, so if built 69as a module it will typically be loaded automatically via standard udev or 70systemd (God help us) configurations. 71 72visorbus can similarly force auto-loading of function drivers for virtual 73devices it discovers, as it includes a MODALIAS environment variable of this 74form in the hotplug uevent environment when each virtual device is 75discovered: 76 77 visorbus:<device type GUID> 78 79visorbus notifies each function driver when a device of its registered class 80arrives and departs, by calling the function driver's probe() and remove() 81methods. 82 83The actual struct device objects that correspond to each virtual bus and 84each virtual device are created and owned by visorbus. These device objects 85are created in response to messages from the s-Par back-end received on a 86special control channel called the "controlvm channel" (each guest partition 87has access to exactly 1 controlvm channel), and have a lifetime that is 88independent of the function drivers that control them. 89 902.1.2. "struct visor device" Function Driver Interfaces 91------------------------------------------------------- 92 93The interface between visorbus and its function drivers is defined in 94visorbus.h, and described below. 95 96When a visor function driver loads, it calls visorbus_register_visor_driver() 97to register itself with visorbus. The significant information passed in this 98exchange 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 112The following functions implemented within each function driver will be 113called 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 140If/when a function driver creates a Linux device (that needs to be accessed 141from usermode), it calls visorbus_registerdevnode(), passing the major and 142minor number of the device. (Of course not all function drivers will need 143to do this.) This simply creates the appropriate "devmajorminor" sysfs entry 144described below, so that a hotplug script can use it to create a device node. 145 1462.1.3. sysfs Advertised Information 147----------------------------------- 148 149Because visorbus is a standard Linux bus driver in the model described in 150Documentation/driver-model/, the hierarchy of s-Par virtual devices is 151published 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 163visor_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 182Every active visorbus device will have a sysfs subtree under: 183 184 /sys/devices/visorbus<x>/vbus<x>:dev<y>/ 185 186The 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 2382.2. visorhba 239------------- 240 241The visorhba driver registers with visorbus as the function driver to 242handle virtual scsi disk devices, specified using the 243SPAR_VHBA_CHANNEL_PROTOCOL_UUID type in the visorbus_register_visor_driver() 244call. 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 247visorhba provides access to a shared SCSI host bus adapter and one or more 248disk devices, by proxying SCSI commands between the guest and the service 249partition that owns the shared SCSI adapter, using a channel between the 250guest and the service partition. The disks that appear on the shared bus 251are defined by the s-Par configuration and enforced by the service partition, 252while the guest driver handles sending commands and handling responses. Each 253disk is shared as a whole to a guest. Sharing the bus adapter in this way 254provides resiliency; should the device encounter an error, only the service 255partition is rebooted, and the device is reinitialized. This allows 256guests to continue running and to recover from the error. 257 258When compiled as a module, visorhba can be autoloaded by visorbus in 259standard udev/systemd environments, as it includes the modules.alias 260definition: 261 262 "visorbus:"+SPAR_VHBA_CHANNEL_PROTOCOL_UUID_STR 263 264i.e.: 265 266 alias visorbus:414815ed-c58c-11da-95a9-00e08161165f visorhba 267 268 2692.3. visornic 270------------- 271 272The visornic driver registers with visorbus as the function driver to 273handle virtual network devices, specified using the 274SPAR_VNIC_CHANNEL_PROTOCOL_UUID type in the visorbus_register_visor_driver() 275call. 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 277device. 278 279visornic provides a paravirtualized network interface to a 280guest by proxying buffer information between the guest and the service 281partition that owns the shared network interface, using a channel 282between the guest and the service partition. The connectivity of this 283interface with the shared interface and possibly other guest 284partitions is defined by the s-Par configuration and enforced by the 285service partition; the guest driver handles communication and link 286status. 287 288When compiled as a module, visornic can be autoloaded by visorbus in 289standard udev/systemd environments, as it includes the modules.alias 290definition: 291 292 "visorbus:"+SPAR_VNIC_CHANNEL_PROTOCOL_UUID_STR 293 294i.e.: 295 296 alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic 297 298 2992.4. visorinput 300--------------- 301 302The visorinput driver registers with visorbus as the function driver to 303handle human input devices, specified using the 304SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID and SPAR_MOUSE_CHANNEL_PROTOCOL_UUID 305types in the visorbus_register_visor_driver() call. visorinput uses 306input_register_device() to expose devices of class input 307(e.g., /sys/class/input/) for virtual keyboard and virtual mouse devices. 308A s-Par virtual keyboard device maps 1-to-1 with a Linux input device 309named "visor Keyboard", while a s-Par virtual mouse device has 2 Linux input 310devices created for it: 1 named "visor Wheel", and 1 named "visor Mouse". 311 312By registering as input class devices, modern versions of X will 313automatically find and properly use s-Par virtual keyboard and mouse devices. 314As the s-Par back-end reports keyboard and mouse activity via events on the 315virtual device channel, the visorinput driver delivers the activity to the 316Linux environment by calling input_report_key() and input_report_abs(). 317 318You 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 320usyscon Partition Desktop into a Linux environment via the 321usyscon_partitiondesktop-*.rpm, or into a Windows environment via 322PartitionDesktop.msi, you will be able to launch a console for your guest 323Linux environment by clicking the console icon in the s-Par web UI. 324 325When compiled as a module, visorinput can be autoloaded by visorbus in 326standard udev/systemd environments, as it includes the modules.alias 327definition: 328 329 "visorbus:"+SPAR_MOUSE_CHANNEL_PROTOCOL_UUID_STR 330 "visorbus:"+SPAR_KEYBOARD_CHANNEL_PROTOCOL_UUID_STR 331 332i.e.: 333 334 alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorinput 335 alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorinput 336 337 3383. Minimum Required Driver Set 339------------------------------ 340 341visorbus is required for every Linux guest running under s-Par. 342 343visorhba is typically required for a Linux guest running under s-Par, as it 344is required if your guest boot disk is a virtual device provided by the s-Par 345back-end, which is the default configuration. However, for advanced 346configurations where the Linux guest boots via an SR-IOV-provided HBA or 347SAN disk for example, visorhba is not technically required. 348 349visornic is typically required for a Linux guest running under s-Par, as it 350is required if your guest network interface is a virtual device provided by 351the s-Par back-end, which is the default configuration. However, for 352configurations where the Linux guest is provided with an SR-IOV NIC 353for example, visornic is not technically required. 354 355visorinput is only required for a Linux guest running under s-Par if you 356require graphics-mode access to your guest console. 357