On Thu, Jan 2, 2020 at 10:11 PM Philippe Mathieu-Daudé <
address@hidden> 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
> <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="">
>
>
>
> --
> Niek Linnenbank
>
>
>
> --
> Niek Linnenbank
>