|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Xen-devel] [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
On 27/02/2012 12:37, "Ian Campbell" <Ian.Campbell@xxxxxxxxxx> 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 <ian.campbell@xxxxxxxxxx>
> # 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 <ian.campbell@xxxxxxxxxx>
Acked-by: Keir Fraser <keir@xxxxxxx>
(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 <dom> must be DOMID_SELF.
> * 2. <rdom> 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
> * <local_port>.
> * NOTES:
> - * 2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
> + * 1. <remote_dom> 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 <irq>.
> + * EVTCHNOP_bind_pirq: Bind a local event channel to a real IRQ (PIRQ <irq>).
> * 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 <port>.
> */
> -#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 <dom> 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. <dom> 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@xxxxxxxxxxxxx
> http://lists.xen.org/xen-devel
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |