[PATCH 0/4] arm: socfpga: mailbox_s10: cleanup and error handling

[PATCH 0/4] arm: socfpga: mailbox_s10: cleanup and error handling

[Michael Tretter]

On Agilex 5, barebox uses the mailbox_s10 to gain access to the QSPI
flash. Depending on the system configuration, the SDM may deny this
access. barebox assumes that the access always works and surprisingly
fails, if this isn't the case. Add at least some error messages for this
situation.

While at it, cleanup the code to make it more readable and easier to
follow.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
---
Michael Tretter (4):
      arm: socfpga: mailbox_s10: make retry logic more visible
      arm: socfpga: mailbox_s10: cleanup send command
      arm: socfpga: mailbox_s10: add error messages for QSPI
      arm: socfpga: mailbox_s10: handle error 0x8f explicitly

 arch/arm/mach-socfpga/mailbox_s10.c | 43 ++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 17 deletions(-)
---
base-commit: 019645e2b1cf0561afa7dd043e169eff416123ee
change-id: 20260311-agilex5-qspi-5a5ee90c0365

Best regards,
-- 
Michael Tretter <m.tretter@pengutronix.de>

[PATCH 1/4] arm: socfpga: mailbox_s10: make retry logic more visible

[Michael Tretter]

The driver tries to open the QSPI a second time after closing the device
if the first open failed. The second try is open coded and repeats code
from the first try.

Refactor the code to have a single open and make the error handling more
obvious.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
---
 arch/arm/mach-socfpga/mailbox_s10.c | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/arch/arm/mach-socfpga/mailbox_s10.c b/arch/arm/mach-socfpga/mailbox_s10.c
index 9211d643e3b6..f9ff6663dc38 100644
--- a/arch/arm/mach-socfpga/mailbox_s10.c
+++ b/arch/arm/mach-socfpga/mailbox_s10.c
@@ -301,20 +301,18 @@ int socfpga_mailbox_s10_qspi_open(void)
 	u32 resp_buf_len;
 	u32 reg;
 	u32 clk_khz;
+	int try = 0;
 
+retry:
 	ret = mbox_send_cmd(MBOX_ID_BAREBOX, MBOX_QSPI_OPEN, MBOX_CMD_DIRECT,
 			    0, NULL, 0, 0, NULL);
-	if (ret) {
-		/* retry again by closing and reopen the QSPI again */
-		ret = socfpga_mailbox_s10_qspi_close();
-		if (ret)
-			return ret;
-
-		ret = mbox_send_cmd(MBOX_ID_BAREBOX, MBOX_QSPI_OPEN,
-				    MBOX_CMD_DIRECT, 0, NULL, 0, 0, NULL);
-		if (ret)
-			return ret;
+	if (ret != MBOX_RESP_STATOK && try++ < 2) {
+		/* retry after closing the QSPI */
+		socfpga_mailbox_s10_qspi_close();
+		goto retry;
 	}
+	if (ret)
+		return ret;
 
 	/* HPS will directly control the QSPI controller, no longer mailbox */
 	resp_buf_len = 1;

-- 
2.47.3

[PATCH 2/4] arm: socfpga: mailbox_s10: cleanup send command

[Michael Tretter]

The casts when passing the response buffer to mbox_send_cmd are useless,
because they already have the correct type.

Furthermore, setting an explicit buffer length is surprising and error
prone. Just use the array size of the response buffer as length.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
---
 arch/arm/mach-socfpga/mailbox_s10.c | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/arch/arm/mach-socfpga/mailbox_s10.c b/arch/arm/mach-socfpga/mailbox_s10.c
index f9ff6663dc38..f6aacd5551f2 100644
--- a/arch/arm/mach-socfpga/mailbox_s10.c
+++ b/arch/arm/mach-socfpga/mailbox_s10.c
@@ -297,8 +297,8 @@ int socfpga_mailbox_s10_qspi_close(void)
 int socfpga_mailbox_s10_qspi_open(void)
 {
 	int ret;
-	u32 resp_buf[1];
-	u32 resp_buf_len;
+	u32 resp_buf[1] = {};
+	u32 resp_buf_len = ARRAY_SIZE(resp_buf);
 	u32 reg;
 	u32 clk_khz;
 	int try = 0;
@@ -315,10 +315,8 @@ int socfpga_mailbox_s10_qspi_open(void)
 		return ret;
 
 	/* HPS will directly control the QSPI controller, no longer mailbox */
-	resp_buf_len = 1;
 	ret = mbox_send_cmd(MBOX_ID_BAREBOX, MBOX_QSPI_DIRECT, MBOX_CMD_DIRECT,
-			    0, NULL, 0, (u32 *)&resp_buf_len,
-			    (u32 *)&resp_buf);
+			    0, NULL, 0, &resp_buf_len, resp_buf);
 	if (ret)
 		goto error;
 

-- 
2.47.3

[PATCH 3/4] arm: socfpga: mailbox_s10: add error messages for QSPI

[Michael Tretter]

The mailbox commands may fail. For example, the SDM may prevent direct
access from the HPS to the QSPI.

Print error messages to help the developer in debugging these issues.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
---
 arch/arm/mach-socfpga/mailbox_s10.c | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/arch/arm/mach-socfpga/mailbox_s10.c b/arch/arm/mach-socfpga/mailbox_s10.c
index f6aacd5551f2..ff2f261014b2 100644
--- a/arch/arm/mach-socfpga/mailbox_s10.c
+++ b/arch/arm/mach-socfpga/mailbox_s10.c
@@ -311,22 +311,29 @@ int socfpga_mailbox_s10_qspi_open(void)
 		socfpga_mailbox_s10_qspi_close();
 		goto retry;
 	}
