MISSENE

My first talk at FOSDEM 2026

2026-02-02T00:00:00+01:00

FOSDEM'26 is my grand premiere as a speaker at the conference.

I presented "Pixel on life-support, upgrading from Android 12 to Android 16", a talk on the relevance of custom ROMs (in 2026 still...) and a quick recap of my journey upgrading my Pixel 4a all the way up to Android 16.

You can watch the replay and download my slides from the event webpage.

Or get the files mirrored here for the record :

It was a very nice experience and even though I've been going to FOSDEM for many years now, this time felt special and personal.

Apart from my obvious involvement with the presentation, I was also fortunate to meet with a fellow Evolution X maintainer and a few people from the custom ROM community : LineageOS, CalyxOS and /e/OS among others.

Meeting people In-Real-Life is the main purpose of this kind of events ; the nature of free and open-source projects makes it so that people are often contributing remotely, from different countries, in different timezones and as their schedule allows them to.

Needless to say having the opportunity to gather and meet in person is quite an exception.

I was very pleased to meet another developer from Evolution X and we got to spend some quality time together.

Along with the people from other Android distribution projects, we spend the week-end together during the conference at the ULB, discussing what we do and sharing some insight on things we haven't get the chance to touch on before.

I am very happy to be part of a welcoming community, and I hope this will become the occasion for recurring reunions.

Wishing you all well on your way back home.

Until we meet again, cheers.

Android 16 QPR1 in Evolution X, FOSDEM release

2026-01-31T00:00:00+01:00

My first Android 16 QPR1 official release is finally here : introducing Evolution X 11.5.2 !

I touched on the QPR1 situation to explain why this first Quarterly Platform Release took so long to be integrated in custom ROMs - Evolution X not being at fault here - and I am pleased to get it out at long last.

I haven't been sitting idle until now though.

Since my first Android 16 release, 11.4.1, I have been trying to improve the performance of my devices after getting feedback from users about lag and general UI responsiveness.

The situation was serious enough to took it upon myself and search for a solution. Thanks to fellow maintainers and fruitful discussions, I spent some time reading code and sweeping through the changes of a QuinceROMs repository, the developer is providing unofficial Evolution X builds for Snapdragon 855 SoC (SM8150 platform) and OnePlus devices in particular, with a special focus on performance improvements. This is exactly what I needed, having all my Pixel devices based on Snapdragon SoCs while being quite older and less powerful than the SM8150.

By filtering the git history on the changes done in the vendor.prop file in the Android 16 branch, I got a list of commits addressing performance issues.

Then it was "just" a matter of :

reading through all those changes,
exercising some common sense with regard to my own issues,
manually cherry-picking some of those,
building and testing them to include or reject.

Simple and straightforward, right ? :-)

I ended up with a few commits providing significant improvements : check them out here.

I also kept rebasing my device tree on the work of LineageOS for Android 16 QPR1, just to make sure I get any upstream fix and improvement that may benefit my users.

Long story short, after a few weeks of patience and multiple testing rounds, we finally have my first official Android 16 QPR1 release : Evolution X 11.5.2 for the Pixel 4a, Pixel 4a 5G and Pixel 5 with decent UI responsiveness !

By the way, I am currently at FOSDEM'26, where I will be presenting on Pixel on life-support, upgrading from Android 12 to Android 16.

Android 16 QPR1 situation, unofficial test builds

2025-12-22T00:00:00+01:00

UPDATE 2025-12-24

Updated all Android 16 builds to include performance improvements.

ORIGINAL 2025-12-22

The Android 16 release has been a peculiar one.

Google usually releases the source code of the latest version of its mobile operation system to the Android Open-Source Project (AOSP) repositories : this process is what allows the custom ROM community to provide alternative builds, with modification and enhancements not found in Google's stock offering.

Things have been changing lately.

Following the release of Android 16, we no longer have the source code being developed in the open, directly in AOSP, as progress is being made.

Instead progress is now made in private, and dropped to AOSP afterwards ; check out this article to learn more on the subject.

As a consequence of this change, Android 16 QPR1 source code has not been available in AOSP repositories until November 2025, while it was officially present within the Pixel 10 lineup, Google's own commercial line of smartphones, at the end of August 2025.

Three months after release, the big Material 3 Expressive redesign of Android 16 could not be included in custom ROM builds as the sources of this major overhaul has been kept private that long.

Was the delay related to some engineering difficulty to release the open-source components ?

Will this kind of situation become a trend, a new norm resulting from Android Open-Source Project new development and release model ?

Only time will tell, and we are starting to see some improvements to make up for the delay.

First of all, Android 16 QPR1 sources are now being integrated into Evolution X code base.

Given the substantial impact, I am still preparing for its official release : to make sure issues are identified and fixed, I am now providing test builds for users willing to help with this process :

Pixel 4a Android 16 QPR1 test build :

Pixel 4a 5G Android 16 QPR1 test build :

Pixel 5 Android 16 QPR1 test build :

Future unofficial builds may be delivered for testing purpqoses, join Evolution X official chat on Discord to stay in touch (in my dedicated "Google Pixel 4a, Pixel 4a 5G & Pixel 5" channel).

The other improvement is the availability of Android 16 QPR2 source code in AOSP.

This one was dropped in December, quickly following the QPR1 code drop a month earlier ; check out AOSP release timeline and Android version history to learn more.

Fingers crossed the outstanding QPR1 release schedule does not become a trend.

Official builds and OTA support

2025-11-23T00:00:00+01:00

As I recently became the official maintainer at Evolution X project for the Pixel 4a, 4a 5G and Pixel 5, the software updates I provide for these devices are now built and released through the CI/CD infrastructure of the project.

Pace of the releases has slowed down recently because we, at Evolution X, have been doing a major upgrade of the build and release tools. The goal is to streamline our work as maintainers, with the added benefit of simplifying our internal processes and making future releases more reliable.

Long story short, from now on the updates for my devices will be available on the project website as official builds :

Pixel 4a : https://evolution-x.org/devices/sunfish,
Pixel 4a 5G : https://evolution-x.org/devices/bramble,
Pixel 5 : https://evolution-x.org/devices/redfin.

At the time of this writing, for each device, you will get the following builds :

Evolution X 10.x, starting with 10.9 (Android 15 with September 2025 security patches),
Evolution X 11.x, starting with 11.4.1 (Android 16 with November 2025 security patches),
each major version comes with Google Apps built-in by default, or without any of these applications if you choose the Vanilla variant.

Every official build is signed with the project keys for security reasons ; once you are running a major version of an official release, the following updates will be delivered through an Over-The-Air download directly to your device.

Neat, isn't it ?

Rooting Android with KernelSU

2025-11-02T00:00:00+01:00

What is rooting ?

Wikipedia definition:

"Rooting is the process by which users of Android devices can attain privileged control (known as root access) over various subsystems of the device, usually smartphones and tablets. Because Android is based on a modified version of the Linux kernel, rooting an Android device gives access to administrative (superuser) permissions similar to those on Linux [...]"

To put it simply, one might want to do something on a device that requires special access, like uninstalling an application that was provided by the vendor as part of the system.

As the application is considered to be part of the system, the user needs to be able to delete the privileged files related to the application, hence the requirement to become a "super-user" in the Unix way.

A case for the Pixel 4a

On Android, there is a way to become superuser of the device at hand.

And just like Linux, it is done by executing the su binary.

Sounds simple and straightforward, right ?

Problem is, su is never shipped by default by any smartphone manufacturer, and for obvious reasons : privilege escalation can be a security loophole in the wrong hands, especially with phones ; devices which are at the same time easily misplaced and contain very personal data nowadays.

The process of gaining access to su has evolved over the years, as security loopholes were patched and new ways were engineered, and one of the popular method for the time being is called KernelSU.

As the name implies, it is a kernel based framework.

It relies on debugging mechanisms like the Linux kernel probes (aka. kprobes) to provide hardware breakpoints, access physical memory or intercept any system call of any process invisibly, among other functionalities, thanks to the capability of running in kernel mode.

"Additionally, KernelSU provides a module system via OverlayFS, which allows you to load your custom plugin into system." [*]

It is actually through that module loading mechanism that we get access to su, which is the primary module provided by the framework.

So, how to actually install KernelSU ?

As said before, this is a kernel based framework : there is no way around rebuilding the kernel with the proper modifications to embed the framework into it.

The resulting modified Android kernel can then be delivered as a boot sector image which needs to be flashed into the device using the flashboot tool (one of the Android SDK Platform Tools).

With the su enabled kernel, it is just a matter of logging in and calling su :

$ ./adb shell
sunfish:/ $ su
su
sunfish:/ #

Notice how the prompt changed from '$' to '#', to mark the change in user. Subtle, yet powerful.

Shortcomings, room for improvement

KernelSU is not without issues though.

For one, it is best suited for Generic Kernel Images (GKI for short).

The GKI project is a key initiative by Google to address kernel fragmentation in Android by unifying the core kernel across all devices, beginning with Android 12 and devices shipping with kernel version 5.10.

Reducing the fragmentation due to vendor specific changes in the kernel allowed both security and Android major release updates to be rolled-out in more efficient and streamlined way, thus reducing the overall fragmentation across Android releases (ie. it is now easier for hardware vendors to improve their software update support thanks to the GKI project).

Helas, the Pixel 4a shipped with Android 10 and kernel 4.14 : GKI was still in the works at the time.

As a consequence, the latest versions of KernelSU are not compatible with Android kernel 4.14, and I had to rely on the older KernelSU v0.9.5, which is not ideal because a lot of fixes, new features and improvements are not available.

This situation brings me to the second shortcoming : application developers came out with ways to detect root privileges escalation provided by KernelSU and prevent their apps to be run in such situations (again, obvious security concerns may justify such a move, at the expense of the user rights to do what he needs to with the device).

One solution to that problem is called KernelSU Next.

Simply put, this new framework improves upon the former by :

providing support for both GKI and non-GKI Android kernels,
providing a module called SUSFS which goal is to hide root escalation to userspace applications.

And these are only two of the benefits highlighted with regards to the Pixel 4a case.

Once again, I got my hands dirty and patched my kernel in a suitable manner to obtain a boot sector image to be flashed into the device ; the installation process remains the same once you are familiar with the ways of KernelSU.

Going forward, it might be interesting to provide those modified boot sector images for my Evolution X users who need root access on their phones.

For now, if you are interested in this experiment, you can download below :

my kernelSU boot image for the Pixel 4a, and
my kernelSU Next + SUSFS patches boot image for the Pixel 4a.

This is additional work on top of providing security and major release updates, so it will depend on community demand ; as is the case with community driven projects.

That is the way :-).

[*]	https://kernelsu.org/guide/what-is-kernelsu.html

Joining an awesome project, terrific community

2025-10-12T00:00:00+02:00

If you followed my recent posts, you know I have been interesting by Android custom ROMs lately.

Not only as a user, effectively modifying my main daily phone to run Android 16 (it was released six years ago and abandoned on Android 12), but also as an Android apprentice developer learning how to build and modify the system to keep targeted devices up-to-date with the latest AOSP release.

Scratching that itch, I built and publicly released multiple versions of Android for the Google Pixel 4a, 4a 5G and Pixel 5, using Evolution X (here is a summary of my latest releases).

Long story short, after supporting those devices on my spare time just for fun and learning from the community along the way for the past few months, I recently joined the project as an official maintainer.

What it means to be official maintainer

So, what does it change ?

Not much to tell the truth, but the differences are impactful.

As a maintainer for the project, I am expected to keep the source code of my devices up-to-date (as long as technically possible) and suitable to be built on its CI/CD infrastructure,
As a benefit of building on Evolution X servers, my releases will now be officially signed and can be pushed to devices as Over-The-Air updates, bypassing the need for a computer to do a manual update each time.

A huge leap in both developer and user experience obviously.

The path moving forward

So, what now ?

More of the same, basically.

My intent is to keep releasing updates as regularly as possible, and use the newly gained communication channels with other maintainers to stay informed of changes ahead of time and help fixing bugs.

Here goes hoping I'll still find some spare time to continue supporting my devices, keeping the process fun and improving by learning from the community.

Search for "Pixel 4a", "Pixel 4a 5G" or "Pixel 5" among Evolution X supported devices list to get my official releases.

It's been a long time coming

2025-09-29T00:00:00+02:00

I posted "Pixel 5, Sweet 16" a few days ago to announce the release of Android 16 by way of my custom ROM of choice, Evolution X.

It may have gone unnoticed, but there was no such release for Pixel 4a at the time.

Even though I was able to make some adaptations and build an image for the device, flashing the image and trying to boot it resulted into infinite loops of boot process (aka. boot-loop), only halted by automatic restarts.

Knowing that LineageOS sources for Android 16 (on which Evolution X is based) haven't been released yet, this kind of issue was to be expected at some point : by trying to do some adaptations ahead of time, I am inevitably facing some early barriers to make things work.

