hw/arm: add AX650X Pyramid Linux boot model

MAINTAINERS

@@ -882,6 +882,22 @@ F: include/hw/misc/arm_integrator_debug.h
 F: tests/functional/arm/test_integratorcp.py
 F: docs/system/arm/integratorcp.rst
 
+M5Stack AI Pyramid (AX650X)
+M: Chao Liu <[email protected]>
+L: [email protected]
+S: Maintained
+F: docs/system/arm/ax650x-pyramid.rst
+F: hw/arm/ax650x*.c
+F: hw/gpio/dw-apb-gpio.c
+F: hw/misc/ax650x-*.c
+F: hw/sd/ax650x-sdhci.c
+F: include/hw/arm/ax650x*.h
+F: include/hw/gpio/dw-apb-gpio.h
+F: include/hw/misc/ax650x-*.h
+F: include/hw/sd/ax650x-sdhci.h
+F: tests/functional/aarch64/test_ax650x_ubuntu.py
+F: tests/qtest/ax650x-pyramid-test.c
+
 MAX78000FTHR
 L: [email protected]
 S: Orphan

README.md

@@ -15,6 +15,7 @@ for new machine requests or bug reports.
 | RISC-V | [`k3-pico-itx`](docs/system/riscv/spacemit-k3.rst) | ✅ | ✅ | PM |
 | RISC-V | [`milkv-duo`](docs/system/riscv/milkv-duo.rst) | ✅ | ✅ | UP |
 | RISC-V | [`riscv-server-ref`](docs/system/riscv/riscv-server-ref.rst) | ✅ | ✅ | UP |
+| ARM | [`ax650x-pyramid`](docs/system/arm/ax650x-pyramid.rst) | ✅ | ❌ | PM |
 | ARM | [`phytium-pi`](docs/system/arm/phytium-pi.rst) | ✅ | ✅ | PM |
 | ARM | [`rk3588-evb`](docs/system/arm/rk3588.rst) | ✅ | ✅ | PM |
 | ARM | [`rk3588s-roc-pc`](docs/system/arm/rk3588.rst) | ✅ | ✅ | PM |
@@ -34,3 +35,77 @@ It provides agent skills for planning, register extraction, peripheral modeling,
 board modeling, qtest, build, debugging, and verification.
 
 - Skill repository: <https://github.com/processmission/oh-my-qemu>
+
+## AX650X Pyramid quick start
+
+The `ax650x-pyramid` machine directly boots Linux on the M5Stack AI Pyramid /
+AXERA AX650X platform. Detailed machine documentation is available in
+[docs/system/arm/ax650x-pyramid.rst](docs/system/arm/ax650x-pyramid.rst).
+
+### Boot Ubuntu 22.04 from eMMC
+
+The Ubuntu image has no MBR or GPT. Linux creates its twelve partitions from
+the fixed `blkdevparts` command line. The command below uses `snapshot=on`, so
+guest writes are discarded when QEMU exits.
+
+```sh
+QEMU=${QEMU:-build/qemu-system-aarch64}
+ASSET_DIR=${ASSET_DIR:-assets/ax650x}
+KERNEL=${KERNEL:-$ASSET_DIR/Image-5.15.73-axera}
+EMMC=${EMMC:-$ASSET_DIR/ax650x-ubuntu-22.04-emmc.raw}
+
+PARTS='mmcblk0:1536K(uboot),1536K(uboot_bk),1M(env),20M(param)'
+PARTS="$PARTS,6M(logo),1M(dtb),64M(kernel),1M(atf),1M(optee)"
+PARTS="$PARTS,1M(recovery_dtb),74M(recovery),30380032K(rootfs)"
+CMDLINE='console=ttyS0,115200n8 earlycon=uart8250,mmio32,0x2016000'
+CMDLINE="$CMDLINE root=/dev/mmcblk0p12 rootfstype=ext4 rw rootwait"
+CMDLINE="$CMDLINE blkdevparts=$PARTS"
+CMDLINE="$CMDLINE systemd.show_status=yes systemd.log_target=console"
+
+for input in "$QEMU" "$KERNEL" "$EMMC"; do
+    if [ ! -r "$input" ]; then
+        echo "missing input: $input" >&2
+        exit 1
+    fi
+done
+
+exec "$QEMU" \
+    -machine ax650x-pyramid \
+    -accel tcg,thread=multi \
+    -cpu cortex-a55 \
+    -smp 8 \
+    -m 2G \
+    -kernel "$KERNEL" \
+    -append "$CMDLINE" \
+    -drive "file=$EMMC,if=sd,format=raw,snapshot=on" \
+    -chardev stdio,id=serial0,signal=off \
+    -serial chardev:serial0 \
+    -display none \
+    -monitor none \
+    -no-reboot
+```
+
+Override `QEMU`, `KERNEL`, or `EMMC` in the environment when the artifacts
+live elsewhere. Remove `snapshot=on` only when persistent image writes are
+intentional.
+
+### Run the Ubuntu quick-boot functional test
+
+The functional test uses the same direct-boot contract but lets the test
+harness own the serial chardev. It is in the `thorough` suite because the
+kernel and compressed eMMC image are downloaded assets.
+
+```sh
+meson test -C build \
+    --suite thorough \
+    func-aarch64-ax650x_ubuntu \
+    --print-errorlogs
+```
+
+The pinned kernel and qcow2 image are published at:
+
+<https://github.com/processmission/qemu/releases/tag/ax650x-ubuntu-22.04-qemu1>
+
+The harness verifies both SHA-256 digests. The test uses disposable eMMC
+writes and waits for DWMAC probe, partition 12, the mounted ext4 root
+filesystem, Ubuntu readiness markers, and the serial login prompt.