-	if (ret)
+	if (ret) {
+		pr_err("QSPI: QSPI_OPEN failed: 0x%x\n", ret);
 		return ret;
+	}
 
 	/* HPS will directly control the QSPI controller, no longer mailbox */
 	ret = mbox_send_cmd(MBOX_ID_BAREBOX, MBOX_QSPI_DIRECT, MBOX_CMD_DIRECT,
 			    0, NULL, 0, &resp_buf_len, resp_buf);
-	if (ret)
+	if (ret) {
+		pr_err("QSPI: QSPI_DIRECT failed: 0x%x\n", ret);
 		goto error;
+	}
 
 	/* Get the QSPI clock from SDM response and save for later use */
 	clk_khz = resp_buf[0];
-	if (clk_khz < 1000)
+	if (clk_khz < 1000) {
+		pr_err("QSPI: Unexpected reference clock rate: %d kHz\n",
+		       clk_khz);
 		return -EINVAL;
+	}
 
 	clk_khz /= 1000;
-	pr_info("QSPI: reference clock at %d kHZ\n", clk_khz);
+	pr_info("QSPI: reference clock at %d kHz\n", clk_khz);
 
 	reg = (readl(SOCFPGA_SYSMGR_ADDRESS + SYSMGR_SOC64_BOOT_SCRATCH_COLD0)) &
 			~(SYSMGR_SCRATCH_REG_0_QSPI_REFCLK_MASK);

-- 
2.47.3

[PATCH 4/4] arm: socfpga: mailbox_s10: handle error 0x8f explicitly

[Michael Tretter]

The 0x8f is a command specific error code that indicates that the SDM
denied the HPS direct access to the QSPI. This is a valid SDM
configuration, but prevents barebox from using the QSPI flash, which may
or may not be a problem.

This configuration may also happen accidentally when using Quartus 25.3
to add a FSBL to a board SDM configuration created by Quartus 24.3.

Print a specific error message for this situation to help the developer.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
---
 arch/arm/mach-socfpga/mailbox_s10.c | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/arch/arm/mach-socfpga/mailbox_s10.c b/arch/arm/mach-socfpga/mailbox_s10.c
index ff2f261014b2..4199c4fb913a 100644
--- a/arch/arm/mach-socfpga/mailbox_s10.c
+++ b/arch/arm/mach-socfpga/mailbox_s10.c
@@ -319,7 +319,13 @@ int socfpga_mailbox_s10_qspi_open(void)
 	/* HPS will directly control the QSPI controller, no longer mailbox */
 	ret = mbox_send_cmd(MBOX_ID_BAREBOX, MBOX_QSPI_DIRECT, MBOX_CMD_DIRECT,
 			    0, NULL, 0, &resp_buf_len, resp_buf);
-	if (ret) {
+	switch (ret) {
+	case MBOX_RESP_STATOK:
+		break;
+	case 0x8f:
+		pr_err("QSPI: SDM denied direct QSPI access\n");
+		goto error;
+	default:
 		pr_err("QSPI: QSPI_DIRECT failed: 0x%x\n", ret);
 		goto error;
 	}

-- 
2.47.3

Re: [PATCH 0/4] arm: socfpga: mailbox_s10: cleanup and error handling

[Sascha Hauer]

On Wed, 11 Mar 2026 12:06:38 +0100, Michael Tretter wrote:
> On Agilex 5, barebox uses the mailbox_s10 to gain access to the QSPI
> flash. Depending on the system configuration, the SDM may deny this
> access. barebox assumes that the access always works and surprisingly
> fails, if this isn't the case. Add at least some error messages for this
> situation.
> 
> While at it, cleanup the code to make it more readable and easier to
> follow.
> 
> [...]

Applied, thanks!

[1/4] arm: socfpga: mailbox_s10: make retry logic more visible
      https://git.pengutronix.de/cgit/barebox/commit/?id=c3920dcbc08a (link may not be stable)
[2/4] arm: socfpga: mailbox_s10: cleanup send command
      https://git.pengutronix.de/cgit/barebox/commit/?id=946b13cc5561 (link may not be stable)
[3/4] arm: socfpga: mailbox_s10: add error messages for QSPI
      https://git.pengutronix.de/cgit/barebox/commit/?id=af333e386455 (link may not be stable)
[4/4] arm: socfpga: mailbox_s10: handle error 0x8f explicitly
      https://git.pengutronix.de/cgit/barebox/commit/?id=547859d6d325 (link may not be stable)

Best regards,
-- 
Sascha Hauer <s.hauer@pengutronix.de>