What were those issues, you may ask : some I knew from experience, and others I was introduced to. Let's go over both.

The devil I know

First was some Framework Compatibility Matrix issues : I wrote about those in an article detailing this trouble during 10.8 release.

Then was a Linux kernel compilation breakage for which I had to backport the fix. The culprit here is 'struct sched_param', a well known type in POSIX APIs exposed by the kernel for userspace applications.

Problem is this particular type is also defined by glibc, so any attempt to build some code that includes a compilation unit with that type from both glibc and the kernel will result in

error: redefinition of ‘struct sched_param’

Again, the issue is known at this point in time so I ported a work-around from the Linux kernel community to fix it.

Apart from these minor hiccups, I also faced tricky new ones.

The devil I don't

As said in introduction, the image I obtained after solving some build errors was boot-looping.

Little did I know about the importance of Security-Enhanced Linux (SELinux in short) in the Android kernel boot process before getting to this point.

SELinux is a framework in the kernel that allows enforcing access control security policies for hardware and software components on the system.

It basically says if a component is allowed to function or run on the system, and to which extent it can do so.

For instance the camera service may be allowed to run while being restricted from accessing properties from the display, which may have an impact for that service to change display calibration when taking pictures or video. Some other sensors may also not be permitted to create specific specific file types (eg. socket or fifo), thus preventing access to certain modes of operation.

Simply put, SELinux not only has an invisible impact on user experience but it can also hinder the boot process if the combination of those policies result in an incoherent state for the device to function properly.

Not having a complete picture of all services and policies that need to be set, I guess that was the case I fell into due to some major changes introduced with Android 16 ; it is a major release after all.

If you are curious about the fixes I had to apply to make it work, take a look at some of the SELinux changes in my GitHub repository. If you want to know more about SELinux, Lineage has a nice "Working with SELinux on Android" article on their blog.

Last but not least, was an ABI breakage uncovered once SELinux policies were better suited for the device at hand.

out/soong/.intermediates/vendor/google/sunfish/libsecureuisvc_jni/android_arm64_armv8-a_shared/libsecureuisvc_jni.so: error: Unresolved symbol: _ZTVN7android21SurfaceComposerClient11TransactionE
out/soong/.intermediates/vendor/google/sunfish/libsecureuisvc_jni/android_arm64_armv8-a_shared/libsecureuisvc_jni.so: note:
out/soong/.intermediates/vendor/google/sunfish/libsecureuisvc_jni/android_arm64_armv8-a_shared/libsecureuisvc_jni.so: note: Some dependencies might be changed, thus the symbol(s) above cannot be resolved.
out/soong/.intermediates/vendor/google/sunfish/libsecureuisvc_jni/android_arm64_armv8-a_shared/libsecureuisvc_jni.so: note: Please re-build the prebuilt file: "out/soong/.intermediates/vendor/google/sunfish/libsecureuisvc_jni/android_arm64_armv8-a_shared/libsecureuisvc_jni.so".

I was faced with a new compilation error while building some obscure library that was now being pulled into the system : I infer it was a dependency that was not added until this stage, due to prior roadblocks.

The library in question was part of the Wi-Fi Direct (aka. WFD) service, and it was missing some even more obscure symbol that was obviously needed now. Problem is the library was shipped as a binary module, with no source code to be found.

Luckily for me it was being loaded into another component written in C++ for which sources were readily available. The idea to work around the problem was to write a weak definition of the missing symbol, hoping that it will not result in a severe drawback at runtime.

After all, WFD service is one of the cornerstone of features like peer-to-peer wireless sharing and screen casting in Android ; here goes hoping those features will not be hindered on the Pixel 4a because of this.

Once again, you can have a look at the weak implementation for the missing symbol here. And here are interesting reads on Wi-Fi Direct protocol and some of its use in Android.

All is said and done, but it would not have been possible without some specific Android debugging tools.

Better to have it and not need it

My Pixel 4a is a finished commercial product, not an engineering sample or development board : having a kernel that is not booting in that case can be difficult to resolve.

Android comes with useful tools for this kind of situation, and two of them I happily abused was Android Debug Bridge (ADB) and logcat.

For future reference here are a useful "Android debugging crash course" and an overview of "how to take logs on Android".

ADB is a client-server application allowing the user to connect to a device and fetch/push data from/to it. In a production environment (once the phone leaves the factory) the server is disabled for obvious security reasons, but to work on a custom ROM one need to enable it to replace the stock operating system in the first place.

Logcat is the equivalent of Linux syslog, granting access to aggregated system logs with some filtering capabilities to display information related to a chosen process (eg. filtering all SELinux logs without having the noise from other processes in between).

As a consequence, to work on the all the issues described before, I built an engineering image with the debugging tools I needed for the task at hand, with ADB server running during the boot process to have an early entry point into the system.

From that point on, it was a matter of reading kernel and system logs to find some clues, with patience being a key for success :-).

Pixel 5, Sweet 16

2025-09-20T00:00:00+02:00

UPDATE 2025-11-13

Updated all Android 16 builds to Evolution X 11.4.

These are stopgap Unofficial builds to mitigate the delay due to the ongoing rework of Evolution X Official build infrastructure.

UPDATE 2025-09-27

Added links to Evolution X 11 builds, Android 16 update, for the Pixel 4a. At long last.

Third time's the charm, or so it goes.

My previous two attempts to provide an alternative Android distribution (aka "custom ROM") for the Google Pixel 4a and 4a 5G were very successful already, and I am going at it again with the Pixel 5 this time.

Is this the result of plain luck or strictly accumulated know-how ?

Maybe a bit of both, given that the Evolution X custom ROM I am adapting for these devices is relying on LineageOS, which provides a rock solid foundation for this kind of work.

Note that the Lineage project has not officially released their sources for Android 16 yet, at the time of this writing, so I had to do some preemptive hacking and debugging work to make it all run.

So, here we are again, you will find below the Evolution X 11 images for the Pixel 4a 5G and Pixel 5 based on Android 16.

And I have also built Android 15 based Evolution X for the Pixel 5 for good measure, just in case you need it ; check out my previous articles on Evolution X for the Pixel 4a and the one adding the Pixel 4a 5G to the roster if you want the previous releases for these devices.

	Pixel 4a (Sunfish)	Pixel 4a 5G (Bramble)	Pixel 5 (Redfin)
Evolution X 10.x (Android 15)	For Sunfish images, refer to previous post.	For Bramble images, or tips on how to flash multiple boot sector images, refer to previous post.	Redfin Standard image [1] Redfin 10.x boot sector image Redfin 10.x dtbo sector image Redfin 10.x vendor_boot sector image Redfin Vanilla image [2] Redfin 10.x V. boot sector image [3] Redfin 10.x V. dtbo sector image Redfin 10.x V. vendor_boot sector image
Evolution X 11.x (Android 16)	Sunfish Standard image Sunfish 11.x boot image Sunfish Vanilla image Sunfish 11.x V. boot image	Bramble Standard image Bramble 11.x boot sector image Bramble 11.x dtbo sector image Bramble 11.x vendor_boot sector image Bramble Vanilla image Bramble 11.x V. boot sector image Bramble 11.x V. dtbo sector image Bramble 11.x V. vendor_boot sector image	Redfin 11.x Standard image Redfin 11.x boot sector image Redfin 11.x dtbo sector image Redfin 11.x vendor_boot sector image Redfin 11.x Vanilla image Redfin 11.x V. boot sector image Redfin 11.x V. dtbo sector image Redfin 11.x V. vendor_boot sector image

Pixel 4a (Sunfish)

Pixel 4a 5G (Bramble)

Pixel 5 (Redfin)

Evolution X 10.x: (Android 15)

For Sunfish images, refer to previous post.

For Bramble images, or tips on how to flash multiple boot sector images, refer to previous post.

Redfin Standard image [1]

Redfin Vanilla image [2]

Evolution X 11.x: (Android 16)

Sunfish Standard image

Sunfish 11.x boot image

Sunfish Vanilla image

Sunfish 11.x V. boot image

Bramble Standard image

Bramble Vanilla image

Redfin 11.x Standard image

Redfin 11.x Vanilla image

[1]	"Standard" image includes Google Apps

[2]	"Vanilla" image does not include Google Apps

[3]	"V." stands for Vanilla for sake of consiveness

As always, feel free to peek at my GitHub for sources.

Pixel 4a 5G, a new device in our custom Android roster

2025-09-08T00:00:00+02:00

UPDATE 2025-09-08

Just updated both Evolution X 10.9 with Google Apps and Evolution X 10.9 Vanilla (version without any Google Apps) images with a build including September 2025 security patches.

ORIGINAL 2025-09-08

It was bound to happen.

Spending time keeping my trusty old Pixel 4a updated with the latest Android releases, including monthly security patches, got me hooked with the process.

I recently acquired the next device in the "Pixel A series", namely the Pixel 4a 5G, just for the fun of providing the same support to a device that is no longer maintained by Google since Android 14.

Learning with the regular 4a proved to be insightful, and building Android 15 for the Pixel 4a 5G was a more familiar process.

Changes in the filesystem partitioning result in a slightly different flashing procedure, keep reading on if you want to know how to install the build on your device, but for those who just want the files here they are:

Evolution X 10.9 with Google Apps included and its recovery images:

regular boot sector image,

regular dtbo sector image,

regular vendor_boot sector image.

Evolution X 10.9 Vanilla, without any Google Apps, and its associated recovery images:

vanilla boot sector image,

vanilla dtbo sector image,

vanilla vendor_boot sector image.

As previously mentioned, the partitioning of the storage space is slightly different this time around: we have separate sectors to flash in order to modify the boot process and allow the installation of our custom Android distribution.

We will focus on the part where we replace the bootloader with our custom recovery bootloader: for a complete tutorial on how to unlock the device and get to the point described below, check my article on how to install Evolution X on the Google Pixel 3a.

To replace the original bootloader with a custom recovery one, follow these steps:

$ ./fastboot flash boot <path_to_boot_sector_image>
Sending 'boot_b' (98304 KB)                        OKAY [  2.270s]
Writing 'boot_b'                                   OKAY [  0.562s]
Finished. Total time: 3.197s

$ ./fastboot flash dtbo <path_to_dtbo_sector_image>
Sending 'dtbo_b' (16384 KB)                        OKAY [  0.470s]
Writing 'dtbo_b'                                   OKAY [  0.216s]
Finished. Total time: 1.055s

$ ./fastboot flash vendor_boot <path_to_vendor_boot_secor_image>
Sending 'vendor_boot_b' (98304 KB)                 OKAY [  2.270s]
Writing 'vendor_boot_b'                            OKAY [  0.555s]
Finished. Total time: 3.195s

Now reboot into Recovery Mode to install the Evolution X image.

Happy daily driving :)

What's up with Evolution X 10.8

2025-08-26T00:00:00+02:00

This entry is not a change log listing new features, but rather an overview of the changes I faced while building the "August 25 security patches" release of Evolution X.

Sorry for the "somewhat click bait" title :).

This time around, updating the Pixel 4a to Evolution X 10.8 a mere two weeks after getting the sources from LineageOS, I discovered something called Framework Compatibility Matrix (FCM).

The Android Framework Compatibility Matrix (FCM) is an XML file that specifies the requirements the Android framework has for the device it runs on, defining what hardware abstraction layer (HAL) interfaces, kernel configurations, security policies, and other system components must be present and at what versions.

It is a key component of the Vendor Interface (VINTF) framework, which ensures compatibility between the Android framework and vendor implementations.

The FCM is used to enforce requirements at build time, runtime, and during Vendor Test Suite (VTS) testing.

It defines the minimum and maximum version ranges for HALs, kernel configurations, security policies (sepolicy), and other system components that the framework expects to be available on the device.

For instance, a framework compatibility matrix might require a specific version of the camera HAL or a particular kernel configuration.

This might sounds very abstract and the reason is that FCM were introduced to define the requirements the Android framework has, to conform with vendor implementations, thus ensuring compatibility across different devices and Android releases.

For further details on the topic, refer to the Vendor Interface documentation and specifically the Framework Compatibility Matrix documentation.

To get into the weeds of the subject, here is the kind of output one gets when the FCM requirements are no longer in line with the Pixel 4a device manifests and corresponding device compatibility matrices:

