Daniel Stone

Introducing freedesktop.org GitLab

Sun, 29 Jul 2018 15:39:00 +0000

This is quite a long post. The executive summary is that freedesktop.org now hosts an instance of GitLab, which is generally available and now our preferred platform for hosting going forward. We think it offers a vastly better service, and we needed to do it in order to offer the projects we host the modern workflows they have been asking for.

In parallel, we’re working on making our governance, including policies, processes and decision making, much more transparent.

Some history

Founded by Havoc Pennington in 2000, freedesktop.org is now old enough to vote. From the initial development of the cross-desktop XDG specs, to supporting critical infrastructure such as NetworkManager, and now as the home to open-source graphics development (the kernel DRM tree, Mesa, Wayland, X.Org, and more), it’s long been a good home to a lot of good work.

We don’t provide day-to-day technical direction or enforce set rules: it’s a very loose collection of projects which we each trust to do their own thing, some with nothing in common but where they’re hosted.

Unfortunately, that hosting hasn’t really grown up a lot since the turn of the millennium. Our account system was forked (and subsequently heavily hacked) from Debian’s old LDAP-based system in 2004. Everyone needing direct Git commit access to projects, or the ability to upload to web space, has to file a bug in Bugzilla, where after a trip through the project maintainer, eventually an admin will get around to pulling their SSH and GPG (!) keys and adding an account by hand.

Similarly, creating or reconfiguring a Git repository also requires manual admin intervention, where on request one of us will SSH into the Git server and do whatever is required. Beyond Git and cgit for viewing, we provide Bugzilla for issue tracking, Mailman and Patchwork for code review and discussion, and ikiwiki for tracking. For our sins, we also have an FTP server running somewhere. None of these services are really integrated with each other; separate accounts and separate sets of permissions are required.

Maintaining these disparate services is a burden on both admins and projects. Projects are frequently blocked on admins adding users and changing their SSH keys, changing Git hooks, adding people to Patchwork, manually applying more duct tape to the integration between these services, and fixing the duct tape when it breaks (which is surprisingly often). As a volunteer admin for the service, doing these kinds of things is not exactly the reason we get out of bed in the morning; it also consumes so much time treading water that we haven’t been able to enable new features and workflows for the projects we host.

Seeking better workflows

As of writing, around one third of the non-dormant projects on fd.o have at some point migrated their development elsewhere; mostly to GitHub. Sometimes this was because the other sites were a more natural home (e.g. to sibling projects), and sometimes just because they offered a better workflow (integration between issue tracking and commits, web-based code review, etc). Other projects which would have found fd.o a natural home have gone straight to hosting externally, though they may use some of our services - particularly mailing lists.

Not everyone wants to make use of these features, and not everyone will. For example, the kernel might well never move away from email for issue tracking and code review. But the evidence shows us that many others do want to, and our platform will be a non-starter for them unless we provide the services they want.

A bit over three years ago, I set up an instance of Phabricator at Collabora to replace our mix of Bugzilla, Redmine, Trac, and JIRA. It was a great fit for how we worked internally, and upstream seemed like a good fit too; though they were laser-focused on their usecases, their extremely solid data storage and processing model made it quite easy to extend, and projects like MediaWiki, Haskell, LLVM and more were beginning to switch over to use it as their tracker. I set up an instance on fd.o, and we started to use it for a couple of trial projects: some issue tracking and code review for Wayland and Weston, development of PiTiVi, and so on.

The first point we seriously discussed it more widely was at XDC 2016 in Helsinki, where Eric Anholt gave a talk about our broken infrastructure, cleverly disguised as something about test suites. It became clear that we had wide interest in and support for better infrastructure, though with some reservation about particular workflows. There was quite a bit of hallway discussion afterwards, as Eric and Adam Jackson in particular tried out Phabricator and gave some really good feedback on its usability. At that point, it was clear that some fairly major UI changes were required to make it usable for our needs, especially for drive-by contributors and new users.

Last year, GNOME went through a similar process. With Carlos and some of the other members being more familiar with GitLab, myself and Emmanuele Bassi made the case for using Phabricator, based on our experiences with it at Collabora and Endless respectively. At the time, our view was that whilst GitLab’s code review was better, the issue tracking (being much like GitHub’s) would not really scale to our needs. This was mostly based on having last evaluated GitLab during the 8.x series; whilst the discussions were going on, GitLab were making giant strides in issue tracking throughout 9.x.

With GitLab coming up to par on issue tracking, both Emmanuele and I ended up fully supporting GNOME’s decision to base their infrastructure on GitLab. The UI changes required to Phabricator were not really tractable for the resources we had, the code review was and will always be fundamentally unsuitable being based around the Subversion-like model of reviewing large branches in one go, and upstream were also beginning to move to a much more closed community model.

gitlab.freedesktop.org

By contrast, one of the things which really impressed us about GitLab was how openly they worked, and how open they were to collaboration. Early on in GNOME’s journey to GitLab, they dropped their old CLA to replace it with a DCO, and Eliran Mesika from GitLab’s partnership team came to GUADEC to listen and understand how GNOME worked and what they needed from GitLab. Unfortunately this was too early in the process for us, but Robert McQueen later introduced us, and Eliran and I started talking about how they could help freedesktop.org.

One of our bigger issues was infrastructure. Not only were our services getting long in the tooth, but so were the machines they ran on. In order to stand up a large new service, we’d need new physical machines, but a fleet of new machines was beyond the admin time we had. It also didn’t solve issues such as everyone’s favourite: half of Europe can’t route to fd.o for half an hour most mornings due to obscure network issues with our host we’ve had no success diagnosing or fixing.

GitLab Inc. listened to our predicament and suggested a solution to help us: that they would sponsor our hosting on Google Cloud Platform for an initial period to get us on our feet. This involves us running the completely open-source GitLab Community Edition on infrastructure we control ourselves, whilst freeing us from having to worry about failing and full disks or creaking networks. (As with GNOME, we politely declined the offer of a license to the pay-for GitLab Enterprise Edition; we wanted to be fully in control of our infrastructure, and on a level playing field with the rest of the open-source community.)

They have also offered us support, from helping a cloud idiot understand how to deploy and maintain services on Kubernetes, to taking the time to listen and understand our workflows and improve GitLab for our uses. Much of the fruit of this is already visible in GitLab through feedback from us and GNOME, though there is always more to come. In particular, one area we’re looking at is integration with mailing lists and placing tags in commit messages, so developers used to mail-based workflows can continue to consume the firehose through email, rather than being required to use the web UI for everything.

Last Christmas, we gave ourselves the present of standing up gitlab.freedesktop.org on GCP, and set about gradually making it usable and maintainable for our projects. Our first hosted project was Panfrost, who were running on either non-free services or non-collaborative hosted services. We wanted to help them out by getting them on to fd.o, but they didn’t want to use the services we had at the time, and we didn’t want to add new projects to those services anyway.

Over time, as we stabilised the deployment and fleshed out the feature set, we added a few smaller projects, who understood the experimental nature and gave us space to make some mistakes, have some down time, and helped us smooth out the rough edges. Some of the blocker here was migrating bugs: though we reused GNOME’s bztogl script, we needed some adjustments for our different setups, as well as various bugfixes.

Not long ago, we migrated Mesa’s repository hosting as well as Wayland and Weston for both repository tracking and issue tracking which are our biggest projects to date.

What we offer to projects

With GitLab, we offer everything you would expect from gitlab.com (their hosted offering), or everything you would expect from GitHub with the usual external services such as Travis CI. This includes issue tracking integrated with repository management (close issues by pushing), merge requests with online review and merge, a comprehensive CI suite with shared runners available to all, custom sites built with whatever toolchain you like, external web hooks to integrate with other services, and a well-documented stable API which allows you to use external clients like git lab.

In theory, we’ve always provided most of the above services. Most of these - if you ignore the lack of integration between them - were more or less fine for projects running their own standalone infrastructure. But they didn’t scale to something like fd.o, where we have a very disparate family of projects sharing little in common, least of all common infrastructure and practices. For example, we did have a Jenkins deployment for a while, but it became very clear very early that this did not scale out to fd.o: it was impossible for us to empower projects to run their own CI without fatally compromising security.

Anyone familiar with the long wait for an admin to add an account or change an SSH key will be relieved to hear that this is no longer. Anyone can make an account on our GitLab instance using an email address and password, or with trusted external identity providers (currently Google, gitlab.com, GitHub, or Twitter) rather than having another username and password. We delegate permission management to project owners: if you want to give someone commit rights to your project, go right ahead. No need to wait for us.

