- Shell 71%
- C 29%
Switchroot Bootstack Documentation #
Personal fork/consolidation of the Switchroot L4T bootstack documentation, updated with modern (2025-2026) build infrastructure found in
l4t-community.
Why this exists #
The official switchroot/bootstack/documentation
repo is a single-commit stub from Jan 2024. All the actual development happens in
gitlab.com/l4t-community/ now. This repo tracks the real sources as submodules
and documents how to actually build a custom Linux image for the Nintendo Switch.
Repo layout #
.
├── BOOTSTACK_PLAN.md # Full build chain documentation (updated actively)
├── BUILD_FROM_SCRATCH.md # bootc-based next-gen build (F44 atomic images)
├── BOOTC_GUIDE.md # bootc architecture and Switch-specific constraints
├── JET_FACTORY_GUIDE.md # Legacy Python disk image builder (current approach)
├── switch-bootc/ # bootc Containerfiles, profiles, and assembly scripts
├── jet-factory/ # Legacy Python rootfs builder (git submodule)
├── boot.txt # Verified U-Boot boot script source (from l4s-pipeline)
├── documentation/ # git submodule: switchroot/bootstack/documentation (legacy)
├── l4s-pipeline/ # git submodule: l4t-community/gnu-linux/l4s-pipeline (modern CI)
├── build-scripts/ # git submodule: l4t-community/kernel/l4t-kernel-build-scripts
├── copr-specs/ # git submodule: l4t-community/gnu-linux/fedora-copr/l4s-bsp-kernel
│ # + l4s-bsp-bootstack.spec
└── README.md # This file
Key findings #
- Kernel: still 4.9.140, frozen by NVIDIA's L4T BSP.
- Modern distros (Fedora 44, Ubuntu Noble) run on this kernel via massive backports: cgroup v2, clone3, new mount API, futex_waitv, MGLRU, zram writeback.
- Active build pipeline:
l4s-pipeline(see submodule) builds kernel, U-Boot, bootstack, and triggers COPR + image builds. - Bootstack CI jobs:
32.3.1— builds kernel (uImage, dtimg, modules, headers)uboot— builds U-Bootbl33.binfroml4t-community/bootstack/u-bootbootstack_full_fedora— packages boot.scr, bl31.bin, bl33.bin, icons, ini
- COPR:
linux4switch/l4sproduces RPMs for Fedora images.
Verified boot chain #
hekate (payload) → ATF (bl31.bin) → U-Boot (bl33.bin) → boot.scr →
Kernel (uImage) + Initramfs + DTB (nx-plat.dtimg) → Rootfs (ext4)
All boot files live on the FAT32 partition at switchroot/<distro>/.
Next: reproducing locally #
See BOOTSTACK_PLAN.md for the full build order, dependency lists, and open
questions. The plan is updated as new sources are traced.
Disclaimer and motivation #
yes this repo is slopped by an LLM agent.
There seems to be no devdocs on how to build a custom L4T image from scratch, and there seem to be no public links to these repos except on the Discord server.
The fact that this requires me to ask an LLM agent to trace this whole CI/CD pipeline is genuinely hostile DX. no offense. If you would like to fund the kernel patches that make this work, please consider donating to the maintainers behind the actual project, and maybe beg for them to actually write devdocs in the meantime
https://www.patreon.com/azkali
https://github.com/sponsors/theofficialgman
Documentation and source code is crawled through by Hermes Agent w/ Kimi K2.6.