How external-mirrors/phoenix works
1. What this repo is
Phoenix is an X server written in Zig. The architecture is split between an X11 protocol engine and a host-platform backend layer. The current operational target is nested execution inside an existing X server, with the backend abstraction already prepared for other display/input/graphics implementations later.
2. Process entry and top-level orchestration
src/main.zig and src/phoenix.zig are the likely bootstrap points that assemble the server, choose backends, initialize protocol state, and enter the main event loop. This is the process boundary where client connections, backend events, and rendering work are coordinated.
3. Backend boundary: display, input, graphics
src/backend/display, src/backend/input, and src/backend/graphics form the host integration layer. The abstract interfaces in Display.zig, Input.zig, and Graphics.zig separate Phoenix’s internal X11 state from platform-specific implementations such as DisplayX11.zig, InputLinux.zig, and GraphicsEgl.zig. This is the main portability seam in the design.
4. Current host integration mode
The repo is explicitly built for nested operation first. DisplayX11.zig suggests the server can create and manage its visible surface through an existing X server, while GraphicsEgl.zig provides hardware-accelerated rendering. The README also indicates future backends may target DRM/GBM or Wayland, but those are not the current primary path.
5. Client transport and server I/O
src/net contains the client/server communication plumbing: Server.zig, Client.zig, message.zig, fifo.zig, and utils.zig. This layer is responsible for accepting connections, buffering request/reply/event traffic, and framing protocol messages before they reach the protocol dispatcher.
6. X11 protocol parsing and dispatch
src/protocol is the core protocol engine. It is organized into request.zig, reply.zig, event.zig, error.zig, and opcode.zig, with handlers under src/protocol/handlers. The handler split shows a clear boundary between connection setup, per-request context, core protocol handling, and extension-specific logic.
7. Extension-centric protocol architecture
The extension handlers are first-class modules: Dri3, Glx, Present, Randr, Render, MitShm, Sync, Xfixes, Xkb, Xwayland, and GenericEvent. This indicates Phoenix is organized around the modern X11 feature set needed by real applications, rather than trying to implement the entire historical protocol surface.
8. Server object model
src/resource contains the server-owned X11 objects: Window, Pixmap, Drawable, Cursor, Colormap, Counter, Fence, ShmSegment, EventContext, GlxContext, GlxDrawable, and the common base in resource.zig. These are the authoritative objects that protocol requests operate on, and they are the main units of state passed between protocol handlers and the backend.
9. Global managers and ownership rules
src/manager centralizes cross-cutting server state: ClientManager, AtomManager, ResourceIdBaseManager, and SelectionOwnerManager. These modules likely enforce per-client resource ownership, ID allocation, atom interning, and selection ownership, which are key boundaries for connection isolation and security policy.
10. Display model and monitor-facing state
src/display contains monitor and screen-related structures such as Crtc.zig and ScreenResources.zig. Together with src/internal_resource/Visual.zig and Atom.zig, this is where backend-derived output information becomes X11-visible state such as visuals, monitor resources, and per-screen metadata.
11. Input and keyboard flow
src/backend/input/InputLinux.zig is the host input source, while src/keyboard/keysym.zig and src/misc/InputFocus.zig represent how host key events are translated into X11 key symbols and routed to the focused client. The Xkb protocol extension ties this into keyboard layout and keymap handling.
12. Support utilities and shared types
src/misc provides the shared building blocks used across the server: geometry, fixed-point math, time, versioning, refcounting, and pattern helpers. These are the low-level types that keep protocol, resource, and backend code aligned on common representations.
13. Where rendering meets protocol
Rendering-related extensions and resources form a second major data path: clients submit drawable/GL/SHM-related operations through protocol handlers, those operations map onto Pixmap, Drawable, GlxContext, GlxDrawable, Fence, and Present state, and the backend graphics layer presents the results to the host display. This is the path that enables the current “simple applications with hardware acceleration” goal.
14. External dependencies that matter to the architecture
The design is explicitly tied to Zig and to modern graphics/input stacks: X11 client compatibility, EGL/OpenGL for acceleration, and libxkbcommon for keyboard handling. The backend abstraction exists so the server can later target DRM/GBM or other host display systems without rewriting the protocol or resource layers.
Main entry points: phoenix.zig Phoenix · handlers Handlers · resource.zig Resources · misc Shared Utils
Components 20
Runtime
Process entry and top-level orchestration.
- Main · Bootstraps the server process and enters the event loop.
src/main.zig - Phoenix · Assembles subsystems and coordinates server execution.
src/phoenix.zig - Server · Owns client acceptance and request/reply transport.
src/net/Server.zig - Client · Represents a connected X11 client and its I/O state.
src/net/Client.zig
Backend
Host display, input, and graphics integration.
- Display API · Abstract display boundary for host integration.
src/backend/display/Display.zig - X11 Display · Display backend for running inside an existing X server.
src/backend/display/DisplayX11.zig - Input API · Abstract input boundary for host event sources.
src/backend/input/Input.zig - Linux Input · Host keyboard and pointer input implementation.
src/backend/input/InputLinux.zig - Graphics API · Abstract rendering boundary for host graphics.
src/backend/graphics/Graphics.zig - EGL Graphics · EGL-based rendering backend for host presentation.
src/backend/graphics/GraphicsEgl.zig
Protocol
X11 parsing, dispatch, and extensions.
- Request · Parses incoming X11 requests into typed operations.
src/protocol/request.zig - Reply · Builds X11 replies sent back to clients.
src/protocol/reply.zig - Event · Encodes server events for client delivery.
src/protocol/event.zig - Handlers · Routes setup, core, and extension requests to implementations.
src/protocol/handlers - Extensions · Feature modules for modern X11 and Xwayland support.
src/protocol/handlers/extension
State
Server-owned objects and global managers.
- Resources · Authoritative server-side X11 resource model.
src/resource/resource.zig - Managers · Cross-cutting ownership, atoms, and resource ID policy.
src/manager - Display State · Monitor, screen, and visual information exposed to X11.
src/display/ScreenResources.zig - Internal Types · Shared visual and atom definitions used across the server.
src/internal_resource
Support
Shared utilities and low-level types.
- Shared Utils · Geometry, time, versioning, fixed-point, and refcount helpers.
src/misc
Connections 22
- Main → Phoenix: start · Process bootstrap hands off to the server orchestrator.
- Phoenix → Server: serve · Orchestrator creates the client transport layer.
- Phoenix → Display API: select · Chooses the display backend abstraction.
- Phoenix → Input API: select · Chooses the input backend abstraction.
- Phoenix → Graphics API: select · Chooses the graphics backend abstraction.
- Display API → X11 Display: impl · Nested X11 display implementation.
- Input API → Linux Input: impl · Linux host input implementation.
- Graphics API → EGL Graphics: impl · EGL rendering implementation.
- Server → Client: accept · Server creates and manages client connections.
- Server → Request: parse · Incoming client traffic is decoded as requests.
- Request → Handlers: dispatch · Parsed requests are routed to protocol handlers.
- Handlers → Reply: respond · Handlers build replies for clients.
- Handlers → Event: emit · Handlers emit events to connected clients.
- Handlers → Extensions: route · Extension-specific operations are handled separately.
- Extensions → Resources: mutate · Extensions operate on server-owned X11 objects.
- Managers → Resources: own · Managers enforce identity, ownership, and allocation rules.
- Display State → Resources: expose · Screen and visual state is derived from resources and backend output.
- Internal Types → Display State: feed · Internal atoms and visuals support display-visible state.
- Shared Utils → Request: support · Shared low-level types support protocol decoding.
- Shared Utils → Resources: support · Common utilities support server object implementations.
- Shared Utils → EGL Graphics: support · Shared math and time types support backend rendering.
- Linux Input → Internal Types: keysym · Host input is translated into X11 keyboard symbols.