Blog Details

Traditionally, developing a GPU driver requires a massive engineering effort spanning years. However, Cody Ho and his partner Niklas have fundamentally changed this perception by successfully building a fully OpenGL ES 3.0 compliant GPU driver for the M4 Mac Mini and MacBook Neo in approximately one month. This achievement enabled seamless WebGL performance in Chrome and Firefox browsers and allowed graphically intensive games like Minecraft to run smoothly at 200 fps. This process required reverse engineering the incredibly complex firmware ABI and user-space components of the GPU, which Apple names AGX. All of this work was conducted transparently, using well-established techniques in a verifiably clean room manner, ensuring that the implementation was derived from first principles rather than copied code.

The core motivation behind the project was to transform a previously built hypervisor, originally designed to reverse engineer macOS, into a practical product. In modern systems, the GPU is indispensable for processing tasks that would be orders of magnitude slower and less power-efficient if handled by the CPU alone. The goal was to create conformant OpenGL and, soon, Vulkan drivers for the M4 Mac Mini and MacBook Neo. While completing the task in days was an overly optimistic estimate, finishing it in weeks represents a revolutionary speed improvement over industry standards. During this period, the user spaces of M4, A18 Pro, and largely M5 were reverse engineered using only live probing techniques. This approach allowed the team to discover hardware-supported features and instructions that Apple's own driver did not emit, revealing hidden capabilities of the silicon.

The developed driver includes a fully functional user-space driver, a custom IR/shader compiler, a command stream builder, and numerous other components. One of the most challenging parts was reverse engineering the full AGX firmware ABI from scratch, utilizing traces captured from the previously built hypervisor, and implementing a complete Linux kernel driver for this ABI. Throughout this process, no Apple binaries were examined; only hardware traces and shaders created by the team were used. In user-space graphics reverse engineering, any required Apple blobs were treated as opaque objects. Documentation written by a friend regarding these blobs allowed the team to build their own clean room implementation, which was largely constructed through blind experimentation and trial-and-error methods. All experiments have been published so that anyone can verify the provenance of the work, ensuring transparency and reproducibility in the engineering process.

This blog post and the technical process are divided into two main sections, reflecting the fundamental architectural split in all modern GPU drivers: user space and kernel space. The kernel is responsible for interfacing with the firmware, allocating buffers, and managing scheduling, while the actual contents of those buffers and the nature of the scheduled tasks remain opaque to the kernel. User space is the layer that actually understands how the GPU works and fills those buffers with the correct data. In Apple Silicon architecture, the kernel driver does not interface directly with the hardware; instead, it communicates with the GPU firmware running on a custom real-time operating system called RTKit. This implies that the first step in developing a kernel driver is not talking to the hardware, but rather figuring out the firmware ABI, a critical distinction in system programming.

The firmware ABI was by far the most annoying and complex part of the project. Instead of designing a reasonable interface with clean abstractions, Apple essentially took a regular kernel driver, cut it in half, placed half of it inside the AGX as firmware, and designed the other half to communicate using shared structs in memory. Many of these structs have a complex structure where firmware-owned fields, which must never be modified and must be learned through reverse engineering, are interleaved with host-controlled fields. The complexity of the shared memory tree on M1 and M2 models illustrates just how detailed and difficult this ABI is. This level of architectural depth serves as an inspiring case study for the engineering community, highlighting the intricate layers of system programming and software architecture involved in low-level driver development.

This work demonstrates how deep and multi-layered the process of hardware-level driver development truly is. It is not merely about wrapping an API, but about completely understanding and rebuilding the firmware logic, memory management, and command flow at the lowest levels of the hardware. The clean room approach proves that a new software layer can be created by observing pure hardware behavior, without relying on existing closed-source code, while staying within legal and ethical boundaries. This method serves as a critical reference point for developers working in closed ecosystems like Apple's, showing that it is possible to discover the true capabilities of the hardware and port them to open-source platforms.

In conclusion, this project is a concrete example of how a task that would normally take years can be solved efficiently in as little as one month. It proves that hypervisor-based tracing techniques are far more powerful and yield more accurate results compared to traditional reverse engineering methods. Although the developed driver is not yet ready for end users, the process has been documented transparently, and the codebases have been shared. This demonstrates that community-based development and open-source contributions can make components reusable and understandable, even in the most closed hardware ecosystems. This success on the M4 Mac Mini is a hopeful signal for how much GPU support for Linux and open-source operating systems can expand in the future.