255 migrate the so3 build system to infrabase and move to the new so3 logo

.dockerignore

@@ -1,14 +1,39 @@
+# Docker build context excludes (mainly for docker/Dockerfile.lvperf_* which
+# `COPY . /so3`). Keep the context small and reproducible: drop VCS data, the
+# bitbake work tree and the fetched component trees — Infrabase re-fetches and
+# re-patches the latter during the image build.
+
+# VCS / IDE
+.git
+.github
 .metadata
 */.project
 */.cproject
-.git
-.github
-*.o
-bsp/
-*/sdcard.*
-rootfs/board
-*/*.itb
-usr/lib/libxml2
-usr/build
 
+# Sphinx documentation build output
+doc/build
+
+# Infrabase bitbake work tree (huge, host-specific, regenerated)
+build/tmp
+build/cache
+build/bitbake.lock
+build/bitbake-cookerdaemon.log
+
+# Fetched + patched component trees (re-fetched & re-patched by Infrabase)
+qemu
+u-boot
+avz
+atf
+qemu.back
+u-boot.back
 
+# Generated disk / boot images
+filesystem/*.img*
+filesystem/*.itb
+filesystem/flash0.img
+
+# In-tree build artefacts (regenerated by the build)
+*.o
+so3/so3/so3.bin
+so3/usr/build
+so3/usr/out

.github/workflows/build.yml

@@ -7,39 +7,36 @@ on:
   pull_request:
     branches: ["main"]
 
+# Smoke-build SO3 with Infrabase (bitbake) inside the so3-env image. Both the
+# kernel (build.sh -k so3) and the user space (build.sh -x usr-so3, which also
+# builds the MUSL toolchain via meta-toolchain) are non-privileged, so a plain
+# `docker run` (no --privileged) is enough. The repo is mounted at /so3.
 jobs:
-  build-so3:
+  build:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        # We use the virtXX_fb configs as they're based on the normal virtXX configs with aditional fb support
-        CONFIG: ['virt32_fb_defconfig', 
-                 'virt64_fb_defconfig',
-                 'virt32_lvperf_defconfig',
-        ]
+        PLATFORM: [virt32, virt64]
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
-
-      - name: Build 
-        run: |
-          docker run --rm -v "${PWD}:/so3" ghcr.io/smartobjectoriented/so3-env:latest bash -c "cd so3 && make ${{ matrix.CONFIG }} && make -j`nproc`"
-
-  build-usr:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        CMAKE_TOOLCHAIN_FILE: ['aarch64-linux-musl.cmake',
-                               'arm-linux-musl.cmake']
-        BUILD_TYPE: ['Debug', 'Release']
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: 'true'
 
-      - name: Build
+      - name: Build kernel + user space (Infrabase)
         run: |
-          docker run --rm -t -v "${PWD}:/so3" ghcr.io/smartobjectoriented/so3-env:latest bash -c "mkdir usr/build && cd usr/build && cmake --no-warn-unused-cli -DCMAKE_C_FLAGS='-Werror' -Wno-dev -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -DCMAKE_TOOLCHAIN_FILE=../${{matrix.CMAKE_TOOLCHAIN_FILE }} .. && make -j`nproc`"
+          docker run --rm -v "${PWD}:/so3" \
+            ghcr.io/smartobjectoriented/so3-env:latest bash -c '
+              set -e
+              cd /so3
+              echo "IB_PLATFORM = \"${{ matrix.PLATFORM }}\"" >> build/conf/local.conf
+              . ./env.sh
+              build.sh -k so3
+              build.sh -x usr-so3 || {
+                rc=$?
+                echo "=== build failed (rc=$rc); tail of musl-toolchain do_build log ==="
+                tail -n 120 build/tmp/work/musl-toolchain-1.0-r0/temp/log.do_build* 2>/dev/null || true
+                exit $rc
+              }
+            '

.github/workflows/style.yml

@@ -19,11 +19,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # check-path must be a real directory, otherwise the action silently
+        # falls back to scanning the whole repo. The SO3 sources are nested
+        # under so3/ since the Infrabase migration: so3/so3 (kernel) and
+        # so3/usr (user space). Vendored/third-party trees carry their own
+        # style and are excluded: micropython and libxml2 (tracked), the
+        # usr/lib/linux headers, and lvgl (fetched at build time / gitignored,
+        # listed for safety).
         path:
-          - check: "so3"
-            exclude: ".S"
-          - check: "usr/src"
-            exclude: "(micropython|lv_)"
+          - check: "so3/so3"
+            exclude: '\.S$'
+          - check: "so3/usr"
+            exclude: '(micropython|libxml2|usr/lib/linux|lvgl|lv_)'
     steps:
       - uses: actions/checkout@v4
       - name: Run clang-format style check for C/C++/Protobuf programs.

.gitignore

@@ -16,6 +16,22 @@
 
 **/build
 
