WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-devel

[Xen-devel] [PATCH 1 of 6 DOCDAY] docs: import HVM emulated device unplu

To: xen-devel@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-devel] [PATCH 1 of 6 DOCDAY] docs: import HVM emulated device unplug protocol spec
From: Ian Campbell <ian.campbell@xxxxxxxxxx>
Date: Thu, 27 Oct 2011 09:58:37 +0100
Cc: ian.jackson@xxxxxxxxxx
Delivery-date: Thu, 27 Oct 2011 02:09:29 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
In-reply-to: <patchbomb.1319705916@xxxxxxxxxxxxxxxxxxxxxxxxx>
List-help: <mailto:xen-devel-request@lists.xensource.com?subject=help>
List-id: Xen developer discussion <xen-devel.lists.xensource.com>
List-post: <mailto:xen-devel@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=unsubscribe>
References: <patchbomb.1319705916@xxxxxxxxxxxxxxxxxxxxxxxxx>
Sender: xen-devel-bounces@xxxxxxxxxxxxxxxxxxx
User-agent: Mercurial-patchbomb/1.6.4
# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# Date 1319646021 -3600
# Node ID 03b570c3792bb6abce46de5c9ab560ac169117c3
# Parent  c681dd5aecf3da3c6fd0e4d8a760a9cd18617033
docs: import HVM emulated device unplug protocol spec

Convert to markdown as I go.

Currently this lives in qemu-xen.git i386-dm/README.hvm-pv-magic-ioport-disable
and I can never find it when I want it. As we transition to upstream qemu this
location becomes less useful.

Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>

diff -r c681dd5aecf3 -r 03b570c3792b docs/misc/hvm-emulated-unplug.markdown
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/misc/hvm-emulated-unplug.markdown    Wed Oct 26 17:20:21 2011 +0100
@@ -0,0 +1,68 @@
+#Xen HVM emulated device unplug protocol
+
+The protocol covers three basic things:
+
+ * Disconnecting emulated devices.
+ * Getting log messages out of the drivers and into dom0.
+ * Allowing dom0 to block the loading of specific drivers.  This is
+   intended as a backwards-compatibility thing: if we discover a bug
+   in some old version of the drivers, then rather than working around
+   it in Xen, we have the option of just making those drivers fall
+   back to emulated mode.
+
+The current protocol works like this (from the point of view of
+drivers):
+
+1. When the drivers first come up, they check whether the unplug logic
+   is available by reading a two-byte magic number from IO port `0x10`.
+   These should be `0x49d2`.  If the magic number doesn't match, the
+   drivers don't do anything.
+
+2. The drivers read a one-byte protocol version from IO port `0x12`.  If
+   this is 0, skip to 6.
+
+3. The drivers write a two-byte product number to IO port `0x12`.  At
+   the moment, the only drivers using this protocol are our
+   closed-source ones, which use product number 1.
+
+4. The drivers write a four-byte build number to IO port `0x10`.
+
+5. The drivers check the magic number by reading two bytes from `0x10`
+   again.  If it's changed from `0x49d2` to `0xd249`, the drivers are
+   blacklisted and should not load.
+
+6. The drivers write a two-byte bitmask of devices to unplug to IO
+   port `0x10`.  The defined fields are:
+
+  * `1` -- All IDE disks (not including CD drives)
+  * `2` -- All emulated NICs
+  * `4` -- All IDE disks except for the primary master (not including CD
+          drives)
+
+   The relevant emulated devices then disappear from the relevant
+   buses.  For most guest operating systems, you want to do this
+   before device enumeration happens.
+
+Once the drivers have checked the magic number, they can send log
+messages to qemu which will be logged to wherever qemu's logs go
+(`/var/log/xen/qemu-dm.log` on normal Xen, dom0 syslog on XenServer).
+These messages are written to IO port `0x12` a byte at a time, and are
+terminated by newlines.  There's a fairly aggressive rate limiter on
+these messages, so they shouldn't be used for anything even vaguely
+high-volume, but they're rather useful for debugging and support.
+
+It is still permitted for a driver to use this logging feature if it
+is blacklisted, but *ONLY* if it has checked the magic number and found
+it to be `0x49d2` or `0xd249`.
+
+This isn't exactly a pretty protocol, but it does solve the problem.
+
+The blacklist is, from qemu's point of view, handled mostly through
+xenstore.  A driver version is considered to be blacklisted if
+`/mh/driver-blacklist/{product_name}/{build_number}` exists and is
+readable, where `{build_number}` is the build number from step 4 as a
+decimal number.  `{product_name}` is a string corresponding to the
+product number in step 3.
+
+The master registry of product names and numbers is in
+qemu-xen-unstable's xenstore.c.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel