EwokOS

EwokOS is a lightweight microkernel operating system aimed at OS learning, system bring-up, and practical experimentation across QEMU and real embedded boards. The project combines a small kernel with a large user-space stack: core services, storage, graphics, an X-like desktop, networking, and board-specific drivers.

Misa.Z misa.zhu@gmail.com

This repository is the main EwokOS source tree. It contains:

• The microkernel core and architecture layers
• Base userland, libc pieces, shell, and system daemons
• GUI, display, audio, and image libraries
• An X-like window system and desktop applications
• Networking tools and services such as SSH, SCP, Telnet, HTTP, and ping
• Machine-specific ports for QEMU, Raspberry Pi, x86, RISC-V, handhelds, and board variants
• Extra software trees provided through submodules such as projects/ and sw.extra/, plus native applications under apps/

The build is intentionally machine-centric. Instead of one monolithic top-level build, each target under machine.virt/ or machines/*/ provides its own kernel and rootfs recipes.

Recent work visible in the current branch includes:

• Runtime dynamic loading (dlopen/dlsym/dlclose) on AArch64: a user-space ELF dynamic loader (libdl) over a new kernel anonymous-mapping window with real per-page W^X permissions, a cache-sync syscall, and a build-time generated host ABI export table — boot-verified by a self-test on machine.virt (see Dynamic Library Support)
• Ext3 ported as the default root filesystem: sdfsd now serves journaled, crash-safe ext3, with automatic ext2-compatible fallback when no journal is present; the kernel boot loader reads ext2/ext3 directly
• SD card write performance improvements, including Raspberry Pi SD driver speed-ups, removal of per-write verification, and write-cache flushing tuned for ext3
• Display rotation speed-ups via arch-accelerated graph_rotate_to_arch paths (ARM, AArch64, x86) and a faster display daemon
• Larger projects (browser, macemu, minivmac, nesemu, opengl, video, saver) moved into the new projects/ tree
• The opengl stack now exposes a standard OpenGL ES 2.0 / EGL API (libGLESv2/libEGL) over portablegl, with real GPU acceleration on Raspberry Pi 5 that stays engaged across window resizes
• macemu HiDPI mode support
• Simplified, rewritten Makefiles across the system/ build trees

These items come directly from the latest commits in the current checkout and reflect active development rather than historical roadmap text.

EwokOS follows a microkernel-oriented design:

• The kernel handles low-level memory management, scheduling, interrupts, IPC, semaphores, signals, and process state
• User-space services implement most system behavior, including boot orchestration, service discovery, filesystems, display management, and networking
• Graphics is built on framebuffer/display services plus an X-like window system
• Networking is implemented through user-space drivers and daemons
• Machine ports provide the BSP, boot glue, storage drivers, interrupt/timer setup, and deployment flow for each target

At a high level:

1. The kernel boots and initializes MMU, IRQ, DMA/shared memory, scheduler state, and platform services.
2. The kernel launches /sbin/init.
3. init starts core user-space services such as core, vfsd, and storage helpers.
4. Machine-specific init scripts bring up console, GUI, network, and X sessions.
5. When X is enabled, the default desktop session launches window manager and desktop tools.

• Microkernel core with scheduling, VM/MMU support, IPC, signals, semaphores, and SMP-aware code paths
• User-space services including init, core, vfsd, sdfsd, displaymand, xserverd, netd, sshd, telnetd, and httpd
• Native GUI and desktop stack with framebuffer rendering, themed window managers, and graphical apps
• Networking tools including ssh, scp, ping, host, HTTPS test tooling, and WebSocket test tooling
• Multiple machine ports for QEMU, Raspberry Pi families, x86, RISC-V, handheld devices, and special-purpose boards
• Ext3 root filesystem image generation in-tree as the default (journaled, with ext2-compatible fallback); FAT32 support is also part of the broader stack
• Runtime dynamic loading (dlopen) of ET_DYN plugin .so objects on AArch64, with kernel-enforced W^X and a POSIX <dlfcn.h> API

ewokos/
├── README.md
├── LICENSE
├── kernel/
│   ├── dev/                  # Common kernel device headers
│   ├── kernel/               # Kernel core: proc, IPC, VM, scheduler, syscalls
│   ├── lib/                  # Kernel-side helper libraries and ext2/ext3 readers
│   ├── loadinit/             # Early userspace loading helpers
│   └── platform/             # ARM, AArch64, RISC-V, x86 architecture code
├── system/
│   ├── basic/                # Base userland, shell, core services, libc pieces
│   ├── gui/                  # Display, graphics, fonts, audio/image helpers
│   ├── network/              # Network tools, daemons, and related libraries
│   ├── platform/             # Userland platform build rules
│   └── xwin/                 # X-like window system, libs, apps, and WMs
├── machine.virt/
│   ├── kernel/               # Recommended QEMU virt kernel target
│   └── system/               # Recommended QEMU virt rootfs target
├── machines/
│   ├── docs/                 # SD card notes, screenshots, target-specific docs
│   ├── clockwork/            # Clockwork Pi PicoCalc target
│   ├── lego.ev3/             # LEGO Mindstorms EV3 port
│   ├── miyoo/                # Miyoo handheld port
│   ├── orangepi/             # Orange Pi port
│   ├── raspi5/               # Raspberry Pi 5 port and add-ons
│   ├── raspix/               # Raspberry Pi family ports and many overlays
│   ├── versatilepb/          # ARM versatilepb QEMU target
│   ├── virt.riscv/           # QEMU RISC-V virt target
│   ├── x2lite.rk3128/        # RK3128 target
│   └── x86/                  # x86 PC-style target
├── projects/                 # Larger standalone projects: browser, macemu,
│                             # minivmac, nesemu, opengl, video, saver
├── sw.extra/                 # Extra apps, SDL-based software, alternate WMs
└── apps/                     # Standalone native applications (nputest)

• kernel/kernel/src/: scheduler, process model, IPC, MMU, IRQ, semaphore, signal, syscall dispatch
• kernel/platform/: architecture-specific boot, interrupt, and MMU code
• system/basic/sys/: init, core, vfsd, and rootfs/filesystem daemons
• system/basic/bin/: shell and command-line tools
• system/gui/: display stack, graphics libraries, font and image support
• system/xwin/: X client libraries, input helpers, window managers, and desktop apps
• system/network/: network commands, libraries, and daemons
• machines/*/kernel/: board support packages and per-target boot logic
• machines/*/system/: per-target rootfs packaging, drivers, config, and init scripts
• machines/*/3rd/: board overlays and third-party device integrations