The following HALs in device manifest are not declared in FCM <= level 5:
  android.hardware.audio.effect@7.0::IEffectsFactory/default
  android.hardware.audio@7.0::IDevicesFactory/default
  android.hardware.boot.IBootControl/default (@1)
  android.hardware.camera.provider.ICameraProvider/internal/0 (@1)
  android.hardware.contexthub.IContextHub/default (@3)
  android.hardware.drm.IDrmFactory/clearkey (@1)
  android.hardware.drm.IDrmFactory/widevine (@1)
  android.hardware.identity.IIdentityCredentialStore/default (@4)
  android.hardware.input.processor.IInputProcessor/default (@1)
  android.hardware.memtrack.IMemtrack/default (@1)
  android.hardware.nfc.INfc/default (@1)
  android.hardware.power.IPower/default (@5)
  android.hardware.thermal.IThermal/default (@2)
  android.hardware.usb.IUsb/default (@1)
  android.hardware.vibrator.IVibrator/default (@2)
  android.hardware.wifi.IWifi/default (@2)
  android.hardware.wifi.hostapd.IHostapd/default (@2)
  android.hardware.wifi.supplicant.ISupplicant/default (@3)
  vendor.lineage.livedisplay.IPictureAdjustment/default (@1)
INCOMPATIBLE

2025-08-21 22:24:45 - check_target_files_vintf.py - INFO    : stderr: ERROR: files are incompatible: The following instances are in the device manifest but not specified in framework compatibility matrix:
    vendor.lineage.livedisplay.IPictureAdjustment/default (@1)
Suggested fix:
1. Update deprecated HALs to the latest version.
2. Check for any typos in device manifest or framework compatibility matrices with FCM version >= 5.
3. For new platform HALs, add them to any framework compatibility matrix with FCM version >= 5 where applicable.
4. For device-specific HALs, add to DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE or DEVICE_PRODUCT_COMPATIBILITY_MATRIX_FILE.: Success

[...]
RuntimeError: VINTF compatibility check failed

Note that all changes to solve these issues were done in the repo project "vendor/lineage/" within the file "config/device_framework_matrix.xml".

So I had to amend the aforementioned FCM XML file to add new requirements that were introduced in the framework when I was building Android 15 with August 2025 security patches for the Pixel 4a.

The tricky part was to get the XML syntax right, since many revisions of the compatibility matrix format were introduced alongside each AOSP release throughout the years.

Long story short, I finally came up with the new requirements written with proper syntax : you can have a look at my change to update FCM requirements introduced during Evolution X 10.8 rebase on my Github repository.

In the process, I also stumbled upon a tool that might ease the XML file generation if this occurs again, check it out:

How to generate FCM from fqnames

Android 15 on Pixel 4a with Evolution X

2025-06-25T00:00:00+02:00

UPDATE 2025-09-08

Just updated both Evolution X 10.9 with Google Apps and Evolution X 10.9 Vanilla (version without any Google Apps) images with a build including September 2025 security patches.

ORIGINAL 2025-06-25

Following the walkthrough on how to run Evolution X on the Google Pixel 3a, I have been using the Android custom rom distribution on a Samsung Galaxy S10 as my daily driver.

I got curious about the process of building it myself, and decided to take the experiment with a Pixel 4a, for which Google ended official software support in 2023 with Android 13.

Evolution X provided an alternative with a custom update to Android 14 for the device, so I picked it up from there and built an update to Android 15, with some help from the community and following the project documentation (yes, they do have useful documentation !).

Long story short, the experiment was successful and I came up with two versions of Evolution X, allowing one to update the Pixel 4a to Android 15:

Evolution X 10.9 with Google Apps included and its recovery image,
Evolution X 10.9 Vanilla, without any Google Apps, and its associated recovery image.

If you have a Pixel 4a lying around and dare to try, you can follow the guide I wrote on how to flash those images on your phone.

If you are interested about what happened behind the scenes, take a look at the sources on my github account instead:

Evolution X on the Google Pixel 3a

2024-08-24T00:00:00+02:00

My main issue with Android has always been the very short support we get from manufacturers once we buy their phones; things have been improving lately but I still own a perfectly fine Pixel 3a for which Google has stopped providing any updates since 2022.

So, I decided to install a community maintained distribution (aka "custom rom") to extend software support myself with a more up-to-date version of the Pixel 3a OS: I have chosen Evolution X for this purpose, which should allow me to run Android 14 instead of Google's last Android 12 update.

First let's download the following Evolution X Android 14 files for Pixel 3a:

custom boot recovery image,
Evolution X 14 v9.3 image,
Google Play Integrity fix APK from the project page on XDA Forum,

We will also need the Android SDK Platform Tools to connect and transfer the previous files to the device:

SDK Platform Tools for Linux,

Flashing the vendor official OS voids the device warranty (when warranty is still applicable, which is not the case here since the phone is no longer supported), and the bootloader is locked by default to prevent such practice.

To unlock the bootloader:

Enable developer options:

go to Settings > About phone > Build number, and tap it 7 times to enable "Developer mode",
Enable OEM unlocking:

in Developer options, toggle the switch next to “OEM unlocking” to enable it; also toggle the switch next to "USB debugging" to enable sending files via USB later,
Boot into Bootloader Mode:

with your phone connected to your PC via USB, boot your Pixel 3a into bootloader mode by pressing and holding the "Power" button and the "Volume down" button simultaneously,
Run fastboot commands:

extract the Android SDK Platform Tools archive previously downloaded, open a command prompt, navigate to the directory and run the fastboot command to unlock your bootloader as follows:

$ cd platform-tools/
$ sudo ./fastboot flashing unlock
OKAY [  0.089s]
Finished. Total time: 0.089s

Note that the command is run with sudo to get the rights to communicate with the device; if everything goes well you should get the OKAY output meaning we can now proceed with replacing the original bootloader with a custom recovery bootloader:

$ sudo ./fastboot flash boot ~/boot.img
Sending 'boot_b' (65536 KB)                        OKAY [  1.530s]
Writing 'boot_b'                                   OKAY [  0.342s]
Finished. Total time: 2.185s

Reboot into Recovery Mode to install the Evolution X image:

Press any "Volume" button to scroll until "Recovery Mode" is shown next to "Power" button,
Press "Power" button to select and wait for device to reboot,
In recovery mode, using the "Volume" buttons, navigate to "Factory reset" and select with "Power" button,
Navigate back and select "Apply update".

From the command prompt, sideload the image:

$ sudo ./adb sideload ~/EvolutionX-14.0-20240818-sargo-v9.3-Official.zip
serving: 'EvolutionX-14.0-20240818-sargo-v9.3-Official.zip'  (~100%)
Total xfer: 2.00x

With the transfer complete, navigate back and select "Reboot system now" to boot into your new system ; first boot will be longer than usual.

After initial setup, the familiar Pixel homescreen should show up.

Congratulations, the Google Pixel 3a is now running Android 14 !

Optional: At this point, you can connect the device to your computer, transfer the Google Play Integrity fix APK and install it from "Files" application.

Afterwards, Play Integrity API checks should pass, in case you want to use Google Pay or banking apps on your device.

Create a Steam Deck Debian rescue image

2024-08-18T00:00:00+02:00

Following the installation of Debian 12 on the Steam Deck, we are now going to backup the SD Card content into a rescue image : the idea is to be able to recover and duplicate the whole running system easily without having to re-install again if needs be.

There are at least two ways to achieve this :

using the dd tool from the command line,
relying on gnome-disk-utility GUI to create a disk image.

Using dd command line tool to create a disk image

Since I am making an image of an SD Card mounted at /dev/mmcblk0 and wish to create an image named "steamdeck-debian-repair-20240818.iso", the command line I am using for this purpose is the following:

$ sudo dd status=progress if=/dev/mmcblk0 of=./steamdeck-debian-repair-20240818.iso bs=1M
$ sync

Executing this as root with sudo allows us to read from mmcblk0 device indeed and create an iso from its content.

Conversely, restoring such an image shall be a matter of:

$ sudo dd status=progress if=./steamdeck-debian-repair-20240818.iso of=/dev/mmcblk0 bs=1M
$ sync

Using gnome-disk-utility GUI to create a disk image

As an alternative, if you are using the GNOME desktop environment, you may as well rely on gnome-disk-utility (simply called "Disks" on the desktop) to the same extent:

Choose "Create Disk Image" from the menu...

Name your image accordingly...

And wait for the process to complete.

Once you have your image file, restoring from it is as simple as double-clicking on the file to launch "Disks":

In my experience, creating a backup image of the 64GB SD Card takes around 12 minutes with both methods.

You now have the choice either way.

Running Debian on Steam Deck from SD Card

2024-08-15T00:00:00+02:00

UPDATE 2024-08-18

I recently posted about creating a rescue image of my Debian installation.

That post was driven by issues where it would no longer be possible to boot into the Linux install on the SD Card, due to the bootloader entry mysteriously disappearing.

It looks like the UEFI specs may actually be suggesting that the Debian system shall provide a FAT32 system partition for the UEFI to be able to achieve boot process related operations:

13.3 File System Format
The file system supported by the Extensible Firmware Interface is based on the FAT file system.
[...]
EFI encompasses the use of FAT32 for a system partition, and FAT12 or FAT16 for removable media.

13.3.1 System Partition
A System Partition is a partition in the conventional sense of a partition on a legacy system.
For a hard disk, a partition is a contiguous grouping of sectors on the disk where the starting
sector and size are defined by the Master Boot Record (MBR), which resides on LBA 0 (i.e., the
first sector of the hard disk) ( LBA 0 Format ), or the GUID Partition Table (GPT), which resides
on logical block 1 (the second sector of the hard disk) ( GPT overview ).

13.3.1.1 File System Format
The first block (sector) of a partition contains a data structure called the BIOS Parameter Block
(BPB) that defines the type and location of FAT file system on the drive.
[...]
The first block (sector) also contains code that will be executed as part of the boot process on a
legacy system.

That is, if I understand the UEFI Specification correctly...

As a consequence, I have since revised the partition table of my Debian installation to provide said FAT32 partition at the beginning of the SD Card drive:

As you can see above, it now shows:

148.9 MB for the UEFI FAT32 system partition,
537.9 MB for our UEFI bootloader,
20.9 GB for the root system,
1 GB for the swap,
39.9 GB for the home partition.

ORIGINAL 2024-08-15

It's been a while since I posted online, and I recently bought a Steam Deck so now might be the time to document and share what I am having fun with once again :-).

The Steam Deck is basically a handheld gaming PC running SteamOS, a dedicated Linux distribution developed by Valve.

Valve's current operating system, SteamOS version 3, is based on Arch Linux but the distribution was initially built from Debian.

It currently runs great and serves a purpose ; would it still be possible to run Debian on the Steam Deck though ?

To find out, I tried installing and running Debian 12 from the device's SD Card as a dual boot solution to avoid messing the internal SSD.

Here is my setup:

Steam Deck,
External keyboard & mouse,
External display,
USB flash drive with Debian image,
Dock to connect peripherals to the device,
64 GB SD Card installation medium.

I am not going through where to find those accessories, or even how to create a bootable Debian USB flash drive : there are plenty of resources on the internet to learn about those, let's jump right in.

To boot from the flash drive, hold Volume Down while pressing Power button on the Deck and release after you hear the chime : that should bring you to the boot menu where you can select your flash drive.

First screens of the Debian installer are trivial : language, keyboard selection and keymap.

Then comes the network interface chooser:

Here I select the ethernet interface available on the dock, as it does not need any specific driver to work during installation.

Then the hostname ;-).

Domain name is left by default.

I skipped creating a root user, choosing for the primary user to elevate his rights through sudo instead:

Now comes the tricky part: partitioning to boot Debian from SD while keeping SteamOS on the SSD.

The Steam Deck boots from UEFI, as a consequence we will also need a partition to install a compatible bootloader.

I am starting with an empty card and choosing manual partitioning:

As you can see from the overview, I have access to multiple drives:

the 64 GB SD Card I want to install Debian onto (mmcblk0),
the Deck's 256 GB internal SSD we do not want to mess with (nvme0n1),
the 2 GB flash drive I am running the Debian installer from (sda).

Select the SD Card free space to create a new partition table.

Select again to create a new partition.

The new partition shall start at the beginning of the available space.

And we want it to be a logical partition as you can only have a limited number of primary partitions.

Let's make this partition 64 MB...

...as we want to use it for the EFI compatible bootloader.

Make sure the partition is bootable ; the bootable flag should be on by default though.

After setting up the first partition, select the remaining free space and let the installer automatically partition it.

We want root, home and swap partitions to be separate to keep things simple yet modular enough.

And here we are, with our complete partitioning scheme:

65 MB for our EFI bootloader partition,
21.1 GB for the system,
1 GB for the swap,
40.3 GB for the home partition.

Confirm those changes and write this partition table to disk.

We are out of the woods, the rest is rather straightforward:

To configure the package manager, select the country of the Debian archive mirror you want to get software from.

Then the mirror itself.

A proxy if you need one.

And here I choose to provide the distribution developers with statistics about the packages I will be using on this system.

For software selection, apart from the GNOME desktop environment and the standard utilities I also want an SSH server to connect remotely to the device.

Not sure about that one, it usually messes with the way UEFI and any other operation system handles the system clock: I left it by default since the OSes will be syncing the time from the network anyway.

Here goes nothing: now is the time to reboot into Debian :-).

So far so good, our GRUB bootloader offers a sensible list of choices...

And the proof is in the pudding: here is the Debian 12 login screen, on the Steam Deck, after a successful installation process !

For future reference, I have also included below data gathered during installation:

complete hardware summary,
initial syslog,
Xorg display log file.

That's all folks !

Linux 3.18 released, contributions of mine

2014-12-14T00:00:00+01:00

Catching up on kernel news while recovering from illness, Linux 3.18 was released a week ago like clockwork. As part of this release, there are two patches of mine inside.

Those are about adding DMA support to the MMC/SD card driver of the Ben NanoNote SoC -- namely the JZ4740 SoC.

Until now, the SD card driver was operating in PIO mode: solely relying on the CPU to transfer data between the SD card and main memory. The goal of the patches is to allow the driver to rely on DMA instead in order to improve performance.

So I started by adding DMA support by taking advantage of the DMA Engine driver that was already available for JZ4740. Trying to push performance further, I then took advantage of the asynchronous request capability of the MMC framework to prepare the next DMA transfer request in parallel with the current ongoing transfer.

I posted a few benchmarks with the patch series to track performance improvements. Please refer to LKML to read them (I'm not sure the text output would be correctly formatted on this blog, and I'm being too lazy to find out):

https://lkml.org/lkml/2014/7/21/11

As you can read from my post on LKML, there is a minor improvement in average transfer time (going from 7 to 6 minutes to uncompress Fedora 16 ISO image) and CPU load. This is a good thing overall: considering the limited scope of my benchmark, the improvement might be even more noticeable while doing a bigger transfer while the CPU is under a heavier load.

Also, in hindsight, zcat was probably not a very good utility to benchmark memory transfers. Using dd may have given more relevant results and a better picture of the overall performance improvement gained by using DMA instead of CPU for memory transfers.

Anyway, here are links to the patches:

https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=7ca27a6f80a4042666a28977ff8ee3aa527c6cd4

https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=bb2f45927f8e0d1fc0633f65cc1f17a40c80bf24

And a summary of all the changes by kernelnewbies.org:

http://kernelnewbies.org/Linux_3.18

Attending LinuxCon & ELC Europe 2014

2014-10-26T00:00:00+02:00

LinuxCon Europe and Embedded Linux Conference Europe (ELCE) 2014 took place in Dusseldorf earlier this month, from 13th to 15th of October.

I was granted a scholarship from the Linux Foundation to attend the event for the first time this year. This was unexpected I must say, leading to last minute preparations in order to go to Dusseldorf.

This being my first time attending the event, I didn't know what to expect apart from the experience I got by going to other FOSS conferences like FOSDEM and GUADEC.

What really stood out from my point of view was the logistics around the event, at least the visible part of it. Once on site, at the Congress Center Düsseldorf (CCD) where it happened, everything seemed to have been taken care of. From the people holding the registration/reception desk all day long, to the waitresses and waiters serving food and drinks all day long (including proper breakfast and lunch!), to the people recording the talks and taking pictures in every room again all day long, the organisation was really top notch.

Don't get me wrong now, the other events I experienced in the past certainly required a lot of organising too, and they were just as much enjoyable. In fact, it would have been difficult for me to attend LinuxCon & ELCE without the scholarship given the hefty registration fee required.

Knowing that does not make the care and effort put into the preparations of the event less commendable. Kudos to the Linux Foundation and to all the people who were involved into the "behind the scenes" making of these conferences !

My LinuxCon & ELCE name tag.

As far as the talks went, it was a thrill seeing some key FOSS contributors on stage and actually meeting a few of them in person.

I got the opportunity to meet the team behind the MIPS Creator CI20 project, and it was really energising discussing with them. I also bumped into a few friends, some of them long time attendees of this kind of events, and we hopped on the occasion to share a few beers and good laughs together.

In the end LinuxCon and ELCE were an amazing experience, adding to the already great benefit of being part of the free and open-source software community.

Last but not least, I must take the time here to thank Marina Zhurakhinskaya and Karen Sandler for talking me into going to LinuxCon in the first place; it probably wouldn't have happened without meeting both of them :-).

Let's make sure we all meet soon again !

Linux 3.17 patches status

2014-10-24T00:00:00+02:00

Here is a late post on Linux 3.17 which was pushed out a few weeks ago. I planned to post a short status of my contributions, as usual, but then I was busy making preparations to go to LinuxCon and ELC Europe -- more on that later.

Anyway, this one will be quick: I got a couple of fixes into 3.17 for the JZ4740 MUSB driver.

Thing is, the MUSB driver is using the generic NOP transceiver as its PHY provider, and the transceiver was recently renamed from usb_nop_xceiv to usb_phy_generic. The change induced a kernel panic due to an unhandled kernel unaligned access while trying to dereference musb->xceiv->io_ops in the musb_init_controller() function in drivers/usb/musb/musb_core.c.

My patches were aimed at fixing that issue, by declaring the transceiver under its new name in the JZ4740 platform data and also registering it in the MUSB driver to make sure the driver prints an error message if the transceiver cannot be registered for some reason.

Links to the patches:

http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=c7fb97d65aece5b03a9209ea5a9670e952c62f34

http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=3d75bd3d0af16c7b8dda13440202fa24769d8e17

As always, the ever useful changelog published by kernelnewbies.org:

http://kernelnewbies.org/Linux_3.17

Til next release.

MIPS Creator CI20

2014-08-22T00:00:00+02:00

I'm a happy hacker right now. Just received a MIPS Creator CI20 board in the mailbox a couple of days ago, thanks to Imagination Technologies.

Attention to detail: notice the many power plug adaptors for various countries.

This is a small sized development board powered by an Ingenic JZ4780 SoC with a dual core MIPS processor clocked at 1.2GHz. It comes with:

1GB of RAM + 8GB of NAND preloaded with Debian 7 "Wheezy",
1 x PowerVR SGX540 GPU,
1 x SD Card port,
2 x USB ports,
1 x Infrared receiver,
Audio Jack I/O + HDMI output,
Ethernet + WiFi + Bluetooth connectivity,
Expansion headers with (lo and behold) UART + JTAG support!

Full specs can be found at http://www.elinux.org/CI20_Tech_Stuff.

MIPS architectures seem to have a lesser mindshare compared to other better known ones, even though MIPS processors are widespread in the embedded space. They are usually found in computer network appliances (e.g. routers and residential gateways), digital TV appliances (e.g. set-top boxes) and video game consoles, to name a few.

The MIPS Creator CI20 is a project from Imagination Technologies to foster development around their architecture and raise awareness of the products built upon it. The team behind the project released quite a lot of documentation and source code in order to reach that goal, making it hacker friendly.

Find more about it at http://www.elinux.org/MIPS_Creator_CI20.

Does the Ingenic JZ4780 SoC rings a bell ? If you've been following this blog, then it certainly does. It's the latest generation of the same family of SoCs that powers the Ben NanoNote and the GCW-Zero -- devices I have been writing about here.

Kudos to Graham Whaley and his whole team at ImgTec for building the CI20 ! Let's see what we can squeeze out of it ;-).

Linux 3.16 released: patch inside

2014-08-05T00:00:00+02:00

A new kernel release, and with it comes another patch of mine.

A single patch this time, but this one has been in the works for a while now. It's about providing documentation for the MUSB driver I wrote for the Ingenic JZ4740 SoC which was included into Linux kernel 3.14.

I wrote the documentation back in February 2014 as an attempt to log all the things I learned while writing an MUSB driver for the Ben NanoNote. The end result was more detailed than I initially planned, to my own surprise, thereby I submitted it to be included in the Linux kernel upstream -- that move was a trial balloon, truth to be told.

Then came a series of unexpected events that may explain the lengthy review process that ensued; the main one being a change of maintainer for the kernel documentation. Around that time Rob Landley stepped down as maintainer of the Linux kernel documentation and handed the keys back to Randy Dunlap. As a matter of fact, all pending patches needed to be resent:

http://www.spinics.net/lists/linux-doc/msg20722.html

The sheer size of the documentation I wrote and the Linux kernel review and release process also contributed to the time it took for the patch to be merged into Linux kernel 3.16 -- the rest is history, logged into the Linux Kernel Mailing List archive ;-).

Anyway, here is the documentation as I first published it on this blog:

http://apelete.missene.com/writing-an-musb-glue-layer.html

And the version compiled from the Linux kernel source tree, readable online:

https://www.kernel.org/doc/htmldocs/writing_musb_glue_layer/index.html

For the curious mind, a link to the patch in the kernel source tree:

http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=60b6dbeffb8c253d1f80527b28611e5e236dec51

Let's not forget the detailed changelog for Linux kernel 3.16, courtesy of kernelnewbies.org:

http://kernelnewbies.org/Linux_3.16

Stay tuned for more !

Going to GUADEC 2014

2014-07-31T00:00:00+02:00

The main part of the GNOME Users And Developers European Conference (GUADEC) -- which took place in Strasbourg, France, this year, actually just ended.

GUADEC consists of two parts. The core days are when talks, keynote presentations as well as the GNOME Foundation Annual General Meeting happen. The "Birds of a Feather" (BoFs), as in saying "birds of a feather flock together", are working discussions about a specific topic of interest in a group of people who share that interest.

So the core days ended on July 29th. I have been a GNOME user for the past twelve years, using the Debian distribution for most of that time, but this was the first time I attended the event.

Just like FOSDEM I attended earlier this year, I had a blast going to GUADEC.

Meeting the people making GNOME was an energising experience. The community is a very welcoming and enthusiastic one. From the organisers of the event, to the users, the developers and all the people who manage some aspect of the community, there was a lot of dynamism all over the place. I had many insightful conversations with the folks there and a lot of good laughs too :-).

Colourful GUADEC group shot. Picture by The GNOME Project, licensed under CC-BY-3.0.

I think I really enjoy going to Free Software events in the end. It turns out to be where the real fun lies: these moments where we share something together. Most of the time it's the software itself -- at least from a programmer point of view, but then from time to time it's about the galaxy of things that happen around the software and that is just as much fun.

Kudos to the community for holding such a great event for so long now -- according to Wikipedia it dates back to 2000, I hope it will continue to take place for the years to come.

Fixing Ben NanoNote serial line

2014-05-04T00:00:00+02:00

The serial line soldered to my Ben NanoNote for debugging purpose started to behave erratically. I was getting frequent disconnects while in minicom or gdb. It happened before, but last week it got out of hand and I couldn't get anything done by moving the wires a bit like I used to.

It was time to fix the rush job I did when I first soldered the wires to get a serial line output. At that time, two years ago, I had bought a (very) cheap soldering kit off ebay to get the job done -- painful experience, I still remember.

Since I recently upgraded my soldering tools, this was an opportunity to wield the soldering iron again o/.

First, I peeled off the adhesive tape that was holding the wires in place in the Ben battery compartment to inspect the joints. The problem exposed itself: the TX wire joint came off so easily with the adhesive tape that I believe it was broken for some time already.

Anyway, let's clean the pad with some alcohol, apply some flux on it and see how it goes.

This time I put a drop of solder only on the tip of the wire to see if it is easier than working with a tinned pad.

Took me five minutes to set up everything and hey, it works ! Notice how the TXD joint is much more clean and regular than the other two.

Connection to the serial line seems to be reliable now, didn't experienced any disconnect while working with the Ben, yay !

"A bad workman blames his tools" they say, but let's be honest here: to do good work, one must first have good tools ;-).

Linux 3.14 out, me contributions inside

2014-04-06T00:00:00+02:00

Last edit on 2014-04-09: added details on the whatabouts.

Linus Torvalds released version 3.14 of the Linux kernel last week.

Anything special this time around ? Well, first and foremost, I managed to get a few patches inside \o/ (<-- hacker joy).

Being part of the Qi-Hardware community, I worked on a USB device driver for the Ben NanoNote. We were initially relying on an out-of-tree device driver written by Ingenic for the USB device controller of its JZ4740 SoC. In order to provide full upstream support for the Ben NanoNote in the Linux kernel, I then wrote an upstream compliant MUSB device driver which is feature-wise on par with the initial one.

My first contribution to the Linux kernel landed in version 3.13 in fact. It was a small fix for the MUSB core, paving the way for the following patches I worked on.

In 3.14 it was all about adding support for the Ingenic JZ4740 USB device controller through an MUSB device driver. Had to learn quite a bit about the USB protocol and the Linux kernel internals on my spare time, but it was worth the time and the effort -- let's be honest here: I had a blast working on it late into the nights.

Anyway, here are:

the aforementioned patches on kernel.org: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/log/?qt=author&q=apelete,
and a good summary of all the changes in Linux 3.14 -- it's a community effort after all :-): http://kernelnewbies.org/Linux_3.14.

Let's try to keep it up, and see what contributions land in the next kernel releases ;-).

OpenEmbedded Coverage At FOSDEM 2014

