Zhaoxu OS is a small x86_64 operating system built around the Yuanshuo microkernel. Drivers run in Ring 3. The desktop, called Aqua Desktop Environment, also runs in Ring 3. There is no Linux ABI, no glibc, and no fork/exec. User programs are freestanding ZXE v1 executables loaded at a random base with W^X page permissions.
For a while the Wayland support was custom. A hand-written client opened /run/wayland-0, marshalled messages byte by byte, and passed a memfd with SCM_RIGHTS. That proved the transport, but it was not Wayland compatibility. The goal we set next was stricter: compile the upstream libwayland client core and run it against our server. No rewritten protocol layer. No "Wayland-like" API.
This is the story of what that took, including the bugs that only appear when your libc is a few hundred lines and your kernel headers are on the same include path as the real ones.
The stack
The moving parts:
- libwayland 1.23.1:
wayland-client.c,wayland-util.c, andconnection.c. - Generated core and xdg-shell client bindings from
wayland-scanner. - libffi 3.4.6, x86_64 SysV
ffi_callpath only. - A small POSIX compatibility layer for allocation, strings, errno, pthread stubs, sockets, poll, and time.
- Kernel AF_UNIX sockets, a per-process descriptor table,
SCM_RIGHTS,eventfd,timerfd, andepoll.
The client binary is statically linked and still has zero dynamic imports. libwayland's public API stays intact, but the implementation underneath is ours.
Kernel side: the event loop ABI
libwayland's event loop expects epoll, eventfd, and timerfd to exist. We added them as syscalls 61 through 67:
-
eventfd,timerfd_create,timerfd_settime,timerfd_gettime -
epoll_create1,epoll_ctl,epoll_wait
Descriptors live in a per-process table above 64 (ZFD_BASE). The legacy VFS keeps its low numbers. An epoll object holds up to 32 registrations, is level-triggered, and waits in 1 ms scheduler slices. That is not going to win a benchmark against Linux, but it is enough for a single-threaded client and it is honest about its limits.
A detail that matters for compatibility: libwayland often passes names such as O_NONBLOCK and MSG_DONTWAIT straight through. The kernel has to agree with those values. It also has to agree about when they apply, which brings us to the first real bug.
The socket drain that blocked forever
The stock client connected, sent 24 bytes, received 136 bytes of registry globals, and then stopped. No error. No crash. The serial log simply ended after the receive.
The client was stuck in wl_connection_read. That function drains the display socket in a loop:
len = wl_os_recvmsg_cloexec(connection->fd, &msg, MSG_DONTWAIT);
MSG_DONTWAIT is per call. The descriptor itself is blocking. Our kernel ignored the flags argument on recvmsg, so the first call read the available data and the second call slept forever waiting for more.
The fix is small, but it is the kind of small that takes a while to find:
int nonblock = (entry->flags & ZFD_O_NONBLOCK) != 0 ||
(flags & ZMSG_DONTWAIT) != 0;
sendmsg needed the same treatment. After that the client received the registry, bound wl_compositor and wl_shm, submitted a 320x240 frame through SCM_RIGHTS, and exited 0.
The include path that ate libc
The second bug was entirely a build problem. Our stock sources were compiled with the kernel include directory on the command line, because the demo needed userlib.h and the ZXE entry point. That directory contains a kernel header named poll.h.
The compiler saw:
#include <poll.h>
and resolved it to the kernel's definition, which declares ZPOLLIN, ZPOLLOUT, and struct zpollfd. libwayland then failed with errors like "array type has incomplete element type struct pollfd" and "POLLOUT undeclared".
The fix was to stop mixing the two worlds. The upstream libwayland objects, libffi, and the compatibility layer compile with only the third-party and user include paths. Only the demo and userlib.c see kernel/include. It sounds obvious once you have the error message. It is much less obvious when a single compiler invocation is building five different layers of the system.
Porting libffi without a libc
libwayland does not call listeners directly. It builds a ffi_cif and calls ffi_call, because the event signature is only known at runtime.
Porting all of libffi would have been unnecessary. The client only needs the SysV call path:
ffi_prep_cif-
ffi_type_*descriptors -
ffi_calland theffi_call_unix64assembly entry
Closure support, Windows EFI entry points, and the trampoline code are not used. We compile the objects with -fvisibility=hidden, place every function in its own section, and link with --gc-sections. That lets the linker drop the unused Windows and closure code instead of dragging in undefined symbols.
There is one more piece: ffi_call uses the platform's calling convention, so the generated code must match the ABI. On x86_64 SysV that means the first six integer arguments in registers, with rdi/rsi for the listener's data and target. We verified the path with a tiny self-test in the same binary:
ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 2, &ffi_type_sint32, types);
ffi_call(&cif, FFI_FN(ffi_add), &result, values);
The client prints ffi 42 before it even connects. If that line is wrong, the rest of the event dispatch is not worth debugging.
Generating the protocol bindings
The release tarball does not ship generated protocol files, and we did not want a checked-in blob whose provenance was unclear. We built wayland-scanner from the same source with libxml2 and expat, then generated:
-
wayland-client-protocol.handwayland-protocol.c -
xdg-shell-client-protocol.handxdg-shell-protocol.c
The generated files are vendored, so a normal build does not need the scanner. The XML files stay next to them under protocol/.
FreeType and the header that was included twice
The desktop also needed a real font engine. We vendored FreeType 2.13.3, configured for memory faces only: no zlib, PNG, bzip2, HarfBuzz, Brotli, environment properties, or file-stream support. The image carries the TrueType, CFF, sfnt, psnames, psaux, and smooth rasterizer modules. Only MiSans, MiSans Global, and Inter are accepted as fonts.
The first attempt returned error 11 from FT_New_Memory_Face. Error 11 is FT_Err_Missing_Module, which is not what you expect for a perfectly valid TTF.
The cause was a custom ftmodule.h. I had given it an include guard, like any sane header. But ftinit.c includes that file twice on purpose: once to declare the module symbols and once to expand the module array. The guard made the second include expand to nothing, so the array was empty. FreeType initialized successfully and then had no driver for any font.
Removing the guard fixed it. The file now says so in a comment, because it is the sort of thing that will otherwise be reintroduced by the next person who sees a header without a guard.
A second issue was optimization. With this freestanding configuration, the smooth rasterizer crashed inside FT_Render_Glyph at -O1 and -O2, while the same code at -O0 rendered correctly. The rest of FreeType is happy with -O2, so only smooth.c is compiled at -O0. I would rather have a working, slightly slower rasterizer than a fast one that faults on a CJK glyph.
Text that bobbed and flipped
The first FreeType-backed desktop build had a more visible problem: glyphs were vertically offset, and some looked flipped. The baseline was not stable across characters.
The adapter was passing slot->bitmap_top directly as the offset from the top of the line. bitmap_top is measured upward from the baseline. render.c expects a downward offset from the line top. Positive values therefore pushed glyphs below the line, and the amount changed with each glyph's height. That is the bobbing.
The correct conversion is:
i32 ascent = (i32)((g_face->size->metrics.ascender + 32) >> 6);
out->by = (i8)(ascent - (int)slot->bitmap_top);
Advances were also being truncated in one path and rounded in another. They are now rounded consistently, so spacing stops drifting.
The fix is three lines. The screenshot that confirmed it was worth the build time: the welcome window, calculator, menu bar, and Dock all render upright text sitting on the baseline.
The cursor that disappeared when you stopped moving
The compositor draws the pointer into a system-RAM back buffer, presents only damaged rectangles, and restores the pixels under the previous cursor before each repaint. That design is fine until a damage repaint arrives with no new mouse packet.
The loop was doing this:
int ready = mouse_ready();
if (ready)
dwc_cursor_draw(mx, my);
...
if (ready)
dwc_present_cursor(mx, my);
else
dwc_hide_cursor();
A stationary mouse can still have valid coordinates, but there may be no fresh report. On a repaint triggered by the clock or an animation, ready could be false and the cursor was hidden. If nothing moved afterwards, it stayed hidden.
The fix is to remember that a pointer has been seen at all:
if (mouse_ready())
g_pointer_seen = 1;
int ready = g_pointer_seen;
Now the pointer is composited at its last known position even when the latest sample contains no new data. Six framebuffer captures taken 450 ms apart differ only in the menu-bar clock area; the cursor rectangle is byte-identical.
What runs today
The regression client prints:
[wlstock] ffi 42
[wlstock] connected
[wlstock] registry requested
[wlstock] globals bound
[wlstock] frame committed
[wlstock] WLSTOCK exit 0
On the server side:
[wayland] commit 320x240 stride=1280 first=0x0x00000000ff3366cc
That is upstream libwayland's client core, upstream libffi, and generated xdg-shell bindings running on a kernel with no Linux ABI. FreeType runs the desktop font path, and the text and cursor are stable in real framebuffer captures.
There are still open items. dma-buf and GPU composition are blocked on the test host: the Windows QEMU virtio-gpu-gl device offers the virgl feature but its virglrenderer does not register guest resources, so SET_SCANOUT returns 0x1203. Vulkan and OpenGL are not implemented yet. Unmodified stock applications such as weston-terminal still need more of the POSIX surface, including shm_open.
Things I would tell the next person
- "Stock compatibility" is mostly an ABI scavenger hunt. The interesting bugs are in flag semantics, header resolution, and error paths, not in the protocol itself.
- Kernel headers and libc headers must not share an include path. A file named
poll.his enough to cost you an afternoon. - If a third-party header is included twice by design, do not add an include guard. Read the including file first.
- Vendored C code compiles differently under freestanding flags. Test the real glyph, not just the return code.
- A frame counter and a diff against the previous framebuffer are more useful than a screenshot. Six images told us more about the cursor than a day of reading the compositor.
Zhaoxu OS is a Nexsteaduser project. Contact: admin@nexsteaduser.com
Copyright © 2026 Nexsteaduser. All Rights Reserved.
Top comments (0)