doc: document the filesystem-image step; ci: serialize gh-pages deploys

.github/workflows/documentation.yaml

@@ -1,5 +1,13 @@
 name: Docs
 on: [push, pull_request, workflow_dispatch]
+
+# Serialize per ref so a burst of pushes (e.g. several PRs merged to main within
+# seconds) collapses to the latest run instead of racing multiple gh-pages
+# pushes — overlapping Pages deployments fail with "in progress deployment".
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   docs:
     runs-on: ubuntu-latest

doc/source/build_system.rst

@@ -202,6 +202,22 @@ produced (``rootfs.cpio``, the FIT), so the workflow is *edit → build.sh →
 deploy.sh*. A deploy with no prior build fails clearly rather than silently
 rebuilding.
 
+.. important::
+
+   ``build.sh bsp-so3`` compiles the BSP but does **not** create the SD-card
+   image itself: the empty ``filesystem/sdcard.img.<platform>`` is produced by the
+   separate, privileged ``filesystem`` recipe (``losetup``/``mkfs``/``parted``).
+   ``deploy.sh`` populates and writes that image but does not create it, so a
+   deploy against a fresh tree fails until the image exists. The canonical
+   first-build sequence is therefore three steps::
+
+      build.sh bsp-so3        # compile kernel + user space + U-Boot + rootfs + FIT
+      build.sh -x filesystem  # create + format the SD-card image (privileged, once)
+      deploy.sh bsp-so3       # populate the rootfs and write the boot media
+
+   Once the image exists, later edits only need ``build.sh -x <recipe>`` +
+   ``deploy.sh bsp-so3`` — the ``filesystem`` step is a one-off.
+
 .. note::
 
    ``build.sh`` / ``deploy.sh`` take the recipe as a **positional argument**

doc/source/user_guide.rst

@@ -64,14 +64,23 @@ the FIT image):
 
    build.sh bsp-so3
 
-**4. Deploy** onto the virtual SD-card (this opens the sudo session and writes the
+**4. Create the SD-card image.** ``build.sh bsp-so3`` only *compiles* — the empty
+SD-card image (``filesystem/sdcard.img.<platform>``) is produced by the separate,
+privileged ``filesystem`` recipe (``losetup``/``mkfs``/``parted``, escalated with
+``sudo -n``). Run it once before the first deploy:
+
+.. code-block:: bash
+
+   build.sh -x filesystem
+
+**5. Deploy** onto the virtual SD-card (this opens the sudo session and writes the
 boot partition):
 
 .. code-block:: bash
 
    deploy.sh bsp-so3
 
-**5. Run:**
+**6. Run:**
 
 .. code-block:: bash
 
@@ -133,12 +142,14 @@ To run SO3 as a **guest** on top of AVZ (``CONFIG_SOO=n``, no capsules):
    IB_TARGET_ITS:so3:virt64 = "virt64_avz"
    # IB_BOOT_CHAIN ?= "atf+uboot"     # or "full" (ATF + OP-TEE); default is bare U-Boot
 
-**2.** Build the hypervisor and (re)assemble the BSP, then deploy:
+**2.** Build the hypervisor and (re)assemble the BSP, create the SD-card image if
+it does not exist yet, then deploy:
 
 .. code-block:: bash
 
    build.sh -x avz
    build.sh bsp-so3
+   build.sh -x filesystem     # only needed the first time (creates the SD-card image)
    deploy.sh bsp-so3
 
 **3.** Run — ``st.sh`` enables EL2 automatically because the ITS is an AVZ image:

docker/scripts/run.sh

@@ -34,7 +34,7 @@ QEMU_BIN="qemu/build/qemu-system-${QEMU_ARCH}"
 
 if [ ! -f "$FILESYSTEM_PATH" ]; then
     echo "Error: SD-card image '$FILESYSTEM_PATH' not found." >&2
-    echo "       Build & deploy it first: build.sh bsp-so3 && deploy.sh bsp-so3" >&2
+    echo "       Build & deploy it first: build.sh bsp-so3 && build.sh -x filesystem && deploy.sh bsp-so3" >&2
     exit 1
 fi