Adding a driver to the Android kernel: from theory to practice

Integrating a third-party driver into the kernel Android is a task faced by developers of custom firmware, manufacturers of devices based on SoC (for example, Qualcomm Snapdragon or Mediatek Helio) and enthusiasts adapting equipment to non-standard configurations. Unlike general-purpose systems, where drivers are often loaded as modules, most critical drivers (for example, for a display, camera, or modem) are compiled directly into the kernel. This is due to the requirements for performance, security and energy efficiency. Linux- general purpose systems where drivers are often loaded as modules, in Android Most critical drivers (such as those for the display, camera, or modem) are compiled directly into the kernel. This is driven by performance, safety and energy efficiency requirements.

The process of adding a driver to the kernel Android requires not only knowledge C/Kernel API, but also an understanding of the architecture of a particular device. Errors at this stage can lead to unbootable system (“brick”)conflicts with existing modules or memory leaks. In this article we will analyze the entire cycle: from preparing the source code to debugging on the target device, taking into account the nuances of different kernel versions (from Linux 3.x to 5.x+) and the features of assembly through AOSP or proprietary tools like Qualcomm CodeAurora.

1. Preparing the working environment

Before you start modifying the kernel, you need to configure the environment. Minimum requirements include:

• 🖥️ Operating system: Ubuntu 20.04/22.04 LTS (recommended) or Debian. It is these distributions that are officially supported AOSP and by most vendors.
• 🛠️ Tools: git, make, gcc (version 9.x–12.x), python3, repo (for working with AOSP).
• 📂 Disk space: at least 100 GB for kernel sources and AOSP (full assembly can take up to 200+ GB).
• 🔌 Host machine drivers: for debugging through ADB/Fastboot rules will be required udev (for example, for devices Google Pixel or Xiaomi).

Important: if you are working with proprietary kernel (for example, from Samsung Exynos or Huawei Kirin), you may need access to the vendor's closed repositories. In this case, the preparation process is complicated by the need to obtain vendor blobs - binary files specific to the device model.

⚠️ Attention: Tool versions (especially gcc and clang) must strictly comply with the requirements of the target kernel. For example, kernels for Android 12+ often require clang 14+, while older versions (for example, for Android 9) can only work with gcc 4.9. Check the documentation for the source code of your device.

2. Obtaining kernel source code

Kernel sources for Android can be obtained from several sources, depending on the purpose:

To download sources, use repo (for AOSP) or git clone (for individual repositories), for example, to get the kernel for Google Pixel 6:

mkdir pixel-kernel && cd pixel-kernel
repo init -u https://android.googlesource.com/kernel/manifest -b android-gs-raviole-5.10-android12
repo sync

If you. If you are working with a proprietary device, you may have to look for sources on the manufacturer's website (for example, Samsung publishes them on opensource.samsung.comPlease note: even "open" sources often contain header files (.h) without implementation, which will require using vendor blobs.

3. Android kernel structure: where to add the driver

Drivers in the kernel Android are organized by subsystems, where you may need to add them. code:

• 📁 drivers/ —most device drivers (for example, drivers/gpu/drm/ for graphics, drivers/media/ for cameras).
• 📁 net/ —network drivers (Wi-Fi, Bluetooth, modems).
• 📁 sound/ —audio drivers (codecs ALSA/TinyALSA).
• 📁 arch/arm64/ or arch/arm/ —architecture-dependent drivers (for example, for DSP or TrustZone).

Example: if you are adding a driver for a new light sensor, its logical place is drivers/iio/light/. For a display driver (for example, AMOLED-panel) - drivers/gpu/drm/panel/.

It is important to follow naming conventions:

- Driver files usually have a prefix associated with the vendor (for example, samsung_ambient.c for driver Always-On Display from Samsung).

- Header files (.h) are located in include/linux/ or in the local driver folder.

⚠️ Attention: Some subsystems (for example, drivers/staging/) are intended for temporary placement unstable drivers. Avoid adding code there if you do not plan to further refine it to the state mainline.

4. Driver integration: modification of Kconfig and Makefile

For the driver to be compiled with the kernel, it must be declared in the build system. file:

1. Kconfig —defines configuration parameters (whether the driver will be built-in or module).
2. Makefile —specifies which source files to compile.

Example for a gyroscope driver (file drivers/iio/gyro/Kconfig):

