Replicant

h1. Replicant 4.0 Porting Guide

{{>toc}}

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

h2. 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 [[Replicant40PortingGuide#Prerequisites|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

h2. 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.

h2. Discovering the phone's hardware and associated blobs

h3. Finding the device's codenames

First of all, you'll have to find out the device's codename that was given by its manufacturer. "Wikipedia":http://www.wikipedia.org/ usually has that information on the device's article. For instance, the codename for the European version of the Nexus S given by Samsung is i9023. This codename will help in the process of getting informations about the device.

Then, a second codename (that can turn out the be the same as the previous one) is given to the device at Android-level. If your device is supported by CyanogenMod, you can find it out from the "CyanogenMod Wiki":http://wiki.cyanogenmod.org/ or on "CyanogenMod download page":http://get.cm/. For instance, the "Nexus S":http://wiki.cyanogenmod.org/w/Crespo_Info codename is: @crespo@.

h3. Investigating the hardware

It is useful to have a general idea of what kind of hardware is present in the phone. From the Wikipedia and CyanogenMod pages about the device, it's already possible to know what System on a Chip (SoC) it uses and a couple other details.

To learn more details, you can consider looking for a teardown of the device (for instance on "iFixit":http://www.ifixit.com/), that will reveal what chips are used on the device. Looking at the kernel defconfig for the device will also help a lot, you can also try to find the service manual for the device.

You can then compare that to the devices that are already supported in Replicant to get an idea of what will possibly work.

h3. Finding out if the device checks the kernel's signature

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.

This is not an easy information to find out, but the developers involved in the CyanogenMod port will probably know that information. It's a good idea to just ask them.

h3. Discovering the way of flashing the device

To install the future Replicant image on the device, you have to find out how the device can be flashed with a new operating system. The "CyanogenMod Wiki":http://wiki.cyanogenmod.org/ has install guides for the supported devices and you'll probably find install guides for non-official CM ports as well. It is very important to understand the flashing procedure as it will have to be documented on the Replicant wiki.

There are basically two ways of flashing a new operating system:

# Through the bootloader: a program has to send the images to the phone in bootloader mode. Make sure that program is free if your device supports flashing via bootloader.

# With recovery: a recovery image has to be installed instead of the current kernel so that at next reboot, recovery permits the installation of another operating system. Make sure this doesn't involve rooting the phone using non-free software.

h4. The non-free blobs

The key information to get before starting the port is the list of the non-free components that are required by CyanogenMod.

The easiest way to do this is to spot the device repository in "CyanogenMod repos":https://github.com/CyanogenMod/ and look for the @extract-files.sh@ or @proprietary-blobs.txt@ file on the @ics@ branch.

There is usually a link to the device repository from the "CyanogenMod Wiki":http://wiki.cyanogenmod.org/

For instance, the list of non-free components for the "Nexus S":https://github.com/CyanogenMod/android_device_samsung_crespo is "extract-files.sh":https://github.com/CyanogenMod/android_device_samsung_crespo/blob/ics/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.