We also support such incredible leading-edge security features as two-factor TOTP authentication for your account, Recaptcha to protect against spammers, and ways of deleting spam which don’t involve an admin sighing into a SQL console for half an hour, trying to not accidentally delete all the content.

Having an integrated CI system allows our projects to run test pipelines on merge requests, giving people fast feedback about any required changes without human intervention, and making sure distcheck works all the time, rather than just the week before release. We can capture and store logs, binaries and more as artifacts.

The same powerful system is also the engine for GitLab Pages: you can use static site generators like Jekyll and Hugo, or have a very spartan, hand-written site but also host auto-generated documentation. The choice is yours: running everything in (largely) isolated containers means that you can again do whatever you like with your own sites, without having to ask admins to set up some duct-taped triggers from Git repositories, then ask them to fix it when they’ve upgraded Python and everything has mysteriously stopped working.

Migration to GitLab, and legacy services

Now that we have a decent and battle-tested service to offer, we can look to what this means for our other services.

Phabricator will be decommissioned immediately; a read-only archive will be taken of public issues and code reviews and maintained as static pages forever, and a database dump will also be kept. But we do not plan to bring this service back, as all the projects using it have already migrated away from it.

Similarly, Jenkins has already been decommissioned and deactivated some time ago.

Whilst we are encouraging projects to migrate their issue tracking away from Bugzilla and helping those who do, we realise a lot of projects have built their workflows around Bugzilla. We will continue to maintain our Bugzilla installation and support existing projects with its use, though we are not offering Bugzilla to new projects anymore, and over the long term would like to see Bugzilla eventually retired.

Patchwork (already currently maintained by Intel for their KMS and Mesa work) is in the same boat, complicated by the fact that the kernel might never move away from patches carved into stone tablets.

Hopefully it goes without saying that our mailing lists are going to be long-lived, even if better issue tracking and code review does mean they’re a little less-trafficked than before.

Perhaps most importantly, we have anongit and cgit. anongit is not provided by GitLab, as they rightly prefer to serve repositories over https. Given that, for all existing projects we are maintaining anongit.fd.o as a read-only mirror of GitLab; there are far too many distributions, build scripts, and users out there with anongit URIs to discontinue the service. Over time we will encourage these downstreams to move to HTTPS to lessen the pressure, but this will continue to live for quite some time. Having cgit live alongside anongit is fairly painless, so we will keep it running whilst it isn’t a burden.

Lastly, annarchy.fd.o (aka people.fd.o) is currently offered as a general-purpose shell host. People use this to manage their Git repositories on people.fd.o and their files publicly served there. Since it is also the primary web host for most projects, both people and scripts use it to deploy files to sites. Some people use it for random personal file storage, to run various scripts and even as a personal IRC host. We are trying to transition these people away from using annarchy for this, as it is difficult for us to provide totally arbitrary resources to everyone who has at one point had an account with one of our member projects. Running a source of lots of IRC traffic is also a good way to make yourself deeply unpopular with many hosts.

Migrating your projects

After being iterated and fleshed out, we are happy to offer to migrate all the projects. For each project, we will ask you to file an issue using the migration template. This gives you a checklist with all the information we need to migrate your GitLab repositories, as well as your existing Bugzilla bugs.

Every user with a freedesktop.org SSH account already has an account created for them on GitLab, with access to the same groups. In order to recover access to the migrated accounts, you can request a password-reset link by entering the email address you signed up with into the ‘forgotten password’ box on the GitLab front page.

More information is available on the freedesktop GitLab wiki, and of course the admins are happy to help if you have any problems with this. The usual failure mode is that your email address has changed since you signed up: we’ve had one user who needed it changed as they were still using a Yahoo! mail address.

Governance and process

Away from technical issues, we’re also looking to inject a lot more transparency into our processes. For instance, why do we host kernel graphics development, but not new filesystems? What do we look for (both good and bad), and why is that? What is freedesktop.org even for, and who is it serving?

This has just been folk knowledge for some time; passed on by oral legend over IRC as verbal errata to out-of-date wiki pages. Just as with technical issues, this is not healthy for anyone: it’s more difficult for people to get involved and give us the help we so clearly need, it’s more difficult for our community to find out what they can expect from us and how we can help them, and it’s impossible for anyone to measure how good a job we’re actually doing.

