Some of these could probably do with some review from people who know
what these hypercalls actually do.
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
---
xen/include/public/arch-x86/xen.h | 30 ++++++++++++++++++++++++++++++
xen/include/public/arch-x86_64.h | 16 ++++++++++++++++
xen/include/public/platform.h | 4 ++++
3 files changed, 50 insertions(+), 0 deletions(-)
diff --git a/xen/include/public/arch-x86/xen.h
b/xen/include/public/arch-x86/xen.h
index d663cef..1c186d7 100644
--- a/xen/include/public/arch-x86/xen.h
+++ b/xen/include/public/arch-x86/xen.h
@@ -65,6 +65,11 @@ typedef unsigned long xen_pfn_t;
* SEGMENT DESCRIPTOR TABLES
*/
/*
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_set_gdt(const xen_pfn_t frames[], unsigned int entries);
+ * `
+ */
+/*
* A number of GDT entries are reserved by Xen. These are not situated at the
* start of the GDT because some stupid OSes export hard-coded selector values
* in their ABI. These hard-coded values are always near the start of the GDT,
@@ -83,6 +88,13 @@ typedef unsigned long xen_ulong_t;
/*
* ` enum neg_errnoval
+ * ` HYPERVISOR_stack_switch(unsigned long ss, unsigned long esp);
+ * `
+ * Sets the stack segment and pointer for the current vcpu.
+ */
+
+/*
+ * ` enum neg_errnoval
* ` HYPERVISOR_set_trap_table(const struct trap_info traps[]);
* `
*/
@@ -183,6 +195,24 @@ typedef struct arch_shared_info arch_shared_info_t;
#endif /* !__ASSEMBLY__ */
/*
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_fpu_taskswitch(int set);
+ * `
+ * Sets (if set!=0) or clears (if set==0) CR0.TS.
+ */
+
+/*
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_set_debugreg(int regno, unsigned long value);
+ *
+ * ` unsigned long
+ * ` HYPERVISOR_get_debugreg(int regno);
+ * For 0<=reg<=7, returns the debug register value.
+ * For other values of reg, returns ((unsigned long)-EINVAL).
+ * (Unfortunately, this interface is defective.)
+ */
+
+/*
* Prefix forces emulation of some non-trapping instructions.
* Currently only CPUID.
*/
diff --git a/xen/include/public/arch-x86_64.h b/xen/include/public/arch-x86_64.h
index fbb2639..409805f 100644
--- a/xen/include/public/arch-x86_64.h
+++ b/xen/include/public/arch-x86_64.h
@@ -25,3 +25,19 @@
*/
#include "arch-x86/xen.h"
+
+/*
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_set_callbacks(unsigned long event_selector,
+ * ` unsigned long event_address,
+ * ` unsigned long failsafe_selector,
+ * ` unsigned long failsafe_address);
+ * `
+ * Register for callbacks on events. When an event (from an event
+ * channel) occurs, event_address is used as the value of eip.
+ *
+ * A similar callback occurs if the segment selectors are invalid.
+ * failsafe_address is used as the value of eip.
+ *
+ * On x86_64, event_selector and failsafe_selector are ignored (???).
+ */
diff --git a/xen/include/public/platform.h b/xen/include/public/platform.h
index 7b8d6e8..68e4177 100644
--- a/xen/include/public/platform.h
+++ b/xen/include/public/platform.h
@@ -490,6 +490,10 @@ struct xenpf_mem_hotadd
uint32_t flags;
};
+/*
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_platform_op(const struct xen_platform_op*);
+ */
struct xen_platform_op {
uint32_t cmd;
uint32_t interface_version; /* XENPF_INTERFACE_VERSION */
--
tg: (df19317..) t/xen/docs2.xen-headers.hcalls (depends on: t/xen/gitignore)
On Mon, 2012-03-26 at 18:06 +0100, Ian Jackson wrote:> Some of these could probably do with some review from people who know > what these hypercalls actually do. > > Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com> > > --- > xen/include/public/arch-x86/xen.h | 30 ++++++++++++++++++++++++++++++ > xen/include/public/arch-x86_64.h | 16 ++++++++++++++++ > xen/include/public/platform.h | 4 ++++ > 3 files changed, 50 insertions(+), 0 deletions(-) > > diff --git a/xen/include/public/arch-x86/xen.h b/xen/include/public/arch-x86/xen.h > index d663cef..1c186d7 100644 > --- a/xen/include/public/arch-x86/xen.h > +++ b/xen/include/public/arch-x86/xen.h > @@ -65,6 +65,11 @@ typedef unsigned long xen_pfn_t; > * SEGMENT DESCRIPTOR TABLES > */ > /* > + * ` enum neg_errnoval > + * ` HYPERVISOR_set_gdt(const xen_pfn_t frames[], unsigned int entries); > + * ` > + */ > +/* > * A number of GDT entries are reserved by Xen. These are not situated at the > * start of the GDT because some stupid OSes export hard-coded selector values > * in their ABI. These hard-coded values are always near the start of the GDT, > @@ -83,6 +88,13 @@ typedef unsigned long xen_ulong_t; > > /* > * ` enum neg_errnoval > + * ` HYPERVISOR_stack_switch(unsigned long ss, unsigned long esp); > + * ` > + * Sets the stack segment and pointer for the current vcpu. > + */ > + > +/* > + * ` enum neg_errnoval > * ` HYPERVISOR_set_trap_table(const struct trap_info traps[]); > * ` > */ > @@ -183,6 +195,24 @@ typedef struct arch_shared_info arch_shared_info_t; > #endif /* !__ASSEMBLY__ */ > > /* > + * ` enum neg_errnoval > + * ` HYPERVISOR_fpu_taskswitch(int set); > + * ` > + * Sets (if set!=0) or clears (if set==0) CR0.TS. > + */ > + > +/* > + * ` enum neg_errnoval > + * ` HYPERVISOR_set_debugreg(int regno, unsigned long value); > + * > + * ` unsigned long > + * ` HYPERVISOR_get_debugreg(int regno); > + * For 0<=reg<=7, returns the debug register value.Specifically these are the 8 architectural x86 debug registers %db0-7, this is an x86 only hypercall> + * For other values of reg, returns ((unsigned long)-EINVAL). > + * (Unfortunately, this interface is defective.)I guess you say this because you can''t distinguish -EINVAL from a valid value. Since these are architectural registers this isn''t as bad as it could be I suppose, you would never expect to probe for these registers using the EINVAL return code.> + */ > + > +/* > * Prefix forces emulation of some non-trapping instructions. > * Currently only CPUID. > */ > diff --git a/xen/include/public/arch-x86_64.h b/xen/include/public/arch-x86_64.h > index fbb2639..409805f 100644 > --- a/xen/include/public/arch-x86_64.h > +++ b/xen/include/public/arch-x86_64.h > @@ -25,3 +25,19 @@ > */ > > #include "arch-x86/xen.h" > + > +/* > + * ` enum neg_errnoval > + * ` HYPERVISOR_set_callbacks(unsigned long event_selector, > + * ` unsigned long event_address, > + * ` unsigned long failsafe_selector, > + * ` unsigned long failsafe_address); > + * ` > + * Register for callbacks on events. When an event (from an event > + * channel) occurs, event_address is used as the value of eip.I think this interface is somewhat deprecated in favour of __HYPERVISOR_callback_op.> + * > + * A similar callback occurs if the segment selectors are invalid. > + * failsafe_address is used as the value of eip. > + * > + * On x86_64, event_selector and failsafe_selector are ignored (???).Right, x86_64 doesn''t really have selectors, just a vestigial remnant of selectors.> + */> diff --git a/xen/include/public/platform.h b/xen/include/public/platform.h > index 7b8d6e8..68e4177 100644 > --- a/xen/include/public/platform.h > +++ b/xen/include/public/platform.h > @@ -490,6 +490,10 @@ struct xenpf_mem_hotadd > uint32_t flags; > }; > > +/* > + * ` enum neg_errnoval > + * ` HYPERVISOR_platform_op(const struct xen_platform_op*); > + */ > struct xen_platform_op { > uint32_t cmd; > uint32_t interface_version; /* XENPF_INTERFACE_VERSION */
Ian Campbell writes ("Re: [Xen-devel] [PATCH] docs: Document some more
hypercalls"):> On Mon, 2012-03-26 at 18:06 +0100, Ian Jackson wrote:
> > + * ` unsigned long
> > + * ` HYPERVISOR_get_debugreg(int regno);
> > + * For 0<=reg<=7, returns the debug register value.
>
> Specifically these are the 8 architectural x86 debug registers %db0-7,
> this is an x86 only hypercall
>
> > + * For other values of reg, returns ((unsigned long)-EINVAL).
> > + * (Unfortunately, this interface is defective.)
>
> I guess you say this because you can''t distinguish -EINVAL from a
valid
> value.
>
> Since these are architectural registers this isn''t as bad as it
could be
> I suppose, you would never expect to probe for these registers using the
> EINVAL return code.
Well, my point is that a function which returns either -EINVAL, or a
bit pattern from a register, is definitely wrong.
If the point of this is to catch broken guests, who are accessing
registers that do not exist and never will, it won''t work, and should
be replaced by some kind of crash or log or something.
If the point is to allow probing by hypothetical future guests, there
needs to be a new mechanism since there is no reserved value.
If the point is to allow compatibility by hypothetical future guests,
the "no such register" value should probably have been all-bits-zero
in the hope that that would be a sensible value for for any registers
introduced in the future.
But in a documentation patch, I don''t want to fix the API !
> > + * ` enum neg_errnoval
> > + * ` HYPERVISOR_set_callbacks(unsigned long event_selector,
> > + * ` unsigned long event_address,
> > + * ` unsigned long failsafe_selector,
> > + * ` unsigned long failsafe_address);
> > + * `
> > + * Register for callbacks on events. When an event (from an event
> > + * channel) occurs, event_address is used as the value of eip.
>
> I think this interface is somewhat deprecated in favour of
> __HYPERVISOR_callback_op.
Interesting. Should we write that it''s deprecated ?
> > + *
> > + * A similar callback occurs if the segment selectors are invalid.
> > + * failsafe_address is used as the value of eip.
> > + *
> > + * On x86_64, event_selector and failsafe_selector are ignored (???).
>
> Right, x86_64 doesn''t really have selectors, just a vestigial
remnant of
> selectors.
Good :-). I''m glad I actually managed to find some facts.
Ian.
Ian Jackson writes ("[Xen-devel] [PATCH] docs: Document some more
hypercalls"):> Some of these could probably do with some review from people who know
> what these hypercalls actually do.
I have applied this patch.
Ian.