FPGA-Core/Tutorial/phase-20-linux/phase-20.md

Phase 20 - Linux

Context

This is the summit: boot a minimal Linux kernel with a BusyBox initramfs to a shell over UART on the CPU and SoC you built.

Goals

• Build a kernel matching the implemented ISA and platform.
• Provide DTB and initramfs.
• Reach an interactive shell or a controlled init process.

New Concepts

• Kernel config: set of build-time options selecting architecture and drivers.
• Initramfs: initial root filesystem bundled or loaded with the kernel.
• BusyBox: compact Unix userland used in embedded systems.
• Early console: minimal logging path before normal console drivers initialize.
• Root filesystem: filesystem mounted as / by Linux.

How To Think About It

Linux bring-up is system debugging under poor visibility. Work from known-good layers: CPU tests, DRAM test, boot firmware, DTB validation, early console, then userspace.

Learning Tasks

• Understand the kernel image format and load addresses for RV32.
• Build the smallest kernel config that matches your hardware.
• Trace boot log milestones and map them to hardware dependencies.

Pitfalls

• Debugging Linux before compliance tests and DRAM tests are clean.
• Enabling drivers for devices you do not actually implement.
• Losing console output because UART binding or clock frequency is wrong.

Tooling And Testing

• Use earlycon/earlyprintk-style mechanisms where applicable.
• Keep kernel, DTB, firmware, and bitstream versions tied together.
• Save full boot logs and compare against previous attempts.

References

• Linux RISC-V documentation: https://docs.kernel.org/arch/riscv/
• Buildroot: https://buildroot.org/
• BusyBox: https://busybox.net/