One of the reasons we haven’t done a great job at this is because just keeping the Rube Goldberg machine of our infrastructure running exhausts basically all the time we have to deal with fd.o. The time we spend changing someone’s SSH keys by hand, or debugging a Git post-receive hook, is time we’re not spending on the care and feeding of our community.

We’ve spent the past couple of years paying down our technical debt, and the community equivalent thereof. Our infrastructure is much less error-prone than it was: we’ve gone from fighting fires to being able to prepare the new GitLab infrastructure and spend time shepherding projects through it. Now that we have a fair few projects on GitLab and they’ve been able to serve themselves, we’ve been able to take some time for community issues.

Writing down our processes is still a work in progress, but something we’ve made a little more headway on is governance. Currently fd.o’s governance is myself, Keith and Tollef discussing things and coming to some kind of conclusion. Sometimes that’s in recorded public fora, sometimes over email with searchable archives, sometimes just over IRC message or verbally with no public record of what happened.

Given that there’s a huge overlap between our mission and that of the X.Org Foundation (which is a lot more than just X11!), one idea we’re exploring is to bring fd.o under the Foundation’s oversight, with clear responsibility, accountability, and delegated roles. The combination of the two should give our community much more insight into what we’re doing and why - as well as, crucially, the chance to influence it.

Of course, this is all conditional on fd.o speaking to our member projects, and the Foundation speaking to its individual members, and getting wide agreement. There will be a lot of tuning required - not least, the Foundation’s bylaws would need a change which needs a formal vote from the membership - but this at least seems like a promising avenue.

pl111: the most satisfying driver submission

Tue, 11 Apr 2017 12:03:00 +0100

The pl111 driver might be the most satisfying driver submission yet. Not because I’m desperate to see it in tree; I don’t actually have that hardware. Not because it’s bringing really exciting new capabilities. But, from Eric’s v5 submission:

v2: Nearly complete rewrite by anholt, cutting ²⁄₃ of the code thanks to DRM core’s excellent new helpers.

and a follow-up review:

I must say the driver is really slim and readable with all the new helpers from DRM, good job all who refactored the DRM support for simple framebuffer systems.

The DRM community really has come a long, long, way. Great to see it so thriving and healthy that people are actively dusting off ancient drivers which never got merged, deleting most of them in the process, and getting them in just because the process works so well.

freedesktop.org CoC

Mon, 10 Apr 2017 21:00:00 +0100

On Friday, after consulting with the other freedesktop.org admins, I pushed a change to the freedesktop.org wiki, adding a Code of Conduct, based on the widely-used Contributor Covenant. In doing this, we join pretty much every other large open source project on the planet, with the exception of the Linux kernel, a magnificent anti-pattern. From this point on, all projects hosted on freedesktop.org are subject to this CoC.

why so broad?

fd.o is a notoriously loose collective of communities, who largely run their own affairs. However, freedesktop.org as a project is responsible for the content on our site: mailing list archives, bug tracking systems, website, etc. We’ve already had to intervene to remove legally problematic content from our hosting platforms; ultimately, it is our responsibility.

The culture of our member projects reflect on us as a wider organisation, and the problems of abusive and bullying behaviour weren’t solving themselves. In some specific cases we looked at, we were told directly by senior figures in the project that the lack of a defined fd.o-wide CoC made it harder for them to enforce it themselves.

In the end, the only course of action was completely clear: that we take the same approach to unacceptable behaviour as we do to legally-unacceptable content. Enforcing it across the platform gives everyone complete clarity of what’s required (i.e. behaving like reasonable human beings).

but the honeytrap / bad code

The notion that codes of conduct are used as a kind of submarine device to saddle communities with terrible code, and run completely excellent people out of the community for literally no reason, has been thoroughly debunked over the years that codes of conduct have been implemented. I don’t plan to give these arguments any time at all.

what now?

The conduct mailing list now exists, for confidential reports of any CoC violations. This is currently only manned by fd.o admins. We have, however, been in touch with some of the larger member projects, inviting them to help deal with conduct enforcement in their own projects. This process will take time, but if you’re interested in doing this for your project, please get in touch.

And hopefully, people continue to build healthy communities producing excellent code.

linux.conf.au CfP closing fast!

Wed, 03 Jul 2013 12:00:00 +0000

Everyone’s favourite Australasian open source conference, linux.conf.au, is unsurprisingly back for 2014. This time, it’s in Perth, where it’s relentlessly hot and sunny all year; I’m told the beaches are nice too. A nice break from Europe and north America in January, then. Or wherever you happen to be from the 6th—11th January.

