Mailing List Archive

Convert in-code comments to kernel-doc format wherever possible.

Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
---
Changes in v2:
- remove "enum" comments
- fix line too long
- remove stray blank line
---
xen/include/public/memory.h | 236 ++++++++++++++++++++++++------------
1 file changed, 156 insertions(+), 80 deletions(-)

diff --git a/xen/include/public/memory.h b/xen/include/public/memory.h
index 21d483298e..3a8f668f5f 100644
--- a/xen/include/public/memory.h
+++ b/xen/include/public/memory.h
@@ -30,7 +30,9 @@
#include "xen.h"
#include "physdev.h"

-/*
+/**
+ * DOC: XENMEM_increase_reservation and XENMEM_decrease_reservation
+ *
* Increase or decrease the specified domain's memory reservation. Returns the
* number of extents successfully allocated or freed.
* arg == addr of struct xen_memory_reservation.
@@ -40,29 +42,37 @@
#define XENMEM_populate_physmap 6

#if __XEN_INTERFACE_VERSION__ >= 0x00030209
-/*
- * Maximum # bits addressable by the user of the allocated region (e.g., I/O
- * devices often have a 32-bit limitation even in 64-bit systems). If zero
- * then the user has no addressing restriction. This field is not used by
- * XENMEM_decrease_reservation.
+/**
+ * DOC: XENMEMF_*
+ *
+ * - XENMEMF_address_bits, XENMEMF_get_address_bits:
+ * Maximum # bits addressable by the user of the allocated region
+ * (e.g., I/O devices often have a 32-bit limitation even in 64-bit
+ * systems). If zero then the user has no addressing restriction. This
+ * field is not used by XENMEM_decrease_reservation.
+ * - XENMEMF_node, XENMEMF_get_node: NUMA node to allocate from
+ * - XENMEMF_populate_on_demand: Flag to populate physmap with populate-on-demand entries
+ * - XENMEMF_exact_node_request, XENMEMF_exact_node: Flag to request allocation
+ * only from the node specified
+ * - XENMEMF_vnode: Flag to indicate the node specified is virtual node
*/
#define XENMEMF_address_bits(x) (x)
#define XENMEMF_get_address_bits(x) ((x) & 0xffu)
-/* NUMA node to allocate from. */
#define XENMEMF_node(x) (((x) + 1) << 8)
#define XENMEMF_get_node(x) ((((x) >> 8) - 1) & 0xffu)
-/* Flag to populate physmap with populate-on-demand entries */
#define XENMEMF_populate_on_demand (1<<16)
-/* Flag to request allocation only from the node specified */
#define XENMEMF_exact_node_request (1<<17)
#define XENMEMF_exact_node(n) (XENMEMF_node(n) | XENMEMF_exact_node_request)
-/* Flag to indicate the node specified is virtual node */
#define XENMEMF_vnode (1<<18)
#endif

