xen-devel.lists.xenproject.org archive mirror
 help / color / mirror / Atom feed
From: Jan Beulich <jbeulich@suse.com>
To: Luca Fancellu <luca.fancellu@arm.com>
Cc: bertrand.marquis@arm.com, wei.chen@arm.com,
	Andrew Cooper <andrew.cooper3@citrix.com>,
	George Dunlap <george.dunlap@citrix.com>,
	Ian Jackson <iwj@xenproject.org>, Julien Grall <julien@xen.org>,
	Stefano Stabellini <sstabellini@kernel.org>, Wei Liu <wl@xen.org>,
	xen-devel@lists.xenproject.org
Subject: Re: [PATCH v2 3/3] docs/doxygen: doxygen documentation for grant_table.h
Date: Mon, 19 Apr 2021 13:05:31 +0200	[thread overview]
Message-ID: <c8e1022f-abb0-56f3-db37-5cec4d01dead@suse.com> (raw)
In-Reply-To: <20210419091231.55684-4-luca.fancellu@arm.com>

On 19.04.2021 11:12, Luca Fancellu wrote:
> Modification to include/public/grant_table.h:
> 
> 1) Add doxygen tags to:
>  - Create Grant tables section
>  - include variables in the generated documentation
> 2) Add .rst file for grant table for Arm64

I'm missing some reasoning about at least some of the changes done
to grant_table.h. Looking at this and the earlier patches I also
couldn't spot any general outline of what is acceptable or even
necessary in such a header to be understood by doxygen. Without
this written down somewhere (or, if documented elsewhere, a
pointer provided to that doc) I'm afraid things might get screwed
up again later on.

> --- a/docs/hypercall-interfaces/arm64.rst
> +++ b/docs/hypercall-interfaces/arm64.rst
> @@ -8,6 +8,7 @@ Starting points
>  .. toctree::
>     :maxdepth: 2
>  
> +   arm64/grant_tables
>  
>  
>  Functions
> diff --git a/docs/hypercall-interfaces/arm64/grant_tables.rst b/docs/hypercall-interfaces/arm64/grant_tables.rst
> new file mode 100644
> index 0000000000..8955ec5812
> --- /dev/null
> +++ b/docs/hypercall-interfaces/arm64/grant_tables.rst
> @@ -0,0 +1,8 @@
> +.. SPDX-License-Identifier: CC-BY-4.0
> +
> +Grant Tables
> +============
> +
> +.. doxygengroup:: grant_table

Why is this Arm64-specific?

> @@ -73,20 +75,25 @@
>   *                           frame, or zero if none.
>   *  3. Write memory barrier (WMB).
>   *  4. Write ent->flags, inc. valid type.
> + * @endcode
>   *
>   * Invalidating an unused GTF_permit_access entry:
> + * @code
>   *  1. flags = ent->flags.
>   *  2. Observe that !(flags & (GTF_reading|GTF_writing)).
>   *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
>   *  NB. No need for WMB as reuse of entry is control-dependent on success of
>   *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
> + * @endcode
>   *
>   * Invalidating an in-use GTF_permit_access entry:
> + *
>   *  This cannot be done directly. Request assistance from the domain controller
>   *  which can set a timeout on the use of a grant entry and take necessary
>   *  action. (NB. This is not yet implemented!).
>   *
>   * Invalidating an unused GTF_accept_transfer entry:
> + * @code
>   *  1. flags = ent->flags.
>   *  2. Observe that !(flags & GTF_transfer_committed). [*]
>   *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
> @@ -97,47 +104,55 @@
>   *      transferred frame is written. It is safe for the guest to spin waiting
>   *      for this to occur (detect by observing GTF_transfer_completed in
>   *      ent->flags).
> + * @endcode
>   *
>   * Invalidating a committed GTF_accept_transfer entry:
>   *  1. Wait for (ent->flags & GTF_transfer_completed).
>   *
>   * Changing a GTF_permit_access from writable to read-only:
> + *
>   *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
>   *
>   * Changing a GTF_permit_access from read-only to writable:
> + *
>   *  Use SMP-safe bit-setting instruction.

For example - are the blank lines you add necessary or merely nice
to have in your personal opinion?

> - */
> -
> -/*
> - * Reference to a grant entry in a specified domain's grant table.
> - */
> -typedef uint32_t grant_ref_t;

Why does this get moved ...

> -
> -/*
> + *
>   * A grant table comprises a packed array of grant entries in one or more
>   * page frames shared between Xen and a guest.
> + *
>   * [XEN]: This field is written by Xen and read by the sharing guest.
> + *
>   * [GST]: This field is written by the guest and read by Xen.
> + *
> + * @addtogroup grant_table Grant Tables
> + * @{
>   */
>  
> -/*
> - * Version 1 of the grant table entry structure is maintained purely
> - * for backwards compatibility.  New guests should use version 2.
> +/**
> + * Reference to a grant entry in a specified domain's grant table.
>   */
> +typedef uint32_t grant_ref_t;

... here, past a comment unrelated to it?

