[PATCH 0/7] docs/system/arm: Provide at least skeleton docs for all boards

[PATCH 0/7] docs/system/arm: Provide at least skeleton docs for all boards

[Peter Maydell]

In target-arm.rst there is an apologetic note:

  Unfortunately many of the Arm boards QEMU supports are currently
  undocumented; you can get a complete list by running
  ``qemu-system-aarch64 --machine help``.

However, the situation isn't actually as bleak as this suggests:
over the years we have generally insisted on documentation for
new machine types and have filled in some of the gaps where
there was no documentation for older machine types. Plus we just
deleted a lot of older undocumented or underdocumented boards.

I did a check of all the board types listed in --help and we
really don't have very many left that weren't listed in the
documentation. This series does some cleanup of existing
docs to ensure that every board covered by a .rst file has
a line in the right place in the list that lists the board
name explicitly. It then adds placeholder docs for the remaining
undocumented boards:
 * nuri, smdkc210 (Exynos4 boards)
 * xlnx-zcu102
 * mcimx6ul-evk
 * mcimx7d-sabre

and removes the apologetic note about the list being incomplete.

The placeholder docs are obviously not very useful, but they
mean we at least have an entry in the list for the board
that gives the manufacturer's name for the board, and we
have a place to put expanded information in future if anybody
wants to write it.

Anybody who has more information on the above boards is of
course welcome to expand on the minimal files here :-)

thanks
-- PMM

Peter Maydell (7):
  docs/system/arm/stm32: List olimex-stm32-h405 in document title
  docs/system/arm: Don't use wildcard '*-bmc' in doc titles
  docs/system/arm: Split fby35 out from aspeed.rst
  docs/system/arm: Add placeholder doc for exynos4 boards
  docs/system/arm: Add placeholder doc for xlnx-zcu102 board
  docs/system/arm: Add placeholder docs for mcimx6ul-evk and
    mcimx7d-sabre
  docs/system/target-arm.rst: Remove "many boards are undocumented" note

 MAINTAINERS                       |  5 +++
 docs/system/arm/aspeed.rst        | 52 ++-----------------------------
 docs/system/arm/exynos.rst        |  9 ++++++
 docs/system/arm/fby35.rst         | 47 ++++++++++++++++++++++++++++
 docs/system/arm/mcimx6ul-evk.rst  |  5 +++
 docs/system/arm/mcimx7d-sabre.rst |  5 +++
 docs/system/arm/nuvoton.rst       |  4 +--
 docs/system/arm/stm32.rst         |  4 +--
 docs/system/arm/xlnx-zcu102.rst   | 19 +++++++++++
 docs/system/target-arm.rst        |  9 +++---
 10 files changed, 101 insertions(+), 58 deletions(-)
 create mode 100644 docs/system/arm/exynos.rst
 create mode 100644 docs/system/arm/fby35.rst
 create mode 100644 docs/system/arm/mcimx6ul-evk.rst
 create mode 100644 docs/system/arm/mcimx7d-sabre.rst
 create mode 100644 docs/system/arm/xlnx-zcu102.rst

-- 
2.34.1

[PATCH 1/7] docs/system/arm/stm32: List olimex-stm32-h405 in document title

[Peter Maydell]

List the olimex-stm32-h405 board in the document title, so that the
board name appears in the table of contents in system/target-arm.rst.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/system/arm/stm32.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/system/arm/stm32.rst b/docs/system/arm/stm32.rst
index ca7a55841b4..511e3eb9ac1 100644
--- a/docs/system/arm/stm32.rst
+++ b/docs/system/arm/stm32.rst
@@ -1,5 +1,5 @@
-STMicroelectronics STM32 boards (``netduino2``, ``netduinoplus2``, ``stm32vldiscovery``)
-========================================================================================
+STMicroelectronics STM32 boards (``netduino2``, ``netduinoplus2``, ``olimex-stm32-h405``, ``stm32vldiscovery``)
+===============================================================================================================
 
 The `STM32`_ chips are a family of 32-bit ARM-based microcontroller by
 STMicroelectronics.
-- 
2.34.1

[PATCH 2/7] docs/system/arm: Don't use wildcard '*-bmc' in doc titles

[Peter Maydell]

We have two Arm board doc files which both use '*-bmc' in their
documentation title. The result is that when you read the
table of contents in system/target-arm.html you don't know
which boards are covered by which file.

Expand out the board names entirely in the document titles.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/system/arm/aspeed.rst  | 4 ++--
 docs/system/arm/nuvoton.rst | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/system/arm/aspeed.rst b/docs/system/arm/aspeed.rst
index 6733ffd2b94..968ba88b997 100644
--- a/docs/system/arm/aspeed.rst
+++ b/docs/system/arm/aspeed.rst
@@ -1,5 +1,5 @@
-Aspeed family boards (``*-bmc``, ``ast2500-evb``, ``ast2600-evb``, ``ast2700-evb``)
-===================================================================================
+Aspeed family boards (``ast2500-evb``, ``ast2600-evb``, ``ast2700-evb``, ``bletchley-bmc``, ``fuji-bmc``, ``fby35-bmc``, ``fp5280g2-bmc``, ``g220a-bmc``, ``palmetto-bmc``, ``qcom-dc-scm-v1-bmc``, ``qcom-firework-bmc``, ``quanta-q71l-bmc``, ``rainier-bmc``, ``romulus-bmc``, ``sonorapass-bmc``, ``supermicrox11-bmc``, ``tiogapass-bmc``, ``tacoma-bmc``, ``witherspoon-bmc``, ``yosemitev2-bmc``)
+========================================================================================================================================================================================================================================================================================================================================================================================================
 
 The QEMU Aspeed machines model BMCs of various OpenPOWER systems and
 Aspeed evaluation boards. They are based on different releases of the