2014-03-02T00:00:00+01:00

FOSDEM 2014 took place a month ago in Brussels, Belgium, and the event was once again a success, with over 5000 visitors attending during the weekend. This year I was lucky enough to help the OpenEmbedded guys holding a booth during the event.

I started contributing to OpenEmbedded while playing with the Ben Nanonote, and I'm trying to keep up with new devices I lay my hands on. I naturally went to the OpenEmbedded booth during FOSDEM, hoping to see shiny new toys and say hello to the folks there. Didn't put much thought into it before coming, but it turned out that having one more guy help with the boot allowed the others to attend some talks. We took turns during Sunday.

We had the visit of Ken Fallon who was doing a coverage of FOSDEM for Hacker Public Radio. Listen and watch the whole OpenEmbedded coverage on Hacker Public Radio.

Paul Eggleton & me at FOSDEM 2014. Picture by Hacker Public Radio, licensed under CC-BY-SA 3.0.

It was an interesting experience, welcoming passersby and talking about devices and the OpenEmbedded build system powering them -- people seemed more interested by the devices by the way, having more to showcase might help spreading the word.

I brought my Ben Nanonote to showcase on the stand, and felt psyched that people were amazed by the tiny-ness of the Ben -- "cute" was the word most of them used to describe it. Beth Flanagan, release engineer at Yocto Project, even took a picture of the Ben sitting beside her 17inch-ish laptop, saying that the discrepancy was "awesome" :-).

Thanks to the OpenEmbedded community for holding the booth for a few years now. They surely are a friendly bunch, welcoming and nice to chat with.

Let's hope we meet again next year.

Serial Console Output On GCW-Zero

2014-03-02T00:00:00+01:00

I recently bought a GCW-Zero to play with in my spare time.

My interest being in hardware related issues, I will be needing a serial console output to debug low level code. It turns out this hardware feature is missing on the GCW-Zero out of the box, as it's often the case with embedded products. How come even a product made by geeks for geeks is missing this ? Embedded devices should have serial console output pins soldered on their PCB out of factory, me think.

Anyway, game-play level 0 comes down to soldering a serial console output to the board.

Materials, techniques & tools

For this purpose, here is a list of what you will need:

GCW-Zero unit (obviously),
Flat screwdriver #1.5,
Philips screwdriver #00,
Soldering station,
Conical type of soldering tip 0.4mm diameter,
Soldering wire 0.5mm diameter,
Wire-wrapping wire 30AWG,
3.3V USB to serial RS232 converter,
4 Crocodile clips (optional),
4 Dupont wire cables with pin headers (optional).

The GCW-Zero PCB is crowded with teeny components, thus the tiny diameter of materials and tools above. The screwdrivers will help open the case, sealed by 4 small screws on the back.

Regarding the soldering tip, a 0.8mm diameter one might be workable if you're skilled enough -- I used a 0.4mm tip, better be safe than sorry. Have a look at my SMT soldering tools post for further details.

Connecting the serial output to your computer is what the USB to serial converter is for. I got a cheap one off eBay:

As shown on the picture above, this converter has a 5 pins connector:

RX for receiving data,
TX for transmitting data,
GND for ground line,
3.3V for powering the serial output,
5V for powering the serial output.

Having both 3.3V and 5V pins will allow you to choose the voltage depending on your needs, should you ever plan to reuse the converter for another device.

Wrapping up the materials and tools list are the crocodile clips.

These ones are optional if you choose to solder the USB to serial converter to the GCW-Zero. I use the clips to avoid soldering the converter: result is messier due to more cables, but clips are easily detached to allow me to tuck wires away and keep the device portable.

Going with the crocodile clips, I also use Dupont wire cables and pin headers to space out the USB converter pins which are too close to be grabbed individually with the clips.

A good place to start learning about soldering techniques is the EEVblog on Youtube. David L. Jones shot a three parts soldering tutorial there:

Not being an expert solderer myself, I cannot tell much more on the subject than you'll learn watching those videos. And practicing.

Tinning the wire-wrapping wires and the pads on the PCB is important though. Let's cut to the chase.

Down the rabbit hole

On the back of the device are four cylindrical rubber pads you need to pull out to reveal the screws underneath -- using the flat screwdriver should help.

After removing the screws with the Philips screwdriver, gently detach the black back cover from the case to pry it open -- you can use the flat screwdriver by inserting the blade alongside the case; I just used my fingernails.

Be careful with the shoulder buttons and be aware that the battery is glued onto the inside of the back cover (on its right side) while being soldered to the PCB by two thin wires: you probably don't want to break these, unless you're ok with fixing it later.

There you have it, the GCW-Zero PCB in its full glory. Notice the black back cover on the right side of the picture: I didn't completely remove the back cover due to the battery being soldered to the board as mentioned earlier.

Looking closer, you can see 4 test points below the Ingenic JZ4770 SoC: RX, TX, GND and 3.3v. That's where you'll need to solder the wires to get a serial output.

You must first tin the test points by dropping a small amount of solder onto them.

Strip away the tip of the insulation of your wire-wrapping wire, and slightly coat the strand with solder too.

Having tinned both the pads on the board and the wires, you should now be ready to solder the wires to each of the test points. It's sometimes recommended to slightly tin the tip of the soldering iron to help conduct heat to the components, which I did by the way, but I'm not sure if that is advisable here, due to the small pads size.

I used a little too much solder during the process indeed, resulting in bigger solder joints than needed as you can see above.

Watch out for the green wire which is way too much close to that capacitor: a little push and it will short RX, making the problem hard to find out.

I also had a hard time soldering the GND test point. Despite many tries I couldn't get the solder to stick to the pad, and having less space to work with due to the other test points around didn't help either -- maybe starting with TX and GND and then soldering RX and 3.3v would have made it easier.

Since GND is used for ground connection anyway, I ultimately resorted to soldering it to the large pad next to the GCW-Zero logo.

Too much solder on this joint too, and I'm missing a small wire cutter to cut that strand off.

Big picture looks good. Not exactly pretty but good enough will do.

Don't know if this is a well spread practice but, as you've already noticed, I used the following wire colour code:

White for TX,
Green for RX,
Black for GND,
Red for Power (3.3v).

Cleaning everything up:

To hold everything in place and tidy up a bit, I glued the wires ontop of the MicroSD card holder, removed the speaker grill on the bottom left -- gently pushed it inward from the outside, it came off easily -- and passed the wires through.

Looking at the final contraption, with the wires attached to the USB converter using the crocodile clips, and extended with pin headers and Dupont cables.

Notice two things in the picture above:

RX and TX wires are respectively attached to TX and RX USB converter pins,
It still boots ;-).

Serial console software wonderland

With the GCW-Zero now enabled with a serial output, hook it up to a computer running your favourite serial console software:

Hocus pocus. Initially on the 3.5" screen, Linux boot process is now displayed on a 23" screen here through serial console output.

Software configuration is as follow:

57600 Bits/s baud rate,
8 bits data, No parity, 1 stop bit (8N1),
No hardware flow control,
No software flow control.

Enjoy the beauty of having the terminal at the end of the boot process at your fingertips.

Level 0 complete. Happy hacking :-).

SMT Soldering Tools

2014-02-23T00:00:00+01:00

Last edit on 2014-03-02: added a glue gun section.

A year ago, I had to solder a serial console output to the Ben Nanonote in order to hack its Linux kernel.

Went the cheap way back then, and bought a soldering kit off eBay that got the job done, albeit painfully. I remember the guys at Qi-Hardware making fun of me, for it took me ages to solder 3 wires on the device: "Were you using candles to melt the tin ?" :-).

I'm now planning to hack the GCW Zero, and thought it may be time to invest in proper soldering tools for surface-mount technology (SMT). For the record, here is a breakdown of the gear I will be using from now on.

Soldering station

Out is the cheapo 30W soldering iron, welcome the Xytronic LF-389D soldering station.

It's affordable, quite small and feels sturdy.

Having more power (it's a 60W unit) means it can heat up quicker, recover from a heat loss more rapidly, maintain higher temperatures and heat larger areas. And the iron temperature can be set as needed.

Bought it from Elfa Distrelec since I needed a European plug and 220-240V power supply.

Additional iron tips

SMT means small electronic components to work with. Along the soldering station, I also bought 2 additional soldering tips.

From left to right:

Soldering tip Chisel shaped 1.2mm (ref. XYB06),
Soldering tip Conical 0.4mm (ref. XYB03),
Soldering tip Conical 0.8mm (ref. XYB01, sold with Xytronic LF-389D).

Soldering wire

Lo and behold, all solder formulae are not made equal either.

This one is a manufactured by Stannol and has an Sn62Pb36Ag2 chemical formula, which reads 62% Sn, 36% Pb and 2% Ag.

Having lead in the solder means a lower melting temperature to work at, decreasing the risk of damaging components. This specific formula is designed by the manufacturer to be used with surface-mount devices (SMD), so it seems to be a perfect match for SMT work. Regarding health and RoHS directive in the European Union, this should be ok since the solder will be used in small amounts for personal hardware modifications, nothing industrial or to be sold (in which case it's recommended to use lead-free solder).

Thickness of the solder wire is another important parameter. For SMT, thin (< 0.7mm) is preferable since it makes it easier to drop small amounts of solder at once. 250g of 0.5mm solder wire should be aplenty.

Bought it from pkelektronik.com, I couldn't find it elsewhere.

Flux

"And don't forget the flux: it's the SMT-solderer's best friend" I was told :-).

In order of convenience: marker pen > ballpoint pen > syringe > paste > powder. Of course, this also depends on what you're working on.

Flux is an acid that helps removing oxides and reducing the surface tension of the tin in the solder (the Sn component), preventing it to form little balls that do not stick to the metal you're working on.

There is 3 basic types of flux: RA/RMA, water-soluble and no-clean:

Rosin Activated (RA) is the most vigorous type, but it's very sticky and a pain to remove from PCB (and it must be removed since acid attacks metals). Rosin Midly Activated (RMA) is less strong than RA but still in the same ballpark,
Water-soluble means "hot demineralized water under high pressure". Not quite as easy to get rid of at it may sound, but it's feasible. Use a cheap ultrasonic cleaner for that,
No-clean promises that you don't need to clean up but you should be careful with such statements. It's the weakest of the three though.

When it comes to flux formulae (yeah, flux is a field of its own), better use F-SW33 or F-SW34 types (better the latter). Stay away from all F-SW1x and F-SW2x and avoid F-SW31/32 Rosin flux if possible. This does not tell all the truth about flux though: you should get a non-activated no-clean no-rosin flux, but it still needs explicit classification "for SMT" by manufacturer. Trial and error, and collecting different types of flux for different purposes seems the only way to go here.

Stannol X32-10i is an F-SW33 no-clean type, but I will be using alcohol to clean the PCB after I'm done.

Wire-wrapping wire

Not much to say about that one.

Thinness is the key factor here, so I went for 30AWG Kynar wires. Also bought different colours to make it easier to tell which is connected to what.

Bought it from eBay (love that place).

Glue gun

A useful, affordable tool for finishing touches.

Not directly related to soldering, using a glue gun can be useful to glue wires in place once the job is done. Nothing moves beyond the glue point, preventing wires and joints from being stressed.

Many thanks to Werner Almesberger and Joerg Reisenweber for the invaluable insight and the funny talk.

Writing An MUSB Glue Layer

2014-02-09T00:00:00+01:00

Last edit on 2014-06-29: I submitted this documentation upstream and it has been accepted into Linux kernel 3.16-rc1.

You can read it from the Linux kernel source at https://www.kernel.org/doc/htmldocs/writing_musb_glue_layer/index.html.

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this documentation; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

For more details see the file COPYING in the Linux kernel source tree.

Introduction
Linux MUSB Basics
Handling IRQs
Device Platform Data
Device Quirks
Conclusion
Acknowledgements
Resources

Chapter 1 - Introduction

The Linux MUSB subsystem is part of the larger Linux USB subsystem. It provides support for embedded USB Device Controllers (UDC) that do not use Universal Host Controller Interface (UHCI) or Open Host Controller Interface (OHCI).

Instead, these embedded UDC rely on the USB On-the-Go (OTG) specification which they implement at least partially. The silicon reference design used in most cases is the Multipoint USB Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor Graphics Inventra™ design.

As a self-taught exercise I have written an MUSB glue layer for the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the kernel source tree. This layer can be found at drivers/usb/musb/jz4740.c. In this documentation I will walk through the basics of the jz4740.c glue layer, explaining the different pieces and what needs to be done in order to write your own device glue layer.

Chapter 2 - Linux MUSB Basics

To get started on the topic, please read USB On-the-Go Basics (see Resources) which provides an introduction of USB OTG operation at the hardware level. A couple of wiki pages by Texas Instruments and Analog Devices also provide an overview of the Linux kernel MUSB configuration, albeit focused on some specific devices provided by these companies. Finally, getting acquainted with the USB specification at USB home page may come in handy, with practical instance provided through the Writing USB Device Drivers documentation (again, see Resources).

Linux USB stack is a layered architecture in which the MUSB controller hardware sits at the lowest. The MUSB controller driver abstract the MUSB controller hardware to the Linux USB stack.

    ------------------------
    |                      | <------- drivers/usb/gadget
    | Linux USB Core Stack | <------- drivers/usb/host
    |                      | <------- drivers/usb/core
    ------------------------
               ⬍
   --------------------------
   |                        | <------ drivers/usb/musb/musb_gadget.c
   | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
   |                        | <------ drivers/usb/musb/musb_core.c
   --------------------------
               ⬍
---------------------------------
| MUSB Platform Specific Driver |
|                               | <-- drivers/usb/musb/jz4740.c
|       aka "Glue Layer"        |
---------------------------------
               ⬍
---------------------------------
|   MUSB Controller Hardware    |
---------------------------------

As outlined above, the glue layer is actually the platform specific code sitting in between the controller driver and the controller hardware.

Just like a Linux USB driver needs to register itself with the Linux USB subsystem, the MUSB glue layer needs first to register itself with the MUSB controller driver. This will allow the controller driver to know about which device the glue layer supports and which functions to call when a supported device is detected or released; remember we are talking about an embedded controller chip here, so no insertion or removal at run-time.

All of this information is passed to the MUSB controller driver through a platform_driver structure defined in the glue layer as:

static struct platform_driver jz4740_driver = {
        .probe          = jz4740_probe,
        .remove         = jz4740_remove,
        .driver         = {
                .name   = "musb-jz4740",
        },
};

The probe and remove function pointers are called when a matching device is detected and, respectively, released. The name string describes the device supported by this glue layer. In the current case it matches a platform_device structure declared in arch/mips/jz4740/platform.c. Note that we are not using device tree bindings here.

In order to register itself to the controller driver, the glue layer goes through a few steps, basically allocating the controller hardware resources and initialising a couple of circuits. To do so, it needs to keep track of the information used throughout these steps. This is done by defining a private jz4740_glue structure:

struct jz4740_glue {
        struct device           *dev;
        struct platform_device  *musb;
        struct clk              *clk;
};

The dev and musb members are both device structure variables. The first one holds generic information about the device, since it's the basic device structure, and the latter holds information more closely related to the subsystem the device is registered to. The clk variable keeps information related to the device clock operation.

Let's go through the steps of the probe function that leads the glue layer to register itself to the controller driver.

N.B.: For the sake of readability each function will be split in logical parts, each part being shown as if it was independent from the others.

static int jz4740_probe(struct platform_device *pdev)
{
        struct platform_device          *musb;
        struct jz4740_glue              *glue;
        struct clk                      *clk;
        int                             ret;

        glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
        if (!glue)
                return -ENOMEM;

        musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
        if (!musb) {
                dev_err(&pdev->dev, "failed to allocate musb device\n");
                return -ENOMEM;
        }

        clk = devm_clk_get(&pdev->dev, "udc");
        if (IS_ERR(clk)) {
                dev_err(&pdev->dev, "failed to get clock\n");
                ret = PTR_ERR(clk);
                goto err_platform_device_put;
        }

        ret = clk_prepare_enable(clk);
        if (ret) {
                dev_err(&pdev->dev, "failed to enable clock\n");
                goto err_platform_device_put;
        }

        musb->dev.parent                = &pdev->dev;

        glue->dev                       = &pdev->dev;
        glue->musb                      = musb;
        glue->clk                       = clk;

        return 0;

err_platform_device_put:
        platform_device_put(musb);
        return ret;
}

The first few lines of the probe function allocate and assign the glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows the allocation process to sleep and wait for memory, thus being usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line 12) allows automatic allocation and management of device IDs in order to avoid device namespace collisions with explicit IDs. With devm_clk_get() (line 18) the glue layer allocates the clock -- the devm_ prefix indicates that clk_get() is managed: it automatically frees the allocated clock resource data when the device is released -- and enable it.

