diff mbox series

[08/14] kernel-doc: public/memory.h

Message ID 20200806234933.16448-8-sstabellini@kernel.org
State New
Headers show
Series [01/14] kernel-doc: public/arch-arm.h | expand

Commit Message

Stefano Stabellini Aug. 6, 2020, 11:49 p.m. UTC
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(-)

Comments

Jan Beulich Aug. 7, 2020, 1:07 p.m. UTC | #1
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
Stefano Stabellini Aug. 7, 2020, 9:51 p.m. UTC | #2
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.
Jan Beulich Aug. 17, 2020, 3:32 p.m. UTC | #3
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
Stefano Stabellini Aug. 17, 2020, 10:56 p.m. UTC | #4
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.
Jan Beulich Aug. 18, 2020, 8:05 a.m. UTC | #5
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
Stefano Stabellini Aug. 20, 2020, 11:20 p.m. UTC | #6
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 mbox series

Patch

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;