[PATCH 0/5] docs/system: Document some arm board models

[PATCH 0/5] docs/system: Document some arm board models

[Peter Maydell]

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

[PATCH 1/5] docs/system: Add 'Arm' to the Integrator/CP document title

[Peter Maydell]

Add 'Arm' to the Integrator/CP document title, for consistency with
the titling of the other documentation of Arm devboard models
(versatile, realview).

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

diff --git a/docs/system/arm/integratorcp.rst b/docs/system/arm/integratorcp.rst
index e6f050f602b..594438008e4 100644
--- a/docs/system/arm/integratorcp.rst
+++ b/docs/system/arm/integratorcp.rst
@@ -1,5 +1,5 @@
-Integrator/CP (``integratorcp``)
-================================
+Arm Integrator/CP (``integratorcp``)
+====================================
 
 The Arm Integrator/CP board is emulated with the following devices:
 
-- 
2.20.1

[PATCH 2/5] docs/system: Sort Arm board index into alphabetical order

[Peter Maydell]

Sort the board index into alphabetical order.  (Note that we need to
sort alphabetically by the title text of each file, which isn't the
same ordering as sorting by the filename.)

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

diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index 324e2af1cbc..d1196cbe01c 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -71,15 +71,15 @@ undocumented; you can get a complete list by running
    :maxdepth: 1
 
    arm/integratorcp
-   arm/versatile
    arm/realview
-   arm/xscale
-   arm/palm
-   arm/nseries
-   arm/stellaris
+   arm/versatile
    arm/musicpal
-   arm/sx1
+   arm/nseries
    arm/orangepi
+   arm/palm
+   arm/xscale
+   arm/sx1
+   arm/stellaris
 
 Arm CPU features
 ================
-- 
2.20.1

[PATCH 3/5] docs/system: Document Arm Versatile Express boards

[Peter Maydell]

Provide a minimal documentation of the Versatile Express boards
(vexpress-a9, vexpress-a15).

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

diff --git a/docs/system/arm/vexpress.rst b/docs/system/arm/vexpress.rst
new file mode 100644
index 00000000000..7f1bcbef078
--- /dev/null
+++ b/docs/system/arm/vexpress.rst
@@ -0,0 +1,60 @@
+Arm Versatile Express boards (``vexpress-a9``, ``vexpress-a15``)
+================================================================
+
+QEMU models two variants of the Arm Versatile Express development
+board family:
+
+- ``vexpress-a9`` models the combination of the Versatile Express
+  motherboard and the CoreTile Express A9x4 daughterboard
+- ``vexpress-a15`` models the combination of the Versatile Express
+  motherboard and the CoreTile Express A15x2 daughterboard
+
+Note that as this hardware does not have PCI, IDE or SCSI,
+the only available storage option is emulated SD card.
+
+Implemented devices:
+
+- PL041 audio
+- PL181 SD controller
+- PL050 keyboard and mouse
+- PL011 UARTs
+- SP804 timers
+- I2C controller
+- PL031 RTC
+- PL111 LCD display controller
+- Flash memory
+- LAN9118 ethernet
+
+Unimplemented devices:
+
+- SP810 system control block
+- PCI-express
+- USB controller (Philips ISP1761)
+- Local DAP ROM
+- CoreSight interfaces
+- PL301 AXI interconnect
+- SCC
+- System counter
+- HDLCD controller (``vexpress-a15``)
+- SP805 watchdog
+- PL341 dynamic memory controller
+- DMA330 DMA controller
+- PL354 static memory controller
+- BP147 TrustZone Protection Controller
+- TrustZone Address Space Controller
+
+Other differences between the hardware and the QEMU model:
+
+- QEMU will default to creating one CPU unless you pass a different
+  ``-smp`` argument
+- QEMU allows the amount of RAM provided to be specified with the
+  ``-m`` argument
+- QEMU defaults to providing a CPU which does not provide either
+  TrustZone or the Virtualization Extensions: if you want these you
+  must enable them with ``-machine secure=on`` and ``-machine
+  virtualization=on``
+- QEMU provides 4 virtio-mmio virtio transports; these start at
+  address ``0x10013000`` for ``vexpress-a9`` and at ``0x1c130000`` for
+  ``vexpress-a15``, and have IRQs from 40 upwards. If a dtb is
+  provided on the command line then QEMU will edit it to include
+  suitable entries describing these transports for the guest.
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index d1196cbe01c..4779293d731 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -73,6 +73,7 @@ undocumented; you can get a complete list by running
    arm/integratorcp
    arm/realview
    arm/versatile