Then comes the registration steps:

static int jz4740_probe(struct platform_device *pdev)
{
        struct musb_hdrc_platform_data  *pdata = &jz4740_musb_platform_data;

        pdata->platform_ops             = &jz4740_musb_ops;

        platform_set_drvdata(pdev, glue);

        ret = platform_device_add_resources(musb, pdev->resource,
                                            pdev->num_resources);
        if (ret) {
                dev_err(&pdev->dev, "failed to add resources\n");
                goto err_clk_disable;
        }

        ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
        if (ret) {
                dev_err(&pdev->dev, "failed to add platform_data\n");
                goto err_clk_disable;
        }

        return 0;

err_clk_disable:
        clk_disable_unprepare(clk);
err_platform_device_put:
        platform_device_put(musb);
        return ret;
}

The first step is to pass the device data privately held by the glue layer on to the controller driver through platform_set_drvdata() (line 7). Next is passing on the device resources information, also privately held at that point, through platform_device_add_resources() (line 9).

Finally comes passing on the platform specific data to the controller driver (line 16). Platform data will be discussed in Chapter 4, but here we are looking at the platform_ops function pointer (line 5) in musb_hdrc_platform_data structure (line 3). This function pointer allows the MUSB controller driver to know which function to call for device operation:

static const struct musb_platform_ops jz4740_musb_ops = {
        .init           = jz4740_musb_init,
        .exit           = jz4740_musb_exit,
};

Here we have the minimal case where only init and exit functions are called by the controller driver when needed. Fact is the JZ4740 MUSB controller is a basic controller, lacking some features found in other controllers, otherwise we may also have pointers to a few other functions like a power management function or a function to switch between OTG and non-OTG modes, for instance.

At that point of the registration process, the controller driver actually calls the init function:

static int jz4740_musb_init(struct musb *musb)
{
        musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
        if (!musb->xceiv) {
                pr_err("HS UDC: no transceiver configured\n");
                return -ENODEV;
        }

        /* Silicon does not implement ConfigData register.
         * Set dyn_fifo to avoid reading EP config from hardware.
         */
        musb->dyn_fifo = true;

        musb->isr = jz4740_musb_interrupt;

        return 0;
}

The goal of jz4740_musb_init() is to get hold of the transceiver driver data of the MUSB controller hardware and pass it on to the MUSB controller driver, as usual. The transceiver is the circuitry inside the controller hardware responsible for sending/receiving the USB data. Since it is an implementation of the physical layer of the OSI model, the transceiver is also referred to as PHY.

Getting hold of the MUSB PHY driver data is done with usb_get_phy() which returns a pointer to the structure containing the driver instance data. The next couple of instructions (line 12 and 14) are used as a quirk and to setup IRQ handling respectively. Quirks and IRQ handling will be discussed later in Chapter 5 and Chapter 3.

static int jz4740_musb_exit(struct musb *musb)
{
        usb_put_phy(musb->xceiv);

        return 0;
}

Acting as the counterpart of init, the exit function releases the MUSB PHY driver when the controller hardware itself is about to be released.

Again, note that init and exit are fairly simple in this case due to the basic set of features of the JZ4740 controller hardware. When writing an musb glue layer for a more complex controller hardware, you might need to take care of more processing in those two functions.

Returning from the init function, the MUSB controller driver jumps back into the probe function:

static int jz4740_probe(struct platform_device *pdev)
{
        ret = platform_device_add(musb);
        if (ret) {
                dev_err(&pdev->dev, "failed to register musb device\n");
                goto err_clk_disable;
        }

        return 0;

err_clk_disable:
        clk_disable_unprepare(clk);
err_platform_device_put:
        platform_device_put(musb);
        return ret;
}

This is the last part of the device registration process where the glue layer adds the controller hardware device to Linux kernel device hierarchy: at this stage, all known information about the device is passed on to the Linux USB core stack.

static int jz4740_remove(struct platform_device *pdev)
{
        struct jz4740_glue      *glue = platform_get_drvdata(pdev);

        platform_device_unregister(glue->musb);
        clk_disable_unprepare(glue->clk);

        return 0;
}

Acting as the counterpart of probe, the remove function unregister the MUSB controller hardware (line 5) and disable the clock (line 6), allowing it to be gated.

Chapter 3 - Handling IRQs

Additionally to the MUSB controller hardware basic setup and registration, the glue layer is also responsible for handling the IRQs:

static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
{
        unsigned long   flags;
        irqreturn_t     retval = IRQ_NONE;
        struct musb     *musb = __hci;

        spin_lock_irqsave(&musb->lock, flags);

        musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
        musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
        musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);

        /*
         * The controller is gadget only, the state of the host mode IRQ bits is
         * undefined. Mask them to make sure that the musb driver core will
         * never see them set
         */
        musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
            MUSB_INTR_RESET | MUSB_INTR_SOF;

        if (musb->int_usb || musb->int_tx || musb->int_rx)
                retval = musb_interrupt(musb);

        spin_unlock_irqrestore(&musb->lock, flags);

        return retval;
}

Here the glue layer mostly has to read the relevant hardware registers and pass their values on to the controller driver which will handle the actual event that triggered the IRQ.

The interrupt handler critical section is protected by the spin_lock_irqsave() and counterpart spin_unlock_irqrestore() functions (line 7 and 24 respectively), which prevent the interrupt handler code to be run by two different threads at the same time.

Then the relevant interrupt registers are read (line 9 to 11):

MUSB_INTRUSB: indicates which USB interrupts are currently active,
MUSB_INTRTX: indicates which of the interrupts for TX endpoints are currently active,
MUSB_INTRRX: indicates which of the interrupts for TX endpoints are currently active.

Note that musb_readb() is used to read 8-bit registers at most, while musb_readw() allows us to read at most 16-bit registers. There are other functions that can be used depending on the size of your device registers. See musb_io.h for more information.

Instruction on line 18 is another quirk specific to the JZ4740 USB device controller, which will be discussed later in Chapter 5.

The glue layer still needs to register the IRQ handler though. Remember the instruction on line 14 of the init function:

static int jz4740_musb_init(struct musb *musb)
{
        musb->isr = jz4740_musb_interrupt;

        return 0;
}

This instruction sets a pointer to the glue layer IRQ handler function, in order for the controller hardware to call the handler back when an IRQ comes from the controller hardware. The interrupt handler is now implemented and registered.

Chapter 4 - Device Platform Data

In order to write an MUSB glue layer, you need to have some data describing the hardware capabilities of your controller hardware, which is called the platform data.

Platform data is specific to your hardware, though it may cover a broad range of devices, and is generally found somewhere in the arch/ directory, depending on your device architecture.

For instance, platform data for the JZ4740 SoC is found in arch/mips/jz4740/platform.c. In the platform.c file each device of the JZ4740 SoC is described through a set of structures.

Here is the part of arch/mips/jz4740/platform.c that covers the USB Device Controller (UDC):

/* USB Device Controller */
struct platform_device jz4740_udc_xceiv_device = {
        .name = "usb_phy_gen_xceiv",
        .id   = 0,
};

static struct resource jz4740_udc_resources[] = {
        [0] = {
                .start = JZ4740_UDC_BASE_ADDR,
                .end   = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
                .flags = IORESOURCE_MEM,
        },
        [1] = {
                .start = JZ4740_IRQ_UDC,
                .end   = JZ4740_IRQ_UDC,
                .flags = IORESOURCE_IRQ,
                .name  = "mc",
        },
};

struct platform_device jz4740_udc_device = {
        .name = "musb-jz4740",
        .id   = -1,
        .dev  = {
                .dma_mask          = &jz4740_udc_device.dev.coherent_dma_mask,
                .coherent_dma_mask = DMA_BIT_MASK(32),
        },
        .num_resources = ARRAY_SIZE(jz4740_udc_resources),
        .resource      = jz4740_udc_resources,
};

The jz4740_udc_xceiv_device platform device structure (line 2) describes the UDC transceiver with a name and id number.

At the time of this writing, note that "usb_phy_gen_xceiv" is the specific name to be used for all transceivers that are either built-in with reference USB IP or autonomous and doesn't require any PHY programming. You will need to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make use of the corresponding transceiver driver. The id field could be set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to PLATFORM_DEVID_AUTO) or start with 0 for the first device of this kind if we want a specific id number.

The jz4740_udc_resources resource structure (line 7) defines the UDC registers base addresses.

The first array (line 9 to 11) defines the UDC registers base memory addresses: start points to the first register memory address, end points to the last register memory address and the flags member defines the type of resource we are dealing with. So IORESOURCE_MEM is used to define the registers memory addresses. The second array (line 14 to 17) defines the UDC IRQ registers addresses. Since there is only one IRQ register available for the JZ4740 UDC, start and end point at the same address. The IORESOURCE_IRQ flag tells that we are dealing with IRQ resources, and the name "mc" is in fact hard-coded in the MUSB core in order for the controller driver to retrieve this IRQ resource by querying it by its name.