diff --git a/docs/system/arm/nuvoton.rst b/docs/system/arm/nuvoton.rst
index 0424cae4b01..05059378e55 100644
--- a/docs/system/arm/nuvoton.rst
+++ b/docs/system/arm/nuvoton.rst
@@ -1,5 +1,5 @@
-Nuvoton iBMC boards (``*-bmc``, ``npcm750-evb``, ``quanta-gsj``)
-================================================================
+Nuvoton iBMC boards (``kudo-bmc``, ``mori-bmc``, ``npcm750-evb``, ``quanta-gbs-bmc``, ``quanta-gsj``)
+=====================================================================================================
 
 The `Nuvoton iBMC`_ chips (NPCM7xx) are a family of ARM-based SoCs that are
 designed to be used as Baseboard Management Controllers (BMCs) in various
-- 
2.34.1

[PATCH 3/7] docs/system/arm: Split fby35 out from aspeed.rst

[Peter Maydell]

The fby35 machine is not implemented in hw/arm/aspeed.c,
but its documentation is currently stuck at the end of aspeed.rst,
formatted in a way that it gets its own heading in the top-level
list of boards in target-arm.html.

We don't have any other boards that we document like this; split it
out into its own rst file. This improves consistency with other
board docs and means we can have the entry in the target-arm
list be in the correct alphabetical order.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 MAINTAINERS                |  1 +
 docs/system/arm/aspeed.rst | 48 --------------------------------------
 docs/system/arm/fby35.rst  | 47 +++++++++++++++++++++++++++++++++++++
 docs/system/target-arm.rst |  1 +
 4 files changed, 49 insertions(+), 48 deletions(-)
 create mode 100644 docs/system/arm/fby35.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index c21d6a2f9e1..dff8073c5bc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1121,6 +1121,7 @@ F: include/hw/*/*aspeed*
 F: hw/net/ftgmac100.c
 F: include/hw/net/ftgmac100.h
 F: docs/system/arm/aspeed.rst
+F: docs/system/arm/fby35.rst
 F: tests/*/*aspeed*
 F: hw/arm/fby35.c
 
diff --git a/docs/system/arm/aspeed.rst b/docs/system/arm/aspeed.rst
index 968ba88b997..63910d382fe 100644
--- a/docs/system/arm/aspeed.rst
+++ b/docs/system/arm/aspeed.rst
@@ -257,51 +257,3 @@ To boot a kernel directly from a Zephyr build tree:
 
   $ qemu-system-arm -M ast1030-evb -nographic \
         -kernel zephyr.elf
-
-Facebook Yosemite v3.5 Platform and CraterLake Server (``fby35``)
-==================================================================
-
-Facebook has a series of multi-node compute server designs named
-Yosemite. The most recent version released was
-`Yosemite v3 <https://www.opencompute.org/documents/ocp-yosemite-v3-platform-design-specification-1v16-pdf>`__.
-
-Yosemite v3.5 is an iteration on this design, and is very similar: there's a
-baseboard with a BMC, and 4 server slots. The new server board design termed
-"CraterLake" includes a Bridge IC (BIC), with room for expansion boards to
-include various compute accelerators (video, inferencing, etc). At the moment,
-only the first server slot's BIC is included.
-
-Yosemite v3.5 is itself a sled which fits into a 40U chassis, and 3 sleds
-can be fit into a chassis. See `here <https://www.opencompute.org/products/423/wiwynn-yosemite-v3-server>`__
-for an example.
-
-In this generation, the BMC is an AST2600 and each BIC is an AST1030. The BMC
-runs `OpenBMC <https://github.com/facebook/openbmc>`__, and the BIC runs
-`OpenBIC <https://github.com/facebook/openbic>`__.
-
-Firmware images can be retrieved from the Github releases or built from the
-source code, see the README's for instructions on that. This image uses the
-"fby35" machine recipe from OpenBMC, and the "yv35-cl" target from OpenBIC.
-Some reference images can also be found here:
-
-.. code-block:: bash
-
-    $ wget https://github.com/facebook/openbmc/releases/download/openbmc-e2294ff5d31d/fby35.mtd
-    $ wget https://github.com/peterdelevoryas/OpenBIC/releases/download/oby35-cl-2022.13.01/Y35BCL.elf
-
-Since this machine has multiple SoC's, each with their own serial console, the
-recommended way to run it is to allocate a pseudoterminal for each serial
-console and let the monitor use stdio. Also, starting in a paused state is
-useful because it allows you to attach to the pseudoterminals before the boot
-process starts.
-
-.. code-block:: bash
-
-    $ qemu-system-arm -machine fby35 \
-        -drive file=fby35.mtd,format=raw,if=mtd \
-        -device loader,file=Y35BCL.elf,addr=0,cpu-num=2 \
-        -serial pty -serial pty -serial mon:stdio \
-        -display none -S
-    $ screen /dev/tty0 # In a separate TMUX pane, terminal window, etc.
-    $ screen /dev/tty1
-    $ (qemu) c		   # Start the boot process once screen is setup.
diff --git a/docs/system/arm/fby35.rst b/docs/system/arm/fby35.rst
new file mode 100644
index 00000000000..742b887d44c
--- /dev/null
+++ b/docs/system/arm/fby35.rst
@@ -0,0 +1,47 @@
+Facebook Yosemite v3.5 Platform and CraterLake Server (``fby35``)
+==================================================================
+
+Facebook has a series of multi-node compute server designs named
+Yosemite. The most recent version released was
+`Yosemite v3 <https://www.opencompute.org/documents/ocp-yosemite-v3-platform-design-specification-1v16-pdf>`__.
+
+Yosemite v3.5 is an iteration on this design, and is very similar: there's a
+baseboard with a BMC, and 4 server slots. The new server board design termed
+"CraterLake" includes a Bridge IC (BIC), with room for expansion boards to
+include various compute accelerators (video, inferencing, etc). At the moment,
+only the first server slot's BIC is included.
+
+Yosemite v3.5 is itself a sled which fits into a 40U chassis, and 3 sleds
+can be fit into a chassis. See `here <https://www.opencompute.org/products/423/wiwynn-yosemite-v3-server>`__
+for an example.
+
+In this generation, the BMC is an AST2600 and each BIC is an AST1030. The BMC
+runs `OpenBMC <https://github.com/facebook/openbmc>`__, and the BIC runs
+`OpenBIC <https://github.com/facebook/openbic>`__.
+
+Firmware images can be retrieved from the Github releases or built from the
+source code, see the README's for instructions on that. This image uses the
+"fby35" machine recipe from OpenBMC, and the "yv35-cl" target from OpenBIC.
+Some reference images can also be found here:
+
+.. code-block:: bash
+
+    $ wget https://github.com/facebook/openbmc/releases/download/openbmc-e2294ff5d31d/fby35.mtd
+    $ wget https://github.com/peterdelevoryas/OpenBIC/releases/download/oby35-cl-2022.13.01/Y35BCL.elf
+
+Since this machine has multiple SoC's, each with their own serial console, the
+recommended way to run it is to allocate a pseudoterminal for each serial
+console and let the monitor use stdio. Also, starting in a paused state is
+useful because it allows you to attach to the pseudoterminals before the boot
+process starts.
+
+.. code-block:: bash
+
+    $ qemu-system-arm -machine fby35 \
+        -drive file=fby35.mtd,format=raw,if=mtd \
+        -device loader,file=Y35BCL.elf,addr=0,cpu-num=2 \
+        -serial pty -serial pty -serial mon:stdio \
+        -display none -S
+    $ screen /dev/tty0 # In a separate TMUX pane, terminal window, etc.
+    $ screen /dev/tty1
+    $ (qemu) c		   # Start the boot process once screen is setup.
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index 3c0a5848453..9c01e66ffa9 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -90,6 +90,7 @@ undocumented; you can get a complete list by running
    arm/digic
    arm/cubieboard
    arm/emcraft-sf2
+   arm/fby35
    arm/musicpal
    arm/kzm
    arm/nrf
-- 
2.34.1

[PATCH 4/7] docs/system/arm: Add placeholder doc for exynos4 boards

[Peter Maydell]

Add a placeholder doc for the exynos4 boards nuri and smdkc210.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 MAINTAINERS                | 1 +
 docs/system/arm/exynos.rst | 9 +++++++++
 docs/system/target-arm.rst | 1 +
 3 files changed, 11 insertions(+)
 create mode 100644 docs/system/arm/exynos.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index dff8073c5bc..031b117a3a0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -716,6 +716,7 @@ L: qemu-arm@nongnu.org
 S: Odd Fixes
 F: hw/*/exynos*
 F: include/hw/*/exynos*
+F: docs/system/arm/exynos.rst
 
 Calxeda Highbank
 M: Rob Herring <robh@kernel.org>
diff --git a/docs/system/arm/exynos.rst b/docs/system/arm/exynos.rst
new file mode 100644
index 00000000000..86894bc02b7
--- /dev/null
+++ b/docs/system/arm/exynos.rst
@@ -0,0 +1,9 @@
+Exynos4 boards (``nuri``, ``smdkc210``)
+=======================================
+
+These are machines which use the Samsung Exynos4210 SoC, which has Cortex-A9 CPUs.
+
+``nuri`` models the Samsung NURI board.
+
+``smdkc210`` models the Samsung SMDKC210 board.
+
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index 9c01e66ffa9..a7f88c8f317 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -90,6 +90,7 @@ undocumented; you can get a complete list by running
    arm/digic
    arm/cubieboard
    arm/emcraft-sf2
+   arm/exynos
    arm/fby35
    arm/musicpal
    arm/kzm
-- 
2.34.1

[PATCH 5/7] docs/system/arm: Add placeholder doc for xlnx-zcu102 board

[Peter Maydell]

Add a placeholder doc for the xlnx-zcu102 board.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 MAINTAINERS                     |  1 +
 docs/system/arm/xlnx-zcu102.rst | 19 +++++++++++++++++++
 docs/system/target-arm.rst      |  1 +
 3 files changed, 21 insertions(+)
 create mode 100644 docs/system/arm/xlnx-zcu102.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 031b117a3a0..7c3325628c9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1016,6 +1016,7 @@ F: include/hw/ssi/xilinx_spips.h
 F: hw/display/dpcd.c
 F: include/hw/display/dpcd.h
 F: docs/system/arm/xlnx-versal-virt.rst
+F: docs/system/arm/xlnx-zcu102.rst
 
 Xilinx Versal OSPI
 M: Francisco Iglesias <francisco.iglesias@amd.com>
