Turning my MacBook into a linux kiosk

Sat, 19 Apr 2025 00:00:00 +0000

The unix philosophy speaks clearly - do a thing and do it well. What if there was a need to show a browser window, the time, weather, or even, given the current situation, stock prices. An embedded device with an external display would be a no-brainer choice for such project.

However, could a modern MacBook running Linux be utilized instead?

Asahi Linux is a project that ports the Linux kernel to Apple Silicon MacBooks via reverse-engineering the vastly undocumented hardware. The whole project has made invaluable contributions to freedom. The combined effort on all fronts allowed for a very stable Linux desktop experience on the newest hardware.

The Linux Graphics stack

There are topics to be explored before jumping into a project such as this one. The graphics stack being one of them - after all, that is what will make our kiosk display stuff on the screen! What follows is a bird's eye view of the Linux graphics stack.

Kernel mode driver

The kernel should provide free-as-in-freedom GPU drivers out of the box. A problem arises when there is hardware for which no drivers were written. Worse yet - undocumented Apple hardware.

Asahi Lina wrote the first kernel GPU driver for the Apple M-series and done so in Rust, thereby also claiming the spot for the first Linux GPU driver written in Rust. They made it possible to utilize the hardware and overall allowed us to understand the graphic accelerators more. All that is, at least in this very simplified scenario, left to do is to send instructions from the user-space so the accelerator knows what to do!

User mode driver

There are many graphics and compute APIs one can utilize to draw a game, a graphical application or heck, a whole Window Manager. Namely OpenGL, often utilized for desktops, and Vulkan. As it would be unreasonably difficult to implement support for every GPU into each of these APIs, and it would also disregard the unix philosophy, an intermediate layer, Mesa, came to be. It contains various user-space drivers capturing buffers from the graphics APIs and translates them to calls the underlying kernel GPU driver understands.

The user-space GPU driver on Asahi Linux is called Honeykrisp, with Alyssa Rosenzweig as the main contributor. This driver is Khronos-recognized and, at the time of writing this, is conformant with Vulkan 1.4, OpenGL 4.6, OpenGL ES 3.2, and OpenCL 3.0. Honeykrisp is not entirely upstreamed to Mesa yet, that is why Asahi uses its own fork, Asahi Mesa, with all the patches present.

tinywl is the reference compositor implementation of wlroots, an abstraction library over Wayland. To test the ability of building parts of the Linux graphics stack locally, I decided to attempt to run tinywl through a locally built Mesa and wlroots. Building, apart from some minor hiccups, was quite pleasant as to be expected from Fedora, the distribution Asahi Linux is based on.

After the builds were finished, it was time to run tinywl as a session compositor nested inside of the already running Mutter. Using meson devenv pointing to locally built Asahi Mesa and running tinywl in the newly built wlroots directory. I heard the positive Honeykrisp Vulkan news and was excited to try the Vulkan renderer.

And tadaa ~ it did not work!

Vulkan layers and extensions allow for the insertion of additional functionality or structures to the base Vulkan spec. The Honeykrisp driver was missing an extension required by tinywl, specifically the VK_EXT_queue_family_foreign, to utilize the Vulkan renderer properly. I added the extensions locally and rebuilt.

Voilà, a wild tinywl window has appeared on the screen! I submitted a feature request in the Mesa issue tracker with Alyssa Rosenzweig swiftly adding the extension into Honeykrisp and marking the request as done.

With tinywl running as a session compositor I felt confident to run cage as a system compositor. After cloning and building cage I stumbled upon an issue - to run it via the Vulkan renderer, it required even more extensions to be enabled. Not a problem, I added them as before. Cage started just fine as a session compositor after this addition. However, as it had to start from a locally built version of Mesa running through meson devenv, which prohibits the use of root access, it was not possible to run it as a system compositor. To avoid installing a custom version of Asahi Mesa on the system or waiting for a new version to be packaged I decided to drop the Vulkan renderer and instead opted for OpenGL.

After creating a new entry in `/usr/share/wayland-sessions`, it was possible to launch cage running a terminal window, as shown below!

Cage: a Wayland kiosk running on Asahi Linux

I waved the white flag on the Vulkan renderer, but other than that I consider this experiment to be a success. I am now able to experiment with Cage and the HoneyKrisp driver on Asahi Linux, perhaps submitting more feature requests making it possible to run Cage through Vulkan.

Until then, OpenGL for desktop it is!

Playing around with Wayland

Fri, 25 Oct 2024 00:00:00 +0000

Over the summer, I read a book on the Wayland protocol. Not a typical activity for a high school student to do, but there was something that seemed so intriguing about creating my own compositor.

Wayland is the superior replacement for the X Windowing System on Linux. X (or X11) was originally developed in 1984 and thus marks it's 40 year anniversary this year. Wayland got initially released in 2008, and in contrarily with X, had desktop usage in mind from the beginning. Wayland, in comparision to X, provides developers a simpler API to work with. It is still not an easy feat, but, luckily for me, the amazing wlroots abstraction library exists. It contains about 60 000 lines of boilerplate code that a Wayland compositor developer would have to write anyways. Instead of writting boilerplate, I could focus on the more interesting parts.

Window manager / compositor

These terms tend to be used interchagebly, but there is a difference. When one mentions the term "window manager", they typically mean the part that manages window placement on the screen and the logic behind it. In Wayland the responsibilty of a window manager is closelly tied to handling user input, server-side decorations etc.., Therefore it is called a compositor rather than a window manager, even though the window managing part is still there.

The Cage compositor

After reading through the most crucial parts of the Wayland book I decided to conduct research into compositors that are developed. I stumbled upon few. Namely tinywl, of which I read the whole implementation, but one stood out - the Wayland kiosk compositor Cage. A kiosk is, in essence, a normal compositor, but one that only displays a singular client at a time. I read through the code and was overwhelmed at first. However after rereading the main function a few times I felt like I could understand and visualize what was going on. Concepts learnt in the Wayland book, even though abstracted with wlroots, were still present. The code is by no means simple, at least not for someone who has only done a handful of DSA problems and no serious projects in C whatsoever.

I figured one of the more fun ways of exploring the codebase is to solve a real issue. Since a Wayland kiosk has a lot of usages, there's quite a lot of people creating repository issues asking for help or reporting bugs.

Splash screen

Imagine you are building a car infotainment system that has to display just one application. This is a perfect usecase for a kiosk compositor. There was someone that was doing exactly that asking for help in the repository's issues. They have an application that needs to be displayed reliably everytime it is needed. The computer running the application is regulary turned off and on again. When the computer boots, Plymouth provides a flicker free loading experience. However, when it loads into the system and executes cage, the compositor instantly performs a modeset with black buffer, overriding the loader. Then, the loading application is shown and that's exactly what is not supposed to happen. There should be a way to prevent displaying the application which it is loading to provide a flicker free experience.

Framebuffer, DRI, DRM, KMS

Before diving into Wayland, I had no idea what these terms meant. In short, they are abstractions above the physical display hardware. Each of these components has a specific role in the process of displaying things onto the screen. Framebuffer allows software to display pixels by writting into designated memory spaces.

To be continued...

Vanis