+   arm/vexpress
    arm/musicpal
    arm/nseries
    arm/orangepi
diff --git a/MAINTAINERS b/MAINTAINERS
index 1f84e3ae2c6..74cff1c3818 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -826,6 +826,7 @@ M: Peter Maydell <peter.maydell@linaro.org>
 L: qemu-arm@nongnu.org
 S: Maintained
 F: hw/arm/vexpress.c
+F: docs/system/arm/vexpress.rst
 
 Versatile PB
 M: Peter Maydell <peter.maydell@linaro.org>
-- 
2.20.1

[PATCH 4/5] docs/system: Document the various MPS2 models

[Peter Maydell]

Add basic documentation of the MPS2 board models.

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

diff --git a/docs/system/arm/mps2.rst b/docs/system/arm/mps2.rst
new file mode 100644
index 00000000000..3a98cb59b0d
--- /dev/null
+++ b/docs/system/arm/mps2.rst
@@ -0,0 +1,29 @@
+Arm MPS2 boards (``mps2-an385``, ``mps2-an505``, ``mps2-an511``, ``mps2-an521``)
+================================================================================
+
+These board models all use Arm M-profile CPUs.
+
+The Arm MPS2 and MPS2+ dev boards are FPGA based (the 2+ has a bigger
+FPGA but is otherwise the same as the 2). Since the CPU itself
+and most of the devices are in the FPGA, the details of the board
+as seen by the guest depend significantly on the FPGA image.
+
+QEMU models the following FPGA images:
+
+``mps2-an385``
+  Cortex-M3 as documented in ARM Application Note AN385
+``mps2-an511``
+  Cortex-M3 'DesignStart' as documented in AN511
+``mps2-an505``
+  Cortex-M33 as documented in ARM Application Note AN505
+``mps2-an521``
+  Dual Cortex-M33 as documented in Application Note AN521
+
+Differences between QEMU and real hardware:
+
+- AN385 remapping of low 16K of memory to either ZBT SSRAM1 or to
+  block RAM is unimplemented (QEMU always maps this to ZBT SSRAM1, as
+  if zbt_boot_ctrl is always zero)
+- QEMU provides a LAN9118 ethernet rather than LAN9220; the only guest
+  visible difference is that the LAN9118 doesn't support checksum
+  offloading
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index 4779293d731..15bcf9f81f0 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -71,6 +71,7 @@ undocumented; you can get a complete list by running
    :maxdepth: 1
 
    arm/integratorcp
+   arm/mps2
    arm/realview
    arm/versatile
    arm/vexpress
diff --git a/MAINTAINERS b/MAINTAINERS
index 74cff1c3818..ea7bdd359e0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -699,6 +699,7 @@ F: hw/misc/armsse-cpuid.c
 F: include/hw/misc/armsse-cpuid.h
 F: hw/misc/armsse-mhu.c
 F: include/hw/misc/armsse-mhu.h
+F: docs/system/arm/mps2.rst
 
 Musca
 M: Peter Maydell <peter.maydell@linaro.org>
-- 
2.20.1

[PATCH 5/5] docs/system: Document Musca boards

[Peter Maydell]

Provide a minimal documentation of the Musca boards.

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