Finally, the jz4740_udc_device platform device structure (line 21) describes the UDC itself.

The "musb-jz4740" name (line 22) defines the MUSB driver that is used for this device; remember this is in fact the name that we used in the jz4740_driver platform driver structure in Chapter 2. The id field (line 23) is set to -1 (equivalent to PLATFORM_DEVID_NONE) since we do not need an id for the device: the MUSB controller driver was already set to allocate an automatic id in Chapter 2. In the dev field we care for DMA related information here. The dma_mask field (line 25) defines the width of the DMA mask that is going to be used, and coherent_dma_mask (line 26) has the same purpose but for the alloc_coherent DMA mappings: in both cases we are using a 32 bits mask. Then the resource field (line 29) is simply a pointer to the resource structure defined before, while the num_resources field (line 28) keeps track of the number of arrays defined in the resource structure (in this case there were two resource arrays defined before).

With this quick overview of the UDC platform data at the arch/ level now done, let's get back to the MUSB glue layer specific platform data in drivers/usb/musb/jz4740.c:

static struct musb_hdrc_config jz4740_musb_config = {
        /* Silicon does not implement USB OTG. */
        .multipoint = 0,
        /* Max EPs scanned, driver will decide which EP can be used. */
        .num_eps    = 4,
        /* RAMbits needed to configure EPs from table */
        .ram_bits   = 9,
        .fifo_cfg = jz4740_musb_fifo_cfg,
        .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
};

static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
        .mode   = MUSB_PERIPHERAL,
        .config = &jz4740_musb_config,
};

First the glue layer configures some aspects of the controller driver operation related to the controller hardware specifics. This is done through the jz4740_musb_config musb_hdrc_config structure.

Defining the OTG capability of the controller hardware, the multipoint member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC is not OTG compatible. Then num_eps (line 5) defines the number of USB endpoints of the controller hardware, including endpoint 0: here we have 3 endpoints + endpoint 0. Next is ram_bits (line 7) which is the width of the RAM address bus for the MUSB controller hardware. This information is needed when the controller driver cannot automatically configure endpoints by reading the relevant controller hardware registers. This issue will be discussed when we get to device quirks in Chapter 5. Last two fields (line 8 and 9) are also about device quirks: fifo_cfg points to the USB endpoints configuration table and fifo_cfg_size keeps track of the size of the number of entries in that configuration table. More on that later in Chapter 5.

Then this configuration is embedded inside jz4740_musb_platform_data musb_hdrc_platform_data structure (line 11): config is a pointer to the configuration structure itself, and mode tells the controller driver if the controller hardware may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG which is a dual mode.

Remember that jz4740_musb_platform_data is then used to convey platform data information as we have seen in the probe function in Chapter 2

Chapter 5 - Device Quirks

Completing the platform data specific to your device, you may also need to write some code in the glue layer to work around some device specific limitations. These quirks may be due to some hardware bugs, or simply be the result of an incomplete implementation of the USB On-the-Go specification.

The JZ4740 UDC exhibits such quirks, some of which we will discuss here for the sake of insight even though these might not be found in the controller hardware you are working on.

Let's get back to the init function first:

static int jz4740_musb_init(struct musb *musb)
{
        musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
        if (!musb->xceiv) {
                pr_err("HS UDC: no transceiver configured\n");
                return -ENODEV;
        }

        /* Silicon does not implement ConfigData register.
         * Set dyn_fifo to avoid reading EP config from hardware.
         */
        musb->dyn_fifo = true;

        musb->isr = jz4740_musb_interrupt;

        return 0;
}

Instruction on line 12 helps the MUSB controller driver to work around the fact that the controller hardware is missing registers that are used for USB endpoints configuration.

Without these registers, the controller driver is unable to read the endpoints configuration from the hardware, so we use line 12 instruction to bypass reading the configuration from silicon, and rely on a hard-coded table that describes the endpoints configuration instead:

static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
};

Looking at the configuration table above, we see that each endpoints is described by three fields: hw_ep_num is the endpoint number, style is its direction (either FIFO_TX for the controller driver to send packets in the controller hardware, or FIFO_RX to receive packets from hardware), and maxpacket defines the maximum size of each data packet that can be transmitted over that endpoint. Reading from the table, the controller driver knows that endpoint 1 can be used to send and receive USB data packets of 512 bytes at once (this is in fact a bulk in/out endpoint), and endpoint 2 can be used to send data packets of 64 bytes at once (this is in fact an interrupt endpoint).

Note that there is no information about endpoint 0 here: that one is implemented by default in every silicon design, with a predefined configuration according to the USB specification. For more examples of endpoint configuration tables, see musb_core.c.

Let's now get back to the interrupt handler function:

static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
{
        unsigned long   flags;
        irqreturn_t     retval = IRQ_NONE;
        struct musb     *musb = __hci;

        spin_lock_irqsave(&musb->lock, flags);

        musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
        musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
        musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);

        /*
         * The controller is gadget only, the state of the host mode IRQ bits is
         * undefined. Mask them to make sure that the musb driver core will
         * never see them set
         */
        musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
            MUSB_INTR_RESET | MUSB_INTR_SOF;

        if (musb->int_usb || musb->int_tx || musb->int_rx)
                retval = musb_interrupt(musb);

        spin_unlock_irqrestore(&musb->lock, flags);

        return retval;
}

Instruction on line 18 above is a way for the controller driver to work around the fact that some interrupt bits used for USB host mode operation are missing in the MUSB_INTRUSB register, thus left in an undefined hardware state, since this MUSB controller hardware is used in peripheral mode only. As a consequence, the glue layer masks these missing bits out to avoid parasite interrupts by doing a logical AND operation between the value read from MUSB_INTRUSB and the bits that are actually implemented in the register.

These are only a couple of the quirks found in the JZ4740 USB device controller. Some others were directly addressed in the MUSB core since the fixes were generic enough to provide a better handling of the issues for others controller hardware eventually.

Chapter 6 - Conclusion

Writing a Linux MUSB glue layer should be a more accessible task, as this documentation tries to show the ins and outs of this exercise.

The JZ4740 USB device controller being fairly simple, I hope its glue layer serves as a good example for the curious mind. Used with the current MUSB glue layers, this documentation should provide enough guidance to get started; should anything gets out of hand, the linux-usb mailing list archive is another helpful resource to browse through.

Chapter 7 - Acknowledgements

Many thanks to Lars-Peter Clausen and Maarten ter Huurne for answering my questions while I was writing the JZ4740 glue layer and for helping me out getting the code in good shape.

I would also like to thank the Qi-Hardware community at large for its cheerful guidance and support.

Resources

USB Home Page: http://www.usb.org

linux-usb Mailing List Archives: http://marc.info/?l=linux-usb

USB On-the-Go Basics: http://www.maximintegrated.com/app-notes/index.mvp/id/1822

Writing USB Device Drivers: https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html

Texas Instruments USB Configuration Wiki Page: http://processors.wiki.ti.com/index.php/Usbgeneralpage

Analog Devices Blackfin MUSB Configuration: http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb

The Tao Of Programming

2013-12-31T00:00:00+01:00

Translated by Geoffrey James

Transcribed by Duke Hillard

Transmitted by Anupam Trivedi, Sajitha Tampi, and Meghshyam Jagannath

Re-html-ized and edited by Kragen Sittler

The Silent Void
The Ancient Masters
Design
Coding
Maintenance
Management
Corporate Wisdom
Hardware and Software
Epilogue

Book 1 - The Silent Void

Thus spake the master programmer:

“When you have learned to snatch the error code from the trap frame, it will be time for you to leave.”

1.1

Something mysterious is formed, born in the silent void. Waiting alone and unmoving, it is at once still and yet in constant motion. It is the source of all programs. I do not know its name, so I will call it the Tao of Programming.

If the Tao is great, then the operating system is great. If the operating system is great, then the compiler is great. If the compiler is great, then the application is great. The user is pleased and there exists harmony in the world.

The Tao of Programming flows far away and returns on the wind of morning.

1.2

The Tao gave birth to machine language. Machine language gave birth to the assembler.

The assembler gave birth to the compiler. Now there are ten thousand languages.

Each language has its purpose, however humble. Each language expresses the Yin and Yang of software. Each language has its place within the Tao.

But do not program in COBOL if you can avoid it.

1.3

In the beginning was the Tao. The Tao gave birth to Space and Time. Therefore Space and Time are Yin and Yang of programming.

Programmers that do not comprehend the Tao are always running out of time and space for their programs. Programmers that comprehend the Tao always have enough time and space to accomplish their goals.

How could it be otherwise?

1.4

The wise programmer is told about Tao and follows it. The average programmer is told about Tao and searches for it. The foolish programmer is told about Tao and laughs at it.

If it were not for laughter, there would be no Tao.

The highest sounds are hardest to hear.
Going forward is a way to retreat.
Great talent shows itself late in life.
Even a perfect program still has bugs.

Book 2 - The Ancient Masters

Thus spake the master programmer:

“After three days without programming, life becomes meaningless.”

2.1

The programmers of old were mysterious and profound. We cannot fathom their thoughts, so all we do is describe their appearance.

Aware, like a fox crossing the water. Alert, like a general on the battlefield. Kind, like a hostess greeting her guests. Simple, like uncarved blocks of wood. Opaque, like black pools in darkened caves.

Who can tell the secrets of their hearts and minds?

The answer exists only in Tao.

2.2

Grand Master Turing once dreamed that he was a machine. When he awoke he exclaimed:

“I don't know whether I am Turing dreaming that I am a machine, or a machine dreaming that I am Turing!”

2.3

A programmer from a very large computer company went to a software conference and then returned to report to his manager, saying: “What sort of programmers work for other companies? They behaved badly and were unconcerned with appearances. Their hair was long and unkempt and their clothes were wrinkled and old. They crashed our hospitality suite and they made rude noises during my presentation.”

The manager said: “I should have never sent you to the conference. Those programmers live beyond the physical world. They consider life absurd, an accidental coincidence. They come and go without knowing limitations. Without a care, they live only for their programs. Why should they bother with social conventions?”

“They are alive within the Tao.”

2.4

A novice asked the Master: “Here is a programmer that never designs, documents or tests his programs. Yet all who know him consider him one of the best programmers in the world. Why is this?”

The Master replies: “That programmer has mastered the Tao. He has gone beyond the need for design; he does not become angry when the system crashes, but accepts the universe without concern. He has gone beyond the need for documentation; he no longer cares if anyone else sees his code. He has gone beyond the need for testing; each of his programs are perfect within themselves, serene and elegant, their purpose self-evident. Truly, he has entered the mystery of Tao.”

Book 3 - Design

Thus spake the master programmer:

“When the program is being tested, it is too late to make design changes.”

3.1

There once was a man who went to a computer trade show. Each day as he entered, the man told the guard at the door:

“I am a great thief, renowned for my feats of shoplifting. Be forewarned, for this trade show shall not escape unplundered.”

This speech disturbed the guard greatly, because there were millions of dollars of computer equipment inside, so he watched the man carefully. But the man merely wandered from booth to booth, humming quietly to himself.

When the man left, the guard took him aside and searched his clothes, but nothing was to be found.

On the next day of the trade show, the man returned and chided the guard saying: “I escaped with a vast booty yesterday, but today will be even better.” So the guard watched him ever more closely, but to no avail.

On the final day of the trade show, the guard could restrain his curiosity no longer. “Sir Thief,” he said, “I am so perplexed, I cannot live in peace. Please enlighten me. What is it that you are stealing?”

The man smiled. “I am stealing ideas,” he said.

3.2

There once was a master programmer who wrote unstructured programs. A novice programmer, seeking to imitate him, also began to write unstructured programs. When the novice asked the master to evaluate his progress, the master criticized him for writing unstructured programs, saying, “What is appropriate for the master is not appropriate for the novice. You must understand the Tao before transcending structure.”

3.3

There was once a programmer who was attached to the court of the warlord of Wu. The warlord asked the programmer: “Which is easier to design: an accounting package or an operating system?”

“An operating system,” replied the programmer.

The warlord uttered an exclamation of disbelief. “Surely an accounting package is trivial next to the complexity of an operating system,” he said.

“Not so,” said the programmer, “when designing an accounting package, the programmer operates as a mediator between people having different ideas: how it must operate, how its reports must appear, and how it must conform to the tax laws. By contrast, an operating system is not limited by outside appearances. When designing an operating system, the programmer seeks the simplest harmony between machine and ideas. This is why an operating system is easier to design.”

The warlord of Wu nodded and smiled. “That is all good and well, but which is easier to debug?”

The programmer made no reply.

3.4

A manager went to the master programmer and showed him the requirements document for a new application. The manager asked the master: “How long will it take to design this system if I assign five programmers to it?”

“It will take one year,” said the master promptly.

