Re: [Qemu-ppc] [PATCH] docs: provide documentation on the POWER9 XIVE interrupt controller

[Cédric Le Goater]

On 5/14/19 11:17 AM, Peter Maydell wrote:
> On Tue, 14 May 2019 at 07:46, Cédric Le Goater <address@hidden> wrote:
>>
>> This documents the overall XIVE architecture and gives an overview of
>> the QEMU models. It also provides documentation on the 'info pic'
>> command.
>>
>> Signed-off-by: Cédric Le Goater <address@hidden>
>> ---
>>  docs/index.rst     |   1 +
>>  docs/ppc/index.rst |  13 ++
>>  docs/ppc/xive.rst  | 344 +++++++++++++++++++++++++++++++++++++++++++++
>>  MAINTAINERS        |   1 +
>>  4 files changed, 359 insertions(+)
>>  create mode 100644 docs/ppc/index.rst
>>  create mode 100644 docs/ppc/xive.rst
> 
> Hi -- it's great to see this documentation. Unfortunately,
> where you've put it doesn't match our intended layout for docs.

OK. I guess I need to split the file in multiple parts.
 
> Each subdirectory of docs/ becomes its own manual, and
> the intention is to eventually have five manuals
> (as sketched out in https://wiki.qemu.org/Features/Documentation):
>  * QEMU user mode emulation -- docs/user
>  * QEMU full-system emulation user's guide -- docs/system

Should we put the documentation of machine options under this directory ? 

>  * QEMU full-system emulation management and interoperability guide --
> docs/interop

There, I could put the 'info pic' documentation.

>  * QEMU full-system emulation guest hardware specifications  -- docs/specs

and there, the low level information on the XIVE controller.

>  * QEMU developer's guide -- docs/devel

and finally, there, some of the documentation on QEMU modeling.  

> We don't want to have a separate PPC-specific manual.

OK.

> Currently we only have interop and devel. I have on
> my todo list to try to sort out the others, including
> figuring out how to transition from our current set
> of texinfo-based manuals to this layout.
> 
> I'm not sure exactly where this document should live.
> From a quick scan it appears to be mixing together
> information aimed at several different audiences --
> the "Overview of the QEMU models for XIVE" part looks
> like information about QEMU internals which belongs
> in docs/devel, but some other parts seem to be user
> facing information which should go in one of the
> other manuals.

What is nice about the single file model is that you find all 
the information related to one topic in one place. 

Can manuals reference each another ? 

Thanks,

C.