Support below is based on the checked-in source tree and build recipes in this checkout. Hardware validation depth can vary by board.

The tree already includes a large amount of board-specific and peripheral work.

• Ext3 root filesystem image generation is the default build flow, with journaling for crash safety; cards without a journal are served in ext2-compatible mode
• The kernel boot loader can read ext2/ext3 directly to load init
• FAT32 support has also been ported into the stack
• SD and MMC support exist across many machine BSPs, with recent write-path speed-ups (faster Raspberry Pi SD transfers, removed per-write verification)
• Raspberry Pi 5 includes nvmefsd in its system drivers

• Framebuffer-based display stack
• X-like desktop window system
• Multi-display work is actively landing
• USB keyboard and mouse support on QEMU and x86-style targets
• Bluetooth keyboard, mouse, and gamepad support on Raspberry Pi targets through the unified btd daemon: both classic BR/EDR HID and BLE HOGP links, with pairing/bonding persistence (/etc/bt/bt.json), several simultaneous classic and LE sessions, and per-link release synthesis so a dropped device never leaves a stuck key. Reports are re-published by hid_keybd, hid_moused, and hid_joystickd and feed the standard X input stack (xim_none/xmouse), so Bluetooth devices drop into the same chain as USB ones
• Touch controller integrations under Raspberry Pi add-on trees such as gt911 and xpt2046
• Many LCD HAT and Waveshare-style overlay trees for Raspberry Pi boards