diff --git a/docs/system/arm/musca.rst b/docs/system/arm/musca.rst
new file mode 100644
index 00000000000..8375c5008d5
--- /dev/null
+++ b/docs/system/arm/musca.rst
@@ -0,0 +1,31 @@
+Arm Musca boards (``musca-a``, ``musca-b1``)
+============================================
+
+The Arm Musca development boards are a reference implementation
+of a system using the SSE-200 subsystem for embedded. They are
+dual Cortex-M33 systems.
+
+QEMU provides models of the A and B1 variants of this board.
+
+Unimplemented devices:
+
+- SPI
+- |I2C|
+- |I2S|
+- PWM
+- QSPI
+- Timer
+- SCC
+- GPIO
+- eFlash
+- MHU
+- PVT
+- SDIO
+- CryptoCell
+
+Note that (like the real hardware) the Musca-A machine is
+asymmetric: CPU 0 does not have the FPU or DSP extensions,
+but CPU 1 does. Also like the real hardware, the memory maps
+for the A and B1 variants differ significantly, so guest
+software must be built for the right variant.
+
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index 15bcf9f81f0..1b86b93c346 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -72,6 +72,7 @@ undocumented; you can get a complete list by running
 
    arm/integratorcp
    arm/mps2
+   arm/musca
    arm/realview
    arm/versatile
    arm/vexpress
diff --git a/MAINTAINERS b/MAINTAINERS
index ea7bdd359e0..f8e0fdb4ef2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -706,6 +706,7 @@ M: Peter Maydell <peter.maydell@linaro.org>
 L: qemu-arm@nongnu.org
 S: Maintained
 F: hw/arm/musca.c
+F: docs/system/arm/musca.rst
 
 Musicpal
 M: Jan Kiszka <jan.kiszka@web.de>
-- 
2.20.1

Re: [PATCH 0/5] docs/system: Document some arm board models

[Peter Maydell]

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
>

Re: [PATCH 1/5] docs/system: Add 'Arm' to the Integrator/CP document title

[Edgar E. Iglesias]

On Thu, May 07, 2020 at 04:18:15PM +0100, Peter Maydell wrote:
> Add 'Arm' to the Integrator/CP document title, for consistency with
> the titling of the other documentation of Arm devboard models
> (versatile, realview).

Reviewed-by: Edgar E. Iglesias <edgar.iglesias@xilinx.com>



> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/system/arm/integratorcp.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/system/arm/integratorcp.rst b/docs/system/arm/integratorcp.rst
> index e6f050f602b..594438008e4 100644
> --- a/docs/system/arm/integratorcp.rst
> +++ b/docs/system/arm/integratorcp.rst
> @@ -1,5 +1,5 @@
> -Integrator/CP (``integratorcp``)
> -================================
> +Arm Integrator/CP (``integratorcp``)
> +====================================
>  
>  The Arm Integrator/CP board is emulated with the following devices:
>  
> -- 
> 2.20.1
> 
> 

Re: [PATCH 2/5] docs/system: Sort Arm board index into alphabetical order

[Edgar E. Iglesias]

On Thu, May 07, 2020 at 04:18:16PM +0100, Peter Maydell wrote:
> Sort the board index into alphabetical order.  (Note that we need to
> sort alphabetically by the title text of each file, which isn't the
> same ordering as sorting by the filename.)

Reviewed-by: Edgar E. Iglesias <edgar.iglesias@xilinx.com>


> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/system/target-arm.rst | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 324e2af1cbc..d1196cbe01c 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -71,15 +71,15 @@ undocumented; you can get a complete list by running
>     :maxdepth: 1
>  
>     arm/integratorcp
> -   arm/versatile
>     arm/realview
> -   arm/xscale
> -   arm/palm
> -   arm/nseries
> -   arm/stellaris
> +   arm/versatile
>     arm/musicpal
> -   arm/sx1
> +   arm/nseries
>     arm/orangepi
> +   arm/palm
> +   arm/xscale
> +   arm/sx1
> +   arm/stellaris
>  
>  Arm CPU features
>  ================
> -- 
> 2.20.1
> 
> 

