Skip to contentSkip to conversation

aspeed: Add AST1040 Caliptra mailbox support

PATCH RESEND In review Steven Lee 1 participant 8 messages Jun 3 – Jun 22

Subsystems (2)
lore
Share & tools
lore

Steven Lee

author
#0 lore raw

cover aspeed: Add AST1040 Caliptra mailbox support

This series adds AST1040 Caliptra MCI mailbox support for the ast1040-evb machine.

AST1040 firmware accesses Caliptra through an MCI page aperture. This series adds an AST1040 SCU model with the CPTRA page-select registers, a mailbox frontend that exposes the Caliptra SRAM and CSR windows, and an optional external chardev peer so a Caliptra simulator can service EXECUTE requests.

The SoC wiring maps the mailbox SRAM, CSR window and 4 KiB remap aperture. The EVB machine also gets a cptra-peer option for linking the external peer after the machine is initialized.

The external peer backend is intended for co-simulation with an external Caliptra model. The current bring-up backend used for manual testing is caliptra-server:

https://github.com/stevenlee7189/caliptra-server/blob/main-2.x/README.md

That README includes the server command line, the matching QEMU command line, and the guest-side MFWV smoke test sequence used to validate the MCI aperture, LOCK/CMD/DLEN/EXECUTE flow, and FirmwareVersion response. The qtest added by this series does not depend on that repository; it uses a socket-backed test peer to validate the QEMU-side protocol and mailbox flow.

Resending because some reviewers did not receive the previous email. No changes since the prior posting.

Patch layout:
- patches 1-2 add the AST1040 SCU model and mailbox frontend
- patch 3 adds the external chardev peer backend
- patch 4 wires the mailbox into the AST1040 SoC and EVB machine
- patches 5-6 add qtest coverage and documentation

The qtest covers mailbox lock, execute and completion flow through a socket-backed peer, and verifies that SCU CPTRA_PAGE_REG0 remaps the MCI aperture between CSR and SRAM pages.

Validation:
- scripts/checkpatch.pl --branch origin/master..HEAD
- qtest coverage for the AST1040 mailbox execute path with a socket-backed external peer
- manual co-simulation bring-up with caliptra-server through cptra-mbox-peer-extern

Steven Lee (6):
hw/misc/aspeed_scu: Add AST1040 SCU model hw/misc: Add ASPEED Caliptra mailbox frontend hw/misc: Add external Caliptra mailbox peer hw/arm/aspeed_ast1040: Wire Caliptra mailbox tests/qtest: Add ASPEED Caliptra mailbox test docs/system/arm: Document AST1040 Caliptra mailbox

 MAINTAINERS                          |   1 +
 docs/system/arm/aspeed.rst           |  32 +++
 include/hw/arm/aspeed_soc.h          |  11 +
 include/hw/misc/aspeed_cptra_mbox.h  | 133 ++++++++++
 include/hw/misc/aspeed_scu.h         |  10 +
 hw/arm/aspeed_ast1040.c              |  60 ++++-
 hw/arm/aspeed_ast1040_evb.c          |  74 +++++-
 hw/misc/aspeed_cptra_mbox.c          | 380 +++++++++++++++++++++++++++
 hw/misc/aspeed_scu.c                 | 251 ++++++++++++++++++
 hw/misc/cptra_mbox_peer_extern.c     | 318 ++++++++++++++++++++++
 tests/qtest/aspeed_cptra_mbox-test.c | 223 ++++++++++++++++
 hw/misc/meson.build                  |   2 +
 hw/misc/trace-events                 |   6 +
 tests/qtest/meson.build              |   3 +-
 14 files changed, 1498 insertions(+), 6 deletions(-)
 create mode 100644 include/hw/misc/aspeed_cptra_mbox.h
 create mode 100644 hw/misc/aspeed_cptra_mbox.c
 create mode 100644 hw/misc/cptra_mbox_peer_extern.c
 create mode 100644 tests/qtest/aspeed_cptra_mbox-test.c
Signature · 1 line
2.43.0
author
#1 lore raw

PATCH RESEND 1/6 hw/misc/aspeed_scu: Add AST1040 SCU model

Add an AST1040 variant of the ASPEED SCU with reset values, APB clock calculation, clock-stop handling, and CPTRA page-select registers.

Expose the Caliptra page aperture as a QOM link so the SoC model can wire the remap window without callbacks.

---
 include/hw/misc/aspeed_scu.h |  10 ++
 hw/misc/aspeed_scu.c         | 251 +++++++++++++++++++++++++++++++++++
 hw/misc/trace-events         |   2 +
 3 files changed, 263 insertions(+)
include/hw/misc/aspeed_scu.h +10 -0
index c30940ab76..6445ae5cf4 100644
@@ -22,6 +22,7 @@ OBJECT_DECLARE_TYPE(AspeedSCUState, AspeedSCUClass, ASPEED_SCU)
 #define TYPE_ASPEED_2700_SCU TYPE_ASPEED_SCU "-ast2700"
 #define TYPE_ASPEED_2700_SCUIO TYPE_ASPEED_SCU "io" "-ast2700"
 #define TYPE_ASPEED_1030_SCU TYPE_ASPEED_SCU "-ast1030"
