[Xen-changelog] [xen-unstable] docs/html/: Annotations for two hypercalls

[Xen patchbot-unstable <patchbot@xxxxxxx>]

# HG changeset patch
# User Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
# Date 1322581687 0
# Node ID 2d6bc8712c0135c51f32dd8ea7ed0de3a5100012
# Parent  549b8f4b9560e4947f625656b80ad3218da91675
docs/html/: Annotations for two hypercalls

Add annotations for a couple of the hypercalls:
 HYPERVISOR_set_trap_table
 HYPERVISOR_mmu_update

We do this by
 * annotating the list of #defines for hypercall numbers
 * annotating the list of error values
 * providing a function prototype for the systematically-named functions
The header generator does the rest.

This exercise revealed a couple of infelicities:
 * In the actual source code, do_mmu_update is defined to return an int
   and do_set_trap_table a long.  However both functions return either
   -Efoo (on error) or 0 for success.
 * The error numbers are defined only in the private header file
   xen/include/xen/errno.h and then only with names which will
   typically clash with other projects.  It would be nice to include a
   public version of this header which defines XEN_E*.  But for now
   we run xen-headers on errno.h too.

Signed-off-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
Committed-by: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
---


diff -r 549b8f4b9560 -r 2d6bc8712c01 docs/Makefile
--- a/docs/Makefile     Tue Nov 29 15:48:06 2011 +0000
+++ b/docs/Makefile     Tue Nov 29 15:48:07 2011 +0000
@@ -159,7 +159,7 @@
        ./xen-headers -O $(@D) \
                -T 'arch-x86_64 - Xen public headers' \
                -X arch-ia64 -X arch-x86_32 -X xen-x86_32 \
-               ../xen include/public
+               ../xen include/public include/xen/errno.h
        touch $@
 
 txt/%.txt: %.txt
diff -r 549b8f4b9560 -r 2d6bc8712c01 xen/include/public/arch-x86/xen.h
--- a/xen/include/public/arch-x86/xen.h Tue Nov 29 15:48:06 2011 +0000
+++ b/xen/include/public/arch-x86/xen.h Tue Nov 29 15:48:07 2011 +0000
@@ -82,7 +82,13 @@
 typedef unsigned long xen_ulong_t;
 
 /*
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_set_trap_table(const struct trap_info traps[]);
+ * `
+ */
+/*
  * Send an array of these to HYPERVISOR_set_trap_table().
+ * Terminate the array with a sentinel entry, with traps[].address==0.
  * The privilege level specifies which modes may enter a trap via a software
  * interrupt. On x86/64, since rings 1 and 2 are unavailable, we allocate
  * privilege levels as follows:
diff -r 549b8f4b9560 -r 2d6bc8712c01 xen/include/public/xen.h
--- a/xen/include/public/xen.h  Tue Nov 29 15:48:06 2011 +0000
+++ b/xen/include/public/xen.h  Tue Nov 29 15:48:07 2011 +0000
@@ -55,6 +55,8 @@
  * HYPERCALLS
  */
 
+/* ` enum hypercall_num { // __HYPERVISOR_* => HYPERVISOR_*() */
+
 #define __HYPERVISOR_set_trap_table        0
 #define __HYPERVISOR_mmu_update            1
 #define __HYPERVISOR_set_gdt               2
@@ -105,6 +107,8 @@
 #define __HYPERVISOR_arch_6               54
 #define __HYPERVISOR_arch_7               55
 
+/* ` } */
+
 /*
  * HYPERCALL COMPATIBILITY.
  */
@@ -163,8 +167,11 @@
 #define NR_VIRQS       24
 
 /*
- * HYPERVISOR_mmu_update(reqs, count, pdone, foreigndom)
- * 
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_mmu_update(const struct mmu_update reqs[],
+ * `                       unsigned count, unsigned *done_out,
+ * `                       unsigned foreigndom)
+ * `
  * @reqs is an array of mmu_update_t structures ((ptr, val) pairs).
  * @count is the length of the above array.
  * @pdone is an output parameter indicating number of completed operations
diff -r 549b8f4b9560 -r 2d6bc8712c01 xen/include/xen/errno.h
--- a/xen/include/xen/errno.h   Tue Nov 29 15:48:06 2011 +0000
+++ b/xen/include/xen/errno.h   Tue Nov 29 15:48:07 2011 +0000
@@ -1,6 +1,9 @@
 #ifndef _I386_ERRNO_H
 #define _I386_ERRNO_H
 
+/* ` enum neg_errnoval {  [ -Efoo for each Efoo in the list below ]  } */
+/* ` enum errnoval { */
+
 #define        EPERM            1      /* Operation not permitted */
 #define        ENOENT           2      /* No such file or directory */
 #define        ESRCH            3      /* No such process */
@@ -129,4 +132,6 @@
 #define        ENOMEDIUM       123     /* No medium found */
 #define        EMEDIUMTYPE     124     /* Wrong medium type */
 
+/* ` } */
+
 #endif

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