Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

[Luca Fancellu <luca.fancellu@arm.com>]

> On 27 Apr 2021, at 14:57, Jan Beulich <jbeulich@suse.com> wrote:
> 
> On 26.04.2021 17:37, Luca Fancellu wrote:
>> --- 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
> 
> I continue to object to this giving the impression that grant tables
> are something Arm64 specific.

Hi Jan,

I’ll put it in a folder named “common"

> 
>> @@ -66,6 +67,7 @@
>>  *     compiler barrier will still be required.
>>  *
>>  * Introducing a valid entry into the grant table:
>> + * @code
>>  *  1. Write ent->domid.
>>  *  2. Write ent->frame:
>>  *      GTF_permit_access:   Frame to which access is permitted.
>> @@ -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).
> 
> Since neither in the cover letter nor in the description here I could
> spot a link to the resulting generated doc, I wonder what the
> inconsistencies above are about: You add @code/@endcode (and no blank
> lines) to parts of what's being described, and _instead_ a blank line
> to another part. I think the goal should be that not only the
> generated doc ends up looking "nice", but that the source code also
> remains consistent. Otherwise, someone like me coming across this
> later on might easily conclude that there was a @code/@endcode pair
> missed.

Yes I’ll explain better in the commit message, that part and other parts are
enclosed by @code/@endcode because they are formatted using spaces.
If the block is not enclosed the spaces are missing in the html page resulting
In a mess.
If you can suggest an alias for the @code/@endcode command, I can create
it so that the user looking the source code can understand better what's going on.
An example: @keepformat/@endkeepformat OR @keepindent/@endkeepindent

Here a link to the documentation right now: 
https://luca.fancellu.gitlab.io/xen-docs/hypercall-interfaces/arm64/grant_tables.html

> 
>> @@ -97,18 +104,23 @@
>>  *      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).
>>  *
> 
> Why did this not also get enclosed by @code/@endcode?

In this case there are no spaces that contributes to the indentation.

> 
>>  * 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.
> 
> And these two?

These two lines makes the resulting html page looks better, the source code however
seems not too impacted by the change though.

> 
>> + * @addtogroup grant_table Grant Tables
> 
> And no blank (comment) line ahead of this?

Here there is no need for a blank line in the comment, but if in your opinion the source
code will look better I can add it

> 
>> @@ -120,24 +132,26 @@ typedef uint32_t grant_ref_t;
>>  * [GST]: This field is written by the guest and read by Xen.
>>  */
>> 
>> -/*
>> - * Version 1 of the grant table entry structure is maintained purely
>> - * for backwards compatibility.  New guests should use version 2.
>> - */
>> #if __XEN_INTERFACE_VERSION__ < 0x0003020a
>> #define grant_entry_v1 grant_entry
>> #define grant_entry_v1_t grant_entry_t
>> #endif
>> +/**
>> + * Version 1 of the grant table entry structure is maintained purely
>> + * for backwards compatibility.  New guests should use version 2.
>> + */
> 
> In case I didn't say so already before - I think this would be a good
> opportunity to drop the comment pointing at v2. With v2 optionally
> unavailable altogether, this can't possibly be a generally valid
> course of action.

Could you explain me better that? Do you want to get rid of this comment?

/**
* Version 1 of the grant table entry structure is maintained purely
* for backwards compatibility.  New guests should use version 2.
*/

In this case I don’t think this commit is the right place to do that, I can just
put it back where it was so that the documentation simply doesn’t show that.

> 
>> @@ -451,11 +465,6 @@ 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 {
>>     /* IN parameters. */
>>     struct gnttab_copy_ptr {
>> @@ -471,6 +480,12 @@ struct gnttab_copy {
>>     /* OUT parameters. */
>>     int16_t       status;
>> };
>> +
>> +#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)
> 
> I guess I didn't express myself precisely enough: I think these
> would better live _immediately_ next to the field that uses them.

Ok I didn’t get that, I’ll put them right next to the field

Cheers,
Luca

> 
> Jan