Hey Philippe,

On Thu, Jan 2, 2020 at 10:11 PM Philippe Mathieu-Daudé <philmd@redhat.com>
wrote:

> 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.
>
> Ah great, that is very helpful! I will use the microvm.rst as example and
add a new file docs/orangepi.rst to document the board.


> 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.
>

OK, thanks for clarifying! Yes, I also prefer to have it in the header
files, it
makes the most sense indeed.


>
> Happy new year!
>

And happy new year to you as well Philippe!

Regards,
Niek

>
> Phil.
>
> > On Mon, Dec 30, 2019 at 9:10 PM Niek Linnenbank
> > <nieklinnenbank@gmail.com <mailto:nieklinnenbank@gmail.com>> wrote:
> >
> >
> >
> >     On Mon, Dec 30, 2019 at 3:56 PM Philippe Mathieu-Daudé
> >     <philmd@redhat.com <mailto:philmd@redhat.com>> 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
> >
>
>

-- 
Niek Linnenbank