> @@ -243,23 +258,27 @@ union grant_entry_v2 {
>       * In that case, the frame field has the same semantics as the
>       * field of the same name in the V1 entry structure.
>       */
> +    /** @cond skip anonymous struct/union for doxygen */
>      struct {
>          grant_entry_header_t hdr;
>          uint32_t pad0;
>          uint64_t frame;
>      } full_page;
> +    /** @endcond */
>  
>      /*
>       * If the grant type is GTF_grant_access and GTF_sub_page is set,
>       * @domid is allowed to access bytes [@page_off,@page_off+@length)
>       * in frame @frame.
>       */
> +    /** @cond skip anonymous struct/union for doxygen */
>      struct {
>          grant_entry_header_t hdr;
>          uint16_t page_off;
>          uint16_t length;
>          uint64_t frame;
>      } sub_page;
> +    /** @endcond */
>  
>      /*
>       * If the grant is GTF_transitive, @domid is allowed to use the
> @@ -270,12 +289,14 @@ union grant_entry_v2 {
>       * The current version of Xen does not allow transitive grants
>       * to be mapped.
>       */
> +    /** @cond skip anonymous struct/union for doxygen */
>      struct {
>          grant_entry_header_t hdr;
>          domid_t trans_domid;
>          uint16_t pad0;
>          grant_ref_t gref;
>      } transitive;
> +    /** @endcond */

While already better than the introduction of strange struct tags,
I'm still not convinced we want this extra clutter (sorry). Plus -
don't these additions mean the sub-structures then won't be
represented in the generated doc, rendering it (partly) useless?

> @@ -433,7 +454,12 @@ typedef struct gnttab_transfer gnttab_transfer_t;
>  DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t);
>  
>  
> -/*
> +#define _GNTCOPY_source_gref      (0)
> +#define GNTCOPY_source_gref       (1<<_GNTCOPY_source_gref)
> +#define _GNTCOPY_dest_gref        (1)
> +#define GNTCOPY_dest_gref         (1<<_GNTCOPY_dest_gref)
> +
> +/**
>   * GNTTABOP_copy: Hypervisor based copy
>   * source and destinations can be eithers MFNs or, for foreign domains,
>   * grant references. the foreign domain has to grant read/write access
> @@ -451,18 +477,15 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t);
>   * bytes to be copied.
>   */
>  
> -#define _GNTCOPY_source_gref      (0)
> -#define GNTCOPY_source_gref       (1<<_GNTCOPY_source_gref)
> -#define _GNTCOPY_dest_gref        (1)
> -#define GNTCOPY_dest_gref         (1<<_GNTCOPY_dest_gref)
> -
>  struct gnttab_copy {

Again the question - why the movement?

> @@ -579,17 +602,19 @@ struct gnttab_swap_grant_ref {
>  typedef struct gnttab_swap_grant_ref gnttab_swap_grant_ref_t;
>  DEFINE_XEN_GUEST_HANDLE(gnttab_swap_grant_ref_t);
>  
> -/*
> +/**
>   * Issue one or more cache maintenance operations on a portion of a
>   * page granted to the calling domain by a foreign domain.
>   */
>  struct gnttab_cache_flush {
> +    /** @cond skip anonymous struct/union for doxygen */
>      union {
>          uint64_t dev_bus_addr;
>          grant_ref_t ref;
>      } a;
> -    uint16_t offset; /* offset from start of grant */
> -    uint16_t length; /* size within the grant */
> +    /** @endcond */
> +    uint16_t offset; /**< offset from start of grant */
> +    uint16_t length; /**< size within the grant */

Skipping just part of a struct is perhaps even more confusing than
omitting it altogether.

Also, what's the significance of "/**<" ?

Jan


  reply	other threads:[~2021-04-19 11:05 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-04-19  9:12 [PATCH v2 0/3] Use Doxygen and sphinx for html documentation Luca Fancellu
2021-04-19  9:12 ` [PATCH v2 1/3] docs: add doxygen support " Luca Fancellu
2021-04-19  9:12 ` [PATCH v2 2/3] docs: hypercalls sphinx skeleton for generated html Luca Fancellu
2021-04-19  9:12 ` [PATCH v2 3/3] docs/doxygen: doxygen documentation for grant_table.h Luca Fancellu
2021-04-19 11:05   ` Jan Beulich [this message]
2021-04-20  8:46     ` Luca Fancellu
2021-04-20  9:14       ` Jan Beulich
2021-04-20  9:42         ` Luca Fancellu
2021-04-20 10:27           ` Jan Beulich
2021-04-22  7:39             ` Luca Fancellu
2021-04-22  8:06               ` Jan Beulich
2021-04-26 15:40                 ` Luca Fancellu

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=c8e1022f-abb0-56f3-db37-5cec4d01dead@suse.com \
    --to=jbeulich@suse.com \
    --cc=andrew.cooper3@citrix.com \
    --cc=bertrand.marquis@arm.com \
    --cc=george.dunlap@citrix.com \
    --cc=iwj@xenproject.org \
    --cc=julien@xen.org \
    --cc=luca.fancellu@arm.com \
    --cc=sstabellini@kernel.org \
    --cc=wei.chen@arm.com \
    --cc=wl@xen.org \
    --cc=xen-devel@lists.xenproject.org \
    --subject='Re: [PATCH v2 3/3] docs/doxygen: doxygen documentation for grant_table.h' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).