Re: [PATCH 3/5] docs/system: Document Arm Versatile Express boards

[Edgar E. Iglesias]

On Thu, May 07, 2020 at 04:18:17PM +0100, Peter Maydell wrote:
> Provide a minimal documentation of the Versatile Express boards
> (vexpress-a9, vexpress-a15).

Reviewed-by: Edgar E. Iglesias <edgar.iglesias@xilinx.com>


> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/system/arm/vexpress.rst | 60 ++++++++++++++++++++++++++++++++++++
>  docs/system/target-arm.rst   |  1 +
>  MAINTAINERS                  |  1 +
>  3 files changed, 62 insertions(+)
>  create mode 100644 docs/system/arm/vexpress.rst
> 
> diff --git a/docs/system/arm/vexpress.rst b/docs/system/arm/vexpress.rst
> new file mode 100644
> index 00000000000..7f1bcbef078
> --- /dev/null
> +++ b/docs/system/arm/vexpress.rst
> @@ -0,0 +1,60 @@
> +Arm Versatile Express boards (``vexpress-a9``, ``vexpress-a15``)
> +================================================================
> +
> +QEMU models two variants of the Arm Versatile Express development
> +board family:
> +
> +- ``vexpress-a9`` models the combination of the Versatile Express
> +  motherboard and the CoreTile Express A9x4 daughterboard
> +- ``vexpress-a15`` models the combination of the Versatile Express
> +  motherboard and the CoreTile Express A15x2 daughterboard
> +
> +Note that as this hardware does not have PCI, IDE or SCSI,
> +the only available storage option is emulated SD card.
> +
> +Implemented devices:
> +
> +- PL041 audio
> +- PL181 SD controller
> +- PL050 keyboard and mouse
> +- PL011 UARTs
> +- SP804 timers
> +- I2C controller
> +- PL031 RTC
> +- PL111 LCD display controller
> +- Flash memory
> +- LAN9118 ethernet
> +
> +Unimplemented devices:
> +
> +- SP810 system control block
> +- PCI-express
> +- USB controller (Philips ISP1761)
> +- Local DAP ROM
> +- CoreSight interfaces
> +- PL301 AXI interconnect
> +- SCC
> +- System counter
> +- HDLCD controller (``vexpress-a15``)
> +- SP805 watchdog
> +- PL341 dynamic memory controller
> +- DMA330 DMA controller
> +- PL354 static memory controller
> +- BP147 TrustZone Protection Controller
> +- TrustZone Address Space Controller
> +
> +Other differences between the hardware and the QEMU model:
> +
> +- QEMU will default to creating one CPU unless you pass a different
> +  ``-smp`` argument
> +- QEMU allows the amount of RAM provided to be specified with the
> +  ``-m`` argument
> +- QEMU defaults to providing a CPU which does not provide either
> +  TrustZone or the Virtualization Extensions: if you want these you
> +  must enable them with ``-machine secure=on`` and ``-machine
> +  virtualization=on``
> +- QEMU provides 4 virtio-mmio virtio transports; these start at
> +  address ``0x10013000`` for ``vexpress-a9`` and at ``0x1c130000`` for
> +  ``vexpress-a15``, and have IRQs from 40 upwards. If a dtb is
> +  provided on the command line then QEMU will edit it to include
> +  suitable entries describing these transports for the guest.
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index d1196cbe01c..4779293d731 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -73,6 +73,7 @@ undocumented; you can get a complete list by running
>     arm/integratorcp
>     arm/realview
>     arm/versatile
> +   arm/vexpress
>     arm/musicpal
>     arm/nseries
>     arm/orangepi
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 1f84e3ae2c6..74cff1c3818 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -826,6 +826,7 @@ M: Peter Maydell <peter.maydell@linaro.org>
>  L: qemu-arm@nongnu.org
>  S: Maintained
>  F: hw/arm/vexpress.c
> +F: docs/system/arm/vexpress.rst
>  
>  Versatile PB
>  M: Peter Maydell <peter.maydell@linaro.org>
> -- 
> 2.20.1
> 
> 