+/**
+ * struct xen_memory_reservation
+ */
struct xen_memory_reservation {
-
- /*
+ /**
+ * @extent_start:
+ *
* XENMEM_increase_reservation:
* OUT: MFN (*not* GMFN) bases of extents that were allocated
* XENMEM_decrease_reservation:
@@ -76,18 +86,20 @@ struct xen_memory_reservation {
*/
XEN_GUEST_HANDLE(xen_pfn_t) extent_start;

- /* Number of extents, and size/alignment of each (2^extent_order pages). */
+ /** @nr_extents: Number of extents, and size/alignment of each (2^extent_order pages). */
xen_ulong_t nr_extents;
unsigned int extent_order;

#if __XEN_INTERFACE_VERSION__ >= 0x00030209
- /* XENMEMF flags. */
+ /** @mem_flags: XENMEMF flags. */
unsigned int mem_flags;
#else
unsigned int address_bits;
#endif

- /*
+ /**
+ * @domid:
+ *
* Domain whose reservation is being changed.
* Unprivileged domains can specify only DOMID_SELF.
*/
@@ -96,7 +108,10 @@ struct xen_memory_reservation {
typedef struct xen_memory_reservation xen_memory_reservation_t;
DEFINE_XEN_GUEST_HANDLE(xen_memory_reservation_t);

-/*
+#define XENMEM_exchange 11
+/**
+ * struct xen_memory_exchange - XENMEM_exchange
+ *
* An atomic exchange of memory pages. If return code is zero then
* @out.extent_list provides GMFNs of the newly-allocated memory.
* Returns zero on complete success, otherwise a negative error code.
@@ -105,15 +120,18 @@ DEFINE_XEN_GUEST_HANDLE(xen_memory_reservation_t);
*
* Note that only PV guests can use this operation.
*/
-#define XENMEM_exchange 11
struct xen_memory_exchange {
- /*
+ /**
+ * @in:
+ *
* [IN] Details of memory extents to be exchanged (GMFN bases).
* Note that @in.address_bits is ignored and unused.
*/
struct xen_memory_reservation in;

- /*
+ /**
+ * @out:
+ *
* [IN/OUT] Details of new memory extents.
* We require that:
* 1. @in.domid == @out.domid
@@ -125,7 +143,9 @@ struct xen_memory_exchange {
*/
struct xen_memory_reservation out;

- /*
+ /**
+ * @nr_exchanged:
+ *
* [OUT] Number of input extents that were successfully exchanged:
* 1. The first @nr_exchanged input extents were successfully
* deallocated.
@@ -141,14 +161,18 @@ struct xen_memory_exchange {
typedef struct xen_memory_exchange xen_memory_exchange_t;
DEFINE_XEN_GUEST_HANDLE(xen_memory_exchange_t);

-/*
+/**
+ * DOC: XENMEM_maximum_ram_page
+ *
* Returns the maximum machine frame number of mapped RAM in this system.
* This command always succeeds (it never returns an error code).
* arg == NULL.
*/
#define XENMEM_maximum_ram_page 2

-/*
+/**
+ * DOC: XENMEM_current_reservation and XENMEM_maximum_reservation
+ *
* Returns the current or maximum memory reservation, in pages, of the
* specified domain (may be DOMID_SELF). Returns -ve errcode on failure.
* arg == addr of domid_t.
@@ -156,33 +180,43 @@ DEFINE_XEN_GUEST_HANDLE(xen_memory_exchange_t);
#define XENMEM_current_reservation 3
#define XENMEM_maximum_reservation 4

-/*
+/**
+ * DOC: XENMEM_maximum_gpfn
+ *
* Returns the maximum GPFN in use by the guest, or -ve errcode on failure.
*/
#define XENMEM_maximum_gpfn 14

-/*
+#define XENMEM_machphys_mfn_list 5
+/**
+ * struct xen_machphys_mfn_list - XENMEM_machphys_mfn_list
+ *
* Returns a list of MFN bases of 2MB extents comprising the machine_to_phys
* mapping table. Architectures which do not have a m2p table do not implement
* this command.
* arg == addr of xen_machphys_mfn_list_t.
*/
-#define XENMEM_machphys_mfn_list 5
struct xen_machphys_mfn_list {
- /*
+ /**
+ * @max_extents:
+ *
* Size of the 'extent_start' array. Fewer entries will be filled if the
* machphys table is smaller than max_extents * 2MB.
*/
unsigned int max_extents;

- /*
+ /**
+ * @extent_start:
+ *
* Pointer to buffer to fill with list of extent starts. If there are
* any large discontiguities in the machine address space, 2MB gaps in
* the machphys table will be represented by an MFN base of zero.
*/
XEN_GUEST_HANDLE(xen_pfn_t) extent_start;

- /*
+ /**
+ * @nr_extents:
+ *
* Number of extents written to the above array. This will be smaller
* than 'max_extents' if the machphys table is smaller than max_e * 2MB.
*/
@@ -191,7 +225,9 @@ struct xen_machphys_mfn_list {
typedef struct xen_machphys_mfn_list xen_machphys_mfn_list_t;
DEFINE_XEN_GUEST_HANDLE(xen_machphys_mfn_list_t);

-/*
+/**
+ * DOC: XENMEM_machphys_compat_mfn_list
+ *
* For a compat caller, this is identical to XENMEM_machphys_mfn_list.
*
* For a non compat caller, this functions similarly to
@@ -200,90 +236,113 @@ DEFINE_XEN_GUEST_HANDLE(xen_machphys_mfn_list_t);
*/
#define XENMEM_machphys_compat_mfn_list 25

-/*
+#define XENMEM_machphys_mapping 12
+/**
+ * struct xen_machphys_mapping - XENMEM_machphys_mapping
+ *
* Returns the location in virtual address space of the machine_to_phys
* mapping table. Architectures which do not have a m2p table, or which do not
* map it by default into guest address space, do not implement this command.
* arg == addr of xen_machphys_mapping_t.
*/
-#define XENMEM_machphys_mapping 12
struct xen_machphys_mapping {
+ /** @v_start: Start virtual address */
xen_ulong_t v_start, v_end; /* Start and end virtual addresses. */
- xen_ulong_t max_mfn; /* Maximum MFN that can be looked up. */
+ /** @v_end: End virtual addresses */
+ xen_ulong_t v_end;
+ /** @max_mfn: Maximum MFN that can be looked up */
+ xen_ulong_t max_mfn;
};
typedef struct xen_machphys_mapping xen_machphys_mapping_t;
DEFINE_XEN_GUEST_HANDLE(xen_machphys_mapping_t);

-/* Source mapping space. */
-/* ` enum phys_map_space { */
-#define XENMAPSPACE_shared_info 0 /* shared info page */
-#define XENMAPSPACE_grant_table 1 /* grant table page */
-#define XENMAPSPACE_gmfn 2 /* GMFN */
-#define XENMAPSPACE_gmfn_range 3 /* GMFN range, XENMEM_add_to_physmap only. */
-#define XENMAPSPACE_gmfn_foreign 4 /* GMFN from another dom,
- * XENMEM_add_to_physmap_batch only. */
-#define XENMAPSPACE_dev_mmio 5 /* device mmio region
- ARM only; the region is mapped in
- Stage-2 using the Normal Memory
- Inner/Outer Write-Back Cacheable
- memory attribute. */
-/* ` } */
+/**
+ * DOC: Source mapping space.
+ *
+ * - XENMAPSPACE_shared_info: shared info page
+ * - XENMAPSPACE_grant_table: grant table page
+ * - XENMAPSPACE_gmfn: GMFN
+ * - XENMAPSPACE_gmfn_range: GMFN range, XENMEM_add_to_physmap only.
+ * - XENMAPSPACE_gmfn_foreign: GMFN from another dom,
+ * XENMEM_add_to_physmap_batch only.
+ * - XENMAPSPACE_dev_mmio: device mmio region ARM only; the region is mapped
+ * in Stage-2 using the Normal MemoryInner/Outer
+ * Write-Back Cacheable memory attribute.
+ */
+#define XENMAPSPACE_shared_info 0
+#define XENMAPSPACE_grant_table 1
+#define XENMAPSPACE_gmfn 2
+#define XENMAPSPACE_gmfn_range 3
+#define XENMAPSPACE_gmfn_foreign 4
+#define XENMAPSPACE_dev_mmio 5

-/*
+#define XENMEM_add_to_physmap 7
+/**
+ * struct xen_add_to_physmap - XENMEM_add_to_physmap
+ *
* Sets the GPFN at which a particular page appears in the specified guest's
* physical address space (translated guests only).
* arg == addr of xen_add_to_physmap_t.
*/
-#define XENMEM_add_to_physmap 7
struct xen_add_to_physmap {
- /* Which domain to change the mapping for. */
+ /** @domid: Which domain to change the mapping for. */
domid_t domid;

- /* Number of pages to go through for gmfn_range */
+ /** @size: Number of pages to go through for gmfn_range */
uint16_t size;

- unsigned int space; /* => enum phys_map_space */
+ /** @space: enum phys_map_space */
+ unsigned int space;

#define XENMAPIDX_grant_table_status 0x80000000

- /* Index into space being mapped. */
+ /** @idx: Index into space being mapped. */
xen_ulong_t idx;

- /* GPFN in domid where the source mapping page should appear. */
+ /** @gpfn: GPFN in domid where the source mapping page should appear. */
xen_pfn_t gpfn;
};
typedef struct xen_add_to_physmap xen_add_to_physmap_t;
DEFINE_XEN_GUEST_HANDLE(xen_add_to_physmap_t);

-/* A batched version of add_to_physmap. */
#define XENMEM_add_to_physmap_batch 23
+/**
+ * struct xen_add_to_physmap_batch - XENMEM_add_to_physmap_batch
+ *
+ * A batched version of add_to_physmap.
+ */
struct xen_add_to_physmap_batch {
- /* IN */
- /* Which domain to change the mapping for. */
+ /** @domid: IN, which domain to change the mapping for */
domid_t domid;
- uint16_t space; /* => enum phys_map_space */
+ /** @space: IN, enum phys_map_space */
+ uint16_t space;

- /* Number of pages to go through */
+ /** @size: IN, Number of pages to go through */
uint16_t size;

#if __XEN_INTERFACE_VERSION__ < 0x00040700
- domid_t foreign_domid; /* IFF gmfn_foreign. Should be 0 for other spaces. */
+ /** @foreign_domid: IN, iff gmfn_foreign. Should be 0 for other spaces. */
+ domid_t foreign_domid;
#else
+ /**
+ * @u: IN
+ *
+ * - u.foreign_domid: gmfn_foreign
+ * - u.res0: All the other spaces. Should be 0
+ */
union xen_add_to_physmap_batch_extra {
- domid_t foreign_domid; /* gmfn_foreign */
- uint16_t res0; /* All the other spaces. Should be 0 */
+ domid_t foreign_domid;
+ uint16_t res0;
} u;
#endif

- /* Indexes into space being mapped. */
+ /** @idxs: IN, Indexes into space being mapped. */
XEN_GUEST_HANDLE(xen_ulong_t) idxs;

- /* GPFN in domid where the source mapping page should appear. */
+ /** @gpfns: IN, GPFN in domid where the source mapping page should appear. */
XEN_GUEST_HANDLE(xen_pfn_t) gpfns;

- /* OUT */
-
- /* Per index error code. */
+ /** @errs: OUT, Per index error code. */
XEN_GUEST_HANDLE(int) errs;
};
typedef struct xen_add_to_physmap_batch xen_add_to_physmap_batch_t;
@@ -296,17 +355,19 @@ typedef struct xen_add_to_physmap_batch xen_add_to_physmap_range_t;
DEFINE_XEN_GUEST_HANDLE(xen_add_to_physmap_range_t);
#endif

-/*
+#define XENMEM_remove_from_physmap 15
+/**
+ * struct xen_remove_from_physmap - XENMEM_remove_from_physmap
+ *
* Unmaps the page appearing at a particular GPFN from the specified guest's
* physical address space (translated guests only).
* arg == addr of xen_remove_from_physmap_t.
*/
-#define XENMEM_remove_from_physmap 15
struct xen_remove_from_physmap {
- /* Which domain to change the mapping for. */
+ /** @domid: Which domain to change the mapping for. */
domid_t domid;

- /* GPFN of the current mapping of the page. */
+ /** @gpfn: GPFN of the current mapping of the page. */
xen_pfn_t gpfn;
};
typedef struct xen_remove_from_physmap xen_remove_from_physmap_t;
@@ -315,21 +376,27 @@ DEFINE_XEN_GUEST_HANDLE(xen_remove_from_physmap_t);
/*** REMOVED ***/
/*#define XENMEM_translate_gpfn_list 8*/

-/*
+#define XENMEM_memory_map 9
+/**
+ * struct xen_memory_map - XENMEM_memory_map
+ *
* Returns the pseudo-physical memory map as it was when the domain
* was started (specified by XENMEM_set_memory_map).
* arg == addr of xen_memory_map_t.
*/
-#define XENMEM_memory_map 9
struct xen_memory_map {
- /*
+ /**
+ * @nr_entries:
+ *
* On call the number of entries which can be stored in buffer. On
* return the number of entries which have been stored in
* buffer.
*/
unsigned int nr_entries;

- /*
+ /**
+ * @buffer:
+ *
* Entries in the buffer are in the same format as returned by the
* BIOS INT 0x15 EAX=0xE820 call.
*/
@@ -338,7 +405,9 @@ struct xen_memory_map {
typedef struct xen_memory_map xen_memory_map_t;
DEFINE_XEN_GUEST_HANDLE(xen_memory_map_t);

-/*
+/**
+ * DOC: XENMEM_machine_memory_map
+ *
* Returns the real physical memory map. Passes the same structure as
* XENMEM_memory_map.
* Specifying buffer as NULL will return the number of entries required
@@ -347,12 +416,14 @@ DEFINE_XEN_GUEST_HANDLE(xen_memory_map_t);
*/
#define XENMEM_machine_memory_map 10

-/*
+#define XENMEM_set_memory_map 13
+/**
+ * struct xen_foreign_memory_map - XENMEM_set_memory_map
+ *
* Set the pseudo-physical memory map of a domain, as returned by
* XENMEM_memory_map.
* arg == addr of xen_foreign_memory_map_t.
*/
-#define XENMEM_set_memory_map 13
struct xen_foreign_memory_map {
domid_t domid;
struct xen_memory_map map;
@@ -362,14 +433,19 @@ DEFINE_XEN_GUEST_HANDLE(xen_foreign_memory_map_t);

#define XENMEM_set_pod_target 16
#define XENMEM_get_pod_target 17
+/**
+ * struct xen_pod_target - XENMEM_set_pod_target and XENMEM_get_pod_target
+ */
struct xen_pod_target {
- /* IN */
+ /** @target_pages: IN */
uint64_t target_pages;
- /* OUT */
+ /** @tot_pages: OUT */
uint64_t tot_pages;
+ /** @pod_cache_pages: OUT */
uint64_t pod_cache_pages;
+ /** @pod_entries: OUT */
uint64_t pod_entries;
- /* IN */
+ /** @domid: IN */
domid_t domid;
};
typedef struct xen_pod_target xen_pod_target_t;
--
2.17.1