[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Philippe Mathieu-Daudé
Subject: Re: [PATCH v2 00/10] Add Allwinner H3 SoC and Orange Pi PC Machine
Date: Thu, 2 Jan 2020 22:11:09 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.2

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

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!


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.


         > - 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
         > 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
        mine. See:

            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]
         > [2] https://wiki.netbsd.org/ports/evbarm/allwinner/
         > [3]

-- Niek Linnenbank

Niek Linnenbank

reply via email to

[Prev in Thread] Current Thread [Next in Thread]