“But we need this system immediately or even sooner! How long will it take if I assign ten programmers to it?”

The master programmer frowned. “In that case, it will take two years.”

“And what if I assign a hundred programmers to it?”

The master programmer shrugged. “Then the design will never be completed,” he said.

Book 4 - Coding

Thus spake the master programmer:

“A well-written program is its own heaven; a poorly-written program is its own hell.”

4.1

A program should be light and agile, its subroutines connected like a string of pearls. The spirit and intent of the program should be retained throughout. There should be neither too little or too much, neither needless loops nor useless variables, neither lack of structure nor overwhelming rigidity.

A program should follow the ‘Law of Least Astonishment’. What is this law? It is simply that the program should always respond to the user in the way that astonishes him least.

A program, no matter how complex, should act as a single unit. The program should be directed by the logic within rather than by outward appearances.

If the program fails in these requirements, it will be in a state of disorder and confusion. The only way to correct this is to rewrite the program.

4.2

A novice asked the master: “I have a program that sometime runs and sometimes aborts. I have followed the rules of programming, yet I am totally baffled. What is the reason for this?”

The master replied: “You are confused because you do not understand Tao. Only a fool expects rational behavior from his fellow humans. Why do you expect it from a machine that humans have constructed? Computers simulate determinism; only Tao is perfect.”

“The rules of programming are transitory; only Tao is eternal. Therefore you must contemplate Tao before you receive enlightenment.”

“But how will I know when I have received enlightenment?” asked the novice.

“Your program will then run correctly,” replied the master.

4.3

A master was explaining the nature of Tao of to one of his novices. “The Tao is embodied in all software - regardless of how insignificant,” said the master.

“Is the Tao in a hand-held calculator?” asked the novice.

“It is,” came the reply.

“Is the Tao in a video game?” continued the novice.

“It is even in a video game,” said the master.

“And is the Tao in the DOS for a personal computer?”

The master coughed and shifted his position slightly. “The lesson is over for today,” he said.

4.4

Prince Wang's programmer was coding software. His fingers danced upon the keyboard. The program compiled without an error message, and the program ran like a gentle wind.

“Excellent!” the Prince exclaimed, “Your technique is faultless!”

“Technique?” said the programmer turning from his terminal, “What I follow is Tao - beyond all techniques! When I first began to program I would see before me the whole problem in one mass. After three years I no longer saw this mass. Instead, I used subroutines. But now I see nothing. My whole being exists in a formless void. My senses are idle. My spirit, free to work without plan, follows its own instinct. In short, my program writes itself. True, sometimes there are difficult problems. I see them coming, I slow down, I watch silently. Then I change a single line of code and the difficulties vanish like puffs of idle smoke. I then compile the program. I sit still and let the joy of the work fill my being. I close my eyes for a moment and then log off.”

Prince Wang said, “Would that all of my programmers were as wise!”

Book 5 - Maintenance

Thus spake the master programmer:

“Though a program be but three lines long, someday it will have to be maintained.”

5.1

A well-used door needs no oil on its hinges.
A swift-flowing stream does not grow stagnant.
Neither sound nor thoughts can travel through a vacuum.
Software rots if not used.

These are great mysteries.

5.2

A manager asked a programmer how long it would take him to finish the program on which he was working. “It will be finished tomorrow,” the programmer promptly replied.

“I think you are being unrealistic,” said the manager, “Truthfully, how long will it take?”

The programmer thought for a moment. “I have some features that I wish to add. This will take at least two weeks,” he finally said.

“Even that is too much to expect,” insisted the manager, “I will be satisfied if you simply tell me when the program is complete.”

The programmer agreed to this.

Several years later, the manager retired. On the way to his retirement luncheon, he discovered the programmer asleep at his terminal. He had been programming all night.

5.3

A novice programmer was once assigned to code a simple financial package.

The novice worked furiously for many days, but when his master reviewed his program, he discovered that it contained a screen editor, a set of generalized graphics routines, an artificial intelligence interface, but not the slightest mention of anything financial.

When the master asked about this, the novice became indignant. “Don't be so impatient,” he said, “I'll put in the financial stuff eventually.”

5.4

Does a good farmer neglect a crop he has planted?
Does a good teacher overlook even the most humble student?
Does a good father allow a single child to starve?
Does a good programmer refuse to maintain his code?

Book 6 - Management

Thus spake the master programmer:

“Let the programmers be many and the managers few - then all will be productive.”

6.1

When managers hold endless meetings, the programmers write games. When accountants talk of quarterly profits, the development budget is about to be cut. When senior scientists talk blue sky, the clouds are about to roll in.

Truly, this is not the Tao of Programming.

When managers make commitments, game programs are ignored. When accountants make long-range plans, harmony and order are about to be restored. When senior scientists address the problems at hand, the problems will soon be solved.

Truly, this is the Tao of Programming.

6.2

Why are programmers non-productive?

Because their time is wasted in meetings.

Why are programmers rebellious?

Because the management interferes too much.

Why are the programmers resigning one by one?

Because they are burnt out.

Having worked for poor management, they no longer value their jobs.

6.3

A manager was about to be fired, but a programmer who worked for him invented a new program that became popular and sold well. As a result, the manager retained his job.

The manager tried to give the programmer a bonus, but the programmer refused it, saying, “I wrote the program because I thought it was an interesting concept, and thus I expect no reward.”

The manager upon hearing this remarked, “This programmer, though he holds a position of small esteem, understands well the proper duty of an employee. Let us promote him to the exalted position of management consultant!”

But when told this, the programmer once more refused, saying, “I exist so that I can program. If I were promoted, I would do nothing but waste everyone's time. Can I go now? I have a program that I'm working on."

6.4

A manager went to his programmers and told them: “As regards to your work hours: you are going to have to come in at nine in the morning and leave at five in the afternoon.” At this, all of them became angry and several resigned on the spot.

So the manager said: “All right, in that case you may set your own working hours, as long as you finish your projects on schedule.” The programmers, now satisfied, began to come in at noon and work to the wee hours of the morning.

Book 7 - Corporate Wisdom

Thus spake the master programmer:

“You can demonstrate a program for a corporate executive, but you can't make him computer literate.”

7.1

A novice asked the master: “In the east there is a great tree-structure that men call ‘Corporate Headquarters’. It is bloated out of shape with vice presidents and accountants. It issues a multitude of memos, each saying ‘Go, Hence!’ or ‘Go, Hither!’ and nobody knows what is meant. Every year new names are put onto the branches, but all to no avail. How can such an unnatural entity be?”

The master replied: “You perceive this immense structure and are disturbed that it has no rational purpose. Can you not take amusement from its endless gyrations? Do you not enjoy the untroubled ease of programming beneath its sheltering branches? Why are you bothered by its uselessness?”

7.2

In the east there is a shark which is larger than all other fish. It changes into a bird whose wings are like clouds filling the sky. When this bird moves across the land, it brings a message from Corporate Headquarters. This message it drops into the midst of the programmers, like a seagull making its mark upon the beach. Then the bird mounts on the wind and, with the blue sky at its back, returns home.

The novice programmer stares in wonder at the bird, for he understands it not. The average programmer dreads the coming of the bird, for he fears its message. The master programmer continues to work at his terminal, for he does not know that the bird has come and gone.

7.3

The Magician of the Ivory Tower brought his latest invention for the master programmer to examine. The magician wheeled a large black box into the master's office while the master waited in silence.

“This is an integrated, distributed, general-purpose workstation,” began the magician, “ergonomically designed with a proprietary operating system, sixth generation languages, and multiple state of the art user interfaces. It took my assistants several hundred man years to construct. Is it not amazing?”

The master raised his eyebrows slightly. “It is indeed amazing,” he said.

“Corporate Headquarters has commanded,” continued the magician, “that everyone use this workstation as a platform for new programs. Do you agree to this?”

“Certainly,” replied the master, “I will have it transported to the data center immediately!” And the magician returned to his tower, well pleased.

Several days later, a novice wandered into the office of the master programmer and said, “I cannot find the listing for my new program. Do you know where it might be?”

“Yes,” replied the master, “the listings are stacked on the platform in the data center.”

7.4

The master programmer moves from program to program without fear. No change in management can harm him. He will not be fired, even if the project is cancelled. Why is this? He is filled with Tao.

Book 8 - Hardware and Software

Thus spake the master programmer:

“Without the wind, the grass does not move. Without software, hardware is useless.”

8.1

A novice asked the master: “I perceive that one computer company is much larger than all others. It towers above its competition like a giant among dwarfs. Any one of its divisions could comprise an entire business. Why is this so?”

The master replied, “Why do you ask such foolish questions? That company is large because it is large. If it only made hardware, nobody would buy it. If it only made software, nobody would use it. If it only maintained systems, people would treat it like a servant. But because it combines all of these things, people think it one of the gods! By not seeking to strive, it conquers without effort.”

8.2

A master programmer passed a novice programmer one day. The master noted the novice's preoccupation with a hand-held computer game. “Excuse me,” he said, “may I examine it?”

The novice bolted to attention and handed the device to the master. “I see that the device claims to have three levels of play: Easy, Medium, and Hard,” said the master. “Yet every such device has another level of play, where the device seeks not to conquer the human, nor to be conquered by the human.”

“Pray, great master,” implored the novice, “how does one find this mysterious setting?”

The master dropped the device to the ground and crushed it underfoot. And suddenly the novice was enlightened.

8.3

There was once a programmer who worked upon microprocessors. “Look at how well off I am here,” he said to a mainframe programmer who came to visit, “I have my own operating system and file storage device. I do not have to share my resources with anyone. The software is self-consistent and easy-to-use. Why do you not quit your present job and join me here?”

The mainframe programmer then began to describe his system to his friend, saying “The mainframe sits like an ancient sage meditating in the midst of the data center. Its disk drives lie end-to-end like a great ocean of machinery. The software is as multifaceted as a diamond, and as convoluted as a primeval jungle. The programs, each unique, move through the system like a swift-flowing river. That is why I am happy where I am.”

The microcomputer programmer, upon hearing this, fell silent. But the two programmers remained friends until the end of their days.

8.4

Hardware met Software on the road to Changtse. Software said: “You are Yin and I am Yang. If we travel together we will become famous and earn vast sums of money.” And so the set forth together, thinking to conquer the world.

Presently they met Firmware, who was dressed in tattered rags and hobbled along propped on a thorny stick. Firmware said to them: “The Tao lies beyond Yin and Yang. It is silent and still as a pool of water. It does not seek fame, therefore nobody knows its presence. It does not seek fortune, for it is complete within itself. It exists beyond space and time.”

Software and Hardware, ashamed, returned to their homes.

Book 9 - Epilogue

Thus spake the master programmer:

“It is time for you to leave.”

MISSENE

My first talk at FOSDEM 2026

Android 16 QPR1 in Evolution X, FOSDEM release

Android 16 QPR1 situation, unofficial test builds

Official builds and OTA support

Rooting Android with KernelSU

What is rooting ?

A case for the Pixel 4a

Shortcomings, room for improvement

Joining an awesome project, terrific community

What it means to be official maintainer

The path moving forward

It's been a long time coming

The devil I know

The devil I don't

Better to have it and not need it

Pixel 5, Sweet 16

Pixel 4a 5G, a new device in our custom Android roster

What's up with Evolution X 10.8

Android 15 on Pixel 4a with Evolution X

Evolution X on the Google Pixel 3a

Create a Steam Deck Debian rescue image

Using dd command line tool to create a disk image

Using gnome-disk-utility GUI to create a disk image

Running Debian on Steam Deck from SD Card

Linux 3.18 released, contributions of mine

Attending LinuxCon & ELC Europe 2014

Linux 3.17 patches status

MIPS Creator CI20

Linux 3.16 released: patch inside

Going to GUADEC 2014

Fixing Ben NanoNote serial line

Linux 3.14 out, me contributions inside

OpenEmbedded Coverage At FOSDEM 2014

Serial Console Output On GCW-Zero

Materials, techniques & tools

Down the rabbit hole

Serial console software wonderland

SMT Soldering Tools

Soldering station

Additional iron tips

Soldering wire

Flux

Wire-wrapping wire

Glue gun

Writing An MUSB Glue Layer

Table Of Contents

Chapter 1 - Introduction

Chapter 2 - Linux MUSB Basics

Chapter 3 - Handling IRQs

Chapter 4 - Device Platform Data

Chapter 5 - Device Quirks

Chapter 6 - Conclusion

Chapter 7 - Acknowledgements

Resources

The Tao Of Programming

Table Of Contents

Book 1 - The Silent Void

1.1

1.2

1.3

1.4

Book 2 - The Ancient Masters

2.1

2.2

2.3

2.4

Book 3 - Design

3.1

3.2

3.3

3.4

Book 4 - Coding

4.1

4.2

4.3

4.4

Book 5 - Maintenance

5.1

5.2