• User-space networking stack and daemons
• ssh, scp, ping, host, telnet, https_test, and ws_test
• sshd, telnetd, httpd, and machine-specific network drivers
• Raspberry Pi WLAN work with Broadcom-related sources under machines/raspix/ and machines/raspi5/

• Framebuffer rendering, 2D helpers, fonts, PNG/JPEG/GIF/SVG/TGA support
• Arch-accelerated graphics paths, including scaling and rotation (graph_rotate_to_arch) for ARM, AArch64, and x86
• X client libraries in both C and C++ forms
• Desktop apps such as xterm, xread, ximg, xlog, xapps, clock, cards, and mine
• Alternate window managers and demos in sw.extra/
• A software OpenGL ES 2.0 / EGL stack (opengl) with an on-device GLSL compiler and, on Raspberry Pi 5, real GPU offload — see 3D Graphics and OpenGL

The projects/opengl tree provides a real OpenGL ES 2.0 / EGL stack that runs on EwokOS without a hosted GPU driver. Apps write standard GLES2/EGL code — <GLES2/gl2.h> + <EGL/egl.h>, glCreateShader/glDrawArrays/eglSwapBuffers — and never touch the back end directly:

• gles (libs/gles) — the standard API front end, built as libGLESv2.a + libEGL.a and shipping the usual GLES2/GLES3/EGL/KHR headers. It layers a CPU GLSL ES interpreter (src/glsl) and a single engine adapter (src/engine/pgl_engine.c) over portablegl. An app links only -lEGL -lGLESv2 (plus glcommon and the system X/graph libs); portablegl and v3dcompiler are merged into libGLESv2.a as private intermediates and stay invisible.
• portablegl (libs/gles/portablegl) — a small, self-contained OpenGL ES 2.x-style rasterizer (vertex/fragment shaders, VBOs, textures, depth test) that renders into an EwokOS framebuffer. It is the engine behind the GLES API.
• glcommon (libs/glcommon) — math and GL helper utilities shared by the apps.
• v3dcompiler (libs/gles/v3dcompiler) — a vendored copy of the mesa Broadcom V3D compiler back end (upstream mesa pin f45825a0, see libs/gles/v3dcompiler/VENDORED.txt). It compiles GLSL ES 3.10 shaders through mesa's GLSL → NIR → VIR → QPU pipeline into V3D 7.1 QPU code on the device, built as libv3dcompiler.a.

On most targets the GLES calls rasterize entirely on the CPU (portablegl with NEON acceleration where available, driven by the interpreter in gles/src/glsl). On Raspberry Pi 5 the same app binary additionally offloads geometry to the VideoCore VII (V3D 7.1 / BCM2712) GPU: the engine adapter picks CPU vs GPU per draw, so no app-side change is needed. Because the V3D 7.1 binner cannot rasterize real primitives on BCM2712, opengl transforms, lights, and rasterizes geometry in CSD compute shaders compiled by the vendored mesa compiler, dispatched through the g2dd daemon (pgl_g3d → g2dclient → g2dd → bsp_g3d → vc_pgl3d). This GPU path is gated by PGL_G3D=yes, exported only from machines/raspi5/system/make.inc; its two-pass compute rasterizer (a per-vertex transform pass plus a one-lane-per-triangle raster pass) makes it faster than the CPU rasterizer for scenes such as the teapot demo. The GPU also stays engaged across window resizes — the offload framebuffer is allocated with grow-only geometric headroom, so a drag-to-resize collapses into a handful of reallocations instead of one per event and never exhausts the kernel's contiguous shared-memory pool (which would otherwise silently latch the app back to CPU).