But you can’t make a great conference without great talks, which is where you come in. The Call for Papers is closing this Saturday, the 6th of July. So please, do come and submit your talks about graphics, window systems, input, media, dmabuf, some cool little hack you’ve been working on, whatever. We had a great slate of talks this year, and would love to see them even better next year.

Weston on Raspberry Pi

Thu, 23 May 2013 12:00:00 +0000

One of the platforms we’ve been working on for a while at Collabora is the Raspberry Pi. Obviously the $25 pricepoint makes it hugely appealing to a lot of people — including free software developers who up until now have managed to avoid the ~~agony~~joy we experience on a daily basis working on embedded and mobile platforms — but there are a couple of aspects which speak specifically to us as a company.

Firstly, we did quite a bit of work on OLPC through the years, which had a similar, very laudable, educational mission encouraging not just deep computer literacy in children, but also open source involvement. The Raspberry Pi has broadly the same aims, a very education-friendly pricepoint, and has seen huge success.

Less loftily, it’s a great example of a number of architectures we’ve been quietly working on for quite some time, where hugely powerful special-purpose (i.e. not OpenGL ES) graphics hardware goes nearly unused, in favour of heavily loading the less powerful CPU, or pushing everything through GL.

background etc

The Raspberry Pi has a Broadcom BCM2385 SoC in it, containing an extremely beefy (roughly set-top-box-grade) video, media and graphics processor called the VideoCore (somewhat akin to a display controller, GPU and DSP hybrid), and a … somewhat less beefy general-purpose ARMv6¹ CPU. The ARM side does everything you’d expect, whereas the VideoCore is a multi-functional beast, acting as the GPU for OpenGL ES, the display engine for outputs/overlays/etc, and also any general-purpose processing (e.g. accelerated JPEG decode).

In terms of how this looks from the ARM, the VideoCore exposes its display functionality through DispManX, an API for display control similar, in capability at least, to KMS. The DispManX exposes a number of output displays, each of which can have a number of planes (sometimes called overlays or sprites) which can each be in different colourspaces (think: video), scaled, alpha-blended, or variously stacked. No surprise there, as this is how most GPUs and display controllers look everywhere: from your phone, to your desktop, to your set-top box.

A recurring theme for us is how to properly use and expose these overlays. There’s a huge benefit in doing so over using GL: not only are they a lot faster, but they also have hugely better quality when doing colourspace conversion and scaling, and extra filters for much better image quality². There’s also a pretty strong power argument to be made; at one stage, measuring on a phone, we found a 20% runtime difference — from 4 hours to a bit over 5 — when watching videos using the overlay, compared to pumping them through GL ES. And that was without the zerocopy support we enjoy nowadays!

The X Video extension (Xv) exposes overlays in a very limiting and frustrating way, meaning they’re only really suitable for video, and even then aren’t capable of zerocopy. DRI2 video support was proposed to fix this, but so far TI’s OMAP is the only real deployment of this, and client support is very patchy.

