[RFC PATCH V5 10/14] xen: document 2/3-level event channel ABI

[Wei Liu <wei.liu2@citrix.com>]

Signed-off-by: Wei Liu <wei.liu2@citrix.com>
---
 drivers/xen/events.c |   41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/drivers/xen/events.c b/drivers/xen/events.c
index fe1831b..ee33421 100644
--- a/drivers/xen/events.c
+++ b/drivers/xen/events.c
@@ -57,6 +57,47 @@
 #include <xen/interface/sched.h>
 #include <asm/hw_irq.h>
 
+/*
+ * The 2-level (default) event channel ABI:
+ *
+ * This is the default ABI, it is guaranteed to be supported. The name
+ * comes from its 2-level lookup path.
+ *
+ * The first level is a per-cpu selector in struct vcpu_info. The size
+ * of L1 selector is sizeof(xen_ulong_t), in which each bit represents
+ * a xen_ulong_t word in the event bitmap (second level).
+ *
+ * The second level is a shared bitmap of events, embedded in shared
+ * info page.
+ *
+ * The lookup path is as followed. We first look at each bit of the L1
+ * selector. A non-zero bit in L1 selector indicates one or more bits
+ * in the corresponding word in L2 bitmap is / are set. In this case
+ * we pick up the word in bitmap, process each non-zero bit in the
+ * word and process the event.
+ *
+ *
+ * The 3-level event channel ABI:
+ *
+ * This ABI is more or less the same as the 2-level ABI. In this ABI:
+ *
+ * The first level is a per-cpu selector in struct vcpu_info. In fact,
+ * we reuse the same selector in 2-level ABI.
+ *
+ * The second level is a per-cpu bitmap of xen_ulong_t words, whose
+ * size is the same as the second level bitmap in 2-level ABI. However
+ * we cannot reuse the same bitmap in shared info page because this
+ * bitmap is per-cpu.
+ *
+ * The third level is a shared bitmap of events, which is allocated at
+ * boot time by Linux kernel.
+ *
+ * The lookup path is as followed. The first two levels lookup is the
+ * same as the 2-level ABI, but after picking up the non-zero bit in
+ * L2 selector, we still need to go down one level furthur for the
+ * actual event bit.
+ */
+
 /* extended event channel ABI in use, default is EVTCHN_EXTENDED_NONE */
 uint64_t xen_evtchn_extended = EVTCHN_EXTENDED_NONE;
 EXPORT_SYMBOL_GPL(xen_evtchn_extended);
-- 
1.7.10.4