Re: [Xen-devel] [PATCH] xen/arm: io: add function swap_mmio_handler()

[Julien Grall <julien.grall@arm.com>]

HiStefano,

On 25/06/2019 00:59, Stefano Stabellini wrote:
> On Mon, 24 Jun 2019, Julien Grall wrote:
>> Hi,
>>
>> On 6/24/19 9:17 PM, Stefano Stabellini wrote:
>>> On Mon, 24 Jun 2019, Julien Grall wrote:
>>>> Hi Stefano,
>>>>
>>>> On 24/06/2019 19:27, Stefano Stabellini wrote:
>>>>> On Mon, 24 Jun 2019, Stefano Stabellini wrote:
>>>>>> On Thu, 13 Jun 2019, chenbaodong wrote:
>>>>> Let me add that if you prefer to document one of the other interfaces
>>>>> listed above in my email, you are welcome to pick another one. For
>>>>> example, we are also missing a doc about the DomU memory map, listing
>>>>> all memory regions with addresses and sizes, both MMIO and normal
>>>>> memory. For that, most of the information is:
>>>>>
>>>>> xen/include/public/arch-arm.h
>>>>>
>>>>> A well written in-code comment in arch-arm.h would be OK, or also a
>>>>> document under docs/misc/arm.
>>>>
>>>> Please no duplication, it is already quite hard to maintain one place.
>>>> Instead, we should document all the headers in a documented format that
>>>> can be extracted automatically.
>>>
>>> As we have no such thing today (as far as I am aware), please make a
>>> proposal with a bit more details, otherwise I don't think Baodong will
>>> be able to take the next step.
>>
>> I don't have a concrete proposal so far. Except that documentation outside of
>> the headers is a no-go from my side. The goal of documenting within the
>> headers rather than outside is you also help the developer of guest OS.
>>
>> A few weeks ago Ian Jackson pointed to docs/xen-headers for a potential
>> syntax. Sadly, there are no documentation of the script so far. I haven't had
>> time to look it so far.
> 
> In that case, I'd suggest for Baodong to either pick the device tree
> documentation item (assuming you are OK with that one being under
> docs/misc/arm) or just write a normal in-code comment in arch-arm.h for
> the domU memory map not worrying about the format of the in-code comment
> for now.

I don't think we have specific place for documenting device-tree so 
docs/misc/arm would be suitable.

Regarding in-code comment in arch-arm.h This will always be an improvement to 
what we have. However, it would be good if someone take an action to formalize 
the documentation format.

Cheers,

-- 
Julien Grall

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel