Replicant 4.0 Porting Guide¶

Table of contents
Replicant 4.0 Porting Guide

This guide is a step-by-step explanation of the process of porting a new device to Replicant 4.0.

Overview¶

Porting a new device to Replicant is a long task, so make sure you're ready to go through all the steps mentioned below. While it's not technically hard (unless you have to write free software replacements yourself), the process itself takes time as many steps are involved:

Checking that your devices meets the required prerequisites
Discovering the phone's hardware and the amount of non-free blobs involved
Getting Replicant sources, reading all the relevant material about developing on Replicant
Adding the device-specific repositories and files
Setting up the build environment for the new device
Building the recovery image

Prerequisites¶

Before porting your device to Replicant, you must make sure it complies with the following requirements:

The phone is already supported by CyanogenMod (CM) 9.x (or, worst-case scenario, by a non-official CyanogenMod 9.x port)
The phone has a GSM modem: Replicant doesn't support CDMA phones (but you can add support for it if you're skilled)
There is a way of installing another operating system, either through the bootloader or via recovery (this is likely if there is a CM port)
The kernel is not signed: this means that the bootloader doesn't check the kernel's signature to match with the vendor's key to allow it to run

If your device fails to comply with one of these requirements, it won't be possible to port Replicant to it.
If you don't know about whether your device complies or not, you'll probably learn it along the way.

Discovering the phone's hardware and associated blobs¶

First of all, you'll have to find out the device's codename given by its manufacturer

Before doing anything, you will need to know the codename of the device. You can find it out on CyanogenMod Wiki or on CyanogenMod download page.
For instance, the Nexus S codename is: crespo.

One very important step is to find out if the device is Tivoized: that means that even though the manufacturer releases the kernel source code for the device, the bootloader checks the kernel signature and will refuse to start it if it's not properly signed by the manufacturer. In other words, if you build the kernel yourself, the device will refuse to run it since it's not signed by the manufacturer. Since the Linux kernel is released under the GPLv2, there are no specific dispositions to counter Tivoization, and so porting the device to Replicant is pointless as it will require a prebuilt and signed kernel from the manufacturer.

First thing to consider before starting a port, when all of the above is assumed, is to see how many non-free components are required by CyanogenMod.
The easiest way to do this is to spot the device repository in CyanogenMod repos and look for the extract-files.sh or proprietary-blobs.txt file.
For instance, the list of non-free components for the Nexus S is extract-files.sh

From that list, spot what is related to what hardware component (audio, camera, sensors, gps, modem, etc): that gives an idea of the amount of work required to add support for the phone.

During the port, you might need to find precise infos about the hardware that is in the phone. A good to do this is by looking at the kernel defconfig for the device, another way is to download the Service Manual for the device.