Re: [PATCH 4/5] docs/system: Document the various MPS2 models

[Edgar E. Iglesias]

On Thu, May 07, 2020 at 04:18:18PM +0100, Peter Maydell wrote:
> Add basic documentation of the MPS2 board models.
>

Reviewed-by: Edgar E. Iglesias <edgar.iglesias@xilinx.com>

 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/system/arm/mps2.rst   | 29 +++++++++++++++++++++++++++++
>  docs/system/target-arm.rst |  1 +
>  MAINTAINERS                |  1 +
>  3 files changed, 31 insertions(+)
>  create mode 100644 docs/system/arm/mps2.rst
> 
> diff --git a/docs/system/arm/mps2.rst b/docs/system/arm/mps2.rst
> new file mode 100644
> index 00000000000..3a98cb59b0d
> --- /dev/null
> +++ b/docs/system/arm/mps2.rst
> @@ -0,0 +1,29 @@
> +Arm MPS2 boards (``mps2-an385``, ``mps2-an505``, ``mps2-an511``, ``mps2-an521``)
> +================================================================================
> +
> +These board models all use Arm M-profile CPUs.
> +
> +The Arm MPS2 and MPS2+ dev boards are FPGA based (the 2+ has a bigger
> +FPGA but is otherwise the same as the 2). Since the CPU itself
> +and most of the devices are in the FPGA, the details of the board
> +as seen by the guest depend significantly on the FPGA image.
> +
> +QEMU models the following FPGA images:
> +
> +``mps2-an385``
> +  Cortex-M3 as documented in ARM Application Note AN385
> +``mps2-an511``
> +  Cortex-M3 'DesignStart' as documented in AN511
> +``mps2-an505``
> +  Cortex-M33 as documented in ARM Application Note AN505
> +``mps2-an521``
> +  Dual Cortex-M33 as documented in Application Note AN521
> +
> +Differences between QEMU and real hardware:
> +
> +- AN385 remapping of low 16K of memory to either ZBT SSRAM1 or to
> +  block RAM is unimplemented (QEMU always maps this to ZBT SSRAM1, as
> +  if zbt_boot_ctrl is always zero)
> +- QEMU provides a LAN9118 ethernet rather than LAN9220; the only guest
> +  visible difference is that the LAN9118 doesn't support checksum
> +  offloading
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 4779293d731..15bcf9f81f0 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -71,6 +71,7 @@ undocumented; you can get a complete list by running
>     :maxdepth: 1
>  
>     arm/integratorcp
> +   arm/mps2
>     arm/realview
>     arm/versatile
>     arm/vexpress
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 74cff1c3818..ea7bdd359e0 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -699,6 +699,7 @@ F: hw/misc/armsse-cpuid.c
>  F: include/hw/misc/armsse-cpuid.h
>  F: hw/misc/armsse-mhu.c
>  F: include/hw/misc/armsse-mhu.h
> +F: docs/system/arm/mps2.rst
>  
>  Musca
>  M: Peter Maydell <peter.maydell@linaro.org>
> -- 
> 2.20.1
> 
> 

Re: [PATCH 5/5] docs/system: Document Musca boards

[Edgar E. Iglesias]

On Thu, May 07, 2020 at 04:18:19PM +0100, Peter Maydell wrote:
> Provide a minimal documentation of the Musca boards.

Reviewed-by: Edgar E. Iglesias <edgar.iglesias@xilinx.com>



> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/system/arm/musca.rst  | 31 +++++++++++++++++++++++++++++++
>  docs/system/target-arm.rst |  1 +
>  MAINTAINERS                |  1 +
>  3 files changed, 33 insertions(+)
>  create mode 100644 docs/system/arm/musca.rst
> 
> diff --git a/docs/system/arm/musca.rst b/docs/system/arm/musca.rst
> new file mode 100644
> index 00000000000..8375c5008d5
> --- /dev/null
> +++ b/docs/system/arm/musca.rst
> @@ -0,0 +1,31 @@
> +Arm Musca boards (``musca-a``, ``musca-b1``)
> +============================================
> +
> +The Arm Musca development boards are a reference implementation
> +of a system using the SSE-200 subsystem for embedded. They are
> +dual Cortex-M33 systems.
> +
> +QEMU provides models of the A and B1 variants of this board.
> +
> +Unimplemented devices:
> +
> +- SPI
> +- |I2C|
> +- |I2S|
> +- PWM
> +- QSPI
> +- Timer
> +- SCC
> +- GPIO
> +- eFlash
> +- MHU
> +- PVT
> +- SDIO
> +- CryptoCell
> +
> +Note that (like the real hardware) the Musca-A machine is
> +asymmetric: CPU 0 does not have the FPU or DSP extensions,
> +but CPU 1 does. Also like the real hardware, the memory maps
> +for the A and B1 variants differ significantly, so guest
> +software must be built for the right variant.
> +
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 15bcf9f81f0..1b86b93c346 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -72,6 +72,7 @@ undocumented; you can get a complete list by running
>  
>     arm/integratorcp
>     arm/mps2
> +   arm/musca
>     arm/realview
>     arm/versatile
>     arm/vexpress
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ea7bdd359e0..f8e0fdb4ef2 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -706,6 +706,7 @@ M: Peter Maydell <peter.maydell@linaro.org>
>  L: qemu-arm@nongnu.org
>  S: Maintained
>  F: hw/arm/musca.c
> +F: docs/system/arm/musca.rst
>  
>  Musicpal
>  M: Jan Kiszka <jan.kiszka@web.de>
> -- 
> 2.20.1
> 
> 

Re: [PATCH 5/5] docs/system: Document Musca boards

[Philippe Mathieu-Daudé]

On 5/7/20 5:18 PM, Peter Maydell wrote:
> Provide a minimal documentation of the Musca boards.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   docs/system/arm/musca.rst  | 31 +++++++++++++++++++++++++++++++
>   docs/system/target-arm.rst |  1 +
>   MAINTAINERS                |  1 +
>   3 files changed, 33 insertions(+)
>   create mode 100644 docs/system/arm/musca.rst
> 
> diff --git a/docs/system/arm/musca.rst b/docs/system/arm/musca.rst
> new file mode 100644
> index 00000000000..8375c5008d5
> --- /dev/null
> +++ b/docs/system/arm/musca.rst
> @@ -0,0 +1,31 @@
> +Arm Musca boards (``musca-a``, ``musca-b1``)
> +============================================
> +
> +The Arm Musca development boards are a reference implementation
> +of a system using the SSE-200 subsystem for embedded.

Maybe nitpicking, but this sentence seems unfinished.

" ... for embedded [?]."

Maybe triplicate "systems" again?

> They are
> +dual Cortex-M33 systems.
> +
> +QEMU provides models of the A and B1 variants of this board.
> +
> +Unimplemented devices:
> +
> +- SPI
> +- |I2C|
> +- |I2S|
> +- PWM
> +- QSPI
> +- Timer
> +- SCC
> +- GPIO
> +- eFlash
> +- MHU
> +- PVT
> +- SDIO
> +- CryptoCell
> +
> +Note that (like the real hardware) the Musca-A machine is
> +asymmetric: CPU 0 does not have the FPU or DSP extensions,
> +but CPU 1 does. Also like the real hardware, the memory maps
> +for the A and B1 variants differ significantly, so guest
> +software must be built for the right variant.
> +
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 15bcf9f81f0..1b86b93c346 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -72,6 +72,7 @@ undocumented; you can get a complete list by running
>   
>      arm/integratorcp
>      arm/mps2
> +   arm/musca
>      arm/realview
>      arm/versatile
>      arm/vexpress
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ea7bdd359e0..f8e0fdb4ef2 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -706,6 +706,7 @@ M: Peter Maydell <peter.maydell@linaro.org>
>   L: qemu-arm@nongnu.org
>   S: Maintained
>   F: hw/arm/musca.c
> +F: docs/system/arm/musca.rst
>   
>   Musicpal
>   M: Jan Kiszka <jan.kiszka@web.de>
> 