+#define TYPE_ASPEED_1040_SCU TYPE_ASPEED_SCU "-ast1040"
 
 #define ASPEED_SCU_NR_REGS (0x1A8 >> 2)
 #define ASPEED_AST2600_SCU_NR_REGS (0xE20 >> 2)
@@ -39,6 +40,15 @@ struct AspeedSCUState {
     uint32_t hw_strap1;
     uint32_t hw_strap2;
     uint32_t hw_prot_key;
+
+    /*
+     * AST1040 only: alias region (the Caliptra MCI page aperture) whose
+     * target offset is selected by SCU_CPTRA_PAGE_REG0, linked in by the SoC.
+     * cptra_page_window_base is its base in the address map, used to reject a
+     * self-referential remap.
+     */
+    MemoryRegion *cptra_page_window;
+    uint64_t cptra_page_window_base;
 };
 
 #define AST2400_A1_SILICON_REV   0x02010303U
hw/misc/aspeed_scu.c +251 -0

275 lines not on this page · raw message

hw/misc/trace-events +2 -0
index b88accc437..82ddbf4d15 100644
@@ -103,6 +103,8 @@ aspeed_ast2700_scu_write(uint64_t offset, unsigned size, uint32_t data) "To 0x%"
 aspeed_ast2700_scu_read(uint64_t offset, unsigned size, uint32_t data) "To 0x%" PRIx64 " of size %u: 0x%" PRIx32
 aspeed_ast2700_scuio_write(uint64_t offset, unsigned size, uint32_t data) "To 0x%" PRIx64 " of size %u: 0x%" PRIx32
 aspeed_ast2700_scuio_read(uint64_t offset, unsigned size, uint32_t data) "To 0x%" PRIx64 " of size %u: 0x%" PRIx32
+aspeed_ast1040_scu_write(uint64_t offset, unsigned size, uint32_t data) "To 0x%" PRIx64 " of size %u: 0x%" PRIx32
+aspeed_ast1040_scu_read(uint64_t offset, unsigned size, uint32_t data) "To 0x%" PRIx64 " of size %u: 0x%" PRIx32
 
 # mps2-scc.c
 mps2_scc_read(uint64_t offset, uint64_t data, unsigned size) "MPS2 SCC read: offset 0x%" PRIx64 " data 0x%" PRIx64 " size %u"
Signature · 1 line
2.43.0
author
#2 lore raw

PATCH RESEND 2/6 hw/misc: Add ASPEED Caliptra mailbox frontend

In reply to Steven Lee

Add a Caliptra mailbox frontend device with SRAM and CSR regions for the AST1040 MCI mailbox window.

Model the mailbox lock, command registers, execute flow and completion path through a pluggable peer interface so backends can service commands synchronously or asynchronously.

---
 include/hw/misc/aspeed_cptra_mbox.h | 133 ++++++++++
 hw/misc/aspeed_cptra_mbox.c         | 380 ++++++++++++++++++++++++++++
 hw/misc/meson.build                 |   1 +
 hw/misc/trace-events                |   4 +
 4 files changed, 518 insertions(+)
 create mode 100644 include/hw/misc/aspeed_cptra_mbox.h
 create mode 100644 hw/misc/aspeed_cptra_mbox.c
