Ray Bello
Electronics

Expressif S3 Linux Support

Adding Linux support to esp32s3

ray

ray

@raykast_

Expressif S3 Linux Support

Introduction

Embedded Linux on microcontrollers has long been a tantalizing goal for makers and engineers alike. The esp32s3-linux project by Ray Bello brings this vision closer to reality, enabling a full Linux 6.5+ system to run on the ESP32-S3 SoC. By leveraging Docker for a fully containerized build environment and integrating Espressif’s network adapter firmware, this repo streamlines the process of compiling, packaging, and flashing a Linux image—no host toolchain installation required.

In this deep-dive, we’ll explore:

  1. Why Linux on ESP32-S3?
  2. Repo Anatomy & Workflow
  3. Containerized Build System
  4. Toolchain & Kernel Configuration
  5. Partition Layout & Flashing
  6. Runtime & Networking
  7. Customization & Extensibility
  8. Troubleshooting & Best Practices
  9. Use Cases & Roadmap

1. Why Linux on ESP32-S3?

1.1 The ESP32-S3 Advantage

  • AI acceleration with vector instructions and support for TinyML.
  • Dual-core Xtensa LX7 at up to 240 MHz, 8 MB flash/PSRAM variants.
  • Built-in Wi-Fi & BLE, unlocking networked applications.

1.2 Beyond FreeRTOS

While FreeRTOS excels at real-time, single-application tasks, Linux offers:

  • Multi-process, multi-user support
  • Rich POSIX filesystem and permissions
  • Standard toolchains (GCC, BusyBox, Python, MQTT, etc.)
  • SSH, networking stacks, and user-space daemons

This allows turning an ESP32-S3 into a tiny edge server, secure gateway, or autonomous device with familiar Linux tooling.

2. Repo Anatomy & Workflow

esp32s3-linux/
├── Dockerfile
├── scripts/
│   ├── rebuild.sh
│   ├── flash.sh
│   └── ...
├── firmware/       ← prebuilt or output binaries
├── release/        ← final build artifacts
├── .vscode/        ← optional IDE configs
└── README.md
  • Dockerfile: Defines the Ubuntu 22.04-based container that compiles toolchains, kernel, and rootfs.
  • scripts/: Orchestrators for full rebuilds and flashing.
  • firmware/ & release/: Hold firmware blobs (ESP-IDF), kernel image, and filesystems.

Workflow:

  1. Clone repo & submodules (git submodule update --init --recursive).
  2. docker build -t esp32s3-linux .
  3. docker run --device=/dev/ttyUSB0 -v $PWD/release:/app/build/release -it esp32s3-linux bash
  4. Inside container: ./scripts/rebuild.sh → artifacts in /app/build/release.
  5. Exit & docker cp artifacts back to host.
  6. ./scripts/flash.sh or manual esptool.py + parttool.py.

3. Containerized Build System

3.1 Why Docker?

  • Isolation: No host pollution by cross-compilers or kernel sources.
  • Reproducibility: Exact environment versioned in Dockerfile.
  • Portability: Works on Linux, macOS, Windows (with Docker Desktop).

3.2 Key Dockerfile Stages

StagePurpose
Base SetupInstalls git, build-essential, Python, cmake
Crosstool-NGBuilds xtensa-esp32s3-uclibc toolchain
Kernel BuildClones Linux 6.5+, configures and compiles XIP kernel
RootFS & DriversBuildroot generates cramfs, merges Wi-Fi firmware
CleanupPrunes intermediate layers, retains /app/build
FROM ubuntu:22.04 AS builder
ENV DEBIAN_FRONTEND=noninteractive
 
# 1. Install dependencies
RUN apt-get update && \
    apt-get install -y git build-essential python3 python3-pip cmake libncurses-dev ...
 
# 2. Crosstool-NG for Xtensa
RUN git clone --depth=1 https://github.com/crosstool-ng/crosstool-ng.git && \
    cd crosstool-ng && ./bootstrap && ./configure --prefix=/usr/local && make -j && make install
 