diff --git a/docs/system/arm/xlnx-zcu102.rst b/docs/system/arm/xlnx-zcu102.rst
new file mode 100644
index 00000000000..534cd1dc887
--- /dev/null
+++ b/docs/system/arm/xlnx-zcu102.rst
@@ -0,0 +1,19 @@
+Xilinx ZynqMP ZCU102 (``xlnx-zcu102``)
+======================================
+
+The ``xlnx-zcu102`` board models the Xilinx ZynqMP ZCU102 board.
+This board has 4 Cortex-A53 CPUs and 2 Cortex-R5F CPUs.
+
+Machine-specific options
+""""""""""""""""""""""""
+
+The following machine-specific options are supported:
+
+secure
+  Set ``on``/``off`` to enable/disable emulating a guest CPU which implements the
+  Arm Security Extensions (TrustZone). The default is ``off``.
+
+virtualization
+  Set ``on``/``off`` to enable/disable emulating a guest CPU which implements the
+  Arm Virtualization Extensions. The default is ``off``.
+
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index a7f88c8f317..ace36d1b17d 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -107,6 +107,7 @@ undocumented; you can get a complete list by running
    arm/xenpvh
    arm/xlnx-versal-virt
    arm/xlnx-zynq
+   arm/xlnx-zcu102
 
 Emulated CPU architecture support
 =================================
-- 
2.34.1

[PATCH 6/7] docs/system/arm: Add placeholder docs for mcimx6ul-evk and mcimx7d-sabre

[Peter Maydell]

Add placeholder docs for the mcimx6ul-evk and mcimx7d-sabre boards.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 MAINTAINERS                       | 2 ++
 docs/system/arm/mcimx6ul-evk.rst  | 5 +++++
 docs/system/arm/mcimx7d-sabre.rst | 5 +++++
 docs/system/target-arm.rst        | 2 ++
 4 files changed, 14 insertions(+)
 create mode 100644 docs/system/arm/mcimx6ul-evk.rst
 create mode 100644 docs/system/arm/mcimx7d-sabre.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 7c3325628c9..2866737261b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -791,6 +791,7 @@ F: hw/arm/fsl-imx6ul.c
 F: hw/misc/imx6ul_ccm.c
 F: include/hw/arm/fsl-imx6ul.h
 F: include/hw/misc/imx6ul_ccm.h
+F: docs/system/arm/mcimx6ul-evk.rst
 
 MCIMX7D SABRE / i.MX7
 M: Peter Maydell <peter.maydell@linaro.org>
@@ -804,6 +805,7 @@ F: include/hw/arm/fsl-imx7.h
 F: include/hw/misc/imx7_*.h
 F: hw/pci-host/designware.c
 F: include/hw/pci-host/designware.h
+F: docs/system/arm/mcimx7d-sabre.rst
 
 MPS2 / MPS3
 M: Peter Maydell <peter.maydell@linaro.org>
diff --git a/docs/system/arm/mcimx6ul-evk.rst b/docs/system/arm/mcimx6ul-evk.rst
new file mode 100644
index 00000000000..8871138ab3e
--- /dev/null
+++ b/docs/system/arm/mcimx6ul-evk.rst
@@ -0,0 +1,5 @@
+NXP MCIMX6UL-EVK (``mcimx6ul-evk``)
+===================================
+
+The ``mcimx6ul-evk`` machine models the NXP i.MX6UltraLite Evaluation Kit
+MCIMX6UL-EVK development board. It has a single Cortex-A7 CPU.
diff --git a/docs/system/arm/mcimx7d-sabre.rst b/docs/system/arm/mcimx7d-sabre.rst
new file mode 100644
index 00000000000..c5d35af1d44
--- /dev/null
+++ b/docs/system/arm/mcimx7d-sabre.rst
@@ -0,0 +1,5 @@
+NXP MCIMX7D Sabre (``mcimx7d-sabre``)
+=====================================
+
+The ``mcimx7d-sabre`` machine models the NXP SABRE Board MCIMX7SABRE,
+based an an i.MX7Dual SoC.
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index ace36d1b17d..1f806cf4a46 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -97,6 +97,8 @@ undocumented; you can get a complete list by running
    arm/nrf
    arm/nuvoton
    arm/imx25-pdk
+   arm/mcimx6ul-evk
+   arm/mcimx7d-sabre
    arm/orangepi
    arm/raspi
    arm/collie
-- 
2.34.1

[PATCH 7/7] docs/system/target-arm.rst: Remove "many boards are undocumented" note

[Peter Maydell]

We now have at least placeholder documentation for every Arm board,
so we can remove the apologetic note that says that there are
undocumented ones which you can only find out about via the
``--machine help`` option.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/system/target-arm.rst | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index 1f806cf4a46..9aaa9c414c9 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -63,10 +63,6 @@ large amounts of RAM. It also supports 64-bit CPUs.
 Board-specific documentation
 ============================
 
-Unfortunately many of the Arm boards QEMU supports are currently
-undocumented; you can get a complete list by running
-``qemu-system-aarch64 --machine help``.
-
 ..
    This table of contents should be kept sorted alphabetically
    by the title text of each file, which isn't the same ordering
-- 
2.34.1

