Re: [PATCH v2 00/10] Add Allwinner H3 SoC and Orange Pi PC Machine

[Philippe Mathieu-Daudé]

Hi Niek,

On 1/2/20 8:52 PM, Niek Linnenbank wrote:
> Hi Philippe,
>
> I'm almost ready to send out v3 here.
>
> Now for documentation I'm not sure yet what to do:
>
> 1) Where should I place board documentation?
>      For example, the information that I wrote on the cover letter with 
> instructions on how to get the board up and running,
>      some description of the design, where to find more inforformation, 
> datasheet sources, etc. I don't yet see any documentation

We usually refer the datasheet in the implementation header, see:

$ git grep -F .pdf hw/ | wc -l
62

You can cite the datasheet globally in hw/arm/allwinner-h3.c, and then 
the particular chapters or source files in the other hw/*/allwinner-* files.

>     for the other boards in the source. In my opinion, it is important 
> to keep that information somewhere, such that also in the future
>     the boards can still be properly maintained. Can I / shall I place a 
> new file like ./docs/hw/arm/orangepi.txt for that?

See docs/microvm.rst which is a recent example of machine documentation,
the obvious name is docs/orangepi.rst.

Maybe refer to this file in hw/arm/orangepi.c header for completeness.

>   2) Is is allowed / encouraged to provide Doxygen-style comments in the 
> header files in include/hw/*?
>     I see that some of the API's have that, but the boards and devices 
> mostly are free of Doxygen-style comments.
>     It takes some work, but I think it can really help to give more 
> insight / background info on how things are working
>     for the devices and boards. But if it's not preferred for QEMU, I'm 
> fine with that as well.

Documentation is certainly welcome!

There are 2 different schools over the codebase, one that document the 
declarations, and another that documents the implementation/definition.

I personally prefer to document the headers, which is where I look when 
I want to consume an API.
The implementation school says this can lead to documentation getting 
outdated.

So if you are willing to document, I'd suggest to document your 
include/hw/ files.

Happy new year!

Phil.

> On Mon, Dec 30, 2019 at 9:10 PM Niek Linnenbank 
> <address@hidden <mailto:address@hidden>> wrote:
>
>
>
>     On Mon, Dec 30, 2019 at 3:56 PM Philippe Mathieu-Daudé
>     <address@hidden <mailto:address@hidden>> wrote:
>
>         On 12/30/19 12:28 PM, Niek Linnenbank wrote:
>          > Hi,
>          >
>          > Here a short status report of this patch series.
>
>         Good idea!
>
>          >
>          > For V3 update I already prepared the following:
>          >   - reworked all review comments from Philippe, except:
>          >     - patch#8: question for the SID, whether command-line
>         override is
>          > required (and how is the best way for machine-specific cli
>         arg?) [1]
>
>         Answered recently.
>
>     Thanks!
>
>
>          > - added BootROM support, allows booting with only specifying
>         -sd <IMG>
>          > - added SDRAM controller driver, for U-Boot SPL
>          > - added Allwinner generic RTC driver (for both Cubieboard and
>         OrangePi
>          > PC, supports sun4i, sun6i, sun7i)
>          > - small fixes for EMAC
>          >
>          > My current TODO:
>          >   - integrate Philips acceptance tests in the series
>
>         You can queue them in your series, adding your Signed-off-by tag
>         after
>         mine. See:
>         
> https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
>
>             The sign-off is a simple line at the end of the explanation
>         for the
>         patch, which certifies that you wrote it or otherwise have the
>         right to
>         pass it on as an open-source patch.
>
>         See point (c).
>
>     Ah that certainly helps. I'll read that page.
>
>          >   - integrate Philips work for generalizing the Allwinner
>         timer, and
>          > finish it
>
>         We can also do that later, and get your work merged first.
>
>
>     Ok that sounds very good! Agreed, lets do the timer work later.
>
>
>          >   - test and fix BSD targets (NetBSD, FreeBSD) [2, 3]
>          >   - further generalize the series to cover very similar SoCs:
>         H2+, H5
>          >
>          > Does anyone have more comments/requests for the V3 update?
>          >
>          > [1]
>         https://lists.gnu.org/archive/html/qemu-devel/2019-12/msg04049.html
>          > [2] https://wiki.netbsd.org/ports/evbarm/allwinner/
>          > [3]
>          >
>         
> https://wiki.freebsd.org/action/show/arm/Allwinner?action=show&redirect=FreeBSD%2Farm%2FAllwinner
>
>
>
>     -- 
>     Niek Linnenbank
>
>
>
> --
> Niek Linnenbank