[RFC PATCH v1 02/10] arch-x86/pmu.h: document current memory layout for VPMU

[Edwin Török <edwin.torok@xxxxxxxxx>]

There are nested structs, unions, padding and flexible array members.
The interpretation of the flexible array members is all done with
pointer arithmetic, it is useful to visualize the actual memory layout.

The ascii-art drawing is compatible with ascii-art-to-unicode (aa2u) fro
m hackage.

No functional change.

Signed-off-by: Edwin Török <edwin.torok@xxxxxxxxx>
---
 xen/include/public/arch-x86/pmu.h | 63 +++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/xen/include/public/arch-x86/pmu.h 
b/xen/include/public/arch-x86/pmu.h
index d0a99268af..8be71a88ee 100644
--- a/xen/include/public/arch-x86/pmu.h
+++ b/xen/include/public/arch-x86/pmu.h
@@ -129,6 +129,69 @@ struct xen_pmu_arch {
 typedef struct xen_pmu_arch xen_pmu_arch_t;
 DEFINE_XEN_GUEST_HANDLE(xen_pmu_arch_t);
 
+/* Memory layout:
+*                .---------------------.
+*                | struct xen_pmu_data |
+* +==============+=====================+=======================+ <.
+* | vcpu_id                                                    |  |
+* +------------------------------------------------------------+  |
+* | pcpu_id                                                    |  |
+* +------------------------------------------------------------+  |
+* | domain_id                                                  |  |
+* +------------------------------------------------------------+  |
+* |##pad#######################################################|  |
+* +====+=+===+==================+==============================+  |
+* | pmu| | r | regs             |##pad#########################|  |
+* +----. +---. (xen or guest)   |##############################|  |
+* |      +======================+==============================+  |
+* |      | pmu_flags                                           |  |
+* |      +===+====================+============================+  |
+* |      | l | lapic_lvtpc        |############################|  |
+* |      +---. ###################|##pad#######################|  |
+* |      |     ###################|############################|  |
+* |      +===+=+=======+=====+====+====+=======+========+======+  |
+* |      | c | |       | amd |    |    | intel |         |#####|  |
+* |      +---+ |       .-----.    |    .-------.         |#####|  |
+* |      |     | counter          | fixed_counters       |#####|  | 
+* |      |     +------------------+----------------------+#####|  |
+* |      |     | ctrls            | arch_counters        |#####|  |
+* |      |     +=====+========+===+----------------------+#####|  |
+* |      |     |     | regs[] |  :| global_ctrl          |#####|  |
+* |      |     |     +--------.  :+----------------------+#####|  |
+* |      |     |struct           :| global_ovf_ctrl      |#####|  |
+* |      |     |xen_pmu_cntr_pair:+----------------------+#####|  |
+* |      |     |[counters]       :| global_status        |#####|  |
+* |      |     |                 :+----------------------+#####|  |
+* |      |     |                 :| fixed_ctrl           |#####|  |
+* |      |     |                 :+----------------------+#####|  |
+* |      |     |                 :| ds_area              |#####|  |
+* |      |     |                 :+----------------------+#####|  |
+* |      |     |                 :| pebs_enable          |#pad#|  |
+* |      |     |                 :+----------------------+#####|  |
+* |      |     |                 v| debugctl             |#####|  |
+* |      |     |##################+=======+========+=====+#####|  |
+* |      |     |##################|       | regs[] | :[0]|#####|  |
+* |      |     |##################|       +--------. :   |#####|  |
+* |      |     |##################| uint64_t         :   |#####|  |
+* |      |     |##################| [fixed_counters] :   |#####|  |
+* |      |     |##################|                  :   |#####|  |
+* |      |     |##################|                  :   |#####|  |
+* |      |     |##################| -----------------:   |#####|  |
+* |      |     |##################|  struct          :   |#####|  |
+* |      |     |##################| xen_pmu_cntr_pair:   |#####|  |
+* |      |     +==================+ [arch_counters]  :   +=====+  | 
+* |      |                        |                  :   |     |  |
+* |      |                        |                  v   |     |  |
+* |      |                        +======================+     |  |
+* |      +=====================================================+  |
+* +==========================+=================================+  |
+* |############################################################|  |
+* ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  :
+* ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  :
+* |############################################################|  | PAGE_SIZE
+* +=========+==================================================+ <.
+*/
+
 #endif /* __XEN_PUBLIC_ARCH_X86_PMU_H__ */
 /*
  * Local variables:
-- 
2.47.1