Re: [PATCH 0/7] docs/system/arm: Provide at least skeleton docs for all boards

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> In target-arm.rst there is an apologetic note:
>
>   Unfortunately many of the Arm boards QEMU supports are currently
>   undocumented; you can get a complete list by running
>   ``qemu-system-aarch64 --machine help``.
>
> However, the situation isn't actually as bleak as this suggests:
> over the years we have generally insisted on documentation for
> new machine types and have filled in some of the gaps where
> there was no documentation for older machine types. Plus we just
> deleted a lot of older undocumented or underdocumented boards.
>
> I did a check of all the board types listed in --help and we
> really don't have very many left that weren't listed in the
> documentation. This series does some cleanup of existing
> docs to ensure that every board covered by a .rst file has
> a line in the right place in the list that lists the board
> name explicitly. It then adds placeholder docs for the remaining
> undocumented boards:
>  * nuri, smdkc210 (Exynos4 boards)
>  * xlnx-zcu102
>  * mcimx6ul-evk
>  * mcimx7d-sabre
>
> and removes the apologetic note about the list being incomplete.
>
> The placeholder docs are obviously not very useful, but they
> mean we at least have an entry in the list for the board
> that gives the manufacturer's name for the board, and we
> have a place to put expanded information in future if anybody
> wants to write it.
>
> Anybody who has more information on the above boards is of
> course welcome to expand on the minimal files here :-)

For the series:

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH 5/7] docs/system/arm: Add placeholder doc for xlnx-zcu102 board

[Alistair Francis]

On Sat, Oct 19, 2024 at 12:15 AM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> Add a placeholder doc for the xlnx-zcu102 board.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alistair Francis <alistair.francis@wdc.com>

Alistair

> ---
>  MAINTAINERS                     |  1 +
>  docs/system/arm/xlnx-zcu102.rst | 19 +++++++++++++++++++
>  docs/system/target-arm.rst      |  1 +
>  3 files changed, 21 insertions(+)
>  create mode 100644 docs/system/arm/xlnx-zcu102.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 031b117a3a0..7c3325628c9 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1016,6 +1016,7 @@ F: include/hw/ssi/xilinx_spips.h
>  F: hw/display/dpcd.c
>  F: include/hw/display/dpcd.h
>  F: docs/system/arm/xlnx-versal-virt.rst
> +F: docs/system/arm/xlnx-zcu102.rst
>
>  Xilinx Versal OSPI
>  M: Francisco Iglesias <francisco.iglesias@amd.com>
> diff --git a/docs/system/arm/xlnx-zcu102.rst b/docs/system/arm/xlnx-zcu102.rst
> new file mode 100644
> index 00000000000..534cd1dc887
> --- /dev/null
> +++ b/docs/system/arm/xlnx-zcu102.rst
> @@ -0,0 +1,19 @@
> +Xilinx ZynqMP ZCU102 (``xlnx-zcu102``)
> +======================================
> +
> +The ``xlnx-zcu102`` board models the Xilinx ZynqMP ZCU102 board.
> +This board has 4 Cortex-A53 CPUs and 2 Cortex-R5F CPUs.
> +
> +Machine-specific options
> +""""""""""""""""""""""""
> +
> +The following machine-specific options are supported:
> +
> +secure
> +  Set ``on``/``off`` to enable/disable emulating a guest CPU which implements the
> +  Arm Security Extensions (TrustZone). The default is ``off``.
> +
> +virtualization
> +  Set ``on``/``off`` to enable/disable emulating a guest CPU which implements the
> +  Arm Virtualization Extensions. The default is ``off``.
> +
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index a7f88c8f317..ace36d1b17d 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -107,6 +107,7 @@ undocumented; you can get a complete list by running
>     arm/xenpvh
>     arm/xlnx-versal-virt
>     arm/xlnx-zynq
> +   arm/xlnx-zcu102
>
>  Emulated CPU architecture support
>  =================================
> --
> 2.34.1
>
>

Re: [PATCH 7/7] docs/system/target-arm.rst: Remove "many boards are undocumented" note

[Alistair Francis]

On Sat, Oct 19, 2024 at 12:14 AM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> We now have at least placeholder documentation for every Arm board,
> so we can remove the apologetic note that says that there are
> undocumented ones which you can only find out about via the
> ``--machine help`` option.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alistair Francis <alistair.francis@wdc.com>

Alistair

> ---
>  docs/system/target-arm.rst | 4 ----
>  1 file changed, 4 deletions(-)
>
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 1f806cf4a46..9aaa9c414c9 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -63,10 +63,6 @@ large amounts of RAM. It also supports 64-bit CPUs.
>  Board-specific documentation
>  ============================
>
> -Unfortunately many of the Arm boards QEMU supports are currently
> -undocumented; you can get a complete list by running
> -``qemu-system-aarch64 --machine help``.
> -
>  ..
>     This table of contents should be kept sorted alphabetically
>     by the title text of each file, which isn't the same ordering
> --
> 2.34.1
>
>

Re: [PATCH 1/7] docs/system/arm/stm32: List olimex-stm32-h405 in document title

[Cédric Le Goater]

On 10/18/24 16:13, Peter Maydell wrote:
> List the olimex-stm32-h405 board in the document title, so that the
> board name appears in the table of contents in system/target-arm.rst.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   docs/system/arm/stm32.rst | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/system/arm/stm32.rst b/docs/system/arm/stm32.rst
> index ca7a55841b4..511e3eb9ac1 100644
> --- a/docs/system/arm/stm32.rst
> +++ b/docs/system/arm/stm32.rst
> @@ -1,5 +1,5 @@
> -STMicroelectronics STM32 boards (``netduino2``, ``netduinoplus2``, ``stm32vldiscovery``)
> -========================================================================================
> +STMicroelectronics STM32 boards (``netduino2``, ``netduinoplus2``, ``olimex-stm32-h405``, ``stm32vldiscovery``)
> +===============================================================================================================
>   
>   The `STM32`_ chips are a family of 32-bit ARM-based microcontroller by
>   STMicroelectronics.


Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.

