| Message ID | 20200806234933.16448-8-sstabellini@kernel.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [01/14] kernel-doc: public/arch-arm.h | expand |
On 07.08.2020 01:49, Stefano Stabellini wrote: > From: Stefano Stabellini <stefano.stabellini@xilinx.com> > > Convert in-code comments to kernel-doc format wherever possible. > > Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com> > --- > xen/include/public/memory.h | 232 ++++++++++++++++++++++++------------ > 1 file changed, 155 insertions(+), 77 deletions(-) > > diff --git a/xen/include/public/memory.h b/xen/include/public/memory.h > index 21057ed78e..4c57ed213c 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 Nit: overly long line > + * - 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: > + * Take the opportunity and drop the stray blank line? > @@ -200,90 +236,115 @@ 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. */ > +/** > + * 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. > + */ > /* ` enum phys_map_space { */ Isn't this and ... > -#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. */ > +#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 > /* ` } */ ... this also something that wants converting? Jan
On Fri, 7 Aug 2020, Jan Beulich wrote: > On 07.08.2020 01:49, Stefano Stabellini wrote: > > From: Stefano Stabellini <stefano.stabellini@xilinx.com> > > > > Convert in-code comments to kernel-doc format wherever possible. > > > > Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com> > > --- > > xen/include/public/memory.h | 232 ++++++++++++++++++++++++------------ > > 1 file changed, 155 insertions(+), 77 deletions(-) > > > > diff --git a/xen/include/public/memory.h b/xen/include/public/memory.h > > index 21057ed78e..4c57ed213c 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 > > Nit: overly long line I'll fix > > + * - 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: > > + * > > Take the opportunity and drop the stray blank line? Sure > > @@ -200,90 +236,115 @@ 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. */ > > +/** > > + * 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. > > + */ > > /* ` enum phys_map_space { */ > > Isn't this and ... > > > -#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. */ > > +#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 > > /* ` } */ > > ... this also something that wants converting? For clarity, I take you are talking about these two enum-related comments: /* ` enum phys_map_space { */ [... various #defines ... ] /* ` } */ Is this something we want to convert to kernel-doc? I don't know. I couldn't see an obvious value in doing it, in the sense that it doesn't necessarely make things clearer. I took a second look at the header and the following would work: /** * DOC: Source mapping space. * * enum phys_map_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. * } */ Note the blank line after "enum phys_map_space {" is required. All in all I am in favor of *not* converting the enum comment to kernel-doc, but I'd be OK with it anyway.
On 07.08.2020 23:51, Stefano Stabellini wrote: > On Fri, 7 Aug 2020, Jan Beulich wrote: >> On 07.08.2020 01:49, Stefano Stabellini wrote: >>> From: Stefano Stabellini <stefano.stabellini@xilinx.com> >>> >>> Convert in-code comments to kernel-doc format wherever possible. >>> >>> Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com> >>> --- >>> xen/include/public/memory.h | 232 ++++++++++++++++++++++++------------ >>> 1 file changed, 155 insertions(+), 77 deletions(-) >>> >>> diff --git a/xen/include/public/memory.h b/xen/include/public/memory.h >>> index 21057ed78e..4c57ed213c 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 >> >> Nit: overly long line > > I'll fix > > >>> + * - 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: >>> + * >> >> Take the opportunity and drop the stray blank line? > > Sure > > >>> @@ -200,90 +236,115 @@ 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. */ >>> +/** >>> + * 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. >>> + */ >>> /* ` enum phys_map_space { */ >> >> Isn't this and ... >> >>> -#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. */ >>> +#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 >>> /* ` } */ >> >> ... this also something that wants converting? > > For clarity, I take you are talking about these two enum-related > comments: > > /* ` enum phys_map_space { */ > [... various #defines ... ] > /* ` } */ > > Is this something we want to convert to kernel-doc? I don't know. I > couldn't see an obvious value in doing it, in the sense that it doesn't > necessarely make things clearer. > > I took a second look at the header and the following would work: > > /** > * DOC: Source mapping space. > * > * enum phys_map_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. > * } > */ > > Note the blank line after "enum phys_map_space {" is required. > > > All in all I am in favor of *not* converting the enum comment to > kernel-doc, but I'd be OK with it anyway. Iirc the enum comments were added for documentation purposes. This to me means there are two options at this point: - retain them in a way that the new doc model consumes them, - drop them at the same time as adding the new doc comments. Their (presumed) value is that they identify #define-s which supposed to be enum-like without actually being able to use enums in the public headers (with some exceptions). Jan
On Mon, 17 Aug 2020, Jan Beulich wrote: > On 07.08.2020 23:51, Stefano Stabellini wrote: > > On Fri, 7 Aug 2020, Jan Beulich wrote: > >> On 07.08.2020 01:49, Stefano Stabellini wrote: > >>> From: Stefano Stabellini <stefano.stabellini@xilinx.com> > >>> > >>> Convert in-code comments to kernel-doc format wherever possible. > >>> > >>> Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com> > >>> --- > >>> xen/include/public/memory.h | 232 ++++++++++++++++++++++++------------ > >>> 1 file changed, 155 insertions(+), 77 deletions(-) > >>> > >>> diff --git a/xen/include/public/memory.h b/xen/include/public/memory.h > >>> index 21057ed78e..4c57ed213c 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 > >> > >> Nit: overly long line > > > > I'll fix > > > > > >>> + * - 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: > >>> + * > >> > >> Take the opportunity and drop the stray blank line? > > > > Sure > > > > > >>> @@ -200,90 +236,115 @@ 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. */ > >>> +/** > >>> + * 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. > >>> + */ > >>> /* ` enum phys_map_space { */ > >> > >> Isn't this and ... > >> > >>> -#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. */ > >>> +#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 > >>> /* ` } */ > >> > >> ... this also something that wants converting? > > > > For clarity, I take you are talking about these two enum-related > > comments: > > > > /* ` enum phys_map_space { */ > > [... various #defines ... ] > > /* ` } */ > > > > Is this something we want to convert to kernel-doc? I don't know. I > > couldn't see an obvious value in doing it, in the sense that it doesn't > > necessarely make things clearer. > > > > I took a second look at the header and the following would work: > > > > /** > > * DOC: Source mapping space. > > * > > * enum phys_map_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. > > * } > > */ > > > > Note the blank line after "enum phys_map_space {" is required. > > > > > > All in all I am in favor of *not* converting the enum comment to > > kernel-doc, but I'd be OK with it anyway. > > Iirc the enum comments were added for documentation purposes. This to > me means there are two options at this point: > - retain them in a way that the new doc model consumes them, > - drop them at the same time as adding the new doc comments. > > Their (presumed) value is that they identify #define-s which supposed > to be enum-like without actually being able to use enums in the public > headers (with some exceptions). I understand. Then, it doesn't look like we want to keep them in the code without converting them to kernel-doc. We could either: 1) remove them as part of this series 2) convert them to kernel-doc in the top comment as shown above I could do either, but my preference is 1) because I think it leads to clearer docs.
On 18.08.2020 00:56, Stefano Stabellini wrote: > On Mon, 17 Aug 2020, Jan Beulich wrote: >> On 07.08.2020 23:51, Stefano Stabellini wrote: >>> On Fri, 7 Aug 2020, Jan Beulich wrote: >>>> On 07.08.2020 01:49, Stefano Stabellini wrote: >>>>> @@ -200,90 +236,115 @@ 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. */ >>>>> +/** >>>>> + * 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. >>>>> + */ >>>>> /* ` enum phys_map_space { */ >>>> >>>> Isn't this and ... >>>> >>>>> -#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. */ >>>>> +#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 >>>>> /* ` } */ >>>> >>>> ... this also something that wants converting? >>> >>> For clarity, I take you are talking about these two enum-related >>> comments: >>> >>> /* ` enum phys_map_space { */ >>> [... various #defines ... ] >>> /* ` } */ >>> >>> Is this something we want to convert to kernel-doc? I don't know. I >>> couldn't see an obvious value in doing it, in the sense that it doesn't >>> necessarely make things clearer. >>> >>> I took a second look at the header and the following would work: >>> >>> /** >>> * DOC: Source mapping space. >>> * >>> * enum phys_map_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. >>> * } >>> */ >>> >>> Note the blank line after "enum phys_map_space {" is required. >>> >>> >>> All in all I am in favor of *not* converting the enum comment to >>> kernel-doc, but I'd be OK with it anyway. >> >> Iirc the enum comments were added for documentation purposes. This to >> me means there are two options at this point: >> - retain them in a way that the new doc model consumes them, >> - drop them at the same time as adding the new doc comments. >> >> Their (presumed) value is that they identify #define-s which supposed >> to be enum-like without actually being able to use enums in the public >> headers (with some exceptions). > > I understand. Then, it doesn't look like we want to keep them in the code > without converting them to kernel-doc. We could either: > > 1) remove them as part of this series > 2) convert them to kernel-doc in the top comment as shown above > > I could do either, but my preference is 1) because I think it leads to > clearer docs. While I'd slightly prefer 2, I'll be okay with your choice. Jan
On Tue, 18 Aug 2020, Jan Beulich wrote: > On 18.08.2020 00:56, Stefano Stabellini wrote: > > On Mon, 17 Aug 2020, Jan Beulich wrote: > >> On 07.08.2020 23:51, Stefano Stabellini wrote: > >>> On Fri, 7 Aug 2020, Jan Beulich wrote: > >>>> On 07.08.2020 01:49, Stefano Stabellini wrote: > >>>>> @@ -200,90 +236,115 @@ 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. */ > >>>>> +/** > >>>>> + * 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. > >>>>> + */ > >>>>> /* ` enum phys_map_space { */ > >>>> > >>>> Isn't this and ... > >>>> > >>>>> -#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. */ > >>>>> +#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 > >>>>> /* ` } */ > >>>> > >>>> ... this also something that wants converting? > >>> > >>> For clarity, I take you are talking about these two enum-related > >>> comments: > >>> > >>> /* ` enum phys_map_space { */ > >>> [... various #defines ... ] > >>> /* ` } */ > >>> > >>> Is this something we want to convert to kernel-doc? I don't know. I > >>> couldn't see an obvious value in doing it, in the sense that it doesn't > >>> necessarely make things clearer. > >>> > >>> I took a second look at the header and the following would work: > >>> > >>> /** > >>> * DOC: Source mapping space. > >>> * > >>> * enum phys_map_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. > >>> * } > >>> */ > >>> > >>> Note the blank line after "enum phys_map_space {" is required. > >>> > >>> > >>> All in all I am in favor of *not* converting the enum comment to > >>> kernel-doc, but I'd be OK with it anyway. > >> > >> Iirc the enum comments were added for documentation purposes. This to > >> me means there are two options at this point: > >> - retain them in a way that the new doc model consumes them, > >> - drop them at the same time as adding the new doc comments. > >> > >> Their (presumed) value is that they identify #define-s which supposed > >> to be enum-like without actually being able to use enums in the public > >> headers (with some exceptions). > > > > I understand. Then, it doesn't look like we want to keep them in the code > > without converting them to kernel-doc. We could either: > > > > 1) remove them as part of this series > > 2) convert them to kernel-doc in the top comment as shown above > > > > I could do either, but my preference is 1) because I think it leads to > > clearer docs. > > While I'd slightly prefer 2, I'll be okay with your choice. OK. I removed the enum comments.
diff --git a/xen/include/public/memory.h b/xen/include/public/memory.h index 21057ed78e..4c57ed213c 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,115 @@ 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. */ +/** + * 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. + */ /* ` 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. */ +#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 +357,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 +378,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 +407,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 +418,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 +435,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;