HADK FAQ
Overview
v4.5.0.19 Sailfish OS Hardware Adaptation Development Kit Documentation
This page contains the HADK faq contents derived from: https://docs.sailfishos.org/Develop/HADK/SailfishOS-HardwareAdaptationDevelopmentKit-4.5.0.19.pdf
Preparations
1.1 Goal
By following this guide you can set up a Sailï¬sh OS (or another Sailï¬sh Core based) Linux system that will run
on an Android device, on top of an existing Android Hardware Adaptation kernel and drivers.
This consists of:
• Sailï¬sh Core: the GNU/Linux userspace core
• Android Hardware Adaptation (HA/HAL), consisting of:
• Device-speciï¬c Android Kernel
• Android base which can be:
• LineageOS - https://wiki.lineageos.org
• AOSP - Android Open Source Project - https://source.android.com
• CAF - Code Aurora Forum - https://www.codeaurora.org
• Sony Open Devices program - https://developer.sony.com/develop/open-devices
• Vendor-speciï¬c Android base
• Binary device drivers taken from an Android base
• Hybris patches to the Android base
• The libhybris interface built against the binary drivers
• Middleware packages depending on hardware-speciï¬c plugins
• A Qt/Wayland QPA plugin utilizing the Android hwcomposer
• Sailï¬sh OS components
Instructions
1.2 Development
1.2.1 Requirements
The development environment uses the Platform SDK, with:
• Build Tools consisting of cross-compilers (tooling) and an emulated rootfs for your device architecture (tar-
get), containing device-specific headers and libraries – will also be referred as build environment through-
out the document
• a HA build SDK (a minimal Ubuntu chroot required to build the Android sources
During the HA development you’ll typically have one window/terminal using the HA build SDK where you build
and work on Android code and another session using the Platform SDK where you build RPMs for the hardware
adaptation.
Setting up the Platform SDK, as well as the device-specific build environment and the Ubuntu HA build chroot is
described in Setting up the SDKs.
Commands and output from the Platform SDK session are indicated using PLATFORM_SDK $ at the top of the
code block, like this:
PLATFORM_SDK $
echo "run this command in the Platform SDK terminal"
How to enter PLATFORM_SDK $ is explained in Setup the Platform SDK.
Commands and output from the HA build session are indicated using HABUILD_SDK $ at the top of the code
block, like this:
HABUILD_SDK $
echo "run this command in the Ubuntu HA build SDK terminal"
How to enter HABUILD_SDK $ is explained in Entering Ubuntu Chroot.
1.2.2 The build area root directory
In this guide, we refer to the SDK directory hosting Platform SDK, Build Tools, and Ubuntu chroot with the
environment variable $PLATFORM_SDK_ROOT. You need around 10GB of space in total.
1.2.3 Build components
There are a number of components to build; the lower level and Android related components are built in the HA
build SDK; the rest are built in the Platform SDK.
• In the HA build SDK
• a kernel
• a hacking friendly initrd which supports various boot options
• hybris-boot.img and hybris-recovery.img (for booting and debugging)
• a minimal Android /system/ tree
• modified Android parts for compatibility with libhybris and Sailfish OS (e.g. Bionic libc,
logcat, init, . . . )
• In the Platform SDK
• RPM packages containing all the built binaries and extracted configs
• Hardware-specific middleware and plugins (e.g. Qt QPA plugins, PulseAudio)
For distribution, RPM packages are uploaded to a HA-specific repository. With this repository, full system images
using the mic utility. The mic utility is usually also run inside the Platform SDK
1.3 Deployment
The hybris-boot.img (containing both the kernel and our custom initrd) is flashed to the device, while the
Sailfish OS rootfs is placed in a subdirectory of the /data/ partition alongside an existing, unmodified Android
system.
The Sailfish OS rootfs is then used as a switchroot target with /data bind-mounted inside it for shared access to
any user data.
PREREQUISITES
2.1 Mobile Device
• An Android device officially supported by LineageOS 15.1 (Android 8), 16.0 (Android 9) and 17.1 (Android
10) at the time of writing 2021-02-12. CyanogenMod versions (that are Sailfish OS-compatible) 10.1.x,
11.0, 12.1, 13.0, 14.1 will require additional effort because CM has become obsolete. For more supported
Android versions also check this link
• Throughout this guide we shall use the term Android base, which will refer to the appropriate
base that you are porting on: LineageOS, AOSP, CAF etc
• We also support Sony Open Devices program, and published guidelines how to rebuild flashable
images for:
• Xperia X (Sony AOSP 6)
• Xperia XA2 (Sony AOSP 8)
• Xperia 10 (Sony AOSP 9)
• Xperia 10 II (Sony AOSP 10)
• Xperia 10 III (Sony AOSP 11)
• Starting with Sailfish OS 3.4.0, support for 64bit ARM SFOS userspace has been added
• Sailfish OS adaptations starting with CM 13.0 (Android 6) were constructed by running a mix of
64bit Linux Kernel and Android HAL, whilst Sailfish OS userspace was being run in the 32bit
mode. Such mixed mode is still supported, but we encourage porters to switch to full 64bit ports
(using Xperia 10 II as reference)
• See https://wiki.lineageos.org/devices for a list of compatible devices
• See https://wiki.merproject.org/wiki/Adaptations/libhybris for a status list of devices already
ported using HADK
• See https://wiki.merproject.org/wiki/Adaptations/libhybris/porters for a list of ports in early
stages, and their authors to contact on the IRC
• AOSP or CAF Android base support is also possible, but we choose LineageOS for a wider
range of devices. It will be up to the porter to patch an AOSP/CAF base with hybris patches.
Remaining differences in using it are minimal (e.g. using the lunch command instead of
breakfast)
• Means to do backup and restore of the device contents (e.g. SD card or USB cable to host computer), as
well as flash recovery images to the device
2.2 Build Machine
• A 64-bit x86 machine with a 64-bit Linux kernel
• Sailfish OS Platform SDK (installation explained later)
• At least 30 GiB of free disk space (20 GiB source download + more for building) for a complete Android
6 build; a minimal download and HADK build (only hardware adaptation-related components) requires
slightly less space. Newer Android base versions yield increasingly bigger size requirements.
• At least 4 GiB of RAM (the more the better)
PREPARING YOUR DEVICE
3.1 Backup and Verify Your Device
As mentioned above, it might be helpful to backup the existing stock Android image before flashing the Android
base release for the first time, as obtaining the stock image might be hard for some vendors (e.g. some stock images
are only available as self-extracting .exe package for Windows) or impossible (some vendors do not provide stock
images for download).
Use Android Recovery (e.g. TWRP or ClockworkMod) to:
1. Backup to SD card: system, data, boot and recovery partitions
2. Test restoring the backup (important)
Warning: While backing up to internal device storage is possible for some devices, if during porting you end
up overwriting that partition, your backups will be gone. In that case (and in case of devices without SD card
slots), it’s better to also copy the backup data to your development machine (e.g. via adb pull in recovery).
Recent versions of adb support full-device backups to a host computer using the adb backup feature.
See the ClockworkMod Instructions for additional help.
3.2 Flash and Test your Android base image
Flash an image that you built or obtained of your Android base, whether it’s LineageOS, CAF, AOSP, or another.
The official LineageOS flashing instructions can be found on this LineageOS wiki page.
You may also want to verify that the Android base build for your device is fully functional, to avoid wasting time
with hardware adaptations that have known issues. Also, your device might have some hardware defects - testing
in Android verifies that all components are working correctly, so you have a functionality baseline to compare
your Sailfish OS build results with.
You should at least check the following features:
• OpenGL ES 2.0: Use e.g. Gears for Android to test (the hz you will get there will be max refresh rate).
• WLAN connectivity: Connect to an AP, ad-hoc or set up a mobile access point with your device.
• Audio: Headset detection, earpiece speaker, loudspeakers, etc.
• Bluetooth: Connect to bluetooth headsets, verify discoverability, send files.
• NFC: Check if NFC tags can be detected, read and/or written by the device.
• SD/MicroSD: Use a file manager app to see if inserted SD cards can be detected.
• USB: MTP, mass storage (if available) and adb access.
• Telephony: 2G/3G/LTE calls + data connectivity.
• GPS: Using GPS Test, check GLONASS too; typical time to fix; AGPS.
• Sensors: Using AndroSensor: Accelerometer, Proximity Sensor, Ambient Light Sensor, Gyroscope, Mag-
netometer (Compass), Hall (flip case), . . .
• LEDs: If your device has notification LEDs or keypad backlights.
• Camera (front and back): Also test functionality of zoom, flash, etc..
• Buttons: Volume up, volume down, power, camera shutter, etc..
• Video out: HDMI / MHL connectivity if you have the necessary adapters. TV out.
• Screen backlight: Suspend and backlight control, minimum and maximum brightness.
• Battery meter: Charge level, battery health, charging via USB (wall charger and host PC).
• Vibration motor: Intensity, patterns.
• HW composer version: check dumpsys SurfaceFlinger through ADB (see SF Layer Debugging).
• Fingerprint sensor
• FM Radio
We recommend that you write down the results of these tests, so you can always remember them.