Ian Campbell
2012-Feb-27 12:07 UTC
[PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1330344234 0
# Node ID 31eb9ee09b726bfab1df49580f024693f4f307ae
# 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@citrix.com>
diff -r 71159fb049f2 -r 31eb9ee09b72 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:03:54 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,27 @@
#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).
+ * ` 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 +62,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 +77,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 +100,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 +110,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 +131,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 +143,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 +153,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 +167,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 +183,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 +206,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 +217,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 +229,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 +236,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 31eb9ee09b72 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:03:54 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
Ian Campbell
2012-Feb-27 12:37 UTC
Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
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@citrix.com> # 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@citrix.com> 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
Keir Fraser
2012-Feb-27 15:50 UTC
Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
On 27/02/2012 12:37, "Ian Campbell" <Ian.Campbell@citrix.com> 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@citrix.com> > # 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@citrix.com>Acked-by: Keir Fraser <keir@xen.org> (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@lists.xen.org > http://lists.xen.org/xen-devel
Ian Jackson
2012-Feb-28 12:39 UTC
Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
Ian Campbell writes ("Re: [Xen-devel] [PATCH DOCDAY] hcall: markup the
event channel hypercalls to improve generated
docs"):> Actually, the intro from that chapter is interesting/useful and I missed
> it. Here''s a new version with it included.
...> hcall: markup the event channel hypercalls to improve generated docs
Good stuff.
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Also, as requested:
commit 78ed3b5816ed60e7e86810c2d93069fae63dc406
Author: Ian Jackson <ian.jackson@eu.citrix.com>
Date: Tue Feb 28 12:36:15 2012 +0000
docs: xen-headers: Annotate typedefs
Parse (some) typedef statements. (Make type names links to the
underlying struct if there is one, rather than to just the typedef.)
Also, exclude the new arch-arm headers.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
diff --git a/docs/Makefile b/docs/Makefile
index 49e33cb..007a5a9 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -120,7 +120,7 @@ html/hypercall/index.html: ./xen-headers
@$(INSTALL_DIR) $(@D)
./xen-headers -O $(@D) \
-T ''arch-x86_64 - Xen public headers'' \
- -X arch-ia64 -X arch-x86_32 -X xen-x86_32 \
+ -X arch-ia64 -X arch-x86_32 -X xen-x86_32 -X arch-arm \
../xen include/public include/xen/errno.h
-include html/hypercall/.deps
diff --git a/docs/xen-headers b/docs/xen-headers
index 08fd7f3..68c9504 100755
--- a/docs/xen-headers
+++ b/docs/xen-headers
@@ -120,11 +120,12 @@ sub aelem ($$$) {
return "<a $hparams>$ytext</a>";
}
-sub defn ($$$;$) {
- my ($text,$type,$name,$hparams) = @_;
+sub defn ($$$;$$) {
+ my ($text,$type,$name,$hparams,$deref) = @_;
$hparams='''' if !defined $hparams;
- debug(2,"DEFN $. $type $name $hparams");
+ debug(2,"DEFN $. $type $name $hparams |$text|");
$sdef{$type}{$name}{DefLocs}{"$leaf:$."} = $leaf_opath;
+ $sdef{$type}{$name}{Derefs}{"$leaf:$."} = $deref;
my $xrefs = $sdef{$type}{$name}{Xrefs};
push @pending_xrefs, values %$xrefs if $xrefs;
$hparams .= " name=\"${type}_$name\"" if
$sdef{$type}{$name}{Used};
@@ -140,7 +141,7 @@ sub norm ($) {
} elsif (s/^(struct|union|enum)\s+(\w+)\b//) {
$no .= ahref($&, (ucfirst $1), $2);
} elsif (s/^\w+\b//) {
- $no .= ahref($&, ''Func'', $&);
+ $no .= ahref($&, [qw(Func Typedef)], $&);
} else {
die "$_ ?";
}
@@ -148,18 +149,48 @@ sub norm ($) {
return $no;
}
-sub refhref ($$) {
- my ($type,$name) = @_;
+sub sdefval ($$$) {
+ my ($type,$name,$hkey) = @_;
$sdef{$type}{$name}{Used} = 1;
- my $locs = $sdef{$type}{$name}{DefLocs};
- return '''' unless $locs;
- if ((scalar keys %$locs) != 1 && !$sdef{$type}{$name}{MultiWarned})
{
- warning("multiple definitions of $type $name: $_")
- foreach keys %$locs;
- $sdef{$type}{$name}{MultiWarned}=1;
+ my $sdef = $sdef{$type}{$name};
+ my $hash = $sdef->{$hkey};
+ if ((scalar keys %$hash) > 1 && !$sdef->{MultiWarned}{$hkey})
{
+ warning("multiple definitions of $type $name: $_")
+ foreach keys %$hash;
+ $sdef->{MultiWarned}{$hkey}=1;
+ }
+ my ($val) = values %$hash;
+ return $val;
+}
+
+sub refhref ($$) {
+ my ($types,$name) = @_;
+ foreach my $type (ref($types) ? @$types : ($types)) {
+ my ($ttype,$tname) = ($type,$name);
+ my $loc = sdefval($ttype,$tname,''DefLocs'');
+ for (;;) {
+ my $deref = sdefval($ttype,$tname,''Derefs'');
+ last unless $deref;
+ my ($type2,$name2,$loc2);
+ my @deref = @$deref;
+ if ($name eq ''buf_ioreq_t'') {
+ print STDERR "REFHREF $type $name | $ttype $tname | @deref\n";
+ }
+ while (@deref) {
+ ($type2,$name2,@deref) = @deref;
+ $loc2 = sdefval($type2,$name2,''DefLocs'');
+ if ($name eq ''buf_ioreq_t'') {
+ print STDERR "REFHREF $type $name | $ttype $tname | $type2 $name2 GOT
$loc2\n";
+ }
+ last if defined $loc2;
+ }
+ last unless defined $loc2;
+ ($loc,$ttype,$tname) = ($loc2,$type2,$name2);
+ }
+ next unless defined $loc;
+ return "href=\"$loc#${ttype}_$tname\"";
}
- my ($loc) = values %$locs;
- return "href=\"$loc#${type}_$name\"";
+ return '''';
}
sub ahref ($$$) {
@@ -259,6 +290,14 @@ sub process_file ($$) {
in_enum($1,(ucfirst $2),$3);
}
}
+ } elsif (s/^(typedef \s+ )((struct|union|enum) \ (\w+))
+ (\s+) (\w+)(\;)$
+ / norm($1).norm($2).$5.
+ defn($6,''Typedef'',$6,undef,[(ucfirst
$3),$4]).
+ $7 /xe) {
+ } elsif (s/^(typedef \s+) (\w+) (\s+) (\w+) (\;)$
+ / $1.norm($2).$3.
+
defn($4,''Typedef'',$4,undef,[''Typedef'',$2]).
$5 /xe) {
} elsif (s/^( \s* \#define \s+ ) (\w+) ( \s+\S )
/ $1.defmacro($2).norm($3) /xe) {
} elsif (s/( \`incontents \s+ (\d+) \s+ (\w+) \s+ )(\S .* \S)
@@ -315,6 +354,7 @@ END
$forkind->(''Func'',''Functions'','''',''()'');
$forkind->(''Struct'',''Structs'',''struct
'','''');
$forkind->(''Enum'',''Enums and sets of
#defines'','''','''');
+
$forkind->(''Typedef'',''Typedefs'',''typedef
'','''');
$forkind->(''EnumVal'',''Enum values and
individual #defines'','''','''');
$o .= "</ul>\n<h2>Files</h2><ul>\n";
foreach my $of (sort { $a->[0] cmp $b->[0] } @outfiles) {
Ian Campbell
2012-Feb-28 12:43 UTC
Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
On Tue, 2012-02-28 at 12:39 +0000, Ian Jackson wrote:> Ian Campbell writes ("Re: [Xen-devel] [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs"): > > Actually, the intro from that chapter is interesting/useful and I missed > > it. Here''s a new version with it included. > ... > > hcall: markup the event channel hypercalls to improve generated docs > > Good stuff. > > Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>Thanks.> > Also, as requested: > > commit 78ed3b5816ed60e7e86810c2d93069fae63dc406 > Author: Ian Jackson <ian.jackson@eu.citrix.com> > Date: Tue Feb 28 12:36:15 2012 +0000 > > docs: xen-headers: Annotate typedefs > > Parse (some) typedef statements. (Make type names links to the > underlying struct if there is one, rather than to just the typedef.) > > Also, exclude the new arch-arm headers. > > Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>Thanks, I didn''t review closely or try it yet but this jumped out at me (twice):> + if ($name eq ''buf_ioreq_t'') { > + print STDERR "REFHREF $type $name | $ttype $tname | @deref\n"; > + }And this has a odd looking indentation:> @@ -259,6 +290,14 @@ sub process_file ($$) { > in_enum($1,(ucfirst $2),$3); > } > } > + } elsif (s/^(typedef \s+ )((struct|union|enum) \ (\w+)) > + (\s+) (\w+)(\;)$ > + / norm($1).norm($2).$5. > + defn($6,''Typedef'',$6,undef,[(ucfirst $3),$4]). > + $7 /xe) { > + } elsif (s/^(typedef \s+) (\w+) (\s+) (\w+) (\;)$Extra leading space or a sneaky hard tab? Ian.
Ian Jackson
2012-Mar-01 16:03 UTC
Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
Keir Fraser writes ("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@citrix.com> wrote:
> > hcall: markup the event channel hypercalls to improve generated docs
>
> Acked-by: Keir Fraser <keir@xen.org>
>
> (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).
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Ian.
Ian Jackson
2012-Mar-01 16:09 UTC
Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
Ian Campbell writes ("Re: [Xen-devel] [PATCH DOCDAY] hcall: markup the
event channel hypercalls to improve generated
docs"):> Thanks, I didn''t review closely or try it yet but this jumped out
at me
> (twice):
>
> > + if ($name eq ''buf_ioreq_t'') {
> > + print STDERR "REFHREF $type $name | $ttype $tname |
@deref\n";
> > + }
I obviously wasn''t having a good day that day.
> And this has a odd looking indentation:
...> > + } elsif (s/^(typedef \s+ )((struct|union|enum) \ (\w+))
> > + (\s+) (\w+)(\;)$
> > + / norm($1).norm($2).$5.
> > +
defn($6,''Typedef'',$6,undef,[(ucfirst $3),$4]).
> > + $7 /xe) {
> > + } elsif (s/^(typedef \s+) (\w+) (\s+) (\w+) (\;)$
>
> Extra leading space or a sneaky hard tab?
The code was full of hard tabs. I think this needs a separate patch
to fix it up.
Ian.
Parse (some) typedef statements. (Make type names links to the
underlying struct if there is one, rather than to just the typedef.)
Also, exclude the new arch-arm headers.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Cc: Ian Campbell <Ian.Campbell@citrix.com>
---
docs/Makefile | 2 +-
docs/xen-headers | 62 +++++++++++++++++++++++++++++++++++++++++------------
2 files changed, 49 insertions(+), 15 deletions(-)
diff --git a/docs/Makefile b/docs/Makefile
index 49e33cb..007a5a9 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -120,7 +120,7 @@ html/hypercall/index.html: ./xen-headers
@$(INSTALL_DIR) $(@D)
./xen-headers -O $(@D) \
-T ''arch-x86_64 - Xen public headers'' \
- -X arch-ia64 -X arch-x86_32 -X xen-x86_32 \
+ -X arch-ia64 -X arch-x86_32 -X xen-x86_32 -X arch-arm \
../xen include/public include/xen/errno.h
-include html/hypercall/.deps
diff --git a/docs/xen-headers b/docs/xen-headers
index 08fd7f3..3fea3e3 100755
--- a/docs/xen-headers
+++ b/docs/xen-headers
@@ -120,11 +120,12 @@ sub aelem ($$$) {
return "<a $hparams>$ytext</a>";
}
-sub defn ($$$;$) {
- my ($text,$type,$name,$hparams) = @_;
+sub defn ($$$;$$) {
+ my ($text,$type,$name,$hparams,$deref) = @_;
$hparams='''' if !defined $hparams;
- debug(2,"DEFN $. $type $name $hparams");
+ debug(2,"DEFN $. $type $name $hparams |$text|");
$sdef{$type}{$name}{DefLocs}{"$leaf:$."} = $leaf_opath;
+ $sdef{$type}{$name}{Derefs}{"$leaf:$."} = $deref;
my $xrefs = $sdef{$type}{$name}{Xrefs};
push @pending_xrefs, values %$xrefs if $xrefs;
$hparams .= " name=\"${type}_$name\"" if
$sdef{$type}{$name}{Used};
@@ -140,7 +141,7 @@ sub norm ($) {
} elsif (s/^(struct|union|enum)\s+(\w+)\b//) {
$no .= ahref($&, (ucfirst $1), $2);
} elsif (s/^\w+\b//) {
- $no .= ahref($&, ''Func'', $&);
+ $no .= ahref($&, [qw(Func Typedef)], $&);
} else {
die "$_ ?";
}
@@ -148,18 +149,42 @@ sub norm ($) {
return $no;
}
-sub refhref ($$) {
- my ($type,$name) = @_;
+sub sdefval ($$$) {
+ my ($type,$name,$hkey) = @_;
$sdef{$type}{$name}{Used} = 1;
- my $locs = $sdef{$type}{$name}{DefLocs};
- return '''' unless $locs;
- if ((scalar keys %$locs) != 1 && !$sdef{$type}{$name}{MultiWarned})
{
- warning("multiple definitions of $type $name: $_")
- foreach keys %$locs;
- $sdef{$type}{$name}{MultiWarned}=1;
+ my $sdef = $sdef{$type}{$name};
+ my $hash = $sdef->{$hkey};
+ if ((scalar keys %$hash) > 1 && !$sdef->{MultiWarned}{$hkey})
{
+ warning("multiple definitions of $type $name: $_")
+ foreach keys %$hash;
+ $sdef->{MultiWarned}{$hkey}=1;
+ }
+ my ($val) = values %$hash;
+ return $val;
+}
+
+sub refhref ($$) {
+ my ($types,$name) = @_;
+ foreach my $type (ref($types) ? @$types : ($types)) {
+ my ($ttype,$tname) = ($type,$name);
+ my $loc = sdefval($ttype,$tname,''DefLocs'');
+ for (;;) {
+ my $deref = sdefval($ttype,$tname,''Derefs'');
+ last unless $deref;
+ my ($type2,$name2,$loc2);
+ my @deref = @$deref;
+ while (@deref) {
+ ($type2,$name2,@deref) = @deref;
+ $loc2 = sdefval($type2,$name2,''DefLocs'');
+ last if defined $loc2;
+ }
+ last unless defined $loc2;
+ ($loc,$ttype,$tname) = ($loc2,$type2,$name2);
+ }
+ next unless defined $loc;
+ return "href=\"$loc#${ttype}_$tname\"";
}
- my ($loc) = values %$locs;
- return "href=\"$loc#${type}_$name\"";
+ return '''';
}
sub ahref ($$$) {
@@ -259,6 +284,14 @@ sub process_file ($$) {
in_enum($1,(ucfirst $2),$3);
}
}
+ } elsif (s/^(typedef \s+ )((struct|union|enum) \ (\w+))
+ (\s+) (\w+)(\;)$
+ / norm($1).norm($2).$5.
+ defn($6,''Typedef'',$6,undef,[(ucfirst
$3),$4]).
+ $7 /xe) {
+ } elsif (s/^(typedef \s+) (\w+) (\s+) (\w+) (\;)$
+ / $1.norm($2).$3.
+
defn($4,''Typedef'',$4,undef,[''Typedef'',$2]).
$5 /xe) {
} elsif (s/^( \s* \#define \s+ ) (\w+) ( \s+\S )
/ $1.defmacro($2).norm($3) /xe) {
} elsif (s/( \`incontents \s+ (\d+) \s+ (\w+) \s+ )(\S .* \S)
@@ -315,6 +348,7 @@ END
$forkind->(''Func'',''Functions'','''',''()'');
$forkind->(''Struct'',''Structs'',''struct
'','''');
$forkind->(''Enum'',''Enums and sets of
#defines'','''','''');
+
$forkind->(''Typedef'',''Typedefs'',''typedef
'','''');
$forkind->(''EnumVal'',''Enum values and
individual #defines'','''','''');
$o .= "</ul>\n<h2>Files</h2><ul>\n";
foreach my $of (sort { $a->[0] cmp $b->[0] } @outfiles) {
--
1.7.2.5
Remove hard tabs from the Perl script.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Cc: Ian Campbell <Ian.Campbell@citrix.com>
---
docs/xen-headers | 230 +++++++++++++++++++++++++++---------------------------
1 files changed, 115 insertions(+), 115 deletions(-)
diff --git a/docs/xen-headers b/docs/xen-headers
index 3fea3e3..c4cf2e4 100755
--- a/docs/xen-headers
+++ b/docs/xen-headers
@@ -86,13 +86,13 @@ sub compile_fglobs () {
local ($_);
my $f = "sub file_wanted (\$) {\n local (\$_) =
\"/\$leaf\";\n";
foreach my $fglob (@fglobs) {
- $_ = $fglob->[0];
- $_ = "**$_**" unless m/[?*]/;
- s/\W/\\$&/g;
- s,\\\*\\\*,.*,g;
- s,\\\*,[^/]*,g;
- s,\\\?,[^/],g;
- $f .= " return $fglob->[1] if m,$_,o;\n";
+ $_ = $fglob->[0];
+ $_ = "**$_**" unless m/[?*]/;
+ s/\W/\\$&/g;
+ s,\\\*\\\*,.*,g;
+ s,\\\*,[^/]*,g;
+ s,\\\?,[^/],g;
+ $f .= " return $fglob->[1] if m,$_,o;\n";
}
$f .= " return 1;\n}\n1;\n";
debug(3, $f);
@@ -136,15 +136,15 @@ sub norm ($) {
local ($_) = @_;
my $no = '''';
while (length) {
- if (s/^(?:\s|^\W)+//) {
- $no .= $&;
- } elsif (s/^(struct|union|enum)\s+(\w+)\b//) {
- $no .= ahref($&, (ucfirst $1), $2);
- } elsif (s/^\w+\b//) {
- $no .= ahref($&, [qw(Func Typedef)], $&);
- } else {
- die "$_ ?";
- }
+ if (s/^(?:\s|^\W)+//) {
+ $no .= $&;
+ } elsif (s/^(struct|union|enum)\s+(\w+)\b//) {
+ $no .= ahref($&, (ucfirst $1), $2);
+ } elsif (s/^\w+\b//) {
+ $no .= ahref($&, [qw(Func Typedef)], $&);
+ } else {
+ die "$_ ?";
+ }
}
return $no;
}
@@ -195,25 +195,25 @@ sub ahref ($$$) {
sub defmacro ($) {
my ($valname) = @_;
if (!$in_enum) {
- return $valname;
+ return $valname;
} elsif (substr($valname, 0, (length $in_enum->[0])) ne
$in_enum->[0]) {
- warning("in enum expecting $in_enum->[0]* got $valname");
- return $valname;
+ warning("in enum expecting $in_enum->[0]* got $valname");
+ return $valname;
} else {
- my $reftype = $in_enum->[1];
- my $refname = $in_enum->[2].substr($valname, (length $in_enum->[0]));
- $sdef{$reftype}{$refname}{Xrefs}{$leaf,$.} - "[see <a
href=\"$leaf_opath#EnumVal_$valname\">$valname</a>]";
- $sdef{EnumVal}{$valname}{Used} = 1;
- return defn($valname,''EnumVal'',$valname,
refhref($reftype,$refname));
+ my $reftype = $in_enum->[1];
+ my $refname = $in_enum->[2].substr($valname, (length
$in_enum->[0]));
+ $sdef{$reftype}{$refname}{Xrefs}{$leaf,$.} + "[see
<a
href=\"$leaf_opath#EnumVal_$valname\">$valname</a>]";
+ $sdef{EnumVal}{$valname}{Used} = 1;
+ return defn($valname,''EnumVal'',$valname,
refhref($reftype,$refname));
}
}
sub out_xrefs ($) {
my ($linemapfunc) = @_;
foreach my $xref (@pending_xrefs) {
- $o .= $linemapfunc->($xref);
- $o .= "\n";
+ $o .= $linemapfunc->($xref);
+ $o .= "\n";
}
@pending_xrefs = ();
}
@@ -222,11 +222,11 @@ sub incontents ($$$) {
my ($text, $seq, $anchor) = @_;
$anchor = "incontents_$anchor";
if ($pass==2) {
- push @incontents, {
- Seq => $seq,
- Href => "$leaf_opath#$anchor",
- Title => $text,
- };
+ push @incontents, {
+ Seq => $seq,
+ Href => "$leaf_opath#$anchor",
+ Title => $text,
+ };
}
return "<a
name=\"$anchor\"><strong>$text</strong></a>";
}
@@ -250,41 +250,41 @@ sub process_file ($$) {
$o .= "<html><head><title>$leaf -
$xtitle</title></head><body><pre>\n";
while (<$in>) {
- s/\&/\&/g;
- s/\</\</g;
- s/\>/\>/g;
-
- if (m/^(.*\`)[ \t]*$/) {
- my $lhs = $1;
- out_xrefs(sub { "$1 $_[0]"; });
- } elsif (m/^\s*$/) {
- out_xrefs(sub { sprintf "/* %70s */", $_[0]; });
- }
+ s/\&/\&/g;
+ s/\</\</g;
+ s/\>/\>/g;
+
+ if (m/^(.*\`)[ \t]*$/) {
+ my $lhs = $1;
+ out_xrefs(sub { "$1 $_[0]"; });
+ } elsif (m/^\s*$/) {
+ out_xrefs(sub { sprintf "/* %70s */", $_[0]; });
+ }
- # In case of comments, strip " /* ` " and " * ` ";
- my $lstripped = s,^ \s* /? \* \s* \` \ ,,x ? $&: '''';
+ # In case of comments, strip " /* ` " and " * ` ";
+ my $lstripped = s,^ \s* /? \* \s* \` \ ,,x ? $&:
'''';
- # Strip trailing whitespace and perhaps trailing "*/" or
"*"
- s,(?: \s* \* /? )? \s* $,,x or die;
- my $rstripped = $&;
+ # Strip trailing whitespace and perhaps trailing "*/" or
"*"
+ s,(?: \s* \* /? )? \s* $,,x or die;
+ my $rstripped = $&;
- # Now the actual functionality:
+ # Now the actual functionality:
- debug(3,"$. $_");
+ debug(3,"$. $_");
- if (!m/^(?: __attribute__ | __pragma__ )\b/x &&
- s/^( (?: \w+\ )? ) (\w+[a-z]\w+) ( \( .*)$
+ if (!m/^(?: __attribute__ | __pragma__ )\b/x &&
+ s/^( (?: \w+\ )? ) (\w+[a-z]\w+) ( \( .*)$
/ $1.defn($2,''Func'',$2).norm($3) /xe) {
- } elsif (s/^((struct|union|enum) \ (\w+)) ( \s+ \{ .* )$
+ } elsif (s/^((struct|union|enum) \ (\w+)) ( \s+ \{ .* )$
/ defn($1,(ucfirst $2),$3).norm($4) /xe) {
- if ($2 eq ''enum'') {
- if (m,/[/*] (\w+)\* \=\>\; (\w+)\*\(\),) {
- in_enum($1,''Func'',$2)
- } elsif (m,/[/*] (\w+)\* \=\>\; (struct) (\w+)\*,) {
- in_enum($1,(ucfirst $2),$3);
- }
- }
- } elsif (s/^(typedef \s+ )((struct|union|enum) \ (\w+))
+ if ($2 eq ''enum'') {
+ if (m,/[/*] (\w+)\* \=\>\; (\w+)\*\(\),) {
+ in_enum($1,''Func'',$2)
+ } elsif (m,/[/*] (\w+)\* \=\>\; (struct) (\w+)\*,) {
+ in_enum($1,(ucfirst $2),$3);
+ }
+ }
+ } elsif (s/^(typedef \s+ )((struct|union|enum) \ (\w+))
(\s+) (\w+)(\;)$
/ norm($1).norm($2).$5.
defn($6,''Typedef'',$6,undef,[(ucfirst
$3),$4]).
@@ -292,32 +292,32 @@ sub process_file ($$) {
} elsif (s/^(typedef \s+) (\w+) (\s+) (\w+) (\;)$
/ $1.norm($2).$3.
defn($4,''Typedef'',$4,undef,[''Typedef'',$2]).
$5 /xe) {
- } elsif (s/^( \s* \#define \s+ ) (\w+) ( \s+\S )
+ } elsif (s/^( \s* \#define \s+ ) (\w+) ( \s+\S )
/ $1.defmacro($2).norm($3) /xe) {
- } elsif (s/( \`incontents \s+ (\d+) \s+ (\w+) \s+ )(\S .* \S)
+ } elsif (s/( \`incontents \s+ (\d+) \s+ (\w+) \s+ )(\S .* \S)
/ norm($1).incontents($4, $2, $3) /xe) {
- } else {
- if (m/^\s*\}/) {
- $in_enum = undef;
- }
- $_ = norm($_);
- }
-
- # Write the line out
-
- if ($pass == 2) {
- $o .= $lstripped;
- $o .= $_;
- $o .= $rstripped;
- }
+ } else {
+ if (m/^\s*\}/) {
+ $in_enum = undef;
+ }
+ $_ = norm($_);
+ }
+
+ # Write the line out
+
+ if ($pass == 2) {
+ $o .= $lstripped;
+ $o .= $_;
+ $o .= $rstripped;
+ }
}
warning("pending xrefs at end of file") if @pending_xrefs;
if ($pass == 2) {
- push @outfiles, [ $leaf, $leaf_opath ];
- $o .= "</pre></body></html>";
- write_file($outfile, $o);
+ push @outfiles, [ $leaf, $leaf_opath ];
+ $o .= "</pre></body></html>";
+ write_file($outfile, $o);
}
}
@@ -332,18 +332,18 @@ sub output_index () {
<ul>
END
foreach my $ic (sort { $a->{Seq} <=> $b->{Seq} } @incontents) {
- $o .= "<li><a
href=\"$ic->{Href}\">$ic->{Title}</a></li>\n";
+ $o .= "<li><a
href=\"$ic->{Href}\">$ic->{Title}</a></li>\n";
}
$o .= "</ul>\n";
my $forkind = sub {
- my ($type,$desc,$pfx,$sfx) = @_;
- $o .= "<h2>$desc</h2><ul>\n";
- foreach my $name (sort keys %{ $sdef{$type} }) {
- my $href = refhref($type,$name);
- next unless $href =~ m/\S/;
- $o .= "<li><a
$href>$pfx$name$sfx</a></li>\n";
- }
- $o .= "</ul>\n";
+ my ($type,$desc,$pfx,$sfx) = @_;
+ $o .= "<h2>$desc</h2><ul>\n";
+ foreach my $name (sort keys %{ $sdef{$type} }) {
+ my $href = refhref($type,$name);
+ next unless $href =~ m/\S/;
+ $o .= "<li><a
$href>$pfx$name$sfx</a></li>\n";
+ }
+ $o .= "</ul>\n";
};
$forkind->(''Func'',''Functions'','''',''()'');
$forkind->(''Struct'',''Structs'',''struct
'','''');
@@ -352,7 +352,7 @@ END
$forkind->(''EnumVal'',''Enum values and
individual #defines'','''','''');
$o .= "</ul>\n<h2>Files</h2><ul>\n";
foreach my $of (sort { $a->[0] cmp $b->[0] } @outfiles) {
- $o .= "<li><a
href=\"$of->[1]\">$of->[0]</a></li>\n";
+ $o .= "<li><a
href=\"$of->[1]\">$of->[0]</a></li>\n";
}
$o .= "</ul></body></html>\n";
write_file("$outdir/index.html", $o);
@@ -362,37 +362,37 @@ foreach $pass (qw(1 2)) {
my $depspath = "$outdir/.deps";
my $depsout;
if ($pass==2) {
- $depsout = new IO::File "$depspath.new", ''w'' or
die $!;
+ $depsout = new IO::File "$depspath.new",
''w'' or die $!;
}
find({ wanted =>
- sub {
- return unless m/\.h$/;
- lstat $File::Find::name or die "$File::Find::name $!";
- -f _ or die "$File::Find::name";
- substr($File::Find::name, 0, 1+length $basedir)
- eq "$basedir/"
- or die "$File::Find::name $basedir";
- $leaf = substr($File::Find::name, 1+length $basedir);
- if (!file_wanted()) {
- debug(1,"$pass $File::Find::name excluded");
- return;
- }
- $leaf_opath = $leaf;
- $leaf_opath =~ s#/#,#g;
- $leaf_opath .= ".html";
- print $depsout "$outdir/index.html: $File::Find::name\n"
- or die $!
- if $pass==2;
- process_file($File::Find::name,
$outdir.''/''.$leaf_opath);
- },
- no_chdir => 1,
- },
- map { "$basedir/$_" } @indirs);
+ sub {
+ return unless m/\.h$/;
+ lstat $File::Find::name or die "$File::Find::name
$!";
+ -f _ or die "$File::Find::name";
+ substr($File::Find::name, 0, 1+length $basedir)
+ eq "$basedir/"
+ or die "$File::Find::name $basedir";
+ $leaf = substr($File::Find::name, 1+length $basedir);
+ if (!file_wanted()) {
+ debug(1,"$pass $File::Find::name excluded");
+ return;
+ }
+ $leaf_opath = $leaf;
+ $leaf_opath =~ s#/#,#g;
+ $leaf_opath .= ".html";
+ print $depsout "$outdir/index.html:
$File::Find::name\n"
+ or die $!
+ if $pass==2;
+ process_file($File::Find::name,
$outdir.''/''.$leaf_opath);
+ },
+ no_chdir => 1,
+ },
+ map { "$basedir/$_" } @indirs);
if ($pass==2) {
- close $depsout or die $!;
- rename "$depspath.new", "$depspath" or die $!;
+ close $depsout or die $!;
+ rename "$depspath.new", "$depspath" or die $!;
}
}
--
1.7.2.5
On Thu, 2012-03-01 at 16:11 +0000, Ian Jackson wrote:> Parse (some) typedef statements. (Make type names links to the > underlying struct if there is one, rather than to just the typedef.) > > Also, exclude the new arch-arm headers. > > Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com> > Cc: Ian Campbell <Ian.Campbell@citrix.com>I didn''t review the implementation but the output is what I was hoping for. Acked-by: Ian Campbell <ian.campbell@citrix.com>
On Thu, 2012-03-01 at 16:11 +0000, Ian Jackson wrote:> Remove hard tabs from the Perl script. > > Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com> > Cc: Ian Campbell <Ian.Campbell@citrix.com>Acked-by: Ian Campbell <ian.campbell@citrix.com>
Ian Campbell writes ("Re: [PATCH 2/2] docs: xen-headers: Remove hard
tabs"):> On Thu, 2012-03-01 at 16:11 +0000, Ian Jackson wrote:
> > Remove hard tabs from the Perl script.
> >
> > Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
> > Cc: Ian Campbell <Ian.Campbell@citrix.com>
>
> Acked-by: Ian Campbell <ian.campbell@citrix.com>
Thanks, applied both of them.
Ian.