Re: [PATCH 3/7] docs/system/arm: Split fby35 out from aspeed.rst

[Cédric Le Goater]

On 10/18/24 16:13, Peter Maydell wrote:
> The fby35 machine is not implemented in hw/arm/aspeed.c,
> but its documentation is currently stuck at the end of aspeed.rst,
> formatted in a way that it gets its own heading in the top-level
> list of boards in target-arm.html.
> 
> We don't have any other boards that we document like this; split it
> out into its own rst file. This improves consistency with other
> board docs and means we can have the entry in the target-arm
> list be in the correct alphabetical order.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>


Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.


> ---
>   MAINTAINERS                |  1 +
>   docs/system/arm/aspeed.rst | 48 --------------------------------------
>   docs/system/arm/fby35.rst  | 47 +++++++++++++++++++++++++++++++++++++
>   docs/system/target-arm.rst |  1 +
>   4 files changed, 49 insertions(+), 48 deletions(-)
>   create mode 100644 docs/system/arm/fby35.rst
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index c21d6a2f9e1..dff8073c5bc 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1121,6 +1121,7 @@ F: include/hw/*/*aspeed*
>   F: hw/net/ftgmac100.c
>   F: include/hw/net/ftgmac100.h
>   F: docs/system/arm/aspeed.rst
> +F: docs/system/arm/fby35.rst
>   F: tests/*/*aspeed*
>   F: hw/arm/fby35.c
>   
> diff --git a/docs/system/arm/aspeed.rst b/docs/system/arm/aspeed.rst
> index 968ba88b997..63910d382fe 100644
> --- a/docs/system/arm/aspeed.rst
> +++ b/docs/system/arm/aspeed.rst
> @@ -257,51 +257,3 @@ To boot a kernel directly from a Zephyr build tree:
>   
>     $ qemu-system-arm -M ast1030-evb -nographic \
>           -kernel zephyr.elf
> -
> -Facebook Yosemite v3.5 Platform and CraterLake Server (``fby35``)
> -==================================================================
> -
> -Facebook has a series of multi-node compute server designs named
> -Yosemite. The most recent version released was
> -`Yosemite v3 <https://www.opencompute.org/documents/ocp-yosemite-v3-platform-design-specification-1v16-pdf>`__.
> -
> -Yosemite v3.5 is an iteration on this design, and is very similar: there's a
> -baseboard with a BMC, and 4 server slots. The new server board design termed
> -"CraterLake" includes a Bridge IC (BIC), with room for expansion boards to
> -include various compute accelerators (video, inferencing, etc). At the moment,
> -only the first server slot's BIC is included.
> -
> -Yosemite v3.5 is itself a sled which fits into a 40U chassis, and 3 sleds
> -can be fit into a chassis. See `here <https://www.opencompute.org/products/423/wiwynn-yosemite-v3-server>`__
> -for an example.
> -
> -In this generation, the BMC is an AST2600 and each BIC is an AST1030. The BMC
> -runs `OpenBMC <https://github.com/facebook/openbmc>`__, and the BIC runs
> -`OpenBIC <https://github.com/facebook/openbic>`__.
> -
> -Firmware images can be retrieved from the Github releases or built from the
> -source code, see the README's for instructions on that. This image uses the
> -"fby35" machine recipe from OpenBMC, and the "yv35-cl" target from OpenBIC.
> -Some reference images can also be found here:
> -
> -.. code-block:: bash
> -
> -    $ wget https://github.com/facebook/openbmc/releases/download/openbmc-e2294ff5d31d/fby35.mtd
> -    $ wget https://github.com/peterdelevoryas/OpenBIC/releases/download/oby35-cl-2022.13.01/Y35BCL.elf
> -
> -Since this machine has multiple SoC's, each with their own serial console, the
> -recommended way to run it is to allocate a pseudoterminal for each serial
> -console and let the monitor use stdio. Also, starting in a paused state is
> -useful because it allows you to attach to the pseudoterminals before the boot
> -process starts.
> -
> -.. code-block:: bash
> -
> -    $ qemu-system-arm -machine fby35 \
> -        -drive file=fby35.mtd,format=raw,if=mtd \
> -        -device loader,file=Y35BCL.elf,addr=0,cpu-num=2 \
> -        -serial pty -serial pty -serial mon:stdio \
> -        -display none -S
> -    $ screen /dev/tty0 # In a separate TMUX pane, terminal window, etc.
> -    $ screen /dev/tty1
> -    $ (qemu) c		   # Start the boot process once screen is setup.
> diff --git a/docs/system/arm/fby35.rst b/docs/system/arm/fby35.rst
> new file mode 100644
> index 00000000000..742b887d44c
> --- /dev/null
> +++ b/docs/system/arm/fby35.rst
> @@ -0,0 +1,47 @@
> +Facebook Yosemite v3.5 Platform and CraterLake Server (``fby35``)
> +==================================================================
> +
> +Facebook has a series of multi-node compute server designs named
> +Yosemite. The most recent version released was
> +`Yosemite v3 <https://www.opencompute.org/documents/ocp-yosemite-v3-platform-design-specification-1v16-pdf>`__.
> +
> +Yosemite v3.5 is an iteration on this design, and is very similar: there's a
> +baseboard with a BMC, and 4 server slots. The new server board design termed
> +"CraterLake" includes a Bridge IC (BIC), with room for expansion boards to
> +include various compute accelerators (video, inferencing, etc). At the moment,
> +only the first server slot's BIC is included.
> +
> +Yosemite v3.5 is itself a sled which fits into a 40U chassis, and 3 sleds
> +can be fit into a chassis. See `here <https://www.opencompute.org/products/423/wiwynn-yosemite-v3-server>`__
> +for an example.
> +
> +In this generation, the BMC is an AST2600 and each BIC is an AST1030. The BMC
> +runs `OpenBMC <https://github.com/facebook/openbmc>`__, and the BIC runs
> +`OpenBIC <https://github.com/facebook/openbic>`__.
> +
> +Firmware images can be retrieved from the Github releases or built from the
> +source code, see the README's for instructions on that. This image uses the
> +"fby35" machine recipe from OpenBMC, and the "yv35-cl" target from OpenBIC.
> +Some reference images can also be found here:
> +
> +.. code-block:: bash
> +
> +    $ wget https://github.com/facebook/openbmc/releases/download/openbmc-e2294ff5d31d/fby35.mtd
> +    $ wget https://github.com/peterdelevoryas/OpenBIC/releases/download/oby35-cl-2022.13.01/Y35BCL.elf
> +
> +Since this machine has multiple SoC's, each with their own serial console, the
> +recommended way to run it is to allocate a pseudoterminal for each serial
> +console and let the monitor use stdio. Also, starting in a paused state is
> +useful because it allows you to attach to the pseudoterminals before the boot
> +process starts.
> +
> +.. code-block:: bash
> +
> +    $ qemu-system-arm -machine fby35 \
> +        -drive file=fby35.mtd,format=raw,if=mtd \
> +        -device loader,file=Y35BCL.elf,addr=0,cpu-num=2 \
> +        -serial pty -serial pty -serial mon:stdio \
> +        -display none -S
> +    $ screen /dev/tty0 # In a separate TMUX pane, terminal window, etc.
> +    $ screen /dev/tty1
> +    $ (qemu) c		   # Start the boot process once screen is setup.
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 3c0a5848453..9c01e66ffa9 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -90,6 +90,7 @@ undocumented; you can get a complete list by running
>      arm/digic
>      arm/cubieboard
>      arm/emcraft-sf2
> +   arm/fby35
>      arm/musicpal
>      arm/kzm
>      arm/nrf

Re: [PATCH 2/7] docs/system/arm: Don't use wildcard '*-bmc' in doc titles

[Cédric Le Goater]

On 10/18/24 16:13, Peter Maydell wrote:
> We have two Arm board doc files which both use '*-bmc' in their
> documentation title. The result is that when you read the
> table of contents in system/target-arm.html you don't know
> which boards are covered by which file.
> 
> Expand out the board names entirely in the document titles.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>



Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.


> ---
>   docs/system/arm/aspeed.rst  | 4 ++--
>   docs/system/arm/nuvoton.rst | 4 ++--
>   2 files changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/system/arm/aspeed.rst b/docs/system/arm/aspeed.rst
> index 6733ffd2b94..968ba88b997 100644
> --- a/docs/system/arm/aspeed.rst
> +++ b/docs/system/arm/aspeed.rst
> @@ -1,5 +1,5 @@
> -Aspeed family boards (``*-bmc``, ``ast2500-evb``, ``ast2600-evb``, ``ast2700-evb``)
> -===================================================================================
> +Aspeed family boards (``ast2500-evb``, ``ast2600-evb``, ``ast2700-evb``, ``bletchley-bmc``, ``fuji-bmc``, ``fby35-bmc``, ``fp5280g2-bmc``, ``g220a-bmc``, ``palmetto-bmc``, ``qcom-dc-scm-v1-bmc``, ``qcom-firework-bmc``, ``quanta-q71l-bmc``, ``rainier-bmc``, ``romulus-bmc``, ``sonorapass-bmc``, ``supermicrox11-bmc``, ``tiogapass-bmc``, ``tacoma-bmc``, ``witherspoon-bmc``, ``yosemitev2-bmc``)
> +========================================================================================================================================================================================================================================================================================================================================================================================================
>   
>   The QEMU Aspeed machines model BMCs of various OpenPOWER systems and
>   Aspeed evaluation boards. They are based on different releases of the
> diff --git a/docs/system/arm/nuvoton.rst b/docs/system/arm/nuvoton.rst
> index 0424cae4b01..05059378e55 100644
> --- a/docs/system/arm/nuvoton.rst
> +++ b/docs/system/arm/nuvoton.rst
> @@ -1,5 +1,5 @@
> -Nuvoton iBMC boards (``*-bmc``, ``npcm750-evb``, ``quanta-gsj``)
> -================================================================
> +Nuvoton iBMC boards (``kudo-bmc``, ``mori-bmc``, ``npcm750-evb``, ``quanta-gbs-bmc``, ``quanta-gsj``)
> +=====================================================================================================
>   
>   The `Nuvoton iBMC`_ chips (NPCM7xx) are a family of ARM-based SoCs that are
>   designed to be used as Baseboard Management Controllers (BMCs) in various

Re: [PATCH 7/7] docs/system/target-arm.rst: Remove "many boards are undocumented" note

[Cédric Le Goater]