include/hw/misc/aspeed_cptra_mbox.h new file +133 -0
new file mode 100644
index 0000000000..470e91597f
@@ -0,0 +1,133 @@
+/*
+ * ASPEED Caliptra mailbox model (Caliptra 2.x subsystem mode)
+ *
+ * Copyright (C) 2026 ASPEED Technology Inc.
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#ifndef HW_MISC_ASPEED_CPTRA_MBOX_H
+#define HW_MISC_ASPEED_CPTRA_MBOX_H
+
+#include "qom/object.h"
+#include "hw/core/sysbus.h"
+
+typedef struct Error Error;
+
+/* SRAM size: 2 MiB (matches MCU_MAILBOX0_SRAM_SIZE in caliptra-mcu-sw) */
+#define CPTRA_MBOX0_SRAM_SIZE    (2u * 1024u * 1024u)
+#define CPTRA_MBOX0_SRAM_WORDS   (CPTRA_MBOX0_SRAM_SIZE / 4)
+
+/* CSR window: 4 KiB (covers all defined registers) */
+#define CPTRA_MBOX0_CSR_SIZE     0x1000u
+
+/* CSR register offsets (relative to CSR BAR) */
+#define CPTRA_MBOX0_LOCK_OFF            0x000
+#define CPTRA_MBOX0_USER_OFF            0x004
+#define CPTRA_MBOX0_TARGET_USER_OFF     0x008
+#define CPTRA_MBOX0_TARGET_USER_VAL_OFF 0x00C
+#define CPTRA_MBOX0_CMD_OFF             0x010
+#define CPTRA_MBOX0_DLEN_OFF            0x014
+#define CPTRA_MBOX0_EXECUTE_OFF         0x018
+#define CPTRA_MBOX0_TARGET_STATUS_OFF   0x01C
+#define CPTRA_MBOX0_CMD_STATUS_OFF      0x020
+#define CPTRA_MBOX0_HW_STATUS_OFF       0x024
+
+/* CMD_STATUS values */
+#define CPTRA_MBOX0_STATUS_BUSY        0
+#define CPTRA_MBOX0_STATUS_DATA_READY  1
+#define CPTRA_MBOX0_STATUS_COMPLETE    2
+#define CPTRA_MBOX0_STATUS_CMD_FAILURE 3
+
+/* SoC agent ID reported in the USER register when the lock is acquired */
+#define CPTRA_MBOX0_SOC_USER_ID    1u
+
+/*
+ * Caliptra mailbox interface (frontend), implemented as a QOM interface so
+ * that backends can deliver an asynchronous response without depending on the
+ * concrete frontend device type.
+ */
+#define TYPE_CPTRA_MBOX_IF "cptra-mbox-if"
+typedef struct CptraMboxIfClass CptraMboxIfClass;
+DECLARE_CLASS_CHECKERS(CptraMboxIfClass, CPTRA_MBOX_IF, TYPE_CPTRA_MBOX_IF)
+typedef struct CptraMboxIf CptraMboxIf;
+#define CPTRA_MBOX_IF(obj) \
+    INTERFACE_CHECK(CptraMboxIf, (obj), TYPE_CPTRA_MBOX_IF)
+
+struct CptraMboxIfClass {
+    InterfaceClass parent;
+
+    /*
+     * Called by the peer when a command submitted via handle_execute() has
+     * completed. @status is a CPTRA_MBOX0_STATUS_* value; @data/@len carry the
+     * response payload to be written back into the mailbox SRAM (@len bytes,
+     * @dlen is the reported DLEN).
+     */
+    void (*complete)(CptraMboxIf *s, uint32_t status, uint32_t dlen,
+                     const uint8_t *data, uint32_t len);
+};
+
+/*
+ * Caliptra mailbox peer (backend) base class.
+ */
+#define TYPE_CPTRA_MBOX_PEER "cptra-mbox-peer"
+OBJECT_DECLARE_TYPE(CptraMboxPeer, CptraMboxPeerClass, CPTRA_MBOX_PEER)
+
+struct CptraMboxPeer {
+    DeviceState parent;
+
+    /* Set by the frontend when this peer is linked to it. */
+    CptraMboxIf *intf;
+};
+
+struct CptraMboxPeerClass {
+    DeviceClass parent;
+
+    /*
+     * Process a command. @data/@len is a copy of the request payload from the
+     * mailbox SRAM. The peer must eventually report completion by calling the
+     * interface's complete() method (synchronously or asynchronously).
+     */
+    void (*handle_execute)(CptraMboxPeer *p, uint32_t cmd, uint32_t dlen,
+                           const uint8_t *data, uint32_t len);
+
+    /* Optional: notify the peer of a mailbox reset. */
+    void (*handle_reset)(CptraMboxPeer *p);
+};
+
+/* Concrete frontend device type. */
+#define TYPE_ASPEED_CPTRA_MBOX "aspeed-cptra-mbox"
+OBJECT_DECLARE_SIMPLE_TYPE(AspeedCptraMboxState, ASPEED_CPTRA_MBOX)
+
+struct AspeedCptraMboxState {
+    SysBusDevice parent_obj;
+
+    /* Linked backend; NULL means no Caliptra peer is present. */
+    CptraMboxPeer *peer;
+
+    bool locked;
+    bool command_pending;
+    bool release_pending;
+    uint32_t user;
+    uint32_t target_user;
+    uint32_t target_user_valid;
+    uint32_t cmd;
+    uint32_t dlen;
+    uint32_t execute;
+    uint32_t target_status;
+    uint32_t cmd_status;
+    uint32_t hw_status;
+
+    uint32_t sram[CPTRA_MBOX0_SRAM_WORDS];
+
+    MemoryRegion sram_mr;
+    MemoryRegion csr_mr;
+};
+
+bool aspeed_cptra_mbox_set_peer(AspeedCptraMboxState *s, CptraMboxPeer *peer,
+                                Error **errp);
+
+/* Concrete external (chardev) peer type. */
+#define TYPE_CPTRA_MBOX_PEER_EXTERN "cptra-mbox-peer-extern"
+
+#endif /* HW_MISC_ASPEED_CPTRA_MBOX_H */
hw/misc/aspeed_cptra_mbox.c new file +380 -0

380 lines not on this page · raw message

