Re: [PATCH RFC v2 30/30] docs/system/arm: document Raspberry Pi Pico

["Alex Bennée" <alex.bennee@linaro.org>]

Gilles Grimaud <gilles.grimaud@univ-lille.fr> writes:

> From: gilles grimaud <gilles.grimaud@univ-lille.fr>
>
> Document the RP2040 machine lineage, supported and shallow devices, boot ROM profiles, ELF/UF2/raw loading, persistent flash, serial backends, machine properties, flash policy, Pico SDK exit compatibility, and known limitations.
>
> Add the board page to the Arm system manual and its ownership entry to MAINTAINERS.
>
> Signed-off-by: gilles grimaud <gilles.grimaud@univ-lille.fr>
> ---
>  MAINTAINERS                    |   1 +
>  docs/system/arm/raspi-pico.rst | 641 +++++++++++++++++++++++++++++++++
>  docs/system/target-arm.rst     |   1 +
>  3 files changed, 643 insertions(+)
>  create mode 100644 docs/system/arm/raspi-pico.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 41494eff2a..0fa93d28c8 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1043,6 +1043,7 @@ F: hw/*/rp2040*
>  F: include/hw/*/rp2040*
>  F: hw/arm/raspi_pico.c
>  F: scripts/uf2-to-flash.py
> +F: docs/system/arm/raspi-pico.rst
>  F: tests/qtest/rp2040*
>  F: tests/tcg/arm/system/rp2040*
>  
> diff --git a/docs/system/arm/raspi-pico.rst b/docs/system/arm/raspi-pico.rst
> new file mode 100644
> index 0000000000..d28cd20af8
> --- /dev/null
> +++ b/docs/system/arm/raspi-pico.rst
> @@ -0,0 +1,641 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +Raspberry Pi Pico board (``raspi-pico``)
> +========================================
> +
> +The ``raspi-pico`` machine models a minimal Raspberry Pi Pico 1 board based
> +on the RP2040 microcontroller.  The current model is intended for bare-metal
> +bring-up and tests that execute code from the RP2040 external flash XIP
> +window.
> +
> +RFC lineage
> +-----------
> +
> +This machine starts from Alex Bennee's 2022 RP2040/Pico RFC patch series.
> +The RP2040 SoC skeleton, Pico machine, and memory map are adapted from that
> +series to the current QEMU tree.  The RFC ``pc-bios/pipico.rom`` image was
> +used for bring-up experiments, but it is not installed as a QEMU firmware
> +blob by this machine.
> +
> +RFC patch 0005's mask ROM loading logic is adapted for the current machine:
> +an external boot ROM can be supplied explicitly with ``-bios``.  QEMU still
> +uses a small synthetic boot ROM for direct XIP bring-up, so existing firmware
> +tests remain stable without requiring an external firmware image.

I don't think you need to document the lineage in the user facing docs.
You can add Based-on: <msgid> tags to the individual commits where the
patch started out from one of mine if you wish.

The rest is a lot but I can't really complain about comprehensive
documentation. I do wonder how much is repeating stuff that could just
be pointing as RaspberryPi's extensive and good documentation?

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro