Hey Philippe, On Thu, Jan 2, 2020 at 10:11 PM Philippe Mathieu-Daudé <phi...@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 > > <nieklinnenb...@gmail.com <mailto:nieklinnenb...@gmail.com>> wrote: > > > > > > > > On Mon, Dec 30, 2019 at 3:56 PM Philippe Mathieu-Daudé > > <phi...@redhat.com <mailto:phi...@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