Re: [PATCH 0/5] docs/system: Document some arm board models

[Philippe Mathieu-Daudé]

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
>>
> 

Re: [PATCH 5/5] docs/system: Document Musca boards

[Peter Maydell]

On Fri, 15 May 2020 at 08:56, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>
> On 5/7/20 5:18 PM, Peter Maydell wrote:
> > Provide a minimal documentation of the Musca boards.
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

> > --- /dev/null
> > +++ b/docs/system/arm/musca.rst
> > @@ -0,0 +1,31 @@
> > +Arm Musca boards (``musca-a``, ``musca-b1``)
> > +============================================
> > +
> > +The Arm Musca development boards are a reference implementation
> > +of a system using the SSE-200 subsystem for embedded.
>
> Maybe nitpicking, but this sentence seems unfinished.
>
> " ... for embedded [?]."

That's the name of the IP block:
https://developer.arm.com/docs/101104/latest/introduction/about-the-sse-200

I guess it ought to be capitalized: "SSE-200 Subsystem for Embedded".

thanks
-- PMM

Re: [PATCH 0/5] docs/system: Document some arm board models

[Peter Maydell]

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

Re: [PATCH 1/5] docs/system: Add 'Arm' to the Integrator/CP document title

[Alex Bennée]

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

> Add 'Arm' to the Integrator/CP document title, for consistency with
> the titling of the other documentation of Arm devboard models
> (versatile, realview).
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

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

> ---
>  docs/system/arm/integratorcp.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/system/arm/integratorcp.rst b/docs/system/arm/integratorcp.rst
> index e6f050f602b..594438008e4 100644
> --- a/docs/system/arm/integratorcp.rst
> +++ b/docs/system/arm/integratorcp.rst
> @@ -1,5 +1,5 @@
> -Integrator/CP (``integratorcp``)
> -================================
> +Arm Integrator/CP (``integratorcp``)
> +====================================
>  
>  The Arm Integrator/CP board is emulated with the following devices:


-- 
Alex Bennée

Re: [PATCH 0/5] docs/system: Document some arm board models

[Philippe Mathieu-Daudé]

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
> 

Re: [PATCH 5/5] docs/system: Document Musca boards

[Philippe Mathieu-Daudé]

On 5/15/20 10:48 AM, Peter Maydell wrote:
> On Fri, 15 May 2020 at 08:56, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>>
>> On 5/7/20 5:18 PM, Peter Maydell wrote:
>>> Provide a minimal documentation of the Musca boards.
>>>
>>> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> 
>>> --- /dev/null
>>> +++ b/docs/system/arm/musca.rst
>>> @@ -0,0 +1,31 @@
>>> +Arm Musca boards (``musca-a``, ``musca-b1``)
>>> +============================================
>>> +
>>> +The Arm Musca development boards are a reference implementation
>>> +of a system using the SSE-200 subsystem for embedded.
>>
>> Maybe nitpicking, but this sentence seems unfinished.
>>
>> " ... for embedded [?]."
> 
> That's the name of the IP block:
> https://developer.arm.com/docs/101104/latest/introduction/about-the-sse-200
> 
> I guess it ought to be capitalized: "SSE-200 Subsystem for Embedded".

Ah yes, it is clearer.

> 
> thanks
> -- PMM
> 

Re: [PATCH 2/5] docs/system: Sort Arm board index into alphabetical order

[Alex Bennée]

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

