Ian Campbell
2011-Oct-26 16:25 UTC
[Xen-devel] [PATCH] docs: import HVM emulated device unplug protocol spec
# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# 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@citrix.com>
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@lists.xensource.com
http://lists.xensource.com/xen-devel
Ian Campbell
2011-Oct-26 16:26 UTC
[Xen-devel] [PATCH] qemu-xen: remove i386-dm/README.hvm-pv-magic-ioport-disable
I have just proposed a patch to add this to xen-unstable.hg as
docs/misc/hvm-emulated-unplug.markdown. This repo is not a place where people
look for docs, plus we are transitioning to upstream qemu.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
---
i386-dm/README.hvm-pv-magic-ioport-disable | 70 ----------------------------
1 files changed, 0 insertions(+), 70 deletions(-)
delete mode 100644 i386-dm/README.hvm-pv-magic-ioport-disable
diff --git a/i386-dm/README.hvm-pv-magic-ioport-disable
b/i386-dm/README.hvm-pv-magic-ioport-disable
deleted file mode 100644
index 142394a..0000000
--- a/i386-dm/README.hvm-pv-magic-ioport-disable
+++ /dev/null
@@ -1,70 +0,0 @@
-MAGIC IOPORT 0x10 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.
--
1.7.2.5
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel
Ian Campbell
2011-Oct-26 16:27 UTC
[Xen-devel] [PATCH] docs: add some scaffolding for building HTML docs from markdown
# HG changeset patch # User Ian Campbell <ian.campbell@citrix.com> # Date 1319646217 -3600 # Node ID 52058c9448935818e2a810a438244e06f40b4e0e # Parent 03b570c3792bb6abce46de5c9ab560ac169117c3 docs: add some scaffolding for building HTML docs from markdown Signed-off-by: Ian Campbell <ian.campbell@citrix.com> diff -r 03b570c3792b -r 52058c944893 docs/Docs.mk --- a/docs/Docs.mk Wed Oct 26 17:20:21 2011 +0100 +++ b/docs/Docs.mk Wed Oct 26 17:23:37 2011 +0100 @@ -7,3 +7,4 @@ DOXYGEN := doxygen POD2MAN := pod2man DOT := dot NEATO := neato +MARKDOWN := markdown diff -r 03b570c3792b -r 52058c944893 docs/Makefile --- a/docs/Makefile Wed Oct 26 17:20:21 2011 +0100 +++ b/docs/Makefile Wed Oct 26 17:23:37 2011 +0100 @@ -11,10 +11,11 @@ DOC_MAN1SRC := $(wildcard man/*.pod.1) DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(DOC_MAN1SRC)) DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(DOC_MAN5SRC)) DOC_TEX := src/user.tex src/interface.tex +DOC_MARKDOWN := $(wildcard misc/*.markdown) DOC_PS := $(patsubst src/%.tex,ps/%.ps,$(DOC_TEX)) DOC_PDF := $(patsubst src/%.tex,pdf/%.pdf,$(DOC_TEX)) -DOC_HTML := $(patsubst src/%.tex,html/%/index.html,$(DOC_TEX)) - +DOC_HTML := $(patsubst src/%.tex,html/%/index.html,$(DOC_TEX)) \ + $(patsubst %.markdown,html/%.html,$(DOC_MARKDOWN)) GFX = $(patsubst %.fig, %.eps, $(wildcard figs/*.fig)) .PHONY: all @@ -37,9 +38,7 @@ ps: $(DOC_PS) pdf: $(DOC_PDF) .PHONY: html -html: - @if which $(LATEX2HTML) 1>/dev/null 2>/dev/null; then \ - $(MAKE) $(DOC_HTML); fi +html: $(DOC_HTML) .PHONY: python-dev-docs python-dev-docs: @@ -110,7 +109,16 @@ ps/%.ps: %.dvi $(FIG2DEV) -L eps $< $@ html/%/index.html: src/%.tex - $(INSTALL_DIR) $(@D) + @$(INSTALL_DIR) $(@D) + @set -e ; if which $(LATEX2HTML) 1>/dev/null 2>/dev/null; then \ + echo "Running latex2html to generate $*/index.html ... "; \ $(LATEX2HTML) -split 0 -show_section_numbers -toc_depth 3 -nonavigation \ -numbered_footnotes -local_icons -noinfo -math -dir $(@D) \ - $< 1>/dev/null 2>/dev/null + $< 1>/dev/null 2>/dev/null ;fi + +html/%.html: %.markdown + @$(INSTALL_DIR) $(@D) + @set -e ; if which $(MARKDOWN) 1>/dev/null 2>/dev/null; then \ + echo "Running markdown to generate $*.html ... "; \ + $(MARKDOWN) $< > $@.tmp ; \ + $(call move-if-changed,$@.tmp,$@) ; fi _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Ian Campbell
2011-Oct-26 16:35 UTC
[Xen-devel] Re: [PATCH] docs: import HVM emulated device unplug protocol spec
On Wed, 2011-10-26 at 17:25 +0100, Ian Campbell wrote:> > +The master registry of product names and numbers is in > +qemu-xen-unstable''s xenstore.c.As an aside: This doesn''t seem like the right place anymore (if ever). Where would be better? Ian. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Ian Jackson
2011-Nov-01 18:38 UTC
[Xen-devel] Re: [PATCH] docs: import HVM emulated device unplug protocol spec
Ian Campbell writes ("[Xen-devel] Re: [PATCH] docs: import HVM emulated
device unplug protocol spec"):> On Wed, 2011-10-26 at 17:25 +0100, Ian Campbell wrote:
> > +The master registry of product names and numbers is in
> > +qemu-xen-unstable''s xenstore.c.
>
> As an aside: This doesn''t seem like the right place anymore (if
ever).
> Where would be better?
qemu upstream is where it''s implemented ...
Ian.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel
Ian Jackson
2011-Nov-01 18:43 UTC
Re: [Xen-devel] [PATCH] qemu-xen: remove i386-dm/README.hvm-pv-magic-ioport-disable
Ian Campbell writes ("[Xen-devel] [PATCH] qemu-xen: remove
i386-dm/README.hvm-pv-magic-ioport-disable"):> I have just proposed a patch to add this to xen-unstable.hg as
> docs/misc/hvm-emulated-unplug.markdown. This repo is not a place where
people
> look for docs, plus we are transitioning to upstream qemu.
Right.
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Ian.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel