Embedded Linux From Scratch

1- Why this project

Most embedded work uses a Linux image someone else built. This project goes the other way: it builds the system itself, layer by layer, to understand how an embedded Linux platform actually comes to life — from the boot ROM handoff to a shell running as PID 1, and down into kernel space with a custom driver.

2-Boot stack

The TI AM67A has a multi-stage, vendor-specific boot chain. The three TI binaries are reused as-is; everything in green was built in this project.

3- Cross-compiling the mainline kernel

Compiled on x86 (WSL2) for the ARM64 target, with board support verified in the config before building.

# verify board support (all must be =y)
grep CONFIG_ARCH_K3 .config          # TI K3 SoC
grep CONFIG_SERIAL_8250_OMAP .config # serial console
grep CONFIG_MMC_SDHCI_AM654 .config  # SD card

# build kernel + device trees + modules
make -j8 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- Image dtbs modules

4- Root-cause debugging: the WiFi that couldn't work

At boot, the WiFi service crash-looped. A funnel investigation (systemctl → ip link → dmesg → .config → device tree) peeled back three layers:

5-A rootfs from scratch → PID 1

A minimal root filesystem assembled by hand: a static BusyBox binary (~200 Unix commands in one file) plus a hand-written /init, the very first program the kernel launches.

#!/bin/sh — PID 1, first program launched by the kernel
mount -t proc none /proc
mount -t sysfs none /sys
mount -t devtmpfs none /dev
export PATH=/bin:/sbin:/usr/bin:/usr/sbin
exec setsid cttyhack /bin/sh   # shell attached to serial console

~ # ps
PID   USER     TIME  COMMAND
  1   0        0:00  /bin/sh      ← our shell is PID 1
~ # free
Mem: 3872428 total  51444 used  3813520 free   ← 51 MB for the whole system

6- Into kernel space: a real driver

Step 5 controlled hardware from userspace (a C app writing to /sys/class/leds/). This step crosses into kernel space: a platform driver bound through the device tree, the core pattern behind every real device. It registers a virtual LED in /sys/class/leds/ (no GPIO yet): the goal is to prove the binding mechanism, not to drive the physical LED, which uses the kernel's standard leds-gpio driver.

/* the driver declares what it handles */
static const struct of_device_id myled_of_match[] = {
    { .compatible = "steve,myled", },   // must match the device tree
    { },
};

static int myled_probe(struct platform_device *pdev) {
    const char *label;
    of_property_read_string(pdev->dev.of_node, "label", &label); // read DT property
    led_classdev_register(&pdev->dev, &myled_cdev);            // create /sys interface
    return 0;
}

The kernel calls probe() only when a device-tree node's compatible matches the driver's of_match_table, the same mechanism that activates the standard LED driver and leaves the unsupported WiFi inert.

myled-dt: probe() called - matched by device tree!
myled-dt: label from DT = 'hello-from-devicetree'
myled-dt: registered /sys/class/leds/myled-dt/

7- Bug log : the real content

Every bug taught something. A selection of the thirteen documented in the repo:

8-Key lessons

1. Deploying a kernel = Image + device tree + modules. Forgetting modules is the #1 trap.
2. The device tree decides which drivers activate, a loaded driver with no matching DT node stays inert.
3. Funnel debugging: descend from symptom to root cause, verify each hypothesis before concluding.
4. Boot-time memory layout matters, kernel, DT and initramfs must not overlap in RAM.
5. A platform driver is bound by the device tree, not by loading, insmod alone does nothing.
6. Vendor vs mainline is a real trade-off; knowing when not to forward-port is an engineering decision.