> Sort the board index into alphabetical order.  (Note that we need to
> sort alphabetically by the title text of each file, which isn't the
> same ordering as sorting by the filename.)

Is it possible to leave an inline comment in the rst to this effect so
no one mis-sorts it next time?

Otherwise:

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

-- 
Alex Bennée

Re: [PATCH 3/5] docs/system: Document Arm Versatile Express boards

[Alex Bennée]

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

> Provide a minimal documentation of the Versatile Express boards
> (vexpress-a9, vexpress-a15).
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/system/arm/vexpress.rst | 60 ++++++++++++++++++++++++++++++++++++
>  docs/system/target-arm.rst   |  1 +
>  MAINTAINERS                  |  1 +
>  3 files changed, 62 insertions(+)
>  create mode 100644 docs/system/arm/vexpress.rst
>
> diff --git a/docs/system/arm/vexpress.rst b/docs/system/arm/vexpress.rst
> new file mode 100644
> index 00000000000..7f1bcbef078
> --- /dev/null
> +++ b/docs/system/arm/vexpress.rst
> @@ -0,0 +1,60 @@
> +Arm Versatile Express boards (``vexpress-a9``, ``vexpress-a15``)
> +================================================================
> +
> +QEMU models two variants of the Arm Versatile Express development
> +board family:
> +
> +- ``vexpress-a9`` models the combination of the Versatile Express
> +  motherboard and the CoreTile Express A9x4 daughterboard
> +- ``vexpress-a15`` models the combination of the Versatile Express
> +  motherboard and the CoreTile Express A15x2 daughterboard
> +
> +Note that as this hardware does not have PCI, IDE or SCSI,
> +the only available storage option is emulated SD card.
> +
> +Implemented devices:
> +
> +- PL041 audio
> +- PL181 SD controller
> +- PL050 keyboard and mouse
> +- PL011 UARTs
> +- SP804 timers
> +- I2C controller
> +- PL031 RTC
> +- PL111 LCD display controller
> +- Flash memory
> +- LAN9118 ethernet
> +
> +Unimplemented devices:
> +
> +- SP810 system control block
> +- PCI-express
> +- USB controller (Philips ISP1761)
> +- Local DAP ROM
> +- CoreSight interfaces
> +- PL301 AXI interconnect
> +- SCC
> +- System counter
> +- HDLCD controller (``vexpress-a15``)
> +- SP805 watchdog
> +- PL341 dynamic memory controller
> +- DMA330 DMA controller
> +- PL354 static memory controller
> +- BP147 TrustZone Protection Controller
> +- TrustZone Address Space Controller
> +
> +Other differences between the hardware and the QEMU model:
> +
> +- QEMU will default to creating one CPU unless you pass a different
> +  ``-smp`` argument
> +- QEMU allows the amount of RAM provided to be specified with the
> +  ``-m`` argument
> +- QEMU defaults to providing a CPU which does not provide either
> +  TrustZone or the Virtualization Extensions: if you want these you
> +  must enable them with ``-machine secure=on`` and ``-machine
> +  virtualization=on``
> +- QEMU provides 4 virtio-mmio virtio transports; these start at
> +  address ``0x10013000`` for ``vexpress-a9`` and at ``0x1c130000`` for
> +  ``vexpress-a15``, and have IRQs from 40 upwards. If a dtb is
> +  provided on the command line then QEMU will edit it to include
> +  suitable entries describing these transports for the guest.

TIL ;-)

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

-- 
Alex Bennée

Re: [PATCH 4/5] docs/system: Document the various MPS2 models

[Alex Bennée]

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

> Add basic documentation of the MPS2 board models.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

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

-- 
Alex Bennée

Re: [PATCH 5/5] docs/system: Document Musca boards

[Alex Bennée]

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

> Provide a minimal documentation of the Musca boards.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

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

-- 
Alex Bennée

Re: [PATCH 0/5] docs/system: Document some arm board models

[Peter Maydell]

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