The opengl apps (teapot, gears, 3ddemo, matrix, Fireworks, imgui_demo) and the shadertoy-style fullscreen-compute demos exercise both paths through the same GLES2/EGL front end. The compiler is validated on the host by the dump_uniforms oracle (libs/gles/v3dcompiler, make -f Makefile.host), which compiles every shader and checks the QPU output before it is ever run on the device.

• projects/ holds the larger standalone projects: a web browser, macemu and minivmac Macintosh emulators, nesemu, the opengl software 3D stack, video, and saver
• sw.extra/ contains demos and larger apps such as doom, calculator, calendar, and SDL-related pieces
• apps/nputest/ provides the Q8B native HTP test window and npudemo CLI, with bundled model resources
• Some installations depend on submodules being checked out locally

The kernel source under kernel/ includes:

• Process scheduler and ready queues
• IPC, kernel event queues, and semaphore handling
• Signal delivery and syscall dispatch
• MMU, DMA, shared memory, and kernel allocators
• SMP-related support
• Architecture-specific boot and interrupt handling

The base system under system/basic/ includes:

• Shell, login flow, and standard command-line tools
• Core services such as init, core, and vfsd
• Filesystem helpers and rootfs daemons
• Basic libc and utility libraries (see C Library, Standards, and Bundled Libraries)

The graphics stack is split between system/gui/ and system/xwin/:

• Display, font, graph, and audio/image support libraries
• X client libraries and input helpers
• Desktop apps and window managers
• Machine-specific display configs and init scripts

The network tree under system/network/ provides:

• Interactive tools such as ssh, scp, ping, and host
• Network daemons such as sshd
• Additional services and drivers wired in through machine-specific system trees

EwokOS ships its own C library, libewoksys, instead of relying on a hosted libc. It provides ISO C standard headers plus a POSIX-like API subset, layered over the cross-toolchain runtime (newlib + libgloss), with openlibm for math and softfloat for software floating point on ARM32.

The default link group is declared per architecture in system/platform/<arch>/make.rule:

# AArch64 / x86
EWOK_LIBC = --start-group -lewoksys -lc -lgloss --end-group
# ARM32 additionally links the software FP runtime
EWOK_LIBC = --start-group -lewoksys -lc -lgloss -lsoftfloat --end-group $(LIBGCC)

• system/basic/libc/libewoksys/ — the native EwokOS C library: standard headers, POSIX-like implementations, and the EwokOS system API (IPC, VFS, devices, shared memory, processes, logging)
• system/basic/libc/libgloss/ — toolchain syscall glue (_open, _close, _read, _write, _lseek, _stat, _fstat, _sbrk, _kill, _fork, _wait, _getpid, _gettimeofday, _isatty, ...)
• system/basic/libc/softfloat/ — software floating-point / aeabi runtime helpers used on ARM32 (-mfloat-abi=softfp)

ISO C (C90/C99 subset) — provided by the libewoksys headers: <stdio.h>, <stdlib.h>, <string.h>, <strings.h>, <ctype.h>, <math.h>, <assert.h>, <errno.h>, <setjmp.h>, <time.h>, <float.h>, <inttypes.h>, <stdarg.h>, <stddef.h>, <wchar.h>, <malloc.h>.

POSIX-like API — a practical subset oriented at embedded and system programming:

BSD Sockets — via the socket library (system/network/libs/socket): <sys/socket.h>, <netinet/in.h>, <arpa/inet.h>, <netinet/if_ether.h>, <netinet/ether.h>, with socket, bind, listen, accept, connect, send/recv, sendmsg/recvmsg, shutdown, socketpair, getsockname/getpeername, gethostbyname, and inet_addr/inet_ntoa/inet_pton/inet_ntop.

