9ab30af265a5df6e01ccc95f8cf76edcfdfbd565
[sfrench/cifs-2.6.git] / 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 2.1.3. sysfs Advertised Information
141 -----------------------------------
142
143 Because visorbus is a standard Linux bus driver in the model described in
144 Documentation/driver-model/, the hierarchy of s-Par virtual devices is
145 published in the sysfs tree beneath /bus/visorbus/, e.g.,
146 /sys/bus/visorbus/devices/ might look like:
147
148     vbus1:dev1 -> ../../../devices/visorbus1/vbus1:dev1
149     vbus1:dev2 -> ../../../devices/visorbus1/vbus1:dev2
150     vbus1:dev3 -> ../../../devices/visorbus1/vbus1:dev3
151     vbus2:dev0 -> ../../../devices/visorbus2/vbus2:dev0
152     vbus2:dev1 -> ../../../devices/visorbus2/vbus2:dev1
153     vbus2:dev2 -> ../../../devices/visorbus2/vbus2:dev2
154     visorbus1 -> ../../../devices/visorbus1
155     visorbus2 -> ../../../devices/visorbus2
156
157 visor_device notes:
158
159 * Each visorbus<n> entry denotes the existence of a struct visor_device
160   denoting virtual bus #<n>.  A unique s-Par channel exists for each such
161   virtual bus.
162
163 * Virtual bus numbers uniquely identify s-Par back-end service partitions.
164   In this example, bus 1 corresponds to the s-Par console partition
165   (controls keyboard, video, and mouse), whereas bus 2 corresponds to the
166   s-Par IO partition (controls network and disk).
167
168 * Each vbus<x>:dev<y> entry denotes the existence of a struct visor_device
169   denoting virtual device #<y> outboard of virtual bus #<x>.  A unique s-Par
170   channel exists for each such virtual device.
171
172 * If a function driver has loaded and claimed a particular device, the
173   bus/visorbus/devices/vbus<x>:dev<y>/driver symlink will indicate that
174   function driver.
175
176 Every active visorbus device will have a sysfs subtree under:
177
178     /sys/devices/visorbus<x>/vbus<x>:dev<y>/
179
180 The following files exist under /sys/devices/visorbus<x>/vbus<x>:dev<y>:
181
182     subsystem                 link to sysfs tree that describes the
183                               visorbus bus type; e.g.:
184                                   ../../../bus/visorbus
185
186     driver                    link to sysfs tree that describes the
187                               function driver controlling this device;
188                               e.g.:
189                                   ../../../bus/visorbus/drivers/visorhba
190                               Note that this "driver" link will not exist
191                               if the appropriate function driver has not
192                               been loaded yet.
193
194     channel                   properties of the device channel (all in
195                               ascii text format)
196
197         clientpartition       handle identifying the guest (client) side
198                               of this channel, e.g. 0x10000000.
199
200         nbytes                total size of this channel in bytes
201
202         physaddr              the guest physical address for the base of
203                               the channel
204
205         typeguid              a GUID identifying the channel type, in
206                               xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation
207
208         typename              a "friendly name" for this channel type, e.g.,
209                               "keyboard".  Note that this name is provided by
210                               a particular function driver, so "typename"
211                               will return an empty string until AFTER the
212                               appropriate function driver controlling this
213                               channel type is loaded
214
215         zoneguid              a GUID identifying the channel zone, in
216                               xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx notation
217
218
219 2.2. visorhba
220 -------------
221
222 The visorhba driver registers with visorbus as the function driver to
223 handle virtual scsi disk devices, specified using the
224 VISOR_VHBA_CHANNEL_GUID type in the visorbus_register_visor_driver()
225 call. visorhba uses scsi_add_host() to expose a Linux block device
226 (e.g., /sys/block/) in the guest environment for each s-Par virtual device.
227
228 visorhba provides access to a shared SCSI host bus adapter and one or more
229 disk devices, by proxying SCSI commands between the guest and the service
230 partition that owns the shared SCSI adapter, using a channel between the
231 guest and the service partition. The disks that appear on the shared bus
232 are defined by the s-Par configuration and enforced by the service partition,
233 while the guest driver handles sending commands and handling responses. Each
234 disk is shared as a whole to a guest. Sharing the bus adapter in this way
235 provides resiliency; should the device encounter an error, only the service
236 partition is rebooted, and the device is reinitialized. This allows
237 guests to continue running and to recover from the error.
238
239 When compiled as a module, visorhba can be autoloaded by visorbus in
240 standard udev/systemd environments, as it includes the modules.alias
241 definition:
242
243     "visorbus:"+VISOR_VHBA_CHANNEL_GUID_STR
244
245 i.e.:
246
247     alias visorbus:414815ed-c58c-11da-95a9-00e08161165f visorhba
248
249
250 2.3. visornic
251 -------------
252
253 The visornic driver registers with visorbus as the function driver to
254 handle virtual network devices, specified using the
255 VISOR_VNIC_CHANNEL_GUID type in the visorbus_register_visor_driver()
256 call. visornic uses register_netdev() to expose a Linux device of class net
257 (e.g., /sys/class/net/) in the guest environment for each s-Par virtual
258 device.
259
260 visornic provides a paravirtualized network interface to a
261 guest by proxying buffer information between the guest and the service
262 partition that owns the shared network interface, using a channel
263 between the guest and the service partition. The connectivity of this
264 interface with the shared interface and possibly other guest
265 partitions is defined by the s-Par configuration and enforced by the
266 service partition; the guest driver handles communication and link
267 status.
268
269 When compiled as a module, visornic can be autoloaded by visorbus in
270 standard udev/systemd environments, as it includes the modules.alias
271 definition:
272
273     "visorbus:"+VISOR_VNIC_CHANNEL_GUID_STR
274
275 i.e.:
276
277     alias visorbus:8cd5994d-c58e-11da-95a9-00e08161165f visornic
278
279
280 2.4. visorinput
281 ---------------
282
283 The visorinput driver registers with visorbus as the function driver to
284 handle human input devices, specified using the
285 VISOR_KEYBOARD_CHANNEL_GUID and VISOR_MOUSE_CHANNEL_GUID
286 types in the visorbus_register_visor_driver() call. visorinput uses
287 input_register_device() to expose devices of class input
288 (e.g., /sys/class/input/) for virtual keyboard and virtual mouse devices.
289 A s-Par virtual keyboard device maps 1-to-1 with a Linux input device
290 named "visor Keyboard", while a s-Par virtual mouse device has 2 Linux input
291 devices created for it: 1 named "visor Wheel", and 1 named "visor Mouse".
292
293 By registering as input class devices, modern versions of X will
294 automatically find and properly use s-Par virtual keyboard and mouse devices.
295 As the s-Par back-end reports keyboard and mouse activity via events on the
296 virtual device channel, the visorinput driver delivers the activity to the
297 Linux environment by calling input_report_key() and input_report_abs().
298
299 You can interact with the guest console using the usyscon Partition Desktop
300 (a.k.a., "pd") application, provided as part of s-Par.  After installing the
301 usyscon Partition Desktop into a Linux environment via the
302 usyscon_partitiondesktop-*.rpm, or into a Windows environment via
303 PartitionDesktop.msi, you will be able to launch a console for your guest
304 Linux environment by clicking the console icon in the s-Par web UI.
305
306 When compiled as a module, visorinput can be autoloaded by visorbus in
307 standard udev/systemd environments, as it includes the modules.alias
308 definition:
309
310     "visorbus:"+VISOR_MOUSE_CHANNEL_GUID_STR
311     "visorbus:"+VISOR_KEYBOARD_CHANNEL_GUID_STR
312
313 i.e.:
314
315     alias visorbus:c73416d0-b0b8-44af-b304-9d2ae99f1b3d visorinput
316     alias visorbus:addf07d4-94a9-46e2-81c3-61abcdbdbd87 visorinput
317
318
319 3. Minimum Required Driver Set
320 ------------------------------
321
322 visorbus is required for every Linux guest running under s-Par.
323
324 visorhba is typically required for a Linux guest running under s-Par, as it
325 is required if your guest boot disk is a virtual device provided by the s-Par
326 back-end, which is the default configuration.  However, for advanced
327 configurations where the Linux guest boots via an SR-IOV-provided HBA or
328 SAN disk for example, visorhba is not technically required.
329
330 visornic is typically required for a Linux guest running under s-Par, as it
331 is required if your guest network interface is a virtual device provided by
332 the s-Par back-end, which is the default configuration.  However, for
333 configurations where the Linux guest is provided with an SR-IOV NIC
334 for example, visornic is not technically required.
335
336 visorinput is only required for a Linux guest running under s-Par if you
337 require graphics-mode access to your guest console.