# 3. Configure & build toolchain
COPY crosstool.config /xtensa.config
RUN ct-ng build
 
# 4. Clone & build Linux kernel
RUN git clone --branch v6.5 https://github.com/torvalds/linux.git /linux && \
    cd /linux && make ARCH=xtensa esp32s3_defconfig && make -j
 
# 5. Buildroot + cramfs + firmware
...

Tip: If build times become excessive, you can leverage Docker build cache with minor tweaks to reorder install steps.

4. Toolchain & Kernel Configuration

4.1 Building the Xtensa Toolchain

  • Target triplet: xtensa-esp32s3-linux-uclibcfdpic

  • uClibc with fdpic (position-independent code) support, crucial for XIP.

  • Key ct-ng options:

    • CT_ARCH_XTENSA=y
    • CT_KERNEL_LINUX=y
    • CT_LIBC_UCLIBC=y
    • CT_LIBC_UCLIBC_FDPIC=y

4.2 Kernel Menuconfig Highlights

After make esp32s3_defconfig, run:

make ARCH=xtensa menuconfig

  • Processor type and features → Xtensa Settings

    • Enable CONFIG_MMU for Linux memory management.

  • Networking support → Wireless → esp32s3 wireless driver

    • Select ESP32S3 Wireless Firmware Loader to auto-bundle network_adapter.bin.

  • File systems → Compressed ROM file system support

    • CRAMFS for minimal footprint, or swap to JFFS2 if wear leveling needed.

5. Partition Layout & Flashing

5.1 Default Partition Table

PartitionTypeOffsetSizeDescription
bootloaderapp0x0000256 KBESP-IDF bootloader
networkdata0x400002 MBWi-Fi firmware (network_adapter.bin)
part-tabledata0x8000016 KBPartition definitions
linuxdata0xA00003.5 MBXIP kernel image
rootfsdata0x4200003.5 MBCRAMFS root filesystem
etcdata0x800000512 KBPersistent configs (e.g. wpa)

Pro tip: Adjust sizes via scripts/partition-table.csv to accommodate larger rootfs or JFFS2.

5.2 Flashing Steps

# 1. Write bootloader, network firmware, and partition table
esptool.py --chip esp32s3 -p /dev/ttyUSB0 -b 921600 \
  write_flash 0x0 bootloader.bin \
              0x40000 network_adapter.bin \
              0x80000 partition-table.bin
 
# 2. Use parttool for XIP+CRAMFS
parttool.py write_partition --partition-name linux  --input xipImage
parttool.py write_partition --partition-name rootfs  --input rootfs.cramfs
parttool.py write_partition --partition-name etc    --input etc.jffs2
  • esptool.py handles raw flash writes.
  • parttool.py (ESP-IDF) updates named partitions, preserving alignment and wear leveling.

6. Runtime & Networking

6.1 First Boot & Console

  • Serial console at 115200 baud; you should see kernel boot messages and mount of CRAMFS.
  • Default root user has no password; networking must be configured manually.