hw/misc/meson.build +1 -0
index fa6a961ac9..d23045c4b5 100644
@@ -135,6 +135,7 @@ system_ss.add(when: 'CONFIG_PVPANIC_PCI', if_true: files('pvpanic-pci.c'))
 system_ss.add(when: 'CONFIG_PVPANIC_MMIO', if_true: files('pvpanic-mmio.c'))
 system_ss.add(when: 'CONFIG_AUX', if_true: files('auxbus.c'))
 system_ss.add(when: 'CONFIG_ASPEED_SOC', if_true: files(
+  'aspeed_cptra_mbox.c',
   'aspeed_hace.c',
   'aspeed_lpc.c',
   'aspeed_ltpi.c',
hw/misc/trace-events +4 -0
index 82ddbf4d15..9fe2d27fef 100644
@@ -106,6 +106,10 @@ aspeed_ast2700_scuio_read(uint64_t offset, unsigned size, uint32_t data) "To 0x%
 aspeed_ast1040_scu_write(uint64_t offset, unsigned size, uint32_t data) "To 0x%" PRIx64 " of size %u: 0x%" PRIx32
 aspeed_ast1040_scu_read(uint64_t offset, unsigned size, uint32_t data) "To 0x%" PRIx64 " of size %u: 0x%" PRIx32
 
+# aspeed_cptra_mbox.c
+cptra_mbox_execute(uint32_t cmd, uint32_t dlen) "EXECUTE cmd 0x%" PRIx32 " dlen 0x%" PRIx32
+cptra_mbox_complete(uint32_t status, uint32_t dlen) "complete status %u dlen 0x%" PRIx32
+
 # mps2-scc.c
 mps2_scc_read(uint64_t offset, uint64_t data, unsigned size) "MPS2 SCC read: offset 0x%" PRIx64 " data 0x%" PRIx64 " size %u"
 mps2_scc_write(uint64_t offset, uint64_t data, unsigned size) "MPS2 SCC write: offset 0x%" PRIx64 " data 0x%" PRIx64 " size %u"
Signature · 1 line
2.43.0
author
#3 lore raw

PATCH RESEND 3/6 hw/misc: Add external Caliptra mailbox peer

In reply to Steven Lee

Add a cptra-mbox-peer-extern backend that forwards mailbox execute requests to a chardev peer using a small framed protocol.

Run the blocking chardev transaction from the thread pool and report completion back through the mailbox peer interface. Block migration while this external backend is realized because the peer state lives outside QEMU.

---
 MAINTAINERS                      |   1 +
 hw/misc/cptra_mbox_peer_extern.c | 318 +++++++++++++++++++++++++++++++
 hw/misc/meson.build              |   1 +
 3 files changed, 320 insertions(+)
 create mode 100644 hw/misc/cptra_mbox_peer_extern.c
MAINTAINERS +1 -0
index cd5c4831e2..a0e11d4a0e 100644
@@ -1270,6 +1270,7 @@ L: [email protected]
 S: Maintained
 F: hw/*/*aspeed*
 F: include/hw/*/*aspeed*
+F: hw/misc/cptra_mbox_peer_extern.c
 F: hw/net/ftgmac100.c
 F: include/hw/net/ftgmac100.h
 F: docs/system/arm/aspeed.rst
hw/misc/cptra_mbox_peer_extern.c new file +318 -0

318 lines not on this page · raw message

hw/misc/meson.build +1 -0
index d23045c4b5..9d545e8fb7 100644
@@ -136,6 +136,7 @@ system_ss.add(when: 'CONFIG_PVPANIC_MMIO', if_true: files('pvpanic-mmio.c'))
 system_ss.add(when: 'CONFIG_AUX', if_true: files('auxbus.c'))
 system_ss.add(when: 'CONFIG_ASPEED_SOC', if_true: files(
   'aspeed_cptra_mbox.c',
+  'cptra_mbox_peer_extern.c',
   'aspeed_hace.c',
   'aspeed_lpc.c',
   'aspeed_ltpi.c',
Signature · 1 line
2.43.0
author
#4 lore raw

PATCH RESEND 4/6 hw/arm/aspeed_ast1040: Wire Caliptra mailbox

In reply to Steven Lee

Instantiate the Caliptra mailbox in the AST1040 SoC and map its SRAM and CSR windows at the guest-visible MCI addresses.

Add the 4 KiB MCI aperture controlled by the AST1040 SCU CPTRA page register, switch the SoC to the AST1040 SCU model, and expose a machine option that links an external mailbox peer after machine initialization.

---
 include/hw/arm/aspeed_soc.h | 11 ++++++
 hw/arm/aspeed_ast1040.c     | 60 ++++++++++++++++++++++++++++--
 hw/arm/aspeed_ast1040_evb.c | 74 ++++++++++++++++++++++++++++++++++++-
 3 files changed, 140 insertions(+), 5 deletions(-)
include/hw/arm/aspeed_soc.h +11 -0
index 3aac144cd4..9fad3bc082 100644
@@ -46,6 +46,7 @@
 #include "hw/intc/arm_gicv3.h"
 #include "hw/misc/aspeed_ltpi.h"
 #include "hw/arm/aspeed_ast1700.h"
+#include "hw/misc/aspeed_cptra_mbox.h"
 
 #define VBOOTROM_FILE_NAME  "ast27x0_bootrom.bin"
 
@@ -165,6 +166,16 @@ struct Aspeed10x0SoCState {
 #define TYPE_ASPEED10X0_SOC "aspeed10x0-soc"
 OBJECT_DECLARE_SIMPLE_TYPE(Aspeed10x0SoCState, ASPEED10X0_SOC)
 
+struct Aspeed1040SoCState {
+    Aspeed10x0SoCState parent;
+
+    AspeedCptraMboxState cptra_mbox;
+    MemoryRegion cptra_mci_window;
+};
+
+#define TYPE_ASPEED1040_SOC "ast1040-a0"
+OBJECT_DECLARE_SIMPLE_TYPE(Aspeed1040SoCState, ASPEED1040_SOC)
+
 struct AspeedSoCClass {
     DeviceClass parent_class;
 
hw/arm/aspeed_ast1040.c +56 -4

108 lines not on this page · raw message

hw/arm/aspeed_ast1040_evb.c +73 -1

114 lines not on this page · raw message

Signature · 1 line
2.43.0
author
#5 lore raw

PATCH RESEND 5/6 tests/qtest: Add ASPEED Caliptra mailbox test

In reply to Steven Lee

Cover the AST1040 Caliptra mailbox execute flow through the external peer protocol and verify that the SCU CPTRA page register remaps the MCI aperture between CSR and SRAM pages.

---
 tests/qtest/aspeed_cptra_mbox-test.c | 223 +++++++++++++++++++++++++++
 tests/qtest/meson.build              |   3 +-
 2 files changed, 225 insertions(+), 1 deletion(-)
 create mode 100644 tests/qtest/aspeed_cptra_mbox-test.c
tests/qtest/aspeed_cptra_mbox-test.c new file +223 -0
new file mode 100644
index 0000000000..4d0e1682da
@@ -0,0 +1,223 @@
+/*
+ * QTest for the ASPEED Caliptra mailbox on the ast1040-evb machine.
+ *
+ * Copyright (C) 2026 ASPEED Technology Inc.
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#include "qemu/osdep.h"
+#include "libqtest-single.h"
+#include "qemu/sockets.h"
+
+/* AST1040 guest-visible mailbox bases. */
+#define SRAM_BASE   0x21400000ULL
+#define CSR_BASE    0x21600000ULL
+
+#define CSR_LOCK         0x000
+#define CSR_USER         0x004
+#define CSR_CMD          0x010
+#define CSR_DLEN         0x014
+#define CSR_EXECUTE      0x018
+#define CSR_CMD_STATUS   0x020
+
+#define STATUS_BUSY        0
+#define STATUS_COMPLETE    2
+#define STATUS_CMD_FAILURE 3
+
+/* SCU CPTRA page-select register (SCU base 0x74C02000 + 0x120). */
+#define SCU_CPTRA_PAGE_REG0  0x74C02120ULL
+/* MCI remap aperture. */
+#define MCI_WINDOW           0x74200000ULL
+
+/* Wire protocol. */
+#define PROTO_MAGIC    0x4D424F58u
+#define PROTO_VERSION  1u
+#define CMD_EXECUTE    1u
+#define CMD_RESPONSE   2u
+
+static int peer_lfd = -1;
+static int peer_fd = -1;
+
+static void peer_read(void *buf, size_t len)
+{
+    size_t off = 0;
+
+    while (off < len) {
+        ssize_t r = read(peer_fd, (uint8_t *)buf + off, len - off);
+        g_assert_cmpint(r, >, 0);
+        off += r;
+    }
+}
+
+static void peer_write(const void *buf, size_t len)
+{
+    size_t off = 0;
+
+    while (off < len) {
+        ssize_t w = write(peer_fd, (const uint8_t *)buf + off, len - off);
+        g_assert_cmpint(w, >, 0);
+        off += w;
+    }
+}
+
+static uint32_t ld32(const uint8_t *p)
+{
+    return p[0] | (p[1] << 8) | (p[2] << 16) | ((uint32_t)p[3] << 24);
+}
+
+static void st32(uint8_t *p, uint32_t v)
+{
+    p[0] = v; p[1] = v >> 8; p[2] = v >> 16; p[3] = v >> 24;
+}
+
+/*
+ * Service one MBOX_EXECUTE: read the request, optionally check it, then reply
+ * with MBOX_RESPONSE carrying @rsp_status and @rsp_data.
+ */
+static void peer_serve_execute(uint32_t expect_cmd, uint32_t expect_dlen,
+                               uint32_t rsp_status,
+                               const uint8_t *rsp_data, uint32_t rsp_dlen)
+{
+    uint8_t hdr[12];
+    uint32_t plen, cmd, dlen;
+    g_autofree uint8_t *payload = NULL;
+    uint32_t rsp_padded = (rsp_dlen + 3) & ~3u;
+    uint32_t rsp_plen = 8 + rsp_padded;
+    g_autofree uint8_t *rsp = g_malloc0(12 + rsp_plen);
+
+    peer_read(hdr, sizeof(hdr));
+    g_assert_cmpuint(ld32(hdr), ==, PROTO_MAGIC);
+    g_assert_cmpuint(hdr[4] | (hdr[5] << 8), ==, PROTO_VERSION);
+    g_assert_cmpuint(hdr[6] | (hdr[7] << 8), ==, CMD_EXECUTE);
+    plen = ld32(hdr + 8);
+    g_assert_cmpuint(plen, >=, 8);
+
+    payload = g_malloc(plen);
+    peer_read(payload, plen);
+    cmd = ld32(payload);
+    dlen = ld32(payload + 4);
+    g_assert_cmpuint(cmd, ==, expect_cmd);
+    g_assert_cmpuint(dlen, ==, expect_dlen);
+
+    st32(rsp, PROTO_MAGIC);
+    rsp[4] = PROTO_VERSION; rsp[5] = 0;
+    rsp[6] = CMD_RESPONSE;  rsp[7] = 0;
+    st32(rsp + 8, rsp_plen);
+    st32(rsp + 12, rsp_status);
+    st32(rsp + 16, rsp_dlen);
+    if (rsp_dlen) {
+        memcpy(rsp + 20, rsp_data, rsp_dlen);
+    }
+    peer_write(rsp, 12 + rsp_plen);
+}
+
+static uint32_t poll_cmd_status(void)
+{
+    uint32_t s = STATUS_BUSY;
+    int tries = 1000;
+
+    while (tries--) {
+        s = qtest_readl(global_qtest, CSR_BASE + CSR_CMD_STATUS);
+        if (s != STATUS_BUSY) {
+            break;
+        }
+    }
+    return s;
+}
+
+/*
+ * Realistic mailbox transaction: acquire the lock, run an EXECUTE roundtrip
+ * against the peer, verify the response lands in SRAM, then release.
+ */
+static void test_execute(void)
+{
+    static const uint8_t resp[] = {
+        0x11, 0xf9, 0xff, 0xff,   /* checksum */
+        0x00, 0x00, 0x00, 0x00,
+        0x14, 0x00, 0x00, 0x00,   /* inner dlen = 20 */
+        'C', 'a', 'l', 'i', 'p', 't', 'r', 'a',
+        '_', 'C', 'o', 'r', 'e', '_', 'v', '2', '.', '0', '.', '0',
+    };
+    uint32_t status;
+
+    /*
+     * Acquire: first read returns 0, USER reflects the SoC agent, busy after.
+     */
+    g_assert_cmpuint(qtest_readl(global_qtest, CSR_BASE + CSR_LOCK), ==, 0);
+    g_assert_cmpuint(qtest_readl(global_qtest, CSR_BASE + CSR_USER), ==, 1);
+    g_assert_cmpuint(qtest_readl(global_qtest, CSR_BASE + CSR_LOCK), ==, 1);
+
+    qtest_writel(global_qtest, SRAM_BASE + 0, 0xfffffec0);
+    qtest_writel(global_qtest, CSR_BASE + CSR_CMD, 0x4d465756);
+    qtest_writel(global_qtest, CSR_BASE + CSR_DLEN, 8);
+    qtest_writel(global_qtest, CSR_BASE + CSR_EXECUTE, 1);
+
+    peer_serve_execute(0x4d465756, 8, STATUS_COMPLETE, resp, sizeof(resp));
+
+    status = poll_cmd_status();
+    g_assert_cmpuint(status, ==, STATUS_COMPLETE);
+    g_assert_cmpuint(qtest_readl(global_qtest, CSR_BASE + CSR_DLEN),
+                     ==, sizeof(resp));
+    g_assert_cmpuint(qtest_readl(global_qtest, SRAM_BASE + 0), ==, 0xfffff911);
+    g_assert_cmpuint(qtest_readl(global_qtest, SRAM_BASE + 8), ==, 0x14);
+    g_assert_cmpuint(qtest_readl(global_qtest, SRAM_BASE + 12), ==, 0x696c6143);
+
+    /* Completing the transaction (EXECUTE 1->0) releases the lock. */
+    qtest_writel(global_qtest, CSR_BASE + CSR_EXECUTE, 0);
+    g_assert_cmpuint(qtest_readl(global_qtest, CSR_BASE + CSR_LOCK), ==, 0);
+    qtest_writel(global_qtest, CSR_BASE + CSR_EXECUTE, 0);
+}
+
+/* SCU CPTRA_PAGE_REG0 selects the target page seen through the MCI window. */
+static void test_scu_remap(void)
+{
+    /* Window pointed at the CSR page exposes the CMD register. */
+    qtest_writel(global_qtest, CSR_BASE + CSR_CMD, 0xdeadbeef);
+    qtest_writel(global_qtest, SCU_CPTRA_PAGE_REG0, CSR_BASE);
+    g_assert_cmpuint(qtest_readl(global_qtest, MCI_WINDOW + CSR_CMD),
+                     ==, 0xdeadbeef);
+
+    /* Re-point at the SRAM page. */
+    qtest_writel(global_qtest, SRAM_BASE + 0, 0x12345678);
+    qtest_writel(global_qtest, SCU_CPTRA_PAGE_REG0, SRAM_BASE);
+    g_assert_cmpuint(qtest_readl(global_qtest, MCI_WINDOW + 0),
+                     ==, 0x12345678);
+}
+
+int main(int argc, char **argv)
+{
+    g_autofree char *sock_path = NULL;
+    g_autofree char *cmdline = NULL;
+    int ret;
+
+    g_test_init(&argc, &argv, NULL);
+
+    sock_path = g_strdup_printf("%s/cptra-mbox-%u.sock",
+                                g_get_tmp_dir(), getpid());
+    unlink(sock_path);
+    peer_lfd = qtest_socket_server(sock_path);
+
+    cmdline = g_strdup_printf(
+        "-machine ast1040-evb,cptra-peer=peer0 "
+        "-chardev socket,id=cptra0,path=%s "
+        "-device cptra-mbox-peer-extern,id=peer0,chardev=cptra0", sock_path);
+    qtest_start(cmdline);
+
+    peer_fd = accept(peer_lfd, NULL, NULL);
+    g_assert_cmpint(peer_fd, >=, 0);
+
+    qtest_add_func("/cptra-mbox/execute", test_execute);
+    qtest_add_func("/cptra-mbox/scu-remap", test_scu_remap);
+
+    ret = g_test_run();
+
+    qtest_end();
+    if (peer_fd >= 0) {
+        close(peer_fd);
+    }
+    close(peer_lfd);
+    unlink(sock_path);
+
+    return ret;
+}
tests/qtest/meson.build +2 -1
index 728dde54b3..c50da850f7 100644
@@ -219,7 +219,8 @@ qtests_aspeed = \
   ['aspeed_gpio-test',
    'aspeed_hace-test',
    'aspeed_scu-test',
-   'aspeed_smc-test']
+   'aspeed_smc-test',
+   'aspeed_cptra_mbox-test']
 qtests_aspeed64 = \
   ['ast2700-gpio-test',
    'ast2700-hace-test',
Signature · 1 line
2.43.0
author
#6 lore raw

PATCH RESEND 6/6 docs/system/arm: Document AST1040 Caliptra mailbox

In reply to Steven Lee

Document the AST1040 Caliptra MCI mailbox windows, the SCU-controlled remap aperture, and how to connect the external mailbox peer through a chardev backend.

---
 docs/system/arm/aspeed.rst | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
docs/system/arm/aspeed.rst +32 -0
index 2d51ceeb84..1ffa88c2ae 100644
@@ -483,6 +483,7 @@ Supported devices
  * ADC
  * Secure Boot Controller
  * PECI Controller (minimal)
+ * Caliptra MCI mailbox (AST1040 only)
 
 
 Missing devices
@@ -512,3 +513,34 @@ To boot a kernel directly from a Zephyr build tree:
 
   $ qemu-system-arm -M ast1030-evb -nographic \
         -kernel zephyr.bin
+
+Caliptra MCI mailbox (ast1040-evb)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The AST1040 chip provides a mechanism to map the Caliptra MCI mailbox
+register space into the Cortex-M4F address space. The Caliptra MCI mailbox
+SRAM and CSR are accessible at fixed addresses:
+
+- Mailbox SRAM at ``0x21400000`` (2 MiB, command/response payload)
+- Mailbox CSR  at ``0x21600000`` (4 KiB, LOCK/CMD/DLEN/EXECUTE/STATUS)
+
+The SCU ``CPTRA_PAGE_REG0`` register (at ``0x74C02120``) selects which
+Caliptra MCI page (SRAM or CSR) is exposed through the 4 KiB aperture at
+``0x74200000``, allowing firmware to access either window through a single
+address.
+
+By default the mailbox has no Caliptra peer, so writing ``EXECUTE`` reports
+``CMD_FAILURE``. To service commands with an external Caliptra simulator (for
+example caliptra-server) over a UNIX socket, start the simulator first, then
+create an external peer device and link it with the machine's ``cptra-peer``
+option:
+
+.. code-block:: bash
+
+  $ qemu-system-arm -M ast1040-evb,cptra-peer=peer0 -nographic \
+        -chardev socket,id=cptra0,path=/tmp/mcu_mbox.sock \
+        -device cptra-mbox-peer-extern,id=peer0,chardev=cptra0 \
+        -kernel zephyr.elf
+
+Writing ``EXECUTE`` bridges the command and the mailbox SRAM payload to the
+peer over the socket, and writes the response back into the mailbox SRAM.
Signature · 1 line
2.43.0
author
#7 lore raw
In reply to Steven Lee

Hi,

Gentle ping for this patch series.
Any feedback would be appreciated.

Thanks,
Steven

Quoted 97 lines

-----Original Message-----
From: Steven Lee <[email protected]>
Sent: Wednesday, June 3, 2026 2:38 PM
To: Cédric Le Goater <[email protected]>; Peter Maydell <[email protected]>; Steven Lee <[email protected]>; Troy Lee <[email protected]>; Jamin Lin <[email protected]>; Kane Chen <[email protected]>; Andrew Jeffery <[email protected]>; Joel Stanley <[email protected]>; Pierrick Bouvier <[email protected]>; Fabiano Rosas <[email protected]>; Laurent Vivier <[email protected]>; Paolo Bonzini <[email protected]>; open list:All patches CC here <[email protected]>; open list:ASPEED BMCs <[email protected]>
Cc: Troy Lee <[email protected]>; [email protected]; Yunlin Tang <[email protected]>
Subject: [RESEND PATCH 0/6] aspeed: Add AST1040 Caliptra mailbox support

This series adds AST1040 Caliptra MCI mailbox support for the ast1040-evb machine.

AST1040 firmware accesses Caliptra through an MCI page aperture. This series adds an AST1040 SCU model with the CPTRA page-select registers, a mailbox frontend that exposes the Caliptra SRAM and CSR windows, and an optional external chardev peer so a Caliptra simulator can service EXECUTE requests.

The SoC wiring maps the mailbox SRAM, CSR window and 4 KiB remap aperture. The EVB machine also gets a cptra-peer option for linking the external peer after the machine is initialized.

The external peer backend is intended for co-simulation with an external Caliptra model. The current bring-up backend used for manual testing is caliptra-server:

https://github.com/stevenlee7189/caliptra-server/blob/main-2.x/README.m
d

That README includes the server command line, the matching QEMU command line, and the guest-side MFWV smoke test sequence used to validate the MCI aperture, LOCK/CMD/DLEN/EXECUTE flow, and FirmwareVersion response.
The qtest added by this series does not depend on that repository; it uses a socket-backed test peer to validate the QEMU-side protocol and mailbox flow.

Resending because some reviewers did not receive the previous email. No changes since the prior posting.

Patch layout:
- patches 1-2 add the AST1040 SCU model and mailbox frontend
- patch 3 adds the external chardev peer backend
- patch 4 wires the mailbox into the AST1040 SoC and EVB machine
- patches 5-6 add qtest coverage and documentation

The qtest covers mailbox lock, execute and completion flow through a socket-backed peer, and verifies that SCU CPTRA_PAGE_REG0 remaps the MCI aperture between CSR and SRAM pages.

Validation:
- scripts/checkpatch.pl --branch origin/master..HEAD
- qtest coverage for the AST1040 mailbox execute path with a socket-backed external peer
- manual co-simulation bring-up with caliptra-server through cptra-mbox-peer-extern

Steven Lee (6):
hw/misc/aspeed_scu: Add AST1040 SCU model hw/misc: Add ASPEED Caliptra mailbox frontend hw/misc: Add external Caliptra mailbox peer hw/arm/aspeed_ast1040: Wire Caliptra mailbox tests/qtest: Add ASPEED Caliptra mailbox test docs/system/arm: Document AST1040 Caliptra mailbox

 MAINTAINERS                          |   1 +
 docs/system/arm/aspeed.rst           |  32 +++
 include/hw/arm/aspeed_soc.h          |  11 +
 include/hw/misc/aspeed_cptra_mbox.h  | 133 ++++++++++
 include/hw/misc/aspeed_scu.h         |  10 +
 hw/arm/aspeed_ast1040.c              |  60 ++++-
 hw/arm/aspeed_ast1040_evb.c          |  74 +++++-
 hw/misc/aspeed_cptra_mbox.c          | 380
+++++++++++++++++++++++++++
 hw/misc/aspeed_scu.c                 | 251 ++++++++++++++++++
 hw/misc/cptra_mbox_peer_extern.c     | 318 ++++++++++++++++++++++
 tests/qtest/aspeed_cptra_mbox-test.c | 223 ++++++++++++++++
 hw/misc/meson.build                  |   2 +
 hw/misc/trace-events                 |   6 +
 tests/qtest/meson.build              |   3 +-
 14 files changed, 1498 insertions(+), 6 deletions(-)  create mode 100644
include/hw/misc/aspeed_cptra_mbox.h
 create mode 100644 hw/misc/aspeed_cptra_mbox.c  create mode 100644

hw/misc/cptra_mbox_peer_extern.c create mode 100644 tests/qtest/aspeed_cptra_mbox-test.c

--
2.43.0