README.md

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-Boot bl33.bin from l4t-community/bootstack/u-boot
    • bootstack_full_fedora — packages boot.scr, bl31.bin, bl33.bin, icons, ini
  • COPR: linux4switch/l4s produces 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.