Editing Current Software Specifications

= Software Stack: From First Boot to Full Distribution =

'''Note: This is an initial draft of the software roadmap for the PowerPC Notebook project. This should be treated as high level thinking for now to give us a starting point rather than as a finalized roadmap. Comments and contributions are welcome.''' &nbsp;<br>'''Target architecture: PPC64 Big Endian.'''

== Introduction ==

The software stack for the PowerPC Notebook is a critical enabler for the hardware. Our challenge is to bring up a modern, open-source Linux system on non-mainstream architecture (PowerPC), using a custom motherboard based on the NXP T2080 SoC (?). That means:

* Bootstrapping software from scratch, with limited upstream support &nbsp;<br>* Building and testing a minimal Linux system to prove hardware works &nbsp;<br>* Gradually evolving toward a user-friendly, maintainable Linux distribution &nbsp;
We outline a '''progressive roadmap''': from booting the board to building our own distro, using modern infrastructure and tools wherever possible.

== 1. Basic Plan: Booting the First Prototype ==

The first goal is to ensure our hardware can boot into a minimal Linux environment.

=== What Needs to Be Done ===

{| class="wikitable" style="margin:auto"<br>! Task !! Description<br>|-<br>| Set up cross toolchain || Use NXP’s PowerPC GCC SDK for T2080<br>|-<br>| Build U-Boot || Start from &lt;code&gt;T2080RDB_defconfig&lt;/code&gt;, customize for our board<br>|-<br>| Write Device Tree (DTS) || Tailor the .dts to our motherboard’s peripherals<br>|-<br>| Build kernel || Use NXP's patched or mainline kernel with minimal config<br>|-<br>| Load root filesystem || Use Initramfs, NFS, SD card or TFTP<br>|-<br>| Test via serial console || Use UART for logs and early debugging<br>|}

=== Why ===

* Validates CPU, memory, and power circuitry &nbsp;<br>* Enables testing and debugging of other peripherals &nbsp;<br>* Serves as foundation for OS bring-up and userland development

== 2. Essentials: Proving the Prototype Works ==

Once we can boot, we need a minimal userland to interact with the system.

=== Components Required ===<br>{| class="wikitable"<br>! Component !! Functionality<br>|-<br>| U-Boot || Initialize CPU, memory, load kernel<br>|-<br>| Linux kernel || Hardware detection and device drivers<br>|-<br>| Root filesystem || BusyBox or minimal Debian NFS root<br>|-<br>| Serial console || Primary I/O for early interaction<br>|-<br>| Storage access || SD, SATA, or USB (at least one working path)<br>|-<br>| Device tree blob || Custom for motherboard<br>|}

=== Goal ===

* Boot into a shell prompt &nbsp;<br>* Validate basic system resources (&lt;code&gt;/proc/cpuinfo&lt;/code&gt;, &lt;code&gt;dmesg&lt;/code&gt;, etc.) &nbsp;<br>* Confirm networking, storage, and peripheral availability &nbsp;

== 3. Nice-to-Haves: Editors, Tools, and Utilities ==

Once the system is up, we add tools to support development, testing, and usability.

=== Suggested Additions ===<br>{| class="wikitable"<br>! Category !! Tools<br>|-<br>| Editors || nano, vim<br>|-<br>| Networking || curl, wget, ping, ssh<br>|-<br>| Debugging || gdb, strace, perf, valgrind<br>|-<br>| System info || htop, lshw, i2c-tools, lsusb<br>|-<br>| Disk tools || fdisk, parted, e2fsprogs, btrfs-progs<br>|-<br>| Package management || apt, dpkg, or apk (depending on base)<br>|}

== 4. Distro: Building Our Own PowerPC Linux Distribution ==

Eventually, we want a user-facing Linux distribution specifically optimized for the PowerPC Notebook.

=== Building Blocks ===<br>{| class="wikitable"<br>! Component !! Details<br>|-<br>| Base System || Debian PPC64, Gentoo, or Void PPC<br>|-<br>| Kernel || Custom-built with PowerPC Notebook config<br>|-<br>| Init system || systemd or OpenRC<br>|-<br>| Package management || apt (Debian), emerge (Gentoo), xbps (Void)<br>|-<br>| Desktop environment || XFCE, MATE, GNOME (PPC64 builds)<br>|-<br>| Installer || CLI or graphical installer image<br>|-<br>| Update system || apt repos or rsync-based delta updates<br>|-<br>| Branding || Custom themes, logos, powerpcnotebook.org<br>|}

=== Distro Build Systems to Consider ===

* debootstrap / live-build (Debian-based builds) &nbsp;<br>* Buildroot (for minimal rootfs + kernel images) &nbsp;<br>* Yocto Project (flexible meta-distribution) &nbsp;<br>* Gentoo Catalyst (for full ISO or stage builds) &nbsp;

== 5. Reusing and Cross-compiling from Existing Distros ==

Before reinventing the wheel, we aim to reuse as much as possible from other PowerPC-supporting Linux distributions.

=== Sources of Reusable Packages ===<br>* '''Debian Ports''': Many packages already built for PPC64 (Big Endian) &nbsp;<br>* '''Gentoo PPC64''': Source-based packages easily recompiled for our target &nbsp;<br>* '''Void Linux PPC''': Lightweight, musl or glibc-based &nbsp;<br>* '''Buildroot''': Embedded-focused, ideal for minimal images &nbsp;<br>* '''Yocto layers/meta-ppc''': Helpful BSPs and tooling &nbsp;

=== Cross-compiling Approach ===

1. Use `powerpc64-linux-gnu-gcc` cross-toolchain &nbsp;<br>2. Cross-compile Debian source packages or Gentoo ebuilds &nbsp;<br>3. Create our own package repository (e.g., Debian-style repo or overlay FS) &nbsp;<br>4. Validate on QEMU before deploying to real hardware &nbsp;

=== Tools and Infrastructure ===<br>{| class="wikitable"<br>! Purpose !! Tool<br>|-<br>| Source retrieval || apt-src, emerge, xbps-src<br>|-<br>| Compilation || cross-make, dpkg-buildpackage, Gentoo's crossdev<br>|-<br>| Patching || quilt, debdiff, git am<br>|-<br>| Staging and testing || chroot, Docker, QEMU<br>|}

'''Goal''': Reduce duplication, benefit from upstream security updates, and create a lean maintainable software stack.

== 6. CI/CD Pipelines and Build Infrastructure ==

To ensure maintainability, reproducibility, and collaboration, we aim to adopt continuous integration and modern DevOps practices.

=== CI/CD Goals ===

* Automatically build U-Boot, kernel, and rootfs images &nbsp;<br>* Run tests on emulated environments (QEMU PPC64) &nbsp;<br>* Deploy daily/weekly builds for community testing &nbsp;<br>* Detect regressions early and validate commits &nbsp;
=== Tools ===<br>{| class="wikitable"<br>! Use Case !! Toolchain<br>|-<br>| CI/CD pipelines || GitHub Actions, GitLab CI, Buildbot<br>|-<br>| Emulated testing || QEMU PowerPC64 + expect/serial scripts<br>|-<br>| Cross-builds || Docker + &lt;code&gt;powerpc64-linux-gnu-gcc&lt;/code&gt; toolchains<br>|-<br>| Image hosting || GitHub Pages, Netlify, custom CDN<br>|-<br>| Build orchestration || cbuild, Yocto Autobuilder, Jenkins<br>|}

== 7. Docker Images for Build and Dev Environments ==

Pre-configured Docker images help developers build and test quickly across any host system.

=== Use Cases ===

* Build U-Boot or Linux kernel from any host &nbsp;<br>* Package testing in isolated environments &nbsp;<br>* Running PPC-specific tools in reproducible containers &nbsp;
=== Example Images ===<br>{| class="wikitable"<br>! Image Name !! Description<br>|-<br>| powerpc-dev-env || Full dev env with toolchain and make<br>|-<br>| powerpc-kernel-builder || Kernel-specific builder and configs<br>|-<br>| powerpc-debian-chroot || Debootstrap PPC64 rootfs for package test<br>|}

== 8. Inspirations from Debian and Other Projects ==

We aim to reuse and adapt ideas from existing projects to accelerate development.

=== Relevant Debian Practices ===

* Reproducible Builds &nbsp;<br>* Debian Ports infrastructure &nbsp;<br>* &lt;code&gt;live-build&lt;/code&gt; and &lt;code&gt;debootstrap&lt;/code&gt; &nbsp;<br>* Debian Installer (&lt;code&gt;d-i&lt;/code&gt;) &nbsp;<br>* QA tools: lintian, piuparts, autopkgtest &nbsp;
=== Related Projects to Watch ===<br>{| class="wikitable"<br>! Project !! Relevance<br>|-<br>| Debian PowerPC || Maintains PPC64 ports and packages<br>|-<br>| Void PPC || Maintains lightweight PPC builds<br>|-<br>| Gentoo PPC || Flexible, source-based PPC support<br>|-<br>| Yocto/OpenEmbedded || Board support packages and rootfs config<br>|-<br>| OpenPOWER Firmware || Future firmware replacement roadmap<br>|}

== 9. Build Tooling (WIP Placeholder Section) ==

This section will document the exact steps, tools, and workflows needed to build every part of the software stack.

=== Build Tooling Overview ===

* Cross-toolchain setup (e.g. NXP SDK, crosstool-ng, LLVM)<br>* U-Boot build and customization<br>* Linux kernel configuration and build<br>* Root filesystem generation methods (debootstrap, Buildroot, Yocto)<br>* Build orchestration (Makefiles, shell scripts, CI runners)<br>* Packaging tools for our distro (dpkg, xbps, etc.)<br>* Secure image signing (U-Boot SPL, FIT images, secure boot)<br>* Emulator-based validation and test harnesses
'''Note:''' Details for each item will be populated progressively as we finalize architecture and test results.

== 10. Other Links and Resources ==

=== Technical Resources ===

* [https://www.nxp.com/products/processors-and-microcontrollers/power-architecture/qoriq-platforms/t-series/qoriq-t2080-and-t2081-multicore-communications-processors:T2080 NXP T2080 Reference Manual] &nbsp;<br>* [https://source.denx.de/u-boot/u-boot Denx U-Boot Git] &nbsp;<br>* [https://git.kernel.org/pub/scm/linux/kernel/git/powerpc/linux.git/ Linux PowerPC Git] &nbsp;<br>* [https://wiki.debian.org/PowerPC Debian PowerPC Wiki] &nbsp;<br>* [https://voidlinux-ppc.org/ Void PPC Project] &nbsp;

=== Community and Support ===

* [https://www.powerprogress.org/ Power Progress Community] &nbsp;<br>* [https://wiki.debian.org/PowerPC#Communication PowerPC IRC/Matrix] &nbsp;<br>* [https://openpowerfoundation.org/ OpenPOWER Foundation] &nbsp;<br>