Capture of kernel boot

ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x1 (POWERON),boot:0x2b (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fce3808,len:0x1064
load:0x403c9700,len:0x9e0
load:0x403cc700,len:0x291c
entry 0x403c98d8
etc ptr = 0x420b0000
linux ptr = 0x42120000
rootfs ptr = 0x42480000
[    0.000000] Ignoring boot parameters at (ptrval)
[    0.000000] Linux version 6.5.0 (esp32@buildkitsandbox) (xtensa-esp32s3-linux-uclibcfdpic-gcc (crosstool-NG UNKNOWN) 14.0.0 20231029 (experimental), GNU ld (crosstool-NG UNKNOWN) 2.40.50.20230424) #1 PREEMPT Sat Dec 30 22:10:43 UTC 2023
[    0.000000] config ID: c2f0fffe:23090f1f
[    0.000000] earlycon: esp32s3uart0 at MMIO32 0x60000000 (options '115200n8,40000000')
[    0.000000] printk: bootconsole [esp32s3uart0] enabled
[    0.000000] **********************************************************
[    0.000000] **   NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE   **
[    0.000000] **                                                      **
[    0.000000] ** This system shows unhashed kernel memory addresses   **
[    0.000000] ** via the console, logs, and other interfaces. This    **
[    0.000000] ** might reduce the security of your system.            **
[    0.000000] **                                                      **
[    0.000000] ** If you see this message and you are not debugging    **
[    0.000000] ** the kernel, report this immediately to your system   **
[    0.000000] ** administrator!                                       **
[    0.000000] **                                                      **
[    0.000000] **   NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE   **
[    0.000000] **********************************************************
[    0.000000] Zone ranges:
[    0.000000]   Normal   [mem 0x000000003d800000-0x000000003dffffff]
[    0.000000] Movable zone start for each node
[    0.000000] Early memory node ranges
[    0.000000]   node   0: [mem 0x000000003d800000-0x000000003dffffff]
[    0.000000] Initmem setup node 0 [mem 0x000000003d800000-0x000000003dffffff]
[    0.000000] pcpu-alloc: s0 r0 d32768 u32768 alloc=1*32768
[    0.000000] pcpu-alloc: [0] 0 
[    0.000000] Kernel command line: earlycon=esp32s3uart,mmio32,0x60000000,115200n8,40000000 console=ttyS0,115200n8 debug rw root=mtd:rootfs no_hash_pointers 
[    0.000000] Dentry cache hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.000000] Inode-cache hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.000000] Built 1 zonelists, mobility grouping off.  Total pages: 2032
[    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
[    0.000000] virtual kernel memory layout:
[    0.000000]     lowmem  : 0x3d800000 - 0x3e000000  (    8 MB)
[    0.000000]     .text   : 0x42120000 - 0x4234eb30  ( 2234 kB)
[    0.000000]     .rodata : 0x4234f000 - 0x423a9000  (  360 kB)
[    0.000000]     .data   : 0x3d800000 - 0x3d87c6a0  (  497 kB)
[    0.000000]     .init   : 0x3d87c6a0 - 0x3d87f890  (   12 kB)
[    0.000000]     .bss    : 0x3d87f890 - 0x3d8b6410  (  218 kB)
[    0.000000] Memory: 7340K/8192K available (2234K kernel code, 497K rwdata, 360K rodata, 88K init, 218K bss, 852K reserved, 0K cma-reserved)
[    0.000000] SLUB: HWalign=16, Order=0-3, MinObjects=0, CPUs=1, Nodes=1
[    0.000000] rcu: Preemptible hierarchical RCU implementation.
[    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies.
[    0.000000] NR_IRQS: 33
[    0.000000] rcu: srcu_init: Setting srcu_struct sizes based on contention.
[    0.000000] Calibrating CPU frequency 160.00 MHz
[    0.000000] clocksource: ccount: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 11945377789 ns
[    0.000072] sched_clock: 32 bits at 160MHz, resolution 6ns, wraps every 13421772796ns
[    0.009515] Calibrating delay loop (skipped)... 160.00 BogoMIPS preset
[    0.013414] pid_max: default: 4096 minimum: 301
[    0.021355] Mount-cache hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.025454] Mountpoint-cache hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.080105] rcu: Hierarchical SRCU implementation.
[    0.080894] rcu: 	Max phase no-delay instances is 1000.
[    0.094345] devtmpfs: initialized
[    0.120763] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns
[    0.122090] futex hash table entries: 16 (order: -5, 192 bytes, linear)
[    0.140884] NET: Registered PF_NETLINK/PF_ROUTE protocol family
[    0.172668] platform soc: Fixed dependency cycle(s) with /soc/intc@600c2000
[    0.258813] clocksource: Switched to clocksource ccount
[    0.313741] NET: Registered PF_INET protocol family
[    0.322241] IP idents hash table entries: 2048 (order: 2, 16384 bytes, linear)
[    0.348130] tcp_listen_portaddr_hash hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.351909] Table-perturb hash table entries: 65536 (order: 6, 262144 bytes, linear)
[    0.356779] TCP established hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.365414] TCP bind hash table entries: 1024 (order: 1, 8192 bytes, linear)
[    0.372388] TCP: Hash tables configured (established 1024 bind 1024)
[    0.381244] UDP hash table entries: 256 (order: 0, 4096 bytes, linear)
[    0.384350] UDP-Lite hash table entries: 256 (order: 0, 4096 bytes, linear)
[    0.395525] NET: Registered PF_UNIX/PF_LOCAL protocol family
[    0.408650] RPC: Registered named UNIX socket transport module.
[    0.410967] RPC: Registered udp transport module.
[    0.411567] RPC: Registered tcp transport module.
[    0.414526] RPC: Registered tcp-with-tls transport module.
[    0.420964] RPC: Registered tcp NFSv4.1 backchannel transport module.
[    0.492979] Initialise system trusted keyrings
[    0.497341] workingset: timestamp_bits=30 max_order=11 bucket_order=0
[    0.508093] NFS: Registering the id_resolver key type
[    0.511341] Key type id_resolver registered
[    0.512153] Key type id_legacy registered
[    0.514392] jffs2: version 2.2. (NAND) © 2001-2006 Red Hat, Inc.
[    0.520392] Key type asymmetric registered
[    0.522123] Asymmetric key parser 'x509' registered
[    0.528317] io scheduler mq-deadline registered
[    0.531553] io scheduler kyber registered
[    2.546851] 60000000.serial: ttyS0 at MMIO 0x60000000 (irq = 1, base_baud = 2500000) is a ESP32S3 UART
[    2.550374] printk: console [ttyS0] enabled
[    2.550374] printk: console [ttyS0] enabled
[    2.554144] printk: bootconsole [esp32s3uart0] disabled
[    2.554144] printk: bootconsole [esp32s3uart0] disabled
[    2.590659] random: crng init done
[    2.629608] physmap-flash 42000000.flash: physmap platform flash device: [mem 0x42000000-0x42ffffff]
[    2.641292] 6 esp32 partitions found on MTD device 42000000.flash
[    2.642209] Creating 6 MTD partitions on "42000000.flash":
[    2.642660] 0x00000000a000-0x00000000f000 : "nvs"
[    2.647174] mtd: partition "nvs" doesn't start on an erase/write block boundary -- force read-only
[    2.693280] 0x00000000f000-0x000000010000 : "phy_init"
[    2.694124] mtd: partition "phy_init" doesn't start on an erase/write block boundary -- force read-only
[    2.732090] 0x000000010000-0x0000000b0000 : "factory"
[    2.766305] 0x0000000b0000-0x000000120000 : "etc"
[    2.801095] 0x000000120000-0x000000480000 : "linux"
[    2.834277] 0x000000480000-0x000000800000 : "rootfs"
[    2.882388] ESP chipset detected [esp32-s3]
[    2.931293] NET: Registered PF_INET6 protocol family
[    3.022795] Segment Routing with IPv6
[    3.024454] In-situ OAM (IOAM) with IPv6
[    3.031104] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver
[    3.057075] NET: Registered PF_PACKET protocol family
[    3.058493] Key type dns_resolver registered
[    3.270662] Loading compiled-in X.509 certificates
[    3.366752] cfg80211: Loading compiled-in X.509 certificates for regulatory database
[    3.405487] Loaded X.509 cert 'sforshee: 00b28ddf47aef9cea7'
[    3.410518] clk: Disabling unused clocks
[    3.422854] platform regulatory.0: Direct firmware load for regulatory.db failed with error -2
[    3.423965] cfg80211: failed to load regulatory.db
[    3.427494] cramfs: checking physical address 0x42480000 for linear cramfs image
[    3.435310] cramfs: linear cramfs image on mtd:rootfs appears to be 3196 KB in size
[    3.444737] VFS: Mounted root (cramfs filesystem) readonly on device 31:5.
[    3.451448] devtmpfs: mounted
[    3.453509] Freeing unused kernel image (initmem) memory: 8K
[    3.456449] This architecture does not have kernel memory protection.
[    3.464430] Run /sbin/init as init process
[    3.466950]   with arguments:
[    3.471466]     /sbin/init
[    3.472581]   with environment:
[    3.475670]     HOME=/
[    3.478015]     TERM=linux
Starting syslogd: OK
Starting klogd: OK
Running sysctl: OK
seedrng: can't create directory '/var/lib/seedrng': Read-only file system
Starting network: Successfully initialized wpa_supplicant
OK
Starting inetd: OK