docs/system/arm/ax650x-pyramid.rst

@@ -0,0 +1,142 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+M5Stack AI Pyramid (``ax650x-pyramid``)
+========================================
+
+Overview
+--------
+
+The ``ax650x-pyramid`` machine models the Linux boot subset of the M5Stack
+AI Pyramid, whose runtime device tree identifies the SoC as
+``axera,ax650x``.  The model is intended for direct kernel boot with an
+AX650X-enabled Arm64 Linux kernel.  It does not model the product's AXERA
+accelerators or firmware boot chain.
+
+The machine has a fixed topology matching the target system: eight Cortex-A55
+CPUs and 2 GiB of RAM starting at physical address ``0x100000000``.  Other CPU
+counts and memory sizes are rejected.
+
+Supported devices
+-----------------
+
+The machine provides the following devices and architectural services:
+
+* eight Cortex-A55 CPUs, with MPIDRs ``0x000`` through ``0x700``;
+* GIC-400 compatible GICv2 interrupt controller with virtualization
+  extensions;
+* Arm generic timers running at 24 MHz;
+* PSCI 1.0 using the SMC conduit;
+* the AXERA UART0 console at ``0x02016000``, including the extension
+  registers needed by the AXERA 8250 driver;
+* an AX650X SDHCI/eMMC controller at ``0x28000000``, including the vendor PHY
+  and eMMC registers used during Linux probe;
+* two Synopsys DWMAC 4.10a compatible Ethernet controllers, including the
+  AX650X clock/reset glue, MDIO PHY identity, DMA and interrupt paths;
+* the DesignWare APB GPIO blocks used for PHY reset; and
+* the AX650X hardware spinlock block used by the GPIO driver.
+
+QEMU generates a minimal device tree containing only those implemented
+devices.  An eMMC backend supplied with ``if=sd`` is attached to the AX650X
+controller.
+
+Direct Linux boot
+-----------------
+
+The model requires an uncompressed Arm64 ``Image`` containing the AXERA UART
+and SDHCI drivers.  The following example boots an ext4 root filesystem from
+partition 12 of an eMMC image that uses the target's fixed partition layout.
+The image has no MBR or GPT, so the complete ``blkdevparts`` argument is
+required:
+
+.. code-block:: shell
+
+  QEMU=${QEMU:-build/qemu-system-aarch64}
+  ASSET_DIR=${ASSET_DIR:-assets/ax650x}
+  KERNEL=${KERNEL:-$ASSET_DIR/Image-5.15.73-axera}
+  EMMC=${EMMC:-$ASSET_DIR/ax650x-ubuntu-22.04-emmc.raw}
+
+  PARTS='mmcblk0:1536K(uboot),1536K(uboot_bk),1M(env),20M(param)'
+  PARTS="$PARTS,6M(logo),1M(dtb),64M(kernel),1M(atf),1M(optee)"
+  PARTS="$PARTS,1M(recovery_dtb),74M(recovery),30380032K(rootfs)"
+  CMDLINE='console=ttyS0,115200n8 earlycon=uart8250,mmio32,0x2016000'
+  CMDLINE="$CMDLINE root=/dev/mmcblk0p12 rootfstype=ext4 rw rootwait"
+  CMDLINE="$CMDLINE blkdevparts=$PARTS"
+  CMDLINE="$CMDLINE systemd.show_status=yes systemd.log_target=console"
+
+  for input in "$QEMU" "$KERNEL" "$EMMC"; do
+      if [ ! -r "$input" ]; then
+          echo "missing input: $input" >&2
+          exit 1
+      fi
+  done
+
+  exec "$QEMU" \
+      -machine ax650x-pyramid \
+      -accel tcg,thread=multi \
+      -cpu cortex-a55 \
+      -smp 8 \
+      -m 2G \
+      -kernel "$KERNEL" \
+      -append "$CMDLINE" \
+      -drive "file=$EMMC,if=sd,format=raw,snapshot=on" \
+      -chardev stdio,id=serial0,signal=off \
+      -serial chardev:serial0 \
+      -display none \
+      -monitor none \
+      -no-reboot
+
+``snapshot=on`` keeps the reusable eMMC image unchanged.  Remove it only when
+persistent guest writes are intentional.
+
+The downstream model has been exercised with an AXERA Linux 5.15.73 kernel
+and Ubuntu 22.04.5 LTS.  Linux enumerates all eight CPUs, probes the eMMC using
+64-bit ADMA, creates the twelve fixed partitions, and mounts
+``/dev/mmcblk0p12`` as the writable root filesystem.
+
+Known limitations
+-----------------
+
+* Only QEMU direct kernel boot is implemented.  BootROM, SPL, U-Boot, Arm
+  Trusted Firmware and OP-TEE images are not loaded or executed.
+* NPU, VDSP, RISC-V auxiliary cores, video, ISP, display, audio, USB, PCIe,
+  SATA and the full clock, reset and power-management trees are not modeled.
+  GPIO behavior is limited to the DesignWare APB subset needed for PHY reset.
+* DWMAC TSO, PTP/TSN, multi-queue performance fidelity and analog PHY timing
+  are not modeled.
+* The UART extension window implements the probe-time subset.  The AXERA
+  driver can report a harmless capability mismatch because the UART component
+  version register intentionally selects its compatible fallback path.
+* QEMU direct boot starts CPUs at EL2.  The target firmware starts Linux at
+  EL1, so the vendor kernel can print a non-fatal GICv2 CPU-interface range
+  warning under QEMU.
+* The SDHCI vendor bank implements the registers required for probe, reset and
+  data transfer.  HS200/HS400 timing accuracy is not claimed.
+
+Running tests
+-------------
+
+The board qtest covers CPU topology, RAM, GICv2, UART MMIO and IRQ behavior,
+SDHCI vendor registers, reset, block I/O, eMMC IRQ routing, 64-bit ADMA,
+Auto CMD23, DWMAC synthesis registers, MDIO, GPIO and reset glue, hardware
+spinlocks, 40-bit DMA and Ethernet IRQ routing::
+
+  $ meson test -C build qemu:qtest-aarch64/ax650x-pyramid-test \
+      --print-errorlogs
+
+The Ubuntu quick-boot functional test downloads a pinned kernel and compressed
+qcow2 image from the `AX650X Ubuntu 22.04 QEMU assets release
+<https://github.com/processmission/qemu/releases/tag/ax650x-ubuntu-22.04-qemu1>`__.
+The functional asset layer verifies both SHA-256 digests.  The test uses
+``snapshot=on`` and waits for DWMAC probe, the eMMC partition map, the mounted
+root filesystem, Ubuntu readiness markers and the serial login prompt:
+
+.. code-block:: shell
+
+  $ meson test -C build \
+        --suite thorough \
+        func-aarch64-ax650x_ubuntu \
+        --print-errorlogs
+
+The test is registered in the ``thorough`` functional suite because the
+kernel and Ubuntu image are external assets.  A cached copy is reused only
+after its declared content hash has been checked.

docs/system/target-arm.rst

@@ -72,6 +72,7 @@ Board-specific documentation
    :maxdepth: 1
 
    arm/max78000
+   arm/ax650x-pyramid
    arm/integratorcp
    arm/mps2
    arm/musca

hw/arm/Kconfig

@@ -37,6 +37,20 @@ config ARM_VIRT
     select ACPI_CXL
     select ACPI_HMAT
 
+config AX650X_PYRAMID
+    bool
+    default y
+    depends on TCG && AARCH64
+    select ARM_GIC
+    select AX650X_DWMAC_GLUE
+    select AX650X_HWSPINLOCK
+    select AX650X_SDHCI
+    select DEVICE_TREE
+    select DW_APB_GPIO
+    select DWMAC4
+    select SERIAL_MM
+    select UNIMP
+
 config CUBIEBOARD
     bool
     default y