config SENSORS_MY_GYRO
tristate "My Custom Gyroscope Driver"
depends on IIO
help
Say Y here to enable support for the custom gyroscope sensor.
To compile this driver as a module, choose M here.

Corresponding entry in Makefile:

obj-$(CONFIG_SENSORS_MY_GYRO) += my_gyro.o

After this, the driver will become available in the kernel configuration menu (make menuconfig or make xconfig). For proprietary kernels (for example, from Qualcomm), modification may be required BoardConfig.mk in the tree AOSP.

The driver is added to Kconfig and Makefile|Dependencies on are specified correctly|Driver files are placed in the correct folder|Kernel configuration has been updated (make menuconfig)-->

5. Compiling the kernel with the new driver

The kernel build process for Android is different from the standard Linux-kernels need to integrate with AOSP or proprietary vendor blobs. Basic steps:

1. Kernel configuration:

   make ARCH=arm64 [defconfig_of_your_device]_defconfig

   For example, for Google Pixel 4a it could be sunfish_defconfig.

2. Setting up the driver:

   make ARCH=arm64 menuconfig

   Find your driver in the menu and mark it as built-in (Y) or module (M).

3. Building:

   make ARCH=arm64 -j$(nproc)

   To speed up, use the flag -j with the number of processor cores.

The result of the build is a file arch/arm64/boot/Image.gz-dtb (or Image.lz4-dtb for some devices this file needs to be flashed onto the device). via fastboot:

fastboot flash boot Image.gz-dtb

⚠️ Attention: If you are building a kernel for a device with a locked bootloader (bootloader), first unlock it with the command fastboot flashing unlockOn some devices (for example, Huawei or Xiaomi c Mi Account) additional authorization will be required.

6. Debugging and testing the driver

After flashing the kernel, you need to check the operation of the driver:

• 🔍 dmesg - kernel logs in real time. time:

  adb shell su -c dmesg | grep [driver_name]

• 📊 /proc/ and /sys/ — interfaces for interacting with the driver (for example, /sys/class/iio/device/iio:deviceX/ for sensors). log
• 🐞 logcat - logs Android-system, if the driver interacts with HAL:

adb logcat | grep -iE "sensor|gyro|[keyword]"

If the driver does not load, check:

1. Is it present in /proc/modules (for modules) or in the output lsmod.
2. Whether there are conflicts with existing drivers (for example, two drivers for one device in /dev/).
3. Are compatible lines specified in .dtsfiles (for devices on Device Tree).

For debugging at the code level, use printk (analog printf for the kernel) or ftrace. Example of adding a debugging message:

printk(KERN_INFO "my_driver: probe started for device %s\n", dev_name(&client->dev));

7. Typical errors and their solutions

Even experienced developers face problems when integrating drivers. common:

Pay special attention memory leaks —in the kernel they lead to unstable operation of the system. To identify them, use kmemleak:

echo scan > /sys/kernel/debug/kmemleak
cat /sys/kernel/debug/kmemleak

If the driver interacts with HAL (for example, camera or audio), make sure that the versions of HAL and the kernel are compatible. For example, Camera HAL 3.x will not work with the kernel compiled for HAL 1.x.

8. Optimization and final integration

After successful testing of the driver, it can be optimized:

• ⚡ Performance: use perf to profile critical sections of the code. For example:

adb shell perf stat -e cycles,instructions -p [PID_process]

• 🔒 Security: check the driver for vulnerabilities using checkpatch.pl (included in the kernel sources) and static analyzers like Coverity.
• 📉 Power consumption: use PowerTOP or sysfsinterfaces (for example, /sys/class/power_supply/) for monitoring.

If the driver is intended for public use (for example, for custom firmware), format it according to the standards Linux Kernel Coding Style:

- Indents are tabs (not spaces).

- Line length - no more than 80 characters.

- Comments in the style / ... / (not //).

To distribute the driver as part of the firmware, add it to the repository vendor/ or publish it as a separate module with integration instructions. For example, for a Magiskmodule you will need to create a structure:

custom_driver_module/
├── system/
│   ├── lib/
│   │   └── modules/
│   │       └── my_driver.ko
├── META-INF/
│   └── com/
│       └── google/
│           └── android/
│               └── update-binary
└── module.prop

FAQ: Frequently asked questions

my_sensor@40 {
compatible = "vendor,my-sensor";
reg = <0x40>;
interrupt-parent = <&gpio>;
interrupts = <25 IRQ_TYPE_EDGE_RISING>;
};