Welcome to Buildroot

buildroot login:

6.2 Wi-Fi Setup

  1. Create /etc/wpa_supplicant.conf:

    ctrl_interface=/var/run/wpa_supplicant
network={
    ssid="YourSSID"
    psk="YourPassword"
    key_mgmt=WPA-PSK
}

  2. Bring up interface:

    ip link set espsta0 up
wpa_supplicant -B -i espsta0 -c /etc/wpa_supplicant.conf
udhcpc -i espsta0  # DHCP client
ping 8.8.8.8       # Verify connectivity

7. Customization & Extensibility

7.1 Adding Packages

  • Enter the container, then make menuconfig under the Buildroot directory.
  • Enable additional BusyBox applets, Python support, MQTT clients, or even a lightweight SSH daemon.

7.2 Kernel Modules

  • Configure external modules via Makefile overlays in linux/drivers/.

  • Rebuild only the modules to speed iteration:

    cd /linux
make modules
make modules_install INSTALL_MOD_PATH=/app/build/release

7.3 GUI & Edge-AI

  • While XIP kernels limit RAM use, you can mount an SD card via SPI for larger workloads.
  • Experiment with TinyML frameworks by cross-compiling TensorFlow Lite Micro.

8. Troubleshooting & Best Practices

IssueRemedy
Permission denied on /dev/ttysudo usermod -aG dialout $USER & relogin
Bad partition tableVerify scripts/partition-table.csv offsets and sizes
Page allocation failures (dmesg)Reduce init-time workload, or add swap-like filesystem via JFFS2
Wi-Fi firmware load errorEnsure network_adapter.bin matches kernel’s CONFIG version
  • Enable logging: Append loglevel=8 to kernel cmdline via parttool.py.
  • Serial break: If kernel panics, use screen’s “Ctrl-A k” to reset board.

