Review cleanups

Author: dgarske

docs/Targets.md

@@ -1077,9 +1077,9 @@ Notes:
 ### 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.
+Memory (L2-LIM)**. HSS loads wolfBoot into L2-LIM on a U54 application core, and wolfBoot loads
+the signed application from SC QSPI into L2-LIM as well. This is the configuration for systems
+that keep HSS and run without DDR.
 
 **Features:**
 * S-mode on U54 application core (hart 1), loaded by HSS
@@ -1135,8 +1135,8 @@ python3 tools/scripts/mpfs_qspi_prog.py /dev/ttyUSB1 \
 
 wolfBoot supports running directly in Machine Mode (M-mode) on PolarFire SoC, replacing the Hart
 Software Services (HSS) as the first-stage bootloader. wolfBoot runs on the E51 monitor core from
-eNVM and loads a signed application from SC QSPI flash into L2 Scratchpad (on-chip RAM) — no HSS
-or DDR required. This is the simplest bring-up path.
+eNVM and loads a signed application from SC QSPI flash into L2 Scratchpad (on-chip RAM) -- no HSS
+or DDR required. This is the minimal on-chip-only configuration.
 
 **Features:**
 * Runs on E51 monitor core (hart 0) directly from eNVM
@@ -1267,11 +1267,11 @@ power-on.
   injection via CLINT MSIP), RFENCE (remote `fence.i` / `sfence.vma` with completion wait),
   HSM (`hart_start`/`hart_stop`/`hart_status` backed by per-hart start mailboxes), DBCN and the
   legacy console putchar (shared with the wolfBoot UART), SRST.
-* `rdtime` emulation: the U54/E51 have no `time` CSR, so reads trap as illegal instruction from
-  S/U-mode and are emulated from CLINT MTIME (enabled via SYSREG `RTC_CLOCK_CR`, 1 MHz to match
-  the device tree `timebase-frequency`).
-* Misaligned load/store emulation (not delegatable on these harts) via MPRV byte accesses,
-  including compressed forms; the kernel relies on this for unaligned copy tails.
+* `rdtime` emulation: the U54/E51 have no `time` CSR, so `rdtime` is emulated from CLINT MTIME.
+  The M-mode HAL starts the MTIME time base before hand-off via SYSREG `RTC_CLOCK_CR` at 1 MHz
+  (`mpfs_enable_mtime()`), matching the device-tree `timebase-frequency`.
+* Misaligned load/store emulation (not delegatable on these harts), including compressed forms,
+  for the kernel's unaligned copy tails.
 * Per-hart M-mode trap stacks live in the `hss-buffer` reserved (nomap) DDR region; cross-hart
   state (HSM mailboxes, IPI flags, the hart-release gate flag) lives in the E51 DTIM at
   `0x01000000`, which is uncached and coherent for all harts. Cacheable L2-scratchpad memory
@@ -1291,9 +1291,6 @@ mailbox {entry, dtb} plus MSIP; Linux brings up the remaining harts through SBI
 `hart_start`, which uses the same mailbox + MSIP path. The release path must stay fast
 (no UART access): the kernel allows roughly one second for a started hart to come online.
 
-**DEBUG_DDR note:** DDR training no longer depends on `DEBUG_DDR` console timing; the flag is
-purely diagnostic and off by default.
-
 **Driver structure:** the licensed Cadence DDR controller logic (controller CSR programming, the
 Memory Test Controller engine, and the LPDDR4 mode-register protocol) lives in the
 target-independent `src/ddr_cadence.c` / `include/ddr_cadence.h` (controller base overridable via
@@ -1377,11 +1374,11 @@ make test-app/image.elf
 sudo dd if=test-app/image_v1_signed.bin of=/dev/sdc2 bs=512 && sudo cmp test-app/image_v1_signed.bin /dev/sdc2
 ```
 
-4) Insert SDCARD into PolarFire and let HSS start wolfBoot. You may need to use `boot sdcard` or configure/build HSS to disable MMC / enable SDCARD.
+4) Insert the SD card into the PolarFire and let HSS start wolfBoot. If HSS defaults to eMMC, select the SD card with `boot sdcard` at the HSS console, or build HSS with MMC disabled / SD card enabled.
 
 ### PolarFire Building Hart Software Services (HSS)
 
-The Hart Software Services (HSS) is the zero-stage bootloader for the PolarFire SoC. It runs on the E51 monitor core and is responsible for system initialization, hardware configuration, and booting the U54 application cores. The HSS provides essential services including watchdog management, inter-processor communication (IPC), and loading payloads from various boot sources (eMMC, SD card, or SPI flash).
+The Hart Software Services (HSS) is the PolarFire SoC zero-stage bootloader (E51 monitor core); it is required only for the HSS-based S-mode configurations above, not for the M-mode + DDR path which replaces it.
 
 ```sh
 git clone https://github.com/polarfire-soc/hart-software-services.git
@@ -1393,7 +1390,7 @@ make BOARD=mpfs-video-kit program
 
 ### PolarFire Building Yocto-SDK Linux
 
-The Yocto Project provides a customizable embedded Linux distribution for PolarFire SoC. Microchip maintains the `meta-mchp` layer with board support packages (BSP), drivers, and example applications for their devices. The build system uses OpenEmbedded and produces bootable images that can be flashed to eMMC or SD card.
+The signed Yocto FIT image booted by wolfBoot is produced from Microchip's `meta-mchp` Yocto layer (BSP, drivers, and kernel for the board).
 
 See:
 * https://github.com/linux4microchip/meta-mchp/blob/scarthgap/meta-mchp-common/README.md
@@ -1450,11 +1447,10 @@ mkimage -f hal/mpfs250.its fitImage
 ```
 
 At boot, wolfBoot decompresses the kernel into `0x80200000` directly out of
-the FIT `data` blob. Image integrity is provided by the outer wolfBoot
-signature over the entire FIT (which covers the compressed `data` bytes per
-the FIT spec), and post-decompress integrity by gzip's CRC32 + ISIZE
-trailer; per-image `hash-1` subnodes are not re-verified at runtime since
-they would be redundant with the outer signature.
+the FIT `data` blob. The outer wolfBoot signature covers the whole FIT
+(including the compressed `data`), and gzip's CRC32 + ISIZE trailer covers
+the decompressed output; the per-image `hash-1` subnodes are not re-checked
+at runtime as they would duplicate the outer signature.
 
 ##### Option B - Uncompressed FIT (`GZIP=0`)