+# The top-level infrabase metadata tree (/build) is matched by **/build above,
+# which used to force recipe sources (patches, .bb/.inc, conf) to be added with
+# `git add -f` — easy to forget, and a forgotten patch breaks CI parsing. Un-ignore
+# /build, re-ignore everything one level under it, then re-include only the source
+# dirs. Build output stays ignored: build/tmp (also build/.gitignore), build/cache,
+# build/bitbake.lock, logs/artifacts (*.log, *.o, *.dtb, *.itb, ... from the rules
+# above). Nested build/ dirs elsewhere (optee_os, agency, avz) remain ignored.
+!/build/
+/build/*
+!/build/conf/
+!/build/meta-*/
+
+# The fetched ATF source tree lives at the repo root (/atf), like /u-boot, /avz,
+# qemu. Anchor to /atf so the bare name doesn't also match the meta-atf recipe
+# directory (build/meta-atf/recipes-atf/atf), which holds tracked recipe sources.
+/atf/
 #vmlinux*
 uImage*
 domains*
@@ -55,14 +71,42 @@ agency/rootfs/target/**
 !agency/rootfs/board/**/*.d
 
 *asm-offsets.s
-so3/so3
-so3/so3.bin
-usr/lib/libc/include/asm
-rootfs/rootfs.fat
-filesystem/sdcard.img.*
-so3/scripts/basic/fixdep
-so3/scripts/dtc/dtc
-so3/scripts/kconfig/conf
-so3/scripts/kconfig/lex.zconf.c
-so3/scripts/kconfig/zconf.hash.c
-so3/scripts/kconfig/zconf.tab.c
+# SO3 sources are now nested under so3/ (so3/so3 = kernel, so3/usr, so3/rootfs, so3/target)
+so3/so3/so3
+so3/so3/so3.bin
+so3/usr/lib/libc/include/asm
+so3/rootfs/rootfs.fat
+# lvgl is fetched at build time (meta-usr lvgl bbappend, :lvgl override), not a submodule
+so3/usr/lib/lvgl/
+so3/so3/scripts/basic/fixdep
+so3/so3/scripts/dtc/dtc
+so3/so3/scripts/kconfig/conf
+so3/so3/scripts/kconfig/lex.zconf.c
+so3/so3/scripts/kconfig/zconf.hash.c
+so3/so3/scripts/kconfig/zconf.tab.c
+
+# AVZ out-of-tree (O=) build dir — only the script + readme are tracked,
+# everything else is generated by `build.sh -x avz`.
+/avz/*
+!/avz/build.sh
+!/avz/README.md
+
+# u-boot is FETCHED (meta-uboot recipe: github 2022.04 @ pinned SRCREV +
+# the SO3 patch set), like qemu/avz — not kept in-tree. The build attaches
+# the fetched tree here (backing any prior copy up to u-boot.back).
+/u-boot/
+
+# filesystem/ is entirely build output (sdcard images, u-boot.bin, work symlink)
+/filesystem/
+
+# Junk / build backups
+*.deb
+*.back
+# patch/quilt reject & backup files (e.g. do_updiff regeneration leftovers)
+*.orig
+*.rej
+# do_attach_infrabase dirty-tree guard manifests (sibling of each attached
+# component tree, e.g. avz.attach.sha256, u-boot.attach.sha256)
+*.attach.sha256
+__pycache__/
+/scripts.old/

README.md

@@ -1,29 +1,73 @@
+<p align="center">
+  <img src="doc/source/img/SO3_with_text.png" alt="SO3" width="420">
+</p>
 
+# Welcome to SO3 — the Smart Object Oriented (SOO) Operating System
 
-Welcome to the Smart Object Oriented (SOO) Operating System (code name SO3)
-***************************************************************************
+SO3 is a compact, lightweight, full-featured and extensible operating system,
+particularly well suited to embedded and IoT systems. It is the result of
+several years of research and development at the REDS Institute of HEIG-VD, has
+long been used as a teaching platform, and today forms the foundation of the
+**SOO** framework.
 
-For any information and discussions around SO3, please have a look at the [SO3 discussion forum](https://discourse.heig-vd.ch/c/so3).
+## A polymorphic operating system
 
-Feel free to post any comments/suggestions/remarks about SO3. If you wish to participate to development, please simply ask us and we will manage separate branches of development. 
+The most distinctive feature of SO3 is that it is **polymorphic**: from a
+**single source tree**, the very same code base can be configured and built into
+three different kinds of system.
 
-Furthermore, the full documentation is available [here](https://smartobjectoriented.github.io/so3)
+- **Standalone OS** — SO3 runs directly on the hardware as a conventional
+  monolithic OS (kernel at **EL1**, user applications at **EL0** on ARM64). This
+  is the configuration used for teaching and for plain embedded products.
+- **AVZ hypervisor** — built with `CONFIG_AVZ`, the same tree becomes **AVZ**
+  (*Agency VirtualiZer*), a lightweight type-1 hypervisor running at **EL2** that
+  hosts one or more guest *domains* — the primary guest being the *agency*.
+- **SO3 capsule (S3C)** — on top of AVZ, the **SOO** framework adds *SO3
+  capsules*: lightweight, self-contained guests running at EL1 beside a Linux
+  *agency* and cooperating with it through split (frontend/backend) drivers. The
+  capsule (guest) side lives in this repository; the Linux agency and the rest
+  of the SOO framework live in a separate one.
 
+SO3 targets ARM 32-bit and 64-bit, is multicore, and is kept *as compact as
+possible*. It ships with a MUSL-based user space and integrations such as LVGL,
+lwIP and MicroPython.
 
-We would like to extend our heartfelt thanks to our sponsors for their generous support in funding the development of the SO3 ecosystem, especially [HEIG-VD](http://www.heig-vd.ch) and the [Hasler Foundations](https://haslerstiftung.ch/en/welcome-to-the-hasler-foundation) 
+## Documentation
 
+The complete and up-to-date documentation — philosophy, architecture, build
+system, user guide, debugging and more — is the source of truth. It lives in
+[`doc/`](doc/) and is published at:
 
-Be careful with the requirements of various configs.
+### 👉 https://smartobjectoriented.github.io/so3
 
-- If you use avz -> ./st must have virtualization on => use ./stv
-- If you use the framebuffer (LVGL case) -> ./stg to start QEMU with the graphic display
+Start there for everything about building, configuring, running and debugging
+SO3.
 
-To build the patch related to the CI:
+## Supported targets
 
-- diff -Naur <source> <result> > so3_ci.patch
-and put the ci/so3_ci.patch in ci/
+- QEMU `virt` — ARM 32-bit and 64-bit
+- Raspberry Pi 4 (64-bit)
+- Toradex Verdin iMX8M Plus
 
-To apply the patch, in the root:
-- patch -p1 < ci/so3_ci.patch
+## Contributing
 
+The `main` branch always holds the last released version.
 
+> [!IMPORTANT]
+> Do not push directly to `main`. Each development is tracked by an issue with
+> its own branch; open a merge/pull request as soon as it is stable enough for
+> review.
+
+If you would like to contribute, please first get in touch with the maintainer at
+[info@soo.tech](mailto:info@soo.tech).
+
+## Credits
+
+We warmly thank our sponsors for their generous support in funding the
+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).
+
+## License
+
+SO3 is released under the [GNU General Public License v2](LICENSE).