9. Use Cases & Roadmap

  1. IoT Gateway: Run MQTT, Node-RED, or Home Assistant Light on S3-sized hardware.
  2. Edge Compiler: Compile small C apps directly on device via gcc in rootfs.
  3. Secure Controller: Leverage Linux capabilities (namespaces, cgroups) for containerized tasks.
  4. Tiny GUI: Add an SPI-connected LCD and run a minimal X server or framebuffer app.

Future Directions

  • Upstream integration of S3 support in Buildroot and mainline Linux.
  • Automated CI pipelines for nightly Docker image builds.
  • SD-card based expandable storage and U-Boot bootloader support.
  • Prebuilt Docker images on Docker Hub with tags per kernel version.

Conclusion

The esp32s3-linux repository encapsulates a robust, Docker-powered toolchain and build system that brings Linux 6.5+ to the ESP32-S3 platform. By modularizing kernel, rootfs, and firmware builds—and automating flashing—this project lowers the barrier for embedded Linux enthusiasts. Whether you’re experimenting with edge AI, lightweight servers, or simply pushing the limits of microcontrollers, Ray Bello’s fork provides a solid foundation to build upon.

Feel free to clone the repo, customize the kernel, add new user-space packages, and share your findings with the community!

More Articles

Ultra Violet Lithography Process - Optics

A low-cost microscope projection photolithography system for high-resolution fabrication

April 18, 2025