Even then, this is only applicable to video. Under the X11 model, effectively the only way to do compositing is for an external process to render the entire screen as a single image, then pass that image to the X server to display. This is fine for GL, since that’s exactly what it’s built for, but it means you’re never going to get to use all your lovely 2D compositing hardware. Either that, or you do offload compositing inside the X server: something very difficult which almost no-one does, not only because it means no compositing. And no compositing means that your desktop is all back to 1995, with those attractive flickering backgrounds and jittery resizes. :(

i thought this was about rpi … ?

We’ve been working with the Raspberry Pi Foundation since last year, when we first brought up Weston on Raspberry Pi. At that stage, Weston was still very heavily GLES-based, but was able to opportunistically pull individual surfaces out into overlays if the conditions were right. This worked, and was all well and good, but was an awkward abuse of Weston’s internal model, and made RPi look rather unlike any other backend.

Fast forward to a couple of months ago, and Weston had come a long way along the road towards 1.1. A pretty vital piece for us was the renderer infrastructure: whereas Weston previously only had pluggable backends controlling the final display output backend (think: KMS, fbdev, RDP), it now gained a similar split for the renderers.

The original split was between the original GLES renderer and a purely-software Pixman renderer (which was still capable of everything the GLES renderer was!), but it was also a perfect fit for DispManX. So, the first thing Pekka did, and the base of all our work since, was to split the RPi backend into a backend and a renderer, allowing us to guarantee that we’d never fall back to GLES. This lets us feed the entire set of windows into the hardware, complete with stacking order, alpha blending, and 2D transforms, and have the VideoCore take care of everything, all fully synchronised and tear-free. Without using GL!

Pekka’s blog has more of the gory details on both the Weston internals, and how DispManX works.

shiny demos

Seemingly no-one can talk about open source graphics without getting all misty-eyed over wobbly windows; what good is straight tech with nothing to show for it? So, while Pekka worked on the renderer, Louis-Francis and myself knocked up a couple of demos to show off what we could do with 2D compositing alone.

The first, and most compelling, demo is in our case study, in which Louis-Francis drags some windows around under both X11 and Weston for the camera. X11 struggles badly, whereas Weston with its VideoCore backend keeps up like a champ.

Louis-Francis then added an optional fade layer, where all the background windows were dimmed, complete with a nice fading animation between foreground and background. This is done internally with one or two solid-colour surfaces, with varying alpha.

Last but not least, I added a reimplementation of GNOME3’s window overview mode. It is a little on the rudimentary side, and does certainly suffer from not having an established layout/packing framework to use, but does work, and I think provides a pretty good demonstration of the kinds of smooth and fluid animations that are totally possible without ever touching GLES. And the best part is that windows zoom around, scaled and alpha-blended, at 60fps, whereas X11 struggles to get to 10fps just moving an unscaled, opaque, window. Yeesh.

And then some of the details were just that: details. Pekka add a new background scaling mode which preserves aspect ratio, Louis-Francis and Pekka worked to make sure the memory usage was always as low as humanly possible, including an optional mode where we trade strict visual correctness for performance and memory usage, we fixed some bugs in the XWayland emulation, and some bugfixes.

sounds great; how do i get it?

The source is already winging its way upstream; currently, the renderer has been merged, but some of the effects are still oustanding. In the meantime, you can clone Pekka’s repository:

$ git clone git://git.collabora.co.uk/git/user/pq/weston
$ cd weston
$ git checkout origin/raspberrypi-dispmanx-wip

Or we’ve also got Raspbian packages, based on the stable 1.0.x rather than unreleased git:

# echo deb http://raspberrypi.collabora.com wheezy rpi >> /etc/apt/sources.list
# apt-get update
# apt-get install weston

tl;dr

A lot of hardware — particularly in the media/embedded/mobile space — ships with hugely powerful special-purpose graphics hardware, aside from the usual OpenGL ES. Up until now, this special-purpose hardware has gone unused, but for equally special-purpose hacks. The work we’ve done with Weston and Raspberry Pi, using only its dedicated 2D compositing hardware, is a fantastic example of what we can do with Wayland and these kinds of platforms in general, without using GL ES.

now convince your boss

Would you love us to shut up and take your money, but just need that little bit extra to persuade those humourless lot up in purchasing? Fear not: we have an entire case study for the work we’ve done on the Raspberry Pi, as well as a general graphics page. Raspberry Pi have a writeup themselves too. Or maybe you’re more impressed (ha) by press releases? Either way, our trained operators are standing by to take your call.

ARMv6 is the sixth iteration of the ARM architecture; the chip family is ARM11, which was the generation immediately pre-Cortex. Various ARM11s were used in, e.g., the Nokia N810, the iPhone 3G, and the Nintendo 3DS. If you’re confused by the ARM nomenclature, Wikipedia has a really good table. ^[return]
Fun side note: if you want zero-copy video through GL, thanks to the unbelievably harsh wording of GL_OES_EGL_image_external, then you’re only allowed to use linear or nearest filtering. Not even bilinear, and definitely nothing near what overlays can do. ^[return]

xkbcommon: what is it?

Tue, 09 Apr 2013 12:00:00 +0000

So, in my earlier post, I mentioned that I’d been working on a library called xkbcommon. Since it’s got a massively misleading name (and renaming hasn’t been totally ruled out yet …), it’s probably worth an introductory post.

tl;dr: It loads XKB keymaps and can manage tricky things like modifier state for you.

tell me more!

At its core, xkbcommon is nothing to do, as you might think, with X11. It’s about two things: parsing and loading keymaps, and managing their ongoing state. State, in terms of keyboards, is the usual suspects — modifiers (e.g. Shift, Alt), multiple layouts (mostly for multiple languages), and LEDs. In general, you only want one person keeping a canonical copy of the state, and distributing it to its clients, as both the X server and Wayland do today. xkbcommon allows for this mode of operation, and is indeed how all current Wayland clients handle keyboard input.

One notable thing xkbcommon isn’t, is an input method. Anything more complex than ‘I press one key and get a symbol’, such as phonetic compound composition for CJK/Thai/etc (where you type out a word, which, when completed, becomes much fewer characters on screen) or menu-based selections as common in both Arabic and Mandarin (where you type out the beginnings of a word, and are then offered a selection of choices to complete), or even just the seemingly-straightforward compose key (e.g. right Alt + o + / → ø), are implemented internally to the toolkit, and don’t really use xkbcommon at all. Supporting the two (key-based vs. string-based) methods in the same protocol seems straightforward, but quickly becomes hugely unwieldy if you ever need to do anything weird like, say, process shortcuts. Anyway, if you want to find out more about input methods on Wayland, Michael Hasselmann has a very nice update about Maalit and ibus.

This makes life rather more simple for the keyboard-based protocols: all we have to do is tell xkbcommon every time someone presses (or releases) a key, and ask it which symbols resulted from that.

There are two methods of operation. The self-contained approach, suitable if you’re writing programs which back directly on to a terminal and have absolute full control over the entire keyboard, is used by most of our tests, such as interactive.c, which is a reasonably summary of how to implement one of these clients. Here, the same client manages the entire state, and never needs to deal with any external entities.

However, the most common method of operation is the one used by Wayland and X11, where a central server manages the state and informs the clients. Under this model, the clients never update the state implicitly through xkb_state_update_key(); they only ever use xkb_state_update_mask() in response to its master sending it a new and complete copy of the state.

ok — so how do I use it?

Firstly, create a context:

ctx = xkb_context_new(0);

which will be the base for all your xkbcommon operations. Secondly, we need to compile a keymap. If you have a named keymap you want to compile from (e.g. the user has specified ‘Icelandic Dvorak with Caps Lock mapped to Ctrl’), use:

keymap = xkb_keymap_new_from_names(ctx, rules, model, layout, variant, options);

On Linux, the rules and model are almost always ‘evdev’. Layout is usually the ISO two-character country (not language!) code, variant is specific to the layout, and options are global. In this case, we would use:

keymap = xkb_keymap_new_from_names(ctx, "evdev", "evdev", "is", "dvorak", "ctrl:nocaps");

A keymap is a static and immutable ruleset describing the translation between key events and the resulting output (e.g. if d is pressed while shift is held down, then output D). On top of the keymap, for every keyboard we use, we generate a new state object:

state = xkb_state_new(keymap);

which will track things like which keys are currently held down. Every time a key is pressed or released, we first get the symbols it produces:

sym = xkb_state_key_get_one_sym(state, keycode);

which returns a key symbol (listed in xkbcommon-keysyms.h, and identical to the X11 keysyms; xkb_keysym_to_utf8() may be used to translate this to a string) generated by that keypress. For example, pressing the B key on Icelandic Dvorak with AltGr held down would return XKB_KEY_ssharp (i.e. ß). After we have got the symbol to be used, we then update the state object with the keypress. It is crucial the order of these two operations is not reversed! Anyhow, we update the state object like so for sole-control programs:

changed = xkb_state_update_key(state, keycode, XKB_KEY_DOWN);

or thusly for clients who get their master state from an external program, e.g. Wayland compositor:

changed = xkb_state_update_mask(state, mods_down, mods_latched, mods_locked, ...);

and we have now completed our key processing. Hurrah!

Note that you do not need any special cases anywhere: xkbcommon takes care of the mechanics of handling special keys under the hood for you. The one case where you need extended functionality is shortcut processing (e.g. capture Ctrl+P), but that’s a story for another day.

shouldn’t all this be in the documentation?

… yeah.

PS: Funny story: I was planning to explain in this footnote how I’d just picked Icelandic Dvorak for a laugh and no-one would make a layout that ridiculous. But no, it actually exists …

Been a while

Sat, 06 Apr 2013 12:00:00 +0000

hi

Yeesh, it really has been a while, hasn’t it.

Last time we spoke, I was working on X11, and my blog was being served off a FreeBSD 4.3 machine (obviously named ‘amnesiac’), from the datacentre of an ISP who had long since forgotten which ex-employee’s Pentium II was sitting in that rack. Unfortunately I didn’t back it up, and no longer even have a copy of the RSS feed to import. Looking over the Wayback Machine copy though, I don’t think we’re missing much by losing that one. So here we are with WordPress, having blatantly ripped off Lucas’s theme.

Shortly after that machine died — early in 2012 — I finished up my last proper X11 project for a customer, went back to Australia for linux.conf.au and a holiday, and came back to start working on Wayland’s input subsystem (including xkbcommon, on which more in a future post). Working on Wayland has been really refreshing; not only did it feel like time for a change after nine years of working on X11, but diminishing returns meant that we were increasingly spending enormous amounts of time on X11 to achieve very marginal results.

The last major thing I did there was work with Chase Douglas (ex-Canonical) and Peter Hutterer (Red Hat) — though sadly due to timing, we almost entirely worked in relay, rather than together — on the XI2.3 multitouch protocol and implementation. I was quite proud to see it eventually make its way upstream, but having subsequently both tried to explain to others how it all hangs together, and watched Peter continue to fix corner-case after corner-case in its interactions with other parts of X11 input, it really solidified my view that X11 is a dead end for any new development.

stop whining and get on with it

A couple of months ago, in Canberra for linux.conf.au 2013, I gave a presentation about that very realisation. Originally I thought of giving a kind of dispassionate comparison and explanation of the two, but it ended up becoming a fairly linear narrative of where X began, where it is now, and how Wayland organically developed from this. It’s a fairly well-worn line that Wayland is in many ways the culmination of the last ten years of X.Org development, but it really is true.

Part of that has not just been shedding the X11 cruft and getting the opportunity to start over — though, given the state of the X11 protocol and its 28 common extensions, plus its codebase, that’s really no bad thing — but some radically different design decisions, down to the real fundamentals of the interfaces. Giving compositors a lot more context opens up a huge amount of possibilities for us (beginning with actually being able to activate a screensaver while a pop-up menu’s active …), and I’m really excited about the kinds of things we can do.

It’s been really interesting to see Wayland grow and develop into a fully-fledged window system. At Collabora, we’ve had Pekka, Louis-Francis, Fred and others working on Wayland support across the board: compositors, client toolkits/apps, and hardware enablement too. After the groundwork we’ve been doing, a lot of it is really starting to come to fruition and hopefully we’ll have some more shiny demos soon. Along the way, I managed to fulfill one of my goals I set a while ago, which was to get out of the bubble of only ever working on the server (since X clients were so uniformly unpleasant), and work throughout the stack. Over the past few months, I’ve been able to work on GStreamer, WebKit, Clutter, COGL, Mesa, and other EGL/GLES stacks, which has been really interesting.

where next?

With GTK+, Qt and Clutter all shipping Wayland support in their stable releases, the next big thing for me personally is watching the GNOME port progress. We’ve got a stable and solid core protocol and library now, but there are definitely some gaps to be filled in by having a real desktop environment ported, and certainly around input we’ve got a lot of things to support (e.g. touchpad support on par with xf86-input-synaptics, better mouse acceleration, support for synchronising keyboard repeat rates between clients, tablets, etc). But it’s quite exciting to see what people will be able to make of our work so far.

About me

Mon, 01 Jan 0001 00:00:00 +0000

An Australian living in London, I work as the graphics lead at the open-source consultancy Collabora. During my 10 years with Collabora, I’ve worked with clients such as ARM, Intel, Google, Raspberry Pi, Zodiac Inflight Innovations, and many more. Before Collabora, I worked on Maemo/MeeGo at Nokia, on Ubuntu at Canonical, and at LinuxFund and Trinity College, University of Melbourne.

I focus on the Linux and open-source graphics stack, including Wayland and the associated plumbing both sides of it: kernel modesettting, EGL and GBM, the Vulkan WSI, GStreamer, Chromium’s Exosphere, etc. I believe strongly in having better infrastructure, and have spent time working on build systems, CI, issue trackers, and more; as part of this, I am one of the team who runs freedesktop.org.

In a past life, I worked on X.Org and XFree86 for quite a few years, but not anymore; I’ve also previously worked on Debian, Ubuntu, KDE, and other open-source projects.

Email: daniel@fooishbar.org or daniels@collabora.com