diff --git a/README.md b/README.md index 4095b7060..d9a0e4811 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,9 @@ development of the SO3 ecosystem, in particular [HEIG-VD](https://www.heig-vd.ch) and the [Hasler Foundation](https://haslerstiftung.ch/en/welcome-to-the-hasler-foundation). +We are also grateful to all the contributors — developers, students, researchers +and community members alike — whose code, ideas and feedback have shaped SO3. + ## License SO3 is released under the [GNU General Public License v2](LICENSE). diff --git a/doc/source/avz.rst b/doc/source/avz.rst index b584d2f30..32bed9718 100644 --- a/doc/source/avz.rst +++ b/doc/source/avz.rst @@ -115,6 +115,8 @@ through ``__mmu_switch_vttbr()`` (``arch/arm64/context.S``). Inter-domain communication ========================== +.. _event_channels: + Event channels -------------- diff --git a/doc/source/build_system.rst b/doc/source/build_system.rst index e0cef8663..9f0a5a23d 100644 --- a/doc/source/build_system.rst +++ b/doc/source/build_system.rst @@ -173,7 +173,7 @@ boots through ARM-TF (EL3 → EL2), and ``full`` additionally loads OP-TEE. The build & deploy scripts ========================== -``scripts/build.sh`` runs bitbake to *build* artefacts: +``build.sh`` runs bitbake to *build* artefacts: .. flat-table:: :header-rows: 1 @@ -193,7 +193,7 @@ The build & deploy scripts * - ``-l`` / ``-v`` - **list** all recipes / **verbose** bitbake output. -``scripts/deploy.sh`` then *writes the boot media* (and opens the ``sudo -n`` +``deploy.sh`` then *writes the boot media* (and opens the ``sudo -n`` session the privileged tasks need): ``deploy.sh `` (``-x`` optional) deploys it — a BSP writes the whole image (rootfs → p2 + FIT/ITB → p1), a component (e.g. ``usr-so3``) deploys just its part. ``-l`` / ``-v`` list / @@ -268,7 +268,7 @@ component trees through ``${IB_*_PATH}`` placeholders. The ``do_itb`` task (``so3/images/`` or ``linux/images/``) — expanding ``${IB_SO3_PATH}``, ``${IB_AVZ_PATH}``, ``${IB_LINUX_PATH}`` and ``${IB_ROOTFS_PATH}`` to absolute paths — then assembles the ``.itb`` there with ``mkimage`` (there is no committed -``target/`` tree anymore): +``target/`` tree): .. flat-table:: :header-rows: 1 @@ -347,7 +347,7 @@ hand: #. Edit the working tree directly (e.g. ``qemu/hw/arm/virt.c``). #. Build to test (``build.sh -x qemu``). -#. Regenerate the patches: ``scripts/updiff.sh qemu``. +#. Regenerate the patches: ``updiff.sh qemu``. ``updiff`` (``patch.bbclass``) diffs the pristine upstream snapshot (``${S}.pristine``, taken right after fetch) against the working tree and writes diff --git a/doc/source/capsules.rst b/doc/source/capsules.rst index e77c3e83e..9613a24a9 100644 --- a/doc/source/capsules.rst +++ b/doc/source/capsules.rst @@ -11,10 +11,10 @@ split (frontend/backend) drivers. .. note:: *SO3 Capsule* / *S3C* is the current name and acronym for the concept that - older code and papers called a *Mobile Entity* (ME). The source tree now uses + older code and papers called a *Mobile Entity* (ME). The source tree uses the **S3C** acronym in identifiers (``S3C_desc_t``, ``S3C_state_t``, ``S3C_domID``, ``MAX_S3C_DOMAINS`` …) and *capsule* in prose. The legacy - ``ME`` spelling no longer appears in the code. + ``ME`` spelling does not appear in the code. The agency: Linux + the SOO framework ===================================== @@ -64,7 +64,7 @@ Split (frontend/backend) drivers Every virtual device a capsule uses is a **split driver**: a **frontend** in the capsule talks to a **backend** in the Linux agency through a shared memory ring -and an event channel (set up with grant tables and :ref:`event channels `). +and an event channel (set up with grant tables and :ref:`event channels `). .. figure:: img/so3_capsule.png :width: 100% diff --git a/doc/source/conf.py b/doc/source/conf.py index dd8e4108f..0f295191f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -67,10 +67,10 @@ # built documents. # # The short X.Y version. -version = u'6.1.0' +version = u'6.2.0' # The full version, including alpha/beta/rc tags. -release = u'6.1.0' +release = u'6.2.0' # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/doc/source/debugging.rst b/doc/source/debugging.rst index 3f126e750..7798f7b3d 100644 --- a/doc/source/debugging.rst +++ b/doc/source/debugging.rst @@ -18,9 +18,9 @@ ELF to get source-level debugging while the target runs the matching ``.bin``. Attaching GDB to QEMU ===================== -The launch script already exposes a GDB stub: ``scripts/st.sh`` starts QEMU with +The launch script already exposes a GDB stub: ``st.sh`` starts QEMU with ``-gdb tcp::1234``. To make QEMU **wait** for the debugger before executing the -first instruction, pass ``-S`` through to QEMU (``./scripts/st.sh -S``), or invoke +first instruction, pass ``-S`` through to QEMU (``st.sh -S``), or invoke the patched emulator directly. A minimal headless invocation looks like: .. code-block:: bash @@ -99,7 +99,7 @@ when EL2-only code runs at EL1). Debugging AVZ ============= -For the hypervisor, run ``scripts/st.sh`` with an AVZ ITS selected (it enables +For the hypervisor, run ``st.sh`` with an AVZ ITS selected (it enables EL2 automatically) and pass ``-S`` to wait for the debugger. Load symbols from the hypervisor ELF (``avz/so3``) for the EL2 code and from the SO3 guest ELF (``so3/so3/so3``) for the EL1 guest. The AVZ console trace (the *Loading Guest diff --git a/doc/source/display_input.rst b/doc/source/display_input.rst index 598319158..de5e88b00 100644 --- a/doc/source/display_input.rst +++ b/doc/source/display_input.rst @@ -146,7 +146,7 @@ relative PL050 mouse (``kmi1.c``) is kept in the tree but its dts node is The host GTK window (``stg.sh``) ================================ -The graphical launcher ``scripts/stg.sh`` starts QEMU with the **GTK** display +The graphical launcher ``stg.sh`` starts QEMU with the **GTK** display backend (``-display gtk,zoom-to-fit=off``): * **GTK, not SDL** — the SDL backend does not present the PL111 console surface @@ -160,7 +160,7 @@ backend (``-display gtk,zoom-to-fit=off``): gives a uniform pointer-to-surface mapping, so the cursors coincide on every monitor. It is harmless on a native X11 session. -``scripts/st.sh`` is the headless sibling (``-display none``): no window, console +``st.sh`` is the headless sibling (``-display none``): no window, console only, used for non-graphical work and CI. .. _console_sigint: diff --git a/doc/source/img/so3.drawio b/doc/source/img/so3.drawio index 94aadb885..8faf2c66c 100644 --- a/doc/source/img/so3.drawio +++ b/doc/source/img/so3.drawio @@ -1,2 +1,2 @@ \ No newline at end of file +(e1c-boot x0/x1)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;strokeColor=#444444;fontSize=10;" edge="1" parent="1" source="c4" target="c5"> \ No newline at end of file diff --git a/doc/source/img/so3_build.png b/doc/source/img/so3_build.png index 1875c6bdb..f273c77f3 100644 Binary files a/doc/source/img/so3_build.png and b/doc/source/img/so3_build.png differ diff --git a/doc/source/index.rst b/doc/source/index.rst index 02bc3883f..0c27c9806 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -111,4 +111,7 @@ We would like to thank our sponsors for their generous support in funding the development of the SO3 ecosystem, especially `HEIG-VD `__ and the `Hasler Foundation `__. +We are also grateful to all the contributors — developers, students, researchers +and community members alike — whose code, ideas and feedback have shaped SO3. + .. _SOO_mail: info@soo.tech diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst index 7502e4434..39fc3a1fa 100644 --- a/doc/source/introduction.rst +++ b/doc/source/introduction.rst @@ -49,9 +49,9 @@ SO3 capsule .. note:: *SO3 Capsule*, abbreviated **S3C**, is the current name and acronym for what - older code and papers called a *Mobile Entity* (ME). The code base now uses + older code and papers called a *Mobile Entity* (ME). The code base uses the ``S3C`` acronym in identifiers and *capsule* in prose; the ``ME`` spelling - no longer appears. + does not appear. Approach and philosophy ======================= diff --git a/doc/source/lvgl.rst b/doc/source/lvgl.rst index 3bfd460df..bc4d32133 100644 --- a/doc/source/lvgl.rst +++ b/doc/source/lvgl.rst @@ -88,7 +88,7 @@ real window): .. code-block:: bash - ./scripts/stg.sh + stg.sh QEMU opens a GTK window that shows the PL111 framebuffer; launch an LVGL application from the ``so3%`` prompt to draw into it, for example:: diff --git a/doc/source/micropython.rst b/doc/source/micropython.rst index 01259f681..365c71204 100644 --- a/doc/source/micropython.rst +++ b/doc/source/micropython.rst @@ -22,7 +22,7 @@ Using Micropython in the emulated environment Micropython currently works only for the virt64 platform Micropython is built along with the rest of the user space (the ``usr-so3`` -recipe — ``./scripts/build.sh -x usr-so3``; see :ref:`user_space`). Its CMake +recipe — ``build.sh -x usr-so3``; see :ref:`user_space`). Its CMake rules drive the Makefile in ``so3/usr/src/micropython/ports/soo`` and the resulting ``firmware.elf`` is renamed ``uPython.elf`` and gathered with the other applications for the root filesystem. diff --git a/doc/source/user_guide.rst b/doc/source/user_guide.rst index ab0d201b0..706586420 100644 --- a/doc/source/user_guide.rst +++ b/doc/source/user_guide.rst @@ -62,20 +62,20 @@ the FIT image): .. code-block:: bash - ./scripts/build.sh bsp-so3 + build.sh bsp-so3 **4. Deploy** onto the virtual SD-card (this opens the sudo session and writes the boot partition): .. code-block:: bash - ./scripts/deploy.sh bsp-so3 + deploy.sh bsp-so3 **5. Run:** .. code-block:: bash - ./scripts/st.sh + st.sh You should land at the ``so3%`` prompt. @@ -83,8 +83,8 @@ You should land at the ``so3%`` prompt. After editing only the kernel, rebuild and redeploy it without a full rebuild:: - ./scripts/build.sh -x so3 - ./scripts/deploy.sh bsp-so3 + build.sh -x so3 + deploy.sh bsp-so3 The ``deploy.sh bsp-so3`` step is required because the in-tree kernel binary is not tracked by bitbake (see :ref:`build_system`). @@ -98,10 +98,10 @@ Launch scripts * - Script - Use - * - ``scripts/st.sh`` + * - ``st.sh`` - **headless** run (``-display none``) — serial console only. The default for non-graphical work and CI. - * - ``scripts/stg.sh`` + * - ``stg.sh`` - **graphical** run — a GTK window for the PL111 framebuffer (LVGL, ``fb_test``). See :ref:`display_input`. @@ -137,15 +137,15 @@ To run SO3 as a **guest** on top of AVZ (``CONFIG_SOO=n``, no capsules): .. code-block:: bash - ./scripts/build.sh -x avz - ./scripts/build.sh bsp-so3 - ./scripts/deploy.sh bsp-so3 + build.sh -x avz + build.sh bsp-so3 + deploy.sh bsp-so3 **3.** Run — ``st.sh`` enables EL2 automatically because the ITS is an AVZ image: .. code-block:: bash - ./scripts/st.sh + st.sh .. note:: @@ -167,8 +167,8 @@ relevant ``CMakeLists.txt``. Rebuild and redeploy the user space: .. code-block:: bash - ./scripts/build.sh -x usr-so3 - ./scripts/deploy.sh bsp-so3 # repack the rootfs into the FIT image + write the boot media + build.sh -x usr-so3 + deploy.sh bsp-so3 # repack the rootfs into the FIT image + write the boot media See :ref:`user_space` for the user-space build details and the bundled applications. diff --git a/doc/source/user_space.rst b/doc/source/user_space.rst index 3ce7b4216..dc033c2c6 100644 --- a/doc/source/user_space.rst +++ b/doc/source/user_space.rst @@ -28,9 +28,9 @@ user space with: .. code-block:: bash - ./scripts/build.sh -x usr-so3 # configure + cross-compile (CMake + MUSL) - ./scripts/deploy.sh -x usr-so3 # repopulate so3/rootfs/rootfs.fat with the apps - ./scripts/deploy.sh bsp-so3 # repack rootfs into the FIT image + write the boot media + build.sh -x usr-so3 # configure + cross-compile (CMake + MUSL) + deploy.sh -x usr-so3 # repopulate so3/rootfs/rootfs.fat with the apps + deploy.sh bsp-so3 # repack rootfs into the FIT image + write the boot media The recipe configures and builds under ``so3/usr/build/`` and gathers the deployable, statically-linked ``*.elf`` binaries for the root filesystem. Adding @@ -137,7 +137,7 @@ line reading. .. note:: - Each process now has a **current working directory** (``pcb->cwd``, default + Each process has a **current working directory** (``pcb->cwd``, default ``/``, inherited across ``fork()`` and preserved across ``execve()``). The ``chdir`` / ``getcwd`` syscalls back the ``cd`` / ``pwd`` builtins, and the VFS resolves relative paths (and ``.`` / ``..``) against the cwd before @@ -151,8 +151,8 @@ Root filesystem The applications are delivered through a root filesystem. In the default (ramfs) configuration this is a FAT image, ``so3/rootfs/rootfs.fat``, built by the ``rootfs-so3`` recipe (``meta-rootfs``) from the freshly built user binaries. -``./scripts/deploy.sh bsp-so3`` packs it into the FIT image and writes it to -the SD-card (:ref:`user_guide`); ``./scripts/build.sh bsp-so3`` does the whole +``deploy.sh bsp-so3`` packs it into the FIT image and writes it to +the SD-card (:ref:`user_guide`); ``build.sh bsp-so3`` does the whole build + image in one step. The FAT image can be inspected on the host (e.g. with ``mtools``) — useful when debugging what actually ended up on the target.