On 10/18/24 16:13, Peter Maydell wrote:
> We now have at least placeholder documentation for every Arm board,
> so we can remove the apologetic note that says that there are
> undocumented ones which you can only find out about via the
> ``--machine help`` option.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   docs/system/target-arm.rst | 4 ----
>   1 file changed, 4 deletions(-)
> 
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 1f806cf4a46..9aaa9c414c9 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -63,10 +63,6 @@ large amounts of RAM. It also supports 64-bit CPUs.
>   Board-specific documentation
>   ============================
>   
> -Unfortunately many of the Arm boards QEMU supports are currently
> -undocumented; you can get a complete list by running
> -``qemu-system-aarch64 --machine help``.
> -
>   ..
>      This table of contents should be kept sorted alphabetically
>      by the title text of each file, which isn't the same ordering


Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.

Re: [PATCH 4/7] docs/system/arm: Add placeholder doc for exynos4 boards

[Cédric Le Goater]

On 10/18/24 16:13, Peter Maydell wrote:
> Add a placeholder doc for the exynos4 boards nuri and smdkc210.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>


Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.


> ---
>   MAINTAINERS                | 1 +
>   docs/system/arm/exynos.rst | 9 +++++++++
>   docs/system/target-arm.rst | 1 +
>   3 files changed, 11 insertions(+)
>   create mode 100644 docs/system/arm/exynos.rst
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index dff8073c5bc..031b117a3a0 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -716,6 +716,7 @@ L: qemu-arm@nongnu.org
>   S: Odd Fixes
>   F: hw/*/exynos*
>   F: include/hw/*/exynos*
> +F: docs/system/arm/exynos.rst
>   
>   Calxeda Highbank
>   M: Rob Herring <robh@kernel.org>
> diff --git a/docs/system/arm/exynos.rst b/docs/system/arm/exynos.rst
> new file mode 100644
> index 00000000000..86894bc02b7
> --- /dev/null
> +++ b/docs/system/arm/exynos.rst
> @@ -0,0 +1,9 @@
> +Exynos4 boards (``nuri``, ``smdkc210``)
> +=======================================
> +
> +These are machines which use the Samsung Exynos4210 SoC, which has Cortex-A9 CPUs.
> +
> +``nuri`` models the Samsung NURI board.
> +
> +``smdkc210`` models the Samsung SMDKC210 board.
> +
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 9c01e66ffa9..a7f88c8f317 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -90,6 +90,7 @@ undocumented; you can get a complete list by running
>      arm/digic
>      arm/cubieboard
>      arm/emcraft-sf2
> +   arm/exynos
>      arm/fby35
>      arm/musicpal
>      arm/kzm

Re: [PATCH 6/7] docs/system/arm: Add placeholder docs for mcimx6ul-evk and mcimx7d-sabre

[Cédric Le Goater]

On 10/18/24 16:13, Peter Maydell wrote:
> Add placeholder docs for the mcimx6ul-evk and mcimx7d-sabre boards.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>


Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.


> ---
>   MAINTAINERS                       | 2 ++
>   docs/system/arm/mcimx6ul-evk.rst  | 5 +++++
>   docs/system/arm/mcimx7d-sabre.rst | 5 +++++
>   docs/system/target-arm.rst        | 2 ++
>   4 files changed, 14 insertions(+)
>   create mode 100644 docs/system/arm/mcimx6ul-evk.rst
>   create mode 100644 docs/system/arm/mcimx7d-sabre.rst
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 7c3325628c9..2866737261b 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -791,6 +791,7 @@ F: hw/arm/fsl-imx6ul.c
>   F: hw/misc/imx6ul_ccm.c
>   F: include/hw/arm/fsl-imx6ul.h
>   F: include/hw/misc/imx6ul_ccm.h
> +F: docs/system/arm/mcimx6ul-evk.rst
>   
>   MCIMX7D SABRE / i.MX7
>   M: Peter Maydell <peter.maydell@linaro.org>
> @@ -804,6 +805,7 @@ F: include/hw/arm/fsl-imx7.h
>   F: include/hw/misc/imx7_*.h
>   F: hw/pci-host/designware.c
>   F: include/hw/pci-host/designware.h
> +F: docs/system/arm/mcimx7d-sabre.rst
>   
>   MPS2 / MPS3
>   M: Peter Maydell <peter.maydell@linaro.org>
> diff --git a/docs/system/arm/mcimx6ul-evk.rst b/docs/system/arm/mcimx6ul-evk.rst
> new file mode 100644
> index 00000000000..8871138ab3e
> --- /dev/null
> +++ b/docs/system/arm/mcimx6ul-evk.rst
> @@ -0,0 +1,5 @@
> +NXP MCIMX6UL-EVK (``mcimx6ul-evk``)
> +===================================
> +
> +The ``mcimx6ul-evk`` machine models the NXP i.MX6UltraLite Evaluation Kit
> +MCIMX6UL-EVK development board. It has a single Cortex-A7 CPU.
> diff --git a/docs/system/arm/mcimx7d-sabre.rst b/docs/system/arm/mcimx7d-sabre.rst
> new file mode 100644
> index 00000000000..c5d35af1d44
> --- /dev/null
> +++ b/docs/system/arm/mcimx7d-sabre.rst
> @@ -0,0 +1,5 @@
> +NXP MCIMX7D Sabre (``mcimx7d-sabre``)
> +=====================================
> +
> +The ``mcimx7d-sabre`` machine models the NXP SABRE Board MCIMX7SABRE,
> +based an an i.MX7Dual SoC.
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index ace36d1b17d..1f806cf4a46 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -97,6 +97,8 @@ undocumented; you can get a complete list by running
>      arm/nrf
>      arm/nuvoton
>      arm/imx25-pdk
> +   arm/mcimx6ul-evk
> +   arm/mcimx7d-sabre
>      arm/orangepi
>      arm/raspi
>      arm/collie