[PATCH v2] docs/design: introduce HVMMEM_ioreq_serverX types

[Paul Durrant <paul.durrant@citrix.com>]

This patch adds a new 'designs' subdirectory under docs as a repository
for this and future design proposals. It also adjusts the docs
Makefile to look in the new subdirectory.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
---

For convenience this document can also be viewed in PDF at:

http://xenbits.xen.org/people/pauldu/hvmmem_ioreq_server.pdf

v2:
 - Added the Makefile modification
 - Addressed various review comments on v1 of the design
 - Small amount of re-formatting
---
 docs/Makefile                             |  8 ++--
 docs/designs/hvmmem_ioreq_server.markdown | 66 +++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 3 deletions(-)
 create mode 100755 docs/designs/hvmmem_ioreq_server.markdown

diff --git a/docs/Makefile b/docs/Makefile
index b9da605..c365fdc 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -11,11 +11,13 @@ MAN1SRC-y := $(sort $(shell find man/ -name '*.pod.1' -print))
 MAN5SRC-y := $(sort $(shell find man/ -name '*.pod.5' -print))
 MAN8SRC-y := $(sort $(shell find man/ -name '*.pod.8' -print))
 
-MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
+SUBDIRS := features/ misc/ specs/ designs/
 
-TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
+MARKDOWNSRC-y := $(sort $(shell find $(SUBDIRS) -name '*.markdown' -print))
 
-PANDOCSRC-y := $(sort $(shell find features/ misc/ specs/ -name '*.pandoc' -print))
+TXTSRC-y := $(sort $(shell find $(SUBDIRS) -name '*.txt' -print))
+
+PANDOCSRC-y := $(sort $(shell find $(SUBDIRS) -name '*.pandoc' -print))
 
 # Documentation targets
 DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
diff --git a/docs/designs/hvmmem_ioreq_server.markdown b/docs/designs/hvmmem_ioreq_server.markdown
new file mode 100755
index 0000000..0223b5d
--- /dev/null
+++ b/docs/designs/hvmmem_ioreq_server.markdown
@@ -0,0 +1,66 @@
+# HVMMEM\_ioreq\_serverX
+
+
+## Background
+
+The concept of the IOREQ server was introduced to allow multiple distinct
+device emulators to a single VM. The XenGT project uses an IOREQ server to
+provide mediated pass-through of Intel GPUs to guests and, as part of the
+mediation, needs to intercept accesses to GPU page-tables (or GTTs) that
+reside in guest RAM.
+
+The current implementation of this sets the type of GTT pages to type
+HVMMEM\_mmio\_write\_dm, which causes Xen to emulate writes to such pages,
+and then maps the guest physical addresses of those pages to the XenGT
+IOREQ server using the HVMOP\_map\_io\_range\_to\_ioreq\_server hypercall.
+However, because the number of GTTs is potentially large, using this
+approach does not scale well.
+
+##Proposal
+
+Because the number of spare types available in the P2M type-space is
+currently very limited it is proposed that HVMMEM\_mmio\_write\_dm be
+replaced by a single new type HVMMEM\_ioreq\_server. In future, if the
+P2M type-space is increased, this can be renamed to HVMMEM\_ioreq\_server0
+and new HVMMEM\_ioreq\_server1, HVMMEM\_ioreq\_server2, etc. types
+can be added.
+
+Accesses to a page of type HVMMEM\_ioreq\_serverX should be the same as
+HVMMEM\_ram\_rw until the type is _claimed_ by an IOREQ server. Furthermore
+it should only be possible to change the type of a page to
+HVMMEM\_ioreq\_serverX if that page is currently of type HVMMEM\_ram\_rw, and
+if the page is of type HVMMEM\_ioreq\_serverX it should only be possible to
+change the type to HVMMEM\_ram\_rw.
+
+To allow an IOREQ server to claim or release a claim to a type a hypercall
+will be introduced:
+
+- HVMOP\_map\_mem\_type\_to\_ioreq\_server
+
+and an associated argument structure:
+
+		struct hvm_ioreq_mem_type {
+			domid_t domid;      /* IN - domain to be serviced */
+			ioservid_t id;      /* IN - server id */
+			hvmmem_type_t type; /* IN - memory type */
+			uint32_t flags;     /* IN - types of access to be
+	                                    intercepted */
+
+	#define _HVMOP_IOREQ_MEM_ACCESS_READ 0
+	#define HVMOP_IOREQ_MEM_ACCESS_READ \
+	        (1u << _HVMOP_IOREQ_MEM_ACCESS_READ)
+
+	#define _HVMOP_IOREQ_MEM_ACCESS_WRITE 1
+	#define HVMOP_IOREQ_MEM_ACCESS_WRITE \
+	        (1u << _HVMOP_IOREQ_MEM_ACCESS_WRITE)
+
+		};
+
+
+Once the type has been claimed then the requested types of access to any
+page of the claimed type will be passed to the IOREQ server for handling.
+Only HVMMEM\_ioreq\_serverX types may be claimed and only one IOREQ
+server may have a claim on a type (`-EBUSY` will be returned if an attempt
+is made to claim a type that is already claimed).
+To release a claim the hypercall is issued with the `flags` field set to
+zero.
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel