From mboxrd@z Thu Jan 1 00:00:00 1970 From: Keir Fraser Subject: Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs Date: Mon, 27 Feb 2012 15:50:06 +0000 Message-ID: References: <1330346266.8557.282.camel@zakaz.uk.xensource.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1330346266.8557.282.camel@zakaz.uk.xensource.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: Ian Campbell , "xen-devel@lists.xensource.com" List-Id: xen-devel@lists.xenproject.org On 27/02/2012 12:37, "Ian Campbell" wrote: > On Mon, 2012-02-27 at 12:07 +0000, Ian Campbell wrote: >> As part of this I looked through the relevant chapter from interfaces.tex >> (from >> 4.1, deleted in unstable) to ensure no critical information was missing. > > Actually, the intro from that chapter is interesting/useful and I missed > it. Here's a new version with it included. > > 8<------------------------------------- > > # HG changeset patch > # User Ian Campbell > # Date 1330346207 0 > # Node ID b6a3a0d68c91ce8fa6023aee3046efd3866942df > # Parent 71159fb049f253030c3820c260d092d4aec6b166 > hcall: markup the event channel hypercalls to improve generated docs > > As part of this I looked through the relevant chapter from interfaces.tex > (from > 4.1, deleted in unstable) to ensure no critical information was missing. > > Signed-off-by: Ian Campbell Acked-by: Keir Fraser (Implicit in this Ack is that you can apply this to xen-unstable yourself, even though your commit rights are generally limited to arch/arm). -- Keir > diff -r 71159fb049f2 -r b6a3a0d68c91 xen/include/public/event_channel.h > --- a/xen/include/public/event_channel.h Fri Feb 24 11:46:32 2012 +0100 > +++ b/xen/include/public/event_channel.h Mon Feb 27 12:36:47 2012 +0000 > @@ -1,8 +1,8 @@ > > /*****************************************************************************> * > * event_channel.h > - * > + * > * Event channels between domains. > - * > + * > * Permission is hereby granted, free of charge, to any person obtaining a > copy > * of this software and associated documentation files (the "Software"), to > * deal in the Software without restriction, including without limitation the > @@ -30,12 +30,49 @@ > #include "xen.h" > > /* > - * Prototype for this hypercall is: > - * int event_channel_op(int cmd, void *args) > - * @cmd == EVTCHNOP_??? (event-channel operation). > - * @args == Operation-specific extra arguments (NULL if none). > + * `incontents 150 evtchn Event Channels > + * > + * Event channels are the basic primitive provided by Xen for event > + * notifications. An event is the Xen equivalent of a hardware > + * interrupt. They essentially store one bit of information, the event > + * of interest is signalled by transitioning this bit from 0 to 1. > + * > + * Notifications are received by a guest via an upcall from Xen, > + * indicating when an event arrives (setting the bit). Further > + * notifications are masked until the bit is cleared again (therefore, > + * guests must check the value of the bit after re-enabling event > + * delivery to ensure no missed notifications). > + * > + * Event notifications can be masked by setting a flag; this is > + * equivalent to disabling interrupts and can be used to ensure > + * atomicity of certain operations in the guest kernel. > + * > + * Event channels are represented by the evtchn_* fields in > + * struct shared_info and struct vcpu_info. > */ > > +/* > + * ` enum neg_errnoval > + * ` HYPERVISOR_event_channel_op(enum event_channel_op cmd, void *args) > + * ` > + * @cmd == EVTCHNOP_* (event-channel operation). > + * @args == struct evtchn_* Operation-specific extra arguments (NULL if > none). > + */ > + > +/* ` enum event_channel_op { // EVTCHNOP_* => struct evtchn_* */ > +#define EVTCHNOP_bind_interdomain 0 > +#define EVTCHNOP_bind_virq 1 > +#define EVTCHNOP_bind_pirq 2 > +#define EVTCHNOP_close 3 > +#define EVTCHNOP_send 4 > +#define EVTCHNOP_status 5 > +#define EVTCHNOP_alloc_unbound 6 > +#define EVTCHNOP_bind_ipi 7 > +#define EVTCHNOP_bind_vcpu 8 > +#define EVTCHNOP_unmask 9 > +#define EVTCHNOP_reset 10 > +/* ` } */ > + > typedef uint32_t evtchn_port_t; > DEFINE_XEN_GUEST_HANDLE(evtchn_port_t); > > @@ -47,7 +84,6 @@ DEFINE_XEN_GUEST_HANDLE(evtchn_port_t); > * 1. If the caller is unprivileged then must be DOMID_SELF. > * 2. may be DOMID_SELF, allowing loopback connections. > */ > -#define EVTCHNOP_alloc_unbound 6 > struct evtchn_alloc_unbound { > /* IN parameters */ > domid_t dom, remote_dom; > @@ -63,9 +99,8 @@ typedef struct evtchn_alloc_unbound evtc > * domain. A fresh port is allocated in the calling domain and returned as > * . > * NOTES: > - * 2. may be DOMID_SELF, allowing loopback connections. > + * 1. may be DOMID_SELF, allowing loopback connections. > */ > -#define EVTCHNOP_bind_interdomain 0 > struct evtchn_bind_interdomain { > /* IN parameters. */ > domid_t remote_dom; > @@ -87,10 +122,9 @@ typedef struct evtchn_bind_interdomain e > * The allocated event channel is bound to the specified vcpu and the > * binding cannot be changed. > */ > -#define EVTCHNOP_bind_virq 1 > struct evtchn_bind_virq { > /* IN parameters. */ > - uint32_t virq; > + uint32_t virq; /* enum virq */ > uint32_t vcpu; > /* OUT parameters. */ > evtchn_port_t port; > @@ -98,12 +132,11 @@ struct evtchn_bind_virq { > typedef struct evtchn_bind_virq evtchn_bind_virq_t; > > /* > - * EVTCHNOP_bind_pirq: Bind a local event channel to PIRQ . > + * EVTCHNOP_bind_pirq: Bind a local event channel to a real IRQ (PIRQ ). > * NOTES: > * 1. A physical IRQ may be bound to at most one event channel per domain. > * 2. Only a sufficiently-privileged domain may bind to a physical IRQ. > */ > -#define EVTCHNOP_bind_pirq 2 > struct evtchn_bind_pirq { > /* IN parameters. */ > uint32_t pirq; > @@ -120,7 +153,6 @@ typedef struct evtchn_bind_pirq evtchn_b > * 1. The allocated event channel is bound to the specified vcpu. The > binding > * may not be changed. > */ > -#define EVTCHNOP_bind_ipi 7 > struct evtchn_bind_ipi { > uint32_t vcpu; > /* OUT parameters. */ > @@ -133,7 +165,6 @@ typedef struct evtchn_bind_ipi evtchn_bi > * interdomain then the remote end is placed in the unbound state > * (EVTCHNSTAT_unbound), awaiting a new connection. > */ > -#define EVTCHNOP_close 3 > struct evtchn_close { > /* IN parameters. */ > evtchn_port_t port; > @@ -144,7 +175,6 @@ typedef struct evtchn_close evtchn_close > * EVTCHNOP_send: Send an event to the remote end of the channel whose local > * endpoint is . > */ > -#define EVTCHNOP_send 4 > struct evtchn_send { > /* IN parameters. */ > evtchn_port_t port; > @@ -159,7 +189,6 @@ typedef struct evtchn_send evtchn_send_t > * 2. Only a sufficiently-privileged domain may obtain the status of an > event > * channel for which is not DOMID_SELF. > */ > -#define EVTCHNOP_status 5 > struct evtchn_status { > /* IN parameters */ > domid_t dom; > @@ -176,13 +205,13 @@ struct evtchn_status { > union { > struct { > domid_t dom; > - } unbound; /* EVTCHNSTAT_unbound */ > + } unbound; /* EVTCHNSTAT_unbound */ > struct { > domid_t dom; > evtchn_port_t port; > - } interdomain; /* EVTCHNSTAT_interdomain */ > - uint32_t pirq; /* EVTCHNSTAT_pirq */ > - uint32_t virq; /* EVTCHNSTAT_virq */ > + } interdomain; /* EVTCHNSTAT_interdomain */ > + uint32_t pirq; /* EVTCHNSTAT_pirq */ > + uint32_t virq; /* EVTCHNSTAT_virq */ > } u; > }; > typedef struct evtchn_status evtchn_status_t; > @@ -199,7 +228,6 @@ typedef struct evtchn_status evtchn_stat > * the channel is allocated (a port that is freed and subsequently reused > * has its binding reset to vcpu0). > */ > -#define EVTCHNOP_bind_vcpu 8 > struct evtchn_bind_vcpu { > /* IN parameters. */ > evtchn_port_t port; > @@ -211,7 +239,6 @@ typedef struct evtchn_bind_vcpu evtchn_b > * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver > * a notification to the appropriate VCPU if an event is pending. > */ > -#define EVTCHNOP_unmask 9 > struct evtchn_unmask { > /* IN parameters. */ > evtchn_port_t port; > @@ -224,7 +251,6 @@ typedef struct evtchn_unmask evtchn_unma > * 1. may be specified as DOMID_SELF. > * 2. Only a sufficiently-privileged domain may specify other than > DOMID_SELF. > */ > -#define EVTCHNOP_reset 10 > struct evtchn_reset { > /* IN parameters. */ > domid_t dom; > @@ -232,11 +258,13 @@ struct evtchn_reset { > typedef struct evtchn_reset evtchn_reset_t; > > /* > - * Argument to event_channel_op_compat() hypercall. Superceded by new > - * event_channel_op() hypercall since 0x00030202. > + * ` enum neg_errnoval > + * ` HYPERVISOR_event_channel_op_compat(struct evtchn_op *op) > + * ` > + * Superceded by new event_channel_op() hypercall since 0x00030202. > */ > struct evtchn_op { > - uint32_t cmd; /* EVTCHNOP_* */ > + uint32_t cmd; /* enum event_channel_op */ > union { > struct evtchn_alloc_unbound alloc_unbound; > struct evtchn_bind_interdomain bind_interdomain; > diff -r 71159fb049f2 -r b6a3a0d68c91 xen/include/public/xen.h > --- a/xen/include/public/xen.h Fri Feb 24 11:46:32 2012 +0100 > +++ b/xen/include/public/xen.h Mon Feb 27 12:36:47 2012 +0000 > @@ -146,6 +146,7 @@ DEFINE_XEN_GUEST_HANDLE(xen_pfn_t); > * The latter can be allocated only once per guest: they must initially be > * allocated to VCPU0 but can subsequently be re-bound. > */ > +/* ` enum virq { */ > #define VIRQ_TIMER 0 /* V. Timebase update, and/or requested timeout. > */ > #define VIRQ_DEBUG 1 /* V. Request guest to dump debug info. > */ > #define VIRQ_CONSOLE 2 /* G. (DOM0) Bytes received on emergency console. > */ > @@ -167,6 +168,7 @@ DEFINE_XEN_GUEST_HANDLE(xen_pfn_t); > #define VIRQ_ARCH_5 21 > #define VIRQ_ARCH_6 22 > #define VIRQ_ARCH_7 23 > +/* ` } */ > > #define NR_VIRQS 24 > > > > > _______________________________________________ > Xen-devel mailing list > Xen-devel@lists.xen.org > http://lists.xen.org/xen-devel