grieferpig/esp32-s31-linux

esp32-s31-linux is an experimental project that ports a full Linux kernel, version 6.12, onto the ESP32-S31 microcontroller, a chip normally used for small embedded tasks rather than running a general purpose operating system. The ESP32-S31 has a memory management unit, which is what makes running real Linux possible at all, and this project documents the ongoing, hands on process of getting it to boot and work. The README lays out a detailed status table of what runs and what does not. Busybox init is untested, wireless networking is not implemented, and dual core symmetric multiprocessing is uncertain. Peripheral drivers such as AXI GDMA, the cache driver, and the interrupt controller are also marked untested, while others like flash memory management, timers, and security accelerators are not implemented yet. Connectivity features including UART, USB, GPIO, I2C, I2S, SPI, and networking hardware are mostly listed as not implemented. Because this chip predates its own official technical reference manual, the author had to guess at how several hardware pieces work by comparing it to a related chip and by probing registers directly. Notable workarounds include a custom interrupt driver to bridge Linux's expectations with the chip's actual interrupt hardware, undocumented supervisor mode behavior that was reverse engineered through trial and error, and a modified version of OpenSBI, the firmware that starts Linux, so it can run directly from flash memory and save the chip's limited 16 megabytes of RAM. The repository includes example boot logs, build and flash instructions in a docs folder, and sample command outputs showing the running system, including CPU benchmark results, memory info, and process listings, confirming the kernel actually boots and runs basic commands. This is a niche, technical hobbyist project aimed at people already comfortable with embedded systems, kernel internals, or RISC-V hardware. It is not a ready to use product, and much of the hardware support is incomplete or unverified. No license is stated in the material shown.