Re: [PATCH] xen/public: move xenstore related doc into 9pfs.h

[Jan Beulich <jbeulich@xxxxxxxx>]

On 30.01.2023 08:46, Juergen Gross wrote:
> On 30.01.23 08:36, Jan Beulich wrote:
>> On 30.01.2023 07:37, Juergen Gross wrote:
>>> The Xenstore related documentation is currently to be found in
>>> docs/misc/9pfs.pandoc, instead of the related header file
>>> xen/include/public/io/9pfs.h like for most other paravirtualized
>>> device protocols.
>>>
>>> There is a comment in the header pointing at the document, but the
>>> given file name is wrong. Additionally such headers are meant to be
>>> copied into consuming projects (Linux kernel, qemu, etc.), so pointing
>>> at a doc file in the Xen git repository isn't really helpful for the
>>> consumers of the header.
>>>
>>> This situation is far from ideal, which is already being proved by the
>>> fact that neither qemu nor the Linux kernel are implementing the
>>> device attach/detach protocol correctly. Additionally the documented
>>> Xenstore entries are not matching the reality, as the "tag" Xenstore
>>> entry is on the frontend side, not on the backend one.
>>>
>>> Change that by moving the Xenstore related 9pfs documentation from
>>> docs/misc/9pfs.pandoc into xen/include/public/io/9pfs.h while fixing
>>> the wrong Xenstore entry detail.
>>>
>>> Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
>>> ---
>>>   docs/misc/9pfs.pandoc        | 151 --------------------------------
>>>   xen/include/public/io/9pfs.h | 165 ++++++++++++++++++++++++++++++++++-
>>>   2 files changed, 164 insertions(+), 152 deletions(-)
>>>
>>> diff --git a/docs/misc/9pfs.pandoc b/docs/misc/9pfs.pandoc
>>> index b034fb5fa6..00f6817a01 100644
>>> --- a/docs/misc/9pfs.pandoc
>>> +++ b/docs/misc/9pfs.pandoc
>>> @@ -59,157 +59,6 @@ This document does not cover the 9pfs client/server 
>>> design or
>>>   implementation, only the transport for it.
>>>   
>>>   
>>> -## Xenstore
>>
>> Maybe leave a reference here now pointing at the public header?
> 
> Okay, Would you be fine with:
> 
>    ## Configuration
> 
>    The frontend and backend are configured via Xenstore. Have a look at
>    [header] for the detailed Xenstore entries and the connection protocol.

Sure. (Personally I'd use "See [header] ...", but as so often a native speaker
might actually point out that one wouldn't word it like this.)

Jan