C++ — libcxx (C++ runtime support) plus libewokstl, a lightweight STL subset: string/wstring, vector, list, deque, queue, stack, set, map, unordered_set, unordered_map, algorithm, iterator, functional, memory, tuple, utility, iostream/sstream/fstream, and the header-only object++ (UniObject) helper.

The libc favors a compact, embedded-appropriate subset. A few hosted-libc features are intentionally absent or simplified — for example vprintf is not provided; use vfprintf(stdout, ...) instead.

Beyond libc, the tree builds a set of static libraries grouped under system/*/libs:

The graphics and window-system groups are also declared in make.rule as EWOK_LIB_GRAPH and EWOK_LIB_X, so applications can link them as a unit.

EwokOS links every program statically, so there is no ld.so and no ELF interpreter. Runtime dynamic loading is provided instead as an explicit plugin facility: dlopen() loads an ET_DYN shared object built with -fPIC -shared, relocates it against the host's exported ABI, and returns an opaque handle. It is implemented and boot-verified on AArch64 (machine.virt); the kernel anonymous-mapping window that enforces W^X exists only under #ifdef __aarch64__, and other architectures fall back to heap emulation without per-page permissions.

Three pieces cooperate:

• Kernel (kernel/kernel/src/svc.c, kernel/kernel/src/mm/mmu.c, kernel/kernel/include/mm/mmu.h)
  • SYS_CACHE_SYNC cleans the D-cache to PoU and broadcasts an I-cache invalidate, because EL0 cannot run dc civac / ic ivau itself (SCTLR_EL1.UCI is left clear). Without it, freshly-copied plugin code could never be fetched.
  • SYS_MMAP_ANON / SYS_MPROTECT / SYS_MUNMAP draw from a per-process 256 MB anonymous window (DL_WINDOW_*, 64 KB slots) with real per-page permissions, so a plugin's text is mapped read-only-and-execute and its data read-write — true W^X. The window is released on process exit, including abnormal exit, in proc_funeral.
• libdl (system/basic/libs/dl) — the user-space ELF dynamic loader: ET_DYN parsing, the mandatory DT_HASH symbol table, R_AARCH64_RELATIVE/GLOB_DAT/JUMP_SLOT relocations, DT_NEEDED dependency loading, .init_array/.fini_array ctor/dtor ordering, reference counting, dlerror, and dladdr.
• Host ABI table (system/basic/libs/dl/gen_export.sh) — because a static ET_EXEC has no .dynsym (--export-dynamic is a no-op), the host's exportable surface is generated at build time by nm-ing the EWOK_LIBC archives into a sorted, strongly-referenced table (__ewok_dl_abi[], ~730 symbols). Application-owned symbols are added at runtime with dl_host_publish().

libc routes mmap/mprotect/munmap/getpagesize to the new syscalls, falling back to the heap emulation when the window is absent.

A plugin is a normal -fPIC shared object; the host links EWOK_LIB_DL (-ldl $(EWOK_LIBC)) and installs plugins into the rootfs /lib (the loader's default search path is /lib:/usr/lib:/system/lib):

#include <dlfcn.h>

void* h = dlopen("/lib/libdemo.so", RTLD_NOW);
int (*fn)(int) = (int (*)(int))dlsym(h, "demo_entry");
if(fn) fn(42);
dlclose(h);

Two deliberate deviations from glibc/musl: RTLD_LAZY is accepted but binding is always eager, and RTLD_NEXT is refused by dlsym() (RTLD_DEFAULT works). dlerror() is per-process rather than per-thread.

The bin/dltest app is a boot-time self-test that exercises the whole stack — host ABI, absolute/soname/DT_NEEDED loading, cross-object relocation, ctor/dtor ordering, refcounting, dladdr, error paths, eight simultaneous objects with slot release/reuse, and a wxfault mode that provably takes a data abort when writing to a plugin's read-only text. On machine.virt it reports 94 checks, 0 failures.

For the full mechanism, see the wiki chapter 25 Runtime Dynamic Loading (dlopen) (中文).

At minimum you need:

• make
• A matching cross toolchain for the architecture you want to build
• QEMU for emulator targets
• e2tools and mke2fs or e2fsprogs for ext2/ext3 image creation

sudo apt-get install make qemu-system-arm qemu-system-aarch64 qemu-system-misc e2tools e2fsprogs

On macOS, install the same categories of tools with Homebrew or another package manager, plus the cross compilers required for the target architecture.

machine.virt/ is the easiest place to start because it runs entirely in QEMU and has the most complete out-of-the-box development flow.

cd machine.virt/system
make x
make sd

This stages the root filesystem under system/build/virt/rootfs/ and creates root_aarch64.img under system/build/virt/. The image is ext3 by default; pass FS=ext2 to make sd for an ext2 image instead.

cd machine.virt/kernel
make

The default machine.virt configuration is:

• ARCH=aarch64
• SMP=yes
• PAGE_SIZE=16k

Recent kernel work also adds 64k page support for AArch64-oriented ports.

cd machine.virt/kernel
make run

The current QEMU recipe includes:

• RAM framebuffer output
• VirtIO block storage
• VirtIO network
• VirtIO tablet and keyboard devices
• VirtIO sound
• 9P host sharing mounted as hostshare
• Optional host forwarding through QEMU_HOSTFWD or QEMU_NETDEV

Default users from system/basic/etc/passwd:

make basic    # base userland only
make network  # base userland + networking
make gui      # framebuffer GUI stack
make x        # full desktop stack
make sd       # generate ext3 rootfs image (FS=ext2 supported)
make clean

make          # build the kernel image
make asm      # generate kernel assembly listing
make run      # boot QEMU with GUI
make run-headless
make run-gui  # same as make run (explicit GUI form)
make run-gui-hvf  # GUI run accelerated with QEMU HVF (host CPUs)
make runasm   # boot with instruction tracing
make debug    # QEMU paused with GDB server on :26000
make debugasm
make gdb

# Build a 32-bit ARM virt rootfs and kernel
cd machine.virt/system && make ARCH=arm x && make ARCH=arm sd
cd ../kernel && make ARCH=arm && make ARCH=arm run

# Force a specific QEMU display backend
QEMU_DISPLAY_OPTS=cocoa make run

# Customize host forwarding
QEMU_HOSTFWD='hostfwd=tcp:127.0.0.1:2022-:22' make run

Most machine ports follow the same pattern:

1. Build the target root filesystem in machines/<target>/system
2. Generate the ext2/ext3 image or board-specific storage image
3. Build the kernel in machines/<target>/kernel
4. Run in QEMU or deploy to SD card, eMMC, or board storage as appropriate

For SD-card-oriented flows, see machines/docs/make_sd.md.

If you want to understand the codebase quickly, start here:

1. kernel/kernel/src/ for scheduler, process state, IPC, signals, and VM
2. kernel/platform/ for boot, interrupts, and MMU differences by architecture
3. system/basic/sys/ for init, core, and vfsd
4. system/gui/ and system/xwin/ for graphics, desktop, and X client APIs
5. system/network/ for daemons, tools, and protocol support
6. machine.virt/ for the simplest full boot path
7. machines/raspix/ and machines/raspi5/ for the most active hardware bring-up work

• DeepWiki
• machine.virt/ and machines/*/ for target-specific build files
• kernel/platform/ and system/platform/ for architecture and build rules
• machines/docs/ for SD card notes, board docs, and screenshots

This repository may rely on submodules depending on your checkout state. The current .gitmodules file references trees such as:

• sw.extra
• machines
• projects

If a directory mentioned in the documentation is missing locally, initialize submodules before building or exploring the full software set.

Contributions are welcome. Bug reports, platform notes, board bring-up findings, documentation improvements, and pull requests are all useful.

This project is licensed under the terms in LICENSE.