Documentation improvements. Peer review fixes

Author: dgarske

docs/Targets.md

@@ -795,12 +795,43 @@ The PolarFire SoC is a 64-bit RISC-V SoC featuring a five-core CPU cluster (1×
 * Low power consumption
 * External flash support
 
+### Supported Boot Configurations
+
+Five ready-to-use config templates cover all supported boot mode / storage / memory combinations:
+
+| Configuration | Config File | Boot Mode | Storage | Memory | HSS |
+|---------------|-------------|-----------|---------|--------|-----|
+| **SDCard** | `polarfire_mpfs250.config` | S-mode (U54 via HSS) | SD Card | DDR | Yes |
+| **eMMC** | `polarfire_mpfs250.config` + `DISK_EMMC=1` | S-mode (U54 via HSS) | eMMC | DDR | Yes |
+| **QSPI (S-mode)** | `polarfire_mpfs250_qspi.config` | S-mode (U54 via HSS) | MSS or SC QSPI | DDR | Yes |
+| **QSPI + L2-LIM** | `polarfire_mpfs250_hss_l2lim.config` | S-mode (U54 via HSS) | SC QSPI | L2-LIM (no DDR) | Yes |
+| **M-Mode (no HSS)** | `polarfire_mpfs250_m_qspi.config` | M-mode (E51, no HSS) | SC QSPI | L2 Scratchpad | No |
+
+Key build settings that differ between configurations:
+
+| Setting | SDCard | eMMC | QSPI | L2-LIM | M-Mode |
+|---------|--------|------|------|--------|--------|
+| `WOLFBOOT_ORIGIN` | `0x80000000` | `0x80000000` | `0x80000000` | `0x08040000` | `0x0A000000` |
+| `WOLFBOOT_LOAD_ADDRESS` | `0x8E000000` | `0x8E000000` | `0x8E000000` | `0x08060000` | `0x0A010200` |
+| `EXT_FLASH` | 0 | 0 | 1 | 1 | 1 |
+| `DISK_SDCARD` | 1 | 0 | 0 | 0 | 0 |
+| `DISK_EMMC` | 0 | 1 | 0 | 0 | 0 |
+| `MPFS_L2LIM` | – | – | – | 1 | – |
+| `RISCV_MMODE` | – | – | – | – | 1 |
+| Linker script | `mpfs250.ld` | `mpfs250.ld` | `mpfs250.ld` | `mpfs250-hss.ld` | `mpfs250-m.ld` |
+| HSS YAML | `mpfs.yaml` | `mpfs.yaml` | `mpfs.yaml` | `mpfs-l2lim.yaml` | N/A |
+| `ELF` output | 1 | 1 | 1 | 0 (raw .bin) | 1 |
+
+> **Note:** All configurations require `NO_ASM=1` because the MPFS250 U54/E51 cores lack RISC-V
+> crypto extensions (Zknh); wolfBoot uses portable C implementations for all cryptographic operations.
+
 ### PolarFire SoC Files
 
 `hal/mpfs250.c` - Hardware abstraction layer (UART, QSPI, SD/eMMC, multi-hart)
 `hal/mpfs250.h` - Register definitions and hardware interfaces
 `hal/mpfs250.ld` - Linker script for S-mode (HSS-based boot)
 `hal/mpfs250-m.ld` - Linker script for M-mode (eNVM + L2 SRAM)
+`hal/mpfs250-hss.ld` - Linker script for S-mode (HSS with L2-LIM)
 `hal/mpfs.dts` - Device tree source
 `hal/mpfs.yaml` - HSS payload generator configuration for use of DDR
 `hal/mpfs-l2lim.yaml` - HSS payload generator for the use of L2-LIM
@@ -905,6 +936,63 @@ Notes:
 - The MSS QSPI path expects external flash on the MSS QSPI pins; the SC QSPI path is for
   fabric-connected flash (design flash) accessed via the System Controller's QSPI instance.
 
+### PolarFire SoC HSS S-Mode with L2-LIM (no DDR)
+
+wolfBoot can run in S-mode via HSS without DDR by targeting the on-chip **L2 Loosely Integrated
+Memory (L2-LIM)**. HSS loads wolfBoot from SC QSPI flash into L2-LIM on a U54 application core,
+and wolfBoot loads the signed application from SC QSPI into L2-LIM as well. This is useful for
+early bring-up or power-constrained scenarios where DDR is not yet initialized.
+
+**Features:**
+* S-mode on U54 application core (hart 1), loaded by HSS
+* wolfBoot and application both reside in L2-LIM (`0x08000000`, up to 1.5 MB)
+* No DDR required
+* SC QSPI flash for both wolfBoot payload and signed application image
+* Raw binary output (`ELF=0`) required — ELF with debug symbols is too large for L2-LIM
+
+**Relevant files:**
+
+| File | Description |
+|------|-------------|
+| `config/examples/polarfire_mpfs250_hss_l2lim.config` | HSS S-mode + SC QSPI + L2-LIM |
+| `hal/mpfs250-hss.ld` | Linker script for S-mode with L2-LIM |
+| `hal/mpfs-l2lim.yaml` | HSS payload generator YAML for L2-LIM load target |
+
+**Build:**
+```sh
+cp config/examples/polarfire_mpfs250_hss_l2lim.config .config
+make clean && make wolfboot.bin
+dtc -I dts -O dtb hal/mpfs.dts -o hal/mpfs.dtb
+hss-payload-generator -vvv -c ./hal/mpfs-l2lim.yaml wolfboot.bin
+```
+
+Flash the HSS payload to the eMMC/SD BIOS partition using HSS `USBDMSC`:
+```sh
+sudo dd if=wolfboot.bin of=/dev/sdc1 bs=512 && sudo cmp wolfboot.bin /dev/sdc1
+```
+
+**Build and sign the test application:**
+```sh
+make test-app/image_v1_signed.bin
+```
+
+**Flash the signed application to QSPI:**
+```sh
+python3 tools/scripts/mpfs_qspi_prog.py /dev/ttyUSB1 \
+    test-app/image_v1_signed.bin 0x20000
+```
+
+**Notes:**
+- `ELF=0` is required: the test-app linker script (`test-app/RISCV64-mpfs250.ld`) places `.init`
+  (containing `_reset()`) first so the raw binary entry point is at offset 0. The full ELF with
+  debug symbols exceeds L2-LIM capacity.
+- wolfBoot is placed at `0x08040000` (above the HSS L2-LIM resident region) and the application
+  is loaded at `0x08060000`. The stack resides at the top of the 1.5 MB L2-LIM region.
+- HSS must be built and programmed to eNVM separately (see [PolarFire Building Hart Software Services](#polarfire-building-hart-software-services-hss)).
+- **LIM instruction fetch caveat:** Ensure `L2_WAY_ENABLE` leaves enough cache ways unallocated
+  to back the LIM SRAM region. See the M-mode section for a detailed explanation.
+- UART output appears on MMUART1 (`/dev/ttyUSB1`), same as other S-mode configurations.
+
 ### PolarFire SoC M-Mode (bare-metal eNVM boot)
 
 wolfBoot supports running directly in Machine Mode (M-mode) on PolarFire SoC, replacing the Hart

hal/mpfs250.c

@@ -902,14 +902,20 @@ int ext_flash_erase(uintptr_t address, int len)
  * ============================================================================ */
 #if defined(UART_QSPI_PROGRAM) && defined(__WOLFBOOT)
 
-#define QSPI_PROG_CHUNK     256
-#define QSPI_PROG_ACK       0x06
+#define QSPI_PROG_CHUNK        256
+#define QSPI_PROG_ACK          0x06
+#define QSPI_RX_TIMEOUT_MS     5000U  /* 5 s per byte — aborts if host disappears */
 
-static uint8_t uart_qspi_rx(void)
+/* Returns 0-255 on success, -1 on timeout (so the boot path is never deadlocked). */
+static int uart_qspi_rx(void)
 {
-    while (!(MMUART_LSR(DEBUG_UART_BASE) & MSS_UART_DR))
-        ;
-    return MMUART_RBR(DEBUG_UART_BASE);
+    uint32_t t;
+    for (t = 0; t < QSPI_RX_TIMEOUT_MS; t++) {
+        if (MMUART_LSR(DEBUG_UART_BASE) & MSS_UART_DR)
+            return (int)(uint8_t)MMUART_RBR(DEBUG_UART_BASE);
+        udelay(1000);
+    }
+    return -1; /* timeout */
 }
 
 static void uart_qspi_tx(uint8_t c)
@@ -959,11 +965,23 @@ static void qspi_uart_program(void)
 
     /* Receive destination address then data length (4 bytes LE each) */
     addr = 0;
-    for (i = 0; i < 4; i++)
-        addr |= ((uint32_t)uart_qspi_rx() << (i * 8));
+    for (i = 0; i < 4; i++) {
+        int b = uart_qspi_rx();
+        if (b < 0) {
+            wolfBoot_printf("QSPI-PROG: RX timeout receiving addr\r\n");
+            return;
+        }
+        addr |= ((uint32_t)(uint8_t)b << (i * 8));
+    }
     size = 0;
-    for (i = 0; i < 4; i++)
-        size |= ((uint32_t)uart_qspi_rx() << (i * 8));
+    for (i = 0; i < 4; i++) {
+        int b = uart_qspi_rx();
+        if (b < 0) {
+            wolfBoot_printf("QSPI-PROG: RX timeout receiving size\r\n");
+            return;
+        }
+        size |= ((uint32_t)(uint8_t)b << (i * 8));
+    }
 
     wolfBoot_printf("QSPI-PROG: addr=0x%x size=%u bytes\r\n", addr, size);
 
@@ -972,6 +990,20 @@ static void qspi_uart_program(void)
         return;
     }
 
+    /* Reject writes to unaligned or out-of-partition addresses before any erase */
+    if ((addr & (FLASH_SECTOR_SIZE - 1U)) != 0U) {
+        wolfBoot_printf("QSPI-PROG: addr 0x%x not sector-aligned, aborting\r\n", addr);
+        return;
+    }
+    if (!((addr >= WOLFBOOT_PARTITION_BOOT_ADDRESS &&
+           addr + size <= WOLFBOOT_PARTITION_BOOT_ADDRESS + WOLFBOOT_PARTITION_SIZE) ||
+          (addr >= WOLFBOOT_PARTITION_UPDATE_ADDRESS &&
+           addr + size <= WOLFBOOT_PARTITION_UPDATE_ADDRESS + WOLFBOOT_PARTITION_SIZE))) {
+        wolfBoot_printf("QSPI-PROG: addr 0x%x+%u outside allowed partitions, aborting\r\n",
+                        addr, size);
+        return;
+    }
+
     /* Erase all required sectors (FLASH_SECTOR_SIZE = 64 KB) */
     n_sectors = (size + FLASH_SECTOR_SIZE - 1) / FLASH_SECTOR_SIZE;
     wolfBoot_printf("QSPI-PROG: Erasing %u sector(s) at 0x%x...\r\n",
@@ -1002,8 +1034,16 @@ static void qspi_uart_program(void)
 
         uart_qspi_tx(QSPI_PROG_ACK);          /* request next chunk */
 
-        for (i = 0; i < chunk_len; i++)
-            chunk[i] = uart_qspi_rx();
+        for (i = 0; i < chunk_len; i++) {
+            int b = uart_qspi_rx();
+            if (b < 0) {
+                wolfBoot_printf("QSPI-PROG: RX timeout at 0x%x+%u\r\n",
+                                addr + written, i);
+                ext_flash_lock();
+                return;
+            }
+            chunk[i] = (uint8_t)b;
+        }
 
         ret = ext_flash_write(addr + written, chunk, (int)chunk_len);
         if (ret < 0) {

hal/riscv.h

@@ -124,9 +124,16 @@ static inline void riscv_icache_sync(void)
 #define SSTATUS_SIE  (1UL << 1)
 #define SSTATUS_SPIE (1UL << 5)
 
-/* MIP register bits */
+/* MIP register bits (mip CSR: pending interrupt flags, written by hardware) */
 #define MIP_MSIP     (1 << IRQ_M_SOFT)
 
+/* MIE register bits (mie CSR: interrupt enable, always written by software.
+ * Bit positions match MIP but use these names when targeting the mie register
+ * to avoid confusing the two CSRs.) */
+#define MIE_MSIE     (1 << IRQ_M_SOFT)
+#define MIE_MTIE     (1 << IRQ_M_TIMER)
+#define MIE_MEIE     (1 << IRQ_M_EXT)
+
 /* SIE register bits */
 #define SIE_SSIE     (1 << IRQ_S_SOFT)
 #define SIE_STIE     (1 << IRQ_S_TIMER)

src/boot_riscv_start.S

@@ -118,7 +118,7 @@ _copy_params:
     csrc  mstatus, t0
     csrw  mie, zero
     csrw  mip, zero
-    li    t0, MIP_MSIP                 /* wake only on IPI */
+    li    t0, MIE_MSIE                 /* wake only on IPI */
     csrw  mie, t0
 
     /* Set up per-hart stack: base + (hartid+1)*STACK_SIZE_PER_HART */

src/sdhci.c

@@ -66,8 +66,8 @@ static volatile int g_mmc_irq_pending = 0;
 /* Microsecond delay using hardware timer */
 static void udelay(uint32_t us)
 {
-    uint64_t start = hal_get_timer_us();
-    while ((hal_get_timer_us() - start) < us);
+    uint64_t end = hal_get_timer_us() + us;
+    while (hal_get_timer_us() < end);
 }
 
 /* ============================================================================