| Message ID | 20200507151819.28444-1-peter.maydell@linaro.org |
|---|---|
| Headers | show |
| Series | docs/system: Document some arm board models | expand |
Ping for review? thanks -- PMM On Thu, 7 May 2020 at 16:18, Peter Maydell <peter.maydell@linaro.org> wrote: > > This patchset adds (minimal) documentation of these Arm board models: > > vexpress-a15 ARM Versatile Express for Cortex-A15 > vexpress-a9 ARM Versatile Express for Cortex-A9 > mps2-an385 ARM MPS2 with AN385 FPGA image for Cortex-M35 > mps2-an505 ARM MPS2 with AN505 FPGA image for Cortex-M33 > mps2-an511 ARM MPS2 with AN511 DesignStart FPGA image for Cortex-M3 > mps2-an521 ARM MPS2 with AN521 FPGA image for dual Cortex-M33 > musca-a ARM Musca-A board (dual Cortex-M33) > musca-b1 ARM Musca-B1 board (dual Cortex-M33) > > to the system emulator manual. > > Patches 1 and 2 are minor tidyup of the board table-of-contents > before we start adding new entries with patches 3-5. > > I'm aiming more for "at least note that the boards exist" than > "fully comprehensive" documentation here -- there are still another > 37 Arm board models with no documentation at all... > > thanks > -- PMM > > Peter Maydell (5): > docs/system: Add 'Arm' to the Integrator/CP document title > docs/system: Sort Arm board index into alphabetical order > docs/system: Document Arm Versatile Express boards > docs/system: Document the various MPS2 models > docs/system: Document Musca boards > > docs/system/arm/integratorcp.rst | 4 +-- > docs/system/arm/mps2.rst | 29 +++++++++++++++ > docs/system/arm/musca.rst | 31 +++++++++++++++++ > docs/system/arm/vexpress.rst | 60 ++++++++++++++++++++++++++++++++ > docs/system/target-arm.rst | 15 ++++---- > MAINTAINERS | 3 ++ > 6 files changed, 134 insertions(+), 8 deletions(-) > create mode 100644 docs/system/arm/mps2.rst > create mode 100644 docs/system/arm/musca.rst > create mode 100644 docs/system/arm/vexpress.rst > > -- > 2.20.1 >
Hi Peter, +Markus On 5/14/20 3:28 PM, Peter Maydell wrote: > Ping for review? For the series: Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> However I'd rather see the board documentation in the source code, and extract it when building. It'd be harder to miss updating the documentation when modifying the code. Another way (rather than using external program to extract from source code) can be to add a method/field to MachineClass, and once a build is finished, we could run 'qemu-system-arch -M gendoc' which go thru all machines and display the documentation properly formatted. > > thanks > -- PMM > > On Thu, 7 May 2020 at 16:18, Peter Maydell <peter.maydell@linaro.org> wrote: >> >> This patchset adds (minimal) documentation of these Arm board models: >> >> vexpress-a15 ARM Versatile Express for Cortex-A15 >> vexpress-a9 ARM Versatile Express for Cortex-A9 >> mps2-an385 ARM MPS2 with AN385 FPGA image for Cortex-M35 >> mps2-an505 ARM MPS2 with AN505 FPGA image for Cortex-M33 >> mps2-an511 ARM MPS2 with AN511 DesignStart FPGA image for Cortex-M3 >> mps2-an521 ARM MPS2 with AN521 FPGA image for dual Cortex-M33 >> musca-a ARM Musca-A board (dual Cortex-M33) >> musca-b1 ARM Musca-B1 board (dual Cortex-M33) >> >> to the system emulator manual. >> >> Patches 1 and 2 are minor tidyup of the board table-of-contents >> before we start adding new entries with patches 3-5. >> >> I'm aiming more for "at least note that the boards exist" than >> "fully comprehensive" documentation here -- there are still another >> 37 Arm board models with no documentation at all... >> >> thanks >> -- PMM >> >> Peter Maydell (5): >> docs/system: Add 'Arm' to the Integrator/CP document title >> docs/system: Sort Arm board index into alphabetical order >> docs/system: Document Arm Versatile Express boards >> docs/system: Document the various MPS2 models >> docs/system: Document Musca boards >> >> docs/system/arm/integratorcp.rst | 4 +-- >> docs/system/arm/mps2.rst | 29 +++++++++++++++ >> docs/system/arm/musca.rst | 31 +++++++++++++++++ >> docs/system/arm/vexpress.rst | 60 ++++++++++++++++++++++++++++++++ >> docs/system/target-arm.rst | 15 ++++---- >> MAINTAINERS | 3 ++ >> 6 files changed, 134 insertions(+), 8 deletions(-) >> create mode 100644 docs/system/arm/mps2.rst >> create mode 100644 docs/system/arm/musca.rst >> create mode 100644 docs/system/arm/vexpress.rst >> >> -- >> 2.20.1 >> >
On Fri, 15 May 2020 at 09:03, Philippe Mathieu-Daudé <philmd@redhat.com> wrote: > However I'd rather see the board documentation in the source code, and > extract it when building. It'd be harder to miss updating the > documentation when modifying the code. I definitely agree in principle; but for the moment at least we can have some documentation... > Another way (rather than using external program to extract from source > code) can be to add a method/field to MachineClass, and once a build is > finished, we could run 'qemu-system-arch -M gendoc' which go thru all > machines and display the documentation properly formatted. The documentation needs to include all machines, not just the ones that got compiled into a particular binary, so I'm not sure this will work. I also would prefer it if we avoided having the docs build depend on doing a full binary build -- places like readthedocs will just do a docs build by invoking Sphinx directly, and we'd like the machine docs to be visible there. thanks -- PMM
On 5/15/20 10:51 AM, Peter Maydell wrote: > On Fri, 15 May 2020 at 09:03, Philippe Mathieu-Daudé <philmd@redhat.com> wrote: >> However I'd rather see the board documentation in the source code, and >> extract it when building. It'd be harder to miss updating the >> documentation when modifying the code. > > I definitely agree in principle; but for the moment at least > we can have some documentation... Yes, thank you very much for this effort! > >> Another way (rather than using external program to extract from source >> code) can be to add a method/field to MachineClass, and once a build is >> finished, we could run 'qemu-system-arch -M gendoc' which go thru all >> machines and display the documentation properly formatted. > > The documentation needs to include all machines, not just > the ones that got compiled into a particular binary, so > I'm not sure this will work. I also would prefer it if > we avoided having the docs build depend on doing a full > binary build -- places like readthedocs will just do a docs > build by invoking Sphinx directly, and we'd like the machine > docs to be visible there. Sphinx consumes docs/system/$arch/$machine.rst files committed to the repository, and we don't need to build various qemu-system-arch to generate the documentation. If you work on a particular board, you might end up only building its corresponding qemu-system-ARCH. Maybe we can add an extra-pass once a binary is linked, and re-generate the docs/system/ARCH/$machine.rst files, so if you modified a board and its documentation placeholder in the code, when commiting your code change, you also have to commit the rst changes. Just brainstorming an idea for now ;) > > thanks > -- PMM >
On Fri, 15 May 2020 at 10:05, Philippe Mathieu-Daudé <philmd@redhat.com> wrote: > Sphinx consumes docs/system/$arch/$machine.rst files committed to the > repository, and we don't need to build various qemu-system-arch to > generate the documentation. > > If you work on a particular board, you might end up only building its > corresponding qemu-system-ARCH. Maybe we can add an extra-pass once a > binary is linked, and re-generate the docs/system/ARCH/$machine.rst > files, so if you modified a board and its documentation placeholder in > the code, when commiting your code change, you also have to commit the > rst changes. I'm not a huge fan of committing generated files to source control... I think I'd prefer an approach that worked via some kind of kerneldoc comments that we pull out and parse using the Sphinx plugin we have for that. (There's more complication than that but roughly I think that would be the kind of approach I'd like to see.) thanks -- PMM