From 2d924f07e794bafead9ee317144224a683843134 Mon Sep 17 00:00:00 2001 From: Daniel Rossier Date: Wed, 1 Jul 2026 20:36:31 +0200 Subject: [PATCH 1/2] ci(docs): serialize gh-pages deploys per ref A burst of pushes (e.g. several PRs merged to main within seconds) could race multiple gh-pages deployments, failing with "in progress deployment". Add a concurrency group keyed on the ref with cancel-in-progress so only the latest run deploys. --- .github/workflows/documentation.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index be5753ca44..edafc71e8c 100644 --- a/.github/workflows/documentation.yaml +++ b/.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 From e1256d258a039d0c5f6805b4d24820d7c15d7ca7 Mon Sep 17 00:00:00 2001 From: Daniel Rossier Date: Wed, 1 Jul 2026 20:36:31 +0200 Subject: [PATCH 2/2] doc: document the separate filesystem-image creation step build.sh bsp-so3 only compiles; the empty SD-card image is produced by the privileged 'filesystem' recipe (losetup/mkfs/parted), and deploy.sh populates but does not create it. Document the canonical first-build sequence (build.sh bsp-so3 -> build.sh -x filesystem -> deploy.sh bsp-so3) in the build system + user guide (incl. the AVZ-guest path), and point run.sh's missing-image error at the filesystem step. --- doc/source/build_system.rst | 16 ++++++++++++++++ doc/source/user_guide.rst | 17 ++++++++++++++--- docker/scripts/run.sh | 2 +- 3 files changed, 31 insertions(+), 4 deletions(-) diff --git a/doc/source/build_system.rst b/doc/source/build_system.rst index 9f0a5a23dc..1e3ff41fa5 100644 --- a/doc/source/build_system.rst +++ b/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.`` 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 `` + + ``deploy.sh bsp-so3`` — the ``filesystem`` step is a one-off. + .. note:: ``build.sh`` / ``deploy.sh`` take the recipe as a **positional argument** diff --git a/doc/source/user_guide.rst b/doc/source/user_guide.rst index 7065864207..85abda5d3e 100644 --- a/doc/source/user_guide.rst +++ b/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.``) 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: diff --git a/docker/scripts/run.sh b/docker/scripts/run.sh index 8674c4b4d2..a593c4abe2 100755 --- a/docker/scripts/run.sh +++ b/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