1#Xen HVM emulated device unplug protocol
2
3The protocol covers three basic things:
4
5 * Disconnecting emulated devices.
6 * Getting log messages out of the drivers and into dom0.
7 * Allowing dom0 to block the loading of specific drivers.  This is
8   intended as a backwards-compatibility thing: if we discover a bug
9   in some old version of the drivers, then rather than working around
10   it in Xen, we have the option of just making those drivers fall
11   back to emulated mode.
12
13The current protocol works like this (from the point of view of
14drivers):
15
161. When the drivers first come up, they check whether the unplug logic
17   is available by reading a two-byte magic number from IO port `0x10`.
18   These should be `0x49d2`.  If the magic number doesn't match, the
19   drivers don't do anything.
20
212. The drivers read a one-byte protocol version from IO port `0x12`.  If
22   this is 0, skip to 6.
23
243. The drivers write a two-byte product number to IO port `0x12`.  At
25   the moment, the only drivers using this protocol are our
26   closed-source ones, which use product number 1.
27
284. The drivers write a four-byte build number to IO port `0x10`.
29
305. The drivers check the magic number by reading two bytes from `0x10`
31   again.  If it's changed from `0x49d2` to `0xd249`, the drivers are
32   blacklisted and should not load.
33
346. The drivers write a two-byte bitmask of devices to unplug to IO
35   port `0x10`.  The defined bits are:
36
37  * `0` -- All emulated IDE and SCSI disks (not including CD drives).
38  * `1` -- All emulated NICs.
39  * `2` -- All IDE disks except for the primary master (not including CD
40	   drives). This is overridden by bit 0.
41  * `3` -- All emulated NVMe disks.
42
43   The relevant emulated devices then disappear from the relevant
44   buses.  For most guest operating systems, you want to do this
45   before device enumeration happens.
46
47Once the drivers have checked the magic number, they can send log
48messages to qemu which will be logged to wherever qemu's logs go
49(`/var/log/xen/qemu-dm.log` on normal Xen, dom0 syslog on XenServer).
50These messages are written to IO port `0x12` a byte at a time, and are
51terminated by newlines.  There's a fairly aggressive rate limiter on
52these messages, so they shouldn't be used for anything even vaguely
53high-volume, but they're rather useful for debugging and support.
54
55It is still permitted for a driver to use this logging feature if it
56is blacklisted, but *ONLY* if it has checked the magic number and found
57it to be `0x49d2` or `0xd249`.
58
59This isn't exactly a pretty protocol, but it does solve the problem.
60
61The blacklist is, from qemu's point of view, handled mostly through
62xenstore.  A driver version is considered to be blacklisted if
63`/mh/driver-blacklist/{product_name}/{build_number}` exists and is
64readable, where `{build_number}` is the build number from step 4 as a
65decimal number.  `{product_name}` is a string corresponding to the
66product number in step 3.
67
68The master registry of product names and numbers is in
69xen/include/public/hvm/pvdrivers.h.
70
71NOTE: The IO ports implementing the unplug protocol are implemented
72as part of the Xen Platform PCI Device, so if that device is not
73present in the system then this protocol will not work.
74
75
76Unplug protocol for old SUSE PVonHVM
77
78During xen-3.0.4 timeframe an unofficial unplug protocol was added to
79the xen-platform-pci kernel module. The value 0x1 was written to offset
800x4 in the memory region of the Xen Platform PCI Device. This was done
81unconditionally. The corresponding code in qemu-xen-traditional did an
82unplug of all NIC, IDE and SCSI devices. This was used in all SUSE
83releases up to openSUSE 12.3, SLES11SP3. Starting with openSUSE 13.1 and
84SLES11SP4/SLE12 the official protocol was used.
85
86Unplug protocol for old Novell VMDP
87
88During Xen-3.0 timeframe an unofficial unplug protocol was used in
89Novells VMDP. Depending on how VMDP was configured it would control all
90devices, or either NIC or storage. To control all devices the value 0x1
91was written to offset 0x4 in the memory region of the Xen Platform PCI
92Device. This was supposed to unplug NIC, IDE and SCSI devices. If VMDP
93was configured to control just NIC devices it would write the value 0x2
94to offset 0x8. If VMDP was configured to control just storage devices it
95would write the value 0x1 to offset 0x8. Starting with VMDP version 1.7
96(released 2011) the official protocol was used.
97
98