Index by title

36C3

Presentations

All presentations are available at the Presentations page, alongside with slide-decks and videos (if available).

Hardware to bring

Devices

Good practices:
Person Hardware Comments Usage
GNUtoo Galaxy SIII (I9300) with the stock bootloader Please don't reflash the bootloader or unusual partitions (EFS, etc) Can run Replicant 6.0 => Can be lent or used for demos
Galaxy SIII (I9300) with the stock (signed) OS Please don't reflash the bootloader or unusual partitions (EFS, etc) Will be used for demos at the stand: We will monitor what is transmited on the network
Galaxy SIII (I9300) with u-boot Please don't reflash the modem partitions (EFS, MODEM) Can run Replicant 9 and GNU/Linux
Other Replicant 6.0 compatible phones:
Galaxy SII
Galaxy Nexus
Galaxy Note
Please don't reflash the bootloader or unusual partitions (EFS, etc) Lend them to be able to communicate through the 36C3 phone network

Debug utilities

Person Hardware Comments Usage
GNUtoo Serial port cable with variable resistors Needed for Replicant 9 or GNU/Linux
Screwdriver Needed by dllud
Multimeter Can debug the serial cable if necessary
Simtrace 1: Can get the dialog between the modem and the SIM card in wireshark simtrace packaged in Parabola, please do not reflash or trigger the erase jumper (requires old compiler to recompile the firmware) Do we do demos with it ?
SIM card that is not recognized in Replicant (STK related?) Testing
SIM card + phone that can trigger the audio call issue Testing
5 CCC Camp 2019 SIM cards I've the ADM1 PIN and such if you want to play with it, but I don't have good transportable smartcard reader (only bad transportable or good not transportable) Will be lent to use the 36C3 phone network

Other:

Person Hardware Comments Usage
GNUtoo Blank stickers for labeling the hardware * Put your name, table, and contact information on the hardware you lend to more easily find you when we need to give it back to you
* Put constraints and usage notes on hardware (pinout, settings, what not to reflash)
FSF Replicant stickers Giving some to the attendees

AcademicPapersAndPresentations

Forensics acquisition - Analysis and circumvention of samsung secure boot enforced common criteria mode

Link: https://www.sciencedirect.com/science/article/pii/S1742287618300409
file name: 1-s2.0-S1742287618300409-main.pdf
License: CC BY-NC-ND

Description:

While this paper directly applies to the Galaxy S6 (SM-G920F) and the Galaxy S7 Edge (SM-G935F) witch uses Exynos System On a Chip, some of its findings seem to be directly applicable to the devices supported by Replicant.

The most interesting part is the analysis of some of the bootloader environment variables:

Security Analysis of Android Factory Resets

Link: https://www.cl.cam.ac.uk/~rja14/Papers/fr_most15.pdf
Related bug reports: #2096

A walk with Shannon. Walkthrough of a pwn2own baseband exploit.

Presentation pdf: https://downloads.immunityinc.com/infiltrate2018-slidepacks/amat-cama-a-walk-with-shannon/presentation.pdf
Presentation Video: https://www.youtube.com/watch?v=6bpxrfB9ioo
Target device: unclear, Maybe a Galaxy S6 or Galaxy S8

Description

The device used has shared memory between the SOC running Android and the modem.

There are some interesting points in that presentation:

How to lock the samsung download mode using an undocumented feature of aboot

link: https://ge0n0sis.github.io/posts/2016/05/how-to-lock-the-samsung-download-mode-using-an-undocumented-feature-of-aboot/

The device used seems to use a Qualcomm MSM8974 SOC. What is interesting is that it looks very similar to the "Forensics acquisition - Analysis and circumvention of samsung secure boot enforced common criteria mode" paper, but with another device and SOC.

While the technical information in this research is not directly applicable, it shows that there are systemic trends:

ADB

Installing ADB

See the ToolsInstallation page for how to install adb.

Enabling ADB

In the settings, open Developer options. In the Debugging section, enable Android debugging.

Authorizing the device

In order to allow your host computer to access ADB on the device, it must be allowed on the device. A window should pop up when connecting USB, asking whether to allow USB debugging.
Note: when booting with USB plugged in, the window doesn't pop up and you have to disconnect and reconnect the USB cable to see it happen.

Accessing root shell

Once allowed, you can access the device shell using:

adb shell

The shell is running as an unprivileged user.

To allow root access, open the Developer options in the settings. There, press Root access. In the pop-up menu, select either ADB only or Apps and ADB. A window with "Allow root access?" might pop up and explains the security tradeoffs of enabling root access. After reading the text, select OK to enable root access.

To finally gain root access, use:

adb root

The following shells will then be run as root.

Modifying the system partition

Replicant is installed on the system partition. By default with most devices, this partition is mounted as read-only and can't be modified.
You can mount the partition as writable filesystem using:

adb remount

Files under /system/ can now be edited.

Revoking all computer's USB debugging permissions

Sometimes, you need to use Always allow from this computer to give a computer more permanent USB debugging permissions. This for instance the case in the BackupTheEFS instructions.

However once you are done with what needs such permissions, you might want to revoke the permissions if you don't need anymore, to increase security.

To do that you can select Revoke USB debugging authorizations in Developer options in the Settings (Settings > Developer options > Revoke USB debugging authorizations).


AddingADBRootToAnImage

Introduction

This page explains how to enable adb root support by default without any authentication to an existing Replicant release, for instance to get very early logs or to get a shell very early in the boot process, in order to debug or fix boot issues.

That tutorial can also be used to do other things like:

Issues with zImages

Some devices (The Galaxy S (GT-I9000), Galaxy SII (GT-I9100), and Galaxy Note (GT-N7000) uses a zImage because the nonfree bootloader doesn't support the boot.img format. Because of that, this tutorial doesn't cover theses devices (yet).

Security risks

Keep in mind that once you add adb root support by default without authentication to a Replicant installation (by modifying the boot.img file), your device becomes potentially vulnerable to juice jacking .

So if you want to prevent any issues it might be best to put back the original boot.img once you don't need adb root support by default without any authentication anymore.

If you add adb root support by default without authentication to the recovery instead, the risk is much more limited as the device would probably need to be rebooted into the recovery to be exposed.

Also, we didn't investigate if any supported devices would be exposed during charge mode (when the device is off and you plug an USB cable).

Adding adb root support to an existing Replicant release.

In this tutorial we'll add adb root support to an existing Replicant release. This will gives you adb root during the boot of Replicant. If you want to add adb root to the Replicant 6 recovery, you will need to modify the recovery.img instead of the boot.img file. Like the replicant-*.zip file, the recovery.img file is one of the images releases in the Replicant releases.

This is valid for the following configuration:

You also need to have unbootimg installed. In Parabola this is part of the fso-unbootimg package . It's also possible to compile that tool by hand or to other alternative tools that do exactly the same thing.

You'll need to adapt it slightly for other devices.

First extract the boot.img from the zip

$ mkdir temp
$ cd temp 
$ unzip ../replicant-6.0-0004-rc1-maguro.zip
$ file boot.img
boot.img: Android bootimg, kernel, ramdisk, page size: 2048, cmdline (androidboot.hardware=tuna)

Then extract the kernel, and initramfs from the boot.img. Also save the infos such as the load address, etc in boot.txt:

$ unbootimg --kernel kernel.img --ramdisk ramdisk.cpio.gz -i boot.img | tee boot.txt
total image size:   5619712
kernel size:        4604340
kernel load addr:   0x80008000
ramdisk size:       1009915
ramdisk load addr:  0x81000000
2nd boot size:      0
2nd boot load addr: 0x80f00000
kernel tags addr:   0x80000100
page size:          2048
board:              `'
cmdline:            `androidboot.hardware=tuna'
id:                 9b90141066f527ecd3909d2ab8e383ebd995fd40000

Then uncompress the initramfs

$ gunzip ramdisk.cpio.gz
$ file ramdisk.cpio 
ramdisk.cpio: ASCII cpio archive (SVR4 with no CRC)

Then edit the default.props, we use sed on the raw cpio image for simplicity (we don't have permissions and username to take care of this way):

$ sed 's#ro.adb.secure=1#               #' -i ramdisk.cpio
$ sed 's#ro.secure=1#ro.secure=0#' -i ramdisk.cpio
$ sed 's#persist.sys.usb.config=none#persist.sys.usb.config=adb #' -i ramdisk.cpio

Then recompress the initramfs

$ gzip ramdisk.cpio

We then recreate the image with the infos we saved in boot.txt. Note that the base is 0x80000000. The kernel has an offset and will be in 0x80008000:

$ mkbootimg --cmdline="androidboot.hardware=tuna" --kernel kernel.img --ramdisk ramdisk.cpio.gz  --base 0x80000000 -o boot_new.img

Verify that we got all the arguments right:

$ unbootimg -i boot_new.img | tee boot_new.txt
$ diff -u boot.txt boot_new.txt
$ --- boot.txt    2020-02-18 00:39:59.890285634 +0100
+++ boot_new.txt    2020-02-18 00:44:16.208897037 +0100
@@ -1,7 +1,7 @@
 total image size:   5619712
 kernel size:        4604340
 kernel load addr:   0x80008000
-ramdisk size:       1009915
+ramdisk size:       1010280
 ramdisk load addr:  0x81000000
 2nd boot size:      0
 2nd boot load addr: 0x80f00000
@@ -9,4 +9,4 @@
 page size:          2048
 board:              `'
 cmdline:            `androidboot.hardware=tuna'
-id:                 9b90141066f527ecd3909d2ab8e383ebd995fd40000
+id:                 dd37b2ae1e50be62fe5c94b81b85aa56ffea17be000

You can then reflash the boot.img image.

Don't forget to adjust the heimdall arguments for your device.

If in doubt, it's better to consult the Replicant installation instructions that have the good heimdall arguments, as wrong arguments can completely break your device, making it too complicated to repair (you'd have to un-solder and re-solder resistors that are hardly visible).

heimdall flash --boot boot.img --recovery boot.img

Then you can use adb:

$ adb logcat -b main

Example for the GT-I9300

This is valid for the following configuration:

For other devices like the GT-I9300, the boot.img (or recovery.img) have other parameters:

 unbootimg -i boot.img 
total image size:   4239360
kernel size:        3391376
kernel load addr:   0x40008000
ramdisk size:       844653
ramdisk load addr:  0x41000000
2nd boot size:      0
2nd boot load addr: 0x40f00000
kernel tags addr:   0x40000100
page size:          2048
board:              `'
cmdline:            `console=ttySAC2,115200'
id:                 d34c0412b72d37a2287331e28d902a769c4a86e9000

So we need to adjust the --cmdline and the --base accordingly:

mkbootimg --cmdline="console=ttySAC2,115200" --kernel kernel.img --ramdisk ramdisk.cpio.gz  --base 0x40000000 -o boot_new.img

Like with the Galaxy nexus, when we recreate the image with the infos we saved in boot.txt, we need to make sure that the base is right.

Here the base is 0x40000000, which results in the kernel offset (or load address) of 0x40008000.

Going further

The Linux kernel has more in depth documentation about initramfs in a file named ramfs-rootfs-initramfs.rst which document how to extract an initramfs and how to recreate one.

However we didn't test that yet. Tests and tutorials are welcome.

We also need to understand if something specific needs to be done for the file permissions when extracting, modifying and rebuilding an initramfs.


AKM8976A

The goal here is to add support for AKM8976A to akmd-free (a free rewrite of akmd, the daemon that deals with the accelerometer/magnetometer data for a few chips, including AKM ones).
This page is to coordinate the work around this goal.

Current status

Global tasks achievement

Task Achievement
Modifying the kernel driver to print the requests akmd makes (ioctl, etc) Done
Get an idea of how it works (what akmd does after what) Done
Define the exact steps that akmd follows Done
Implement AKM8976A in akmd-free without any data treatment yet Done
Understand how the data is treated (algorithms, etc) Work in progress
Reproduce the data treatment with standard C code Work in progress
Include the data treatment code in akmd-free TODO
Check that everything is OK on different devices TODO

Specific tasks achievement

Initialization/calibration sequence

Task Global achievement Understood Reproduced Implemented
Before the first ECS_IOCTL_GETDATA Mostly done Done Done TODO

Getting started

Note that before everything, coming on our IRC channel #replicant on irc.freenode.net and introducing yourself is essential: you'll be able to get help there and, of course, if you want to join the effort, communication is fundamental.

If you plan to join the effort to achieve this goal, here are the steps:

Using the scripts/tools

First of all, you need to know that the kernel-side driver that is used for AKM8976A is located at drivers/misc/akm8976.c.
This file has been modified in order to:

Note that before you run any of the scripts, you need to start adb server as root:

Here is a list of the scripts, what they do and how to use them: You can also avoid the use of the scripts and directly run the needed commands:

Conclusions on how it works

To begin with, here is the trace of the requests akmd does to the kernel driver (using the ioctl system call):

<6>[ 2066.362670] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.363220] --> ECS_IOCTL_SET_MODE
<6>[ 2066.364074]  --> AKECS_MODE_E2P_READ
<6>[ 2066.381042] --> ECS_IOCTL_READ #1
<6>[ 2066.381317] what is in rwbuf?
<6>[ 2066.381744] --------------------
<6>[ 2066.382019] |    index    |    hdata    |    ddata    |
<6>[ 2066.382263] |    0    |    0x1    |    1    |
<6>[ 2066.382507] |    1    |    0x42    |    66    |
<6>[ 2066.382934] |    2    |    0x0    |    0    |
<6>[ 2066.383178] |    3    |    0x0    |    0    |
<6>[ 2066.383392] |    4    |    0x0    |    0    |
<6>[ 2066.383636] ----------
<6>[ 2066.384063] --> ECS_IOCTL_READ
<6>[ 2066.384979] --> ECS_IOCTL_READ #3
<6>[ 2066.385253] --------------------
<6>[ 2066.385498] |    index    |    hdata    |    ddata    |
<6>[ 2066.385925] |    0    |    0x1    |    1    |
<6>[ 2066.386169] |    1    |    0x66    |    102    |
<6>[ 2066.386383] |    2    |    0x0    |    0    |
<6>[ 2066.386627] |    3    |    0x0    |    0    |
<6>[ 2066.387054] |    4    |    0x0    |    0    |
<6>[ 2066.387268] ----------
<6>[ 2066.387542] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.387786] --> ECS_IOCTL_SET_MODE
<6>[ 2066.388214]  --> AKECS_MODE_POWERDOWN
<6>[ 2066.401031] --> ECS_IOCTL_GET_OPEN_STATUS
<6>[ 2066.401306] --> ECS_IOCTL_GET_OPEN_STATUS #3
<6>[ 2066.407135] --> ECS_IOCTL_INIT
<6>[ 2066.408020] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.408294] --> ECS_IOCTL_SET_MODE
<6>[ 2066.408721]  --> AKECS_MODE_E2P_READ
<6>[ 2066.421234] --> ECS_IOCTL_READ #1
<6>[ 2066.421630] what is in rwbuf?
<6>[ 2066.422302] --------------------
<6>[ 2066.422637] |    index    |    hdata    |    ddata    |
<6>[ 2066.423004] |    0    |    0x3    |    3    |
<6>[ 2066.423339] |    1    |    0x46    |    70    |
<6>[ 2066.423950] |    2    |    0x0    |    0    |
<6>[ 2066.424285] |    3    |    0x0    |    0    |
<6>[ 2066.424621] |    4    |    0x0    |    0    |
<6>[ 2066.424957] ----------
<6>[ 2066.425567] --> ECS_IOCTL_READ
<6>[ 2066.426696] --> ECS_IOCTL_READ #3
<6>[ 2066.427062] --------------------
<6>[ 2066.427398] |    index    |    hdata    |    ddata    |
<6>[ 2066.428039] |    0    |    0x3    |    3    |
<6>[ 2066.428375] |    1    |    0x97    |    151    |
<6>[ 2066.428710] |    2    |    0x87    |    135    |
<6>[ 2066.429321] |    3    |    0x19    |    25    |
<6>[ 2066.429656] |    4    |    0x0    |    0    |
<6>[ 2066.429992] ----------
<6>[ 2066.431243] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.431915] --> ECS_IOCTL_SET_MODE
<6>[ 2066.432250]  --> AKECS_MODE_POWERDOWN
<6>[ 2066.450866] --> ECS_IOCTL_WRITE #1
<6>[ 2066.451385] what is in rwbuf?
<6>[ 2066.452239] --------------------
<6>[ 2066.452697] |    index    |    hdata    |    ddata    |
<6>[ 2066.453186] |    0    |    0x4    |    4    |
<6>[ 2066.454040] |    1    |    0xe8    |    232    |
<6>[ 2066.454498] |    2    |    0x7    |    7    |
<6>[ 2066.454956] |    3    |    0x7    |    7    |
<6>[ 2066.455413] |    4    |    0x9    |    9    |
<6>[ 2066.456268] ----------
<6>[ 2066.456726] --> ECS_IOCTL_WRITE
<6>[ 2066.457916] --> ECS_IOCTL_WRITE #1
<6>[ 2066.458374] what is in rwbuf?
<6>[ 2066.459228] --------------------
<6>[ 2066.459686] |    index    |    hdata    |    ddata    |
<6>[ 2066.460174] |    0    |    0x4    |    4    |
<6>[ 2066.460784] |    1    |    0xe5    |    229    |
<6>[ 2066.461669] |    2    |    0x89    |    137    |
<6>[ 2066.462127] |    3    |    0x0    |    0    |
<6>[ 2066.462615] |    4    |    0x89    |    137    |
<6>[ 2066.463073] ----------
<6>[ 2066.463928] --> ECS_IOCTL_WRITE
<6>[ 2066.465698] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.466186] --> ECS_IOCTL_SET_MODE
<6>[ 2066.467071]  --> AKECS_MODE_MEASURE_SNG
<6>[ 2066.480468] --> ECS_IOCTL_GETDATA
<6>[ 2066.480987] --> ECS_IOCTL_GETDATA #3
<6>[ 2066.481445] --------------------
<6>[ 2066.482299] |    index    |    hdata    |    ddata    |
<6>[ 2066.482788] gflag1|    0    |    0x70    |    112    |
<6>[ 2066.483245] gflag1|    1    |    0x7f    |    127    |
<6>[ 2066.484100] gflag1|    2    |    0xa5    |    165    |
<6>[ 2066.484588] gflag1|    3    |    0x5c    |    92    |
<6>[ 2066.485046] gflag1|    4    |    0x66    |    102    |
<6>[ 2066.485900] gflag1|    5    |    0x85    |    133    |
<6>[ 2066.486450] gflag1|    6    |    0x5c    |    92    |
<6>[ 2066.486938] gflag1|    7    |    0x85    |    133    |
<6>[ 2066.487792] gflag1|    8    |    0x0    |    0    |
<6>[ 2066.488250] gflag1|    9    |    0x0    |    0    |
<6>[ 2066.488708] gflag1|    10    |    0x0    |    0    |
<6>[ 2066.489196] gflag1|    11    |    0x0    |    0    |
<6>[ 2066.490051] gflag1|    12    |    0x0    |    0    |
<6>[ 2066.490631] gflag1|    13    |    0x0    |    0    |
<6>[ 2066.491119] gflag1|    14    |    0x0    |    0    |
<6>[ 2066.491973] gflag1|    15    |    0x0    |    0    |
<6>[ 2066.492431] gflag1|    16    |    0x0    |    0    |
<6>[ 2066.492919] gflag1|    17    |    0xa5    |    165    |
<6>[ 2066.493774] gflag1|    18    |    0x5c    |    92    |
<6>[ 2066.494262] gflag1|    19    |    0x66    |    102    |
<6>[ 2066.494720] gflag1|    20    |    0x85    |    133    |
<6>[ 2066.495574] gflag1|    21    |    0x5c    |    92    |
<6>[ 2066.496032] gflag1|    22    |    0x85    |    133    |
<6>[ 2066.496520] gflag1|    23    |    0x0    |    0    |
<6>[ 2066.496978] gflag1|    24    |    0x0    |    0    |
<6>[ 2066.497833] gflag1|    25    |    0x0    |    0    |
<6>[ 2066.498291] gflag1|    26    |    0x0    |    0    |
<6>[ 2066.498779] gflag1|    27    |    0x0    |    0    |
<6>[ 2066.499633] gflag1|    28    |    0x0    |    0    |
<6>[ 2066.500122] gflag1|    29    |    0x0    |    0    |
<6>[ 2066.500671] gflag1|    30    |    0x0    |    0    |
<6>[ 2066.501525] gflag1|    31    |    0x0    |    0    |
<6>[ 2066.501983] ----------
<6>[ 2066.509826] --> ECS_IOCTL_GET_NUMFRQ
<6>[ 2066.510559] --> ECS_IOCTL_GET_NUMFRQ #3
<6>[ 2066.511444] --------------------
<6>[ 2066.511901] |    index    |    hdata    |    ddata    |
<6>[ 2066.512390] |    0    |    0x1    |    1    |
<6>[ 2066.513244] |    1    |    0x0    |    0    |
<6>[ 2066.513702] ----------
<6>[ 2066.515655] --> ECS_IOCTL_WRITE #1
<6>[ 2066.516174] what is in rwbuf?
<6>[ 2066.517120] --------------------
<6>[ 2066.517578] |    index    |    hdata    |    ddata    |
<6>[ 2066.518066] |    0    |    0x4    |    4    |
<6>[ 2066.518524] |    1    |    0xee    |    238    |
<6>[ 2066.519378] |    2    |    0x10    |    16    |
<6>[ 2066.519836] |    3    |    0x10    |    16    |
<6>[ 2066.520324] |    4    |    0x10    |    16    |
<6>[ 2066.520904] ----------
<6>[ 2066.521789] --> ECS_IOCTL_WRITE
<6>[ 2066.524230] --> ECS_IOCTL_WRITE #1
<6>[ 2066.524749] what is in rwbuf?
<6>[ 2066.525299] --------------------
<6>[ 2066.526153] |    index    |    hdata    |    ddata    |
<6>[ 2066.526641] |    0    |    0x4    |    4    |
<6>[ 2066.527099] |    1    |    0xeb    |    235    |
<6>[ 2066.527954] |    2    |    0x3    |    3    |
<6>[ 2066.528411] |    3    |    0x7    |    7    |
<6>[ 2066.528869] |    4    |    0x8a    |    138    |
<6>[ 2066.529357] ----------
<6>[ 2066.529815] --> ECS_IOCTL_WRITE
<6>[ 2066.532836] --> ECS_IOCTL_WRITE #1
<6>[ 2066.533355] what is in rwbuf?
<6>[ 2066.533874] --------------------
<6>[ 2066.534729] |    index    |    hdata    |    ddata    |
<6>[ 2066.535186] |    0    |    0x2    |    2    |
<6>[ 2066.535675] |    1    |    0xf4    |    244    |
<6>[ 2066.536132] |    2    |    0x55    |    85    |
<6>[ 2066.537017] |    3    |    0x0    |    0    |
<6>[ 2066.537475] |    4    |    0x0    |    0    |
<6>[ 2066.537933] ----------
<6>[ 2066.538391] --> ECS_IOCTL_WRITE
<6>[ 2066.539947] --> ECS_IOCTL_WRITE #1
<6>[ 2066.540618] what is in rwbuf?
<6>[ 2066.541107] --------------------
<6>[ 2066.541534] |    index    |    hdata    |    ddata    |
<6>[ 2066.542388] |    0    |    0x2    |    2    |
<6>[ 2066.542877] |    1    |    0xf5    |    245    |
<6>[ 2066.543334] |    2    |    0x1b    |    27    |
<6>[ 2066.544219] |    3    |    0x0    |    0    |
<6>[ 2066.544677] |    4    |    0x0    |    0    |
<6>[ 2066.545135] ----------
<6>[ 2066.545623] --> ECS_IOCTL_WRITE
<6>[ 2066.548126] --> ECS_IOCTL_WRITE #1
<6>[ 2066.548370] what is in rwbuf?
<6>[ 2066.548614] --------------------
<6>[ 2066.548858] |    index    |    hdata    |    ddata    |
<6>[ 2066.549285] |    0    |    0x2    |    2    |
<6>[ 2066.549530] |    1    |    0xf6    |    246    |
<6>[ 2066.549743] |    2    |    0x8    |    8    |
<6>[ 2066.549987] |    3    |    0x0    |    0    |
<6>[ 2066.550537] |    4    |    0x0    |    0    |
<6>[ 2066.550781] ----------
<6>[ 2066.551025] --> ECS_IOCTL_WRITE
<6>[ 2066.552398] --> ECS_IOCTL_WRITE #1
<6>[ 2066.552856] what is in rwbuf?
<6>[ 2066.553131] --------------------
<6>[ 2066.553375] |    index    |    hdata    |    ddata    |
<6>[ 2066.553802] |    0    |    0x4    |    4    |
<6>[ 2066.554046] |    1    |    0xf1    |    241    |
<6>[ 2066.554260] |    2    |    0x84    |    132    |
<6>[ 2066.554504] |    3    |    0x87    |    135    |
<6>[ 2066.554931] |    4    |    0x83    |    131    |
<6>[ 2066.555145] ----------
<6>[ 2066.555389] --> ECS_IOCTL_WRITE
<6>[ 2066.557525] --> ECS_IOCTL_GET_CLOSE_STATUS
<6>[ 2066.558074] --> ECS_IOCTL_GET_DELAY
<6>[ 2066.558319] --> ECS_IOCTL_GET_DELAY #3
<6>[ 2066.761016] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.761932] --> ECS_IOCTL_SET_MODE
<6>[ 2066.762420]  --> AKECS_MODE_MEASURE_SNG
<6>[ 2066.781555] --> ECS_IOCTL_GETDATA
<6>[ 2066.782531] --> ECS_IOCTL_GETDATA #3
<6>[ 2066.783020] --------------------
<6>[ 2066.783477] |    index    |    hdata    |    ddata    |
<6>[ 2066.783935] gflag1|    0    |    0x70    |    112    |
<6>[ 2066.784820] gflag1|    1    |    0x7f    |    127    |
<6>[ 2066.785278] gflag1|    2    |    0xa3    |    163    |
<6>[ 2066.785766] gflag1|    3    |    0x5d    |    93    |
<6>[ 2066.786621] gflag1|    4    |    0x68    |    104    |
<6>[ 2066.787078] gflag1|    5    |    0x86    |    134    |
<6>[ 2066.787567] gflag1|    6    |    0x5c    |    92    |
<6>[ 2066.788421] gflag1|    7    |    0x85    |    133    |
<6>[ 2066.788879] gflag1|    8    |    0x0    |    0    |
<6>[ 2066.789367] gflag1|    9    |    0x0    |    0    |
<6>[ 2066.790222] gflag1|    10    |    0x0    |    0    |
<6>[ 2066.790832] gflag1|    11    |    0x0    |    0    |
<6>[ 2066.791320] gflag1|    12    |    0x0    |    0    |
<6>[ 2066.791778] gflag1|    13    |    0x0    |    0    |
<6>[ 2066.792663] gflag1|    14    |    0x0    |    0    |
<6>[ 2066.793121] gflag1|    15    |    0x0    |    0    |
<6>[ 2066.793579] gflag1|    16    |    0x0    |    0    |
<6>[ 2066.794464] gflag1|    17    |    0xa3    |    163    |
<6>[ 2066.794921] gflag1|    18    |    0x5d    |    93    |
<6>[ 2066.795379] gflag1|    19    |    0x68    |    104    |
<6>[ 2066.796264] gflag1|    20    |    0x86    |    134    |
<6>[ 2066.796722] gflag1|    21    |    0x5c    |    92    |
<6>[ 2066.797210] gflag1|    22    |    0x85    |    133    |
<6>[ 2066.798065] gflag1|    23    |    0x0    |    0    |
<6>[ 2066.798553] gflag1|    24    |    0x0    |    0    |
<6>[ 2066.799041] gflag1|    25    |    0x0    |    0    |
<6>[ 2066.799499] gflag1|    26    |    0x0    |    0    |
<6>[ 2066.800354] gflag1|    27    |    0x0    |    0    |
<6>[ 2066.800903] gflag1|    28    |    0x0    |    0    |
<6>[ 2066.801391] gflag1|    29    |    0x0    |    0    |
<6>[ 2066.802246] gflag1|    30    |    0x0    |    0    |
<6>[ 2066.802703] gflag1|    31    |    0x0    |    0    |
<6>[ 2066.803161] ----------
<6>[ 2066.807067] --> ECS_IOCTL_GET_NUMFRQ
<6>[ 2066.808044] --> ECS_IOCTL_GET_NUMFRQ #3
<6>[ 2066.808502] --------------------
<6>[ 2066.808959] |    index    |    hdata    |    ddata    |
<6>[ 2066.809814] |    0    |    0x1    |    1    |
<6>[ 2066.810302] |    1    |    0x0    |    0    |
<6>[ 2066.810943] ----------
<6>[ 2066.813629] --> ECS_IOCTL_SET_YPR #1
<6>[ 2066.814636] --------------------
<6>[ 2066.815093] |    index    |    hdata    |    ddata    |
<6>[ 2066.815582] gflag2|    0    |    0x55    |    85    |
<6>[ 2066.816467] gflag2|    1    |    0xffffffff    |    -1    |
<6>[ 2066.816925] gflag2|    2    |    0x2    |    2    |
<6>[ 2066.817382] gflag2|    3    |    0x1e    |    30    |
<6>[ 2066.817840] gflag2|    4    |    0x1    |    1    |
<6>[ 2066.818328] gflag2|    5    |    0x0    |    0    |
<6>[ 2066.818786] gflag2|    6    |    0x14    |    20    |
<6>[ 2066.819244] gflag2|    7    |    0xfffffd3b    |    -709    |
<6>[ 2066.820129] gflag2|    8    |    0x11    |    17    |
<6>[ 2066.820770] gflag2|    9    |    0x185    |    389    |
<6>[ 2066.821258] gflag2|    10    |    0xffffffe7    |    -25    |
<6>[ 2066.822113] gflag2|    11    |    0xfffffe20    |    -480    |
<6>[ 2066.822570] ----------
<6>[ 2066.823028] --> ECS_IOCTL_SET_YPR
<6>[ 2066.823913] AKECS_Report_Value: yaw = 85, pitch = -1, roll = 2
<6>[ 2066.824401]                     tmp = 30, m_stat= 1, g_stat=0
<6>[ 2066.825286]           G_Sensor:   x = 20 LSB, y = -709 LSB, z = 17 LSB
<6>[ 2066.825744]                MAG:   MAGV_X = 389, MAGV_Y = -25, MAGV_Z = -480
<6>[ 2066.829833] --> ECS_IOCTL_GET_DELAY
<6>[ 2066.830352] --> ECS_IOCTL_GET_DELAY #3
<6>[ 2067.034759] --> ECS_IOCTL_SET_MODE #1
<6>[ 2067.035705] --> ECS_IOCTL_SET_MODE
<6>[ 2067.036163]  --> AKECS_MODE_MEASURE_SNG
<6>[ 2067.051818] --> ECS_IOCTL_GETDATA
<6>[ 2067.052764] --> ECS_IOCTL_GETDATA #3
<6>[ 2067.053253] --------------------
<6>[ 2067.053741] |    index    |    hdata    |    ddata    |
<6>[ 2067.054595] gflag1|    0    |    0x70    |    112    |
<6>[ 2067.055084] gflag1|    1    |    0x7f    |    127    |
<6>[ 2067.055572] gflag1|    2    |    0xa2    |    162    |
<6>[ 2067.056427] gflag1|    3    |    0x5d    |    93    |
<6>[ 2067.056915] gflag1|    4    |    0x65    |    101    |
<6>[ 2067.057373] gflag1|    5    |    0x86    |    134    |
<6>[ 2067.057861] gflag1|    6    |    0x5b    |    91    |
<6>[ 2067.058715] gflag1|    7    |    0x85    |    133    |
<6>[ 2067.059173] gflag1|    8    |    0x0    |    0    |
<6>[ 2067.059661] gflag1|    9    |    0x0    |    0    |
<6>[ 2067.060577] gflag1|    10    |    0x0    |    0    |
<6>[ 2067.061157] gflag1|    11    |    0x0    |    0    |
<6>[ 2067.061645] gflag1|    12    |    0x0    |    0    |
<6>[ 2067.062500] gflag1|    13    |    0x0    |    0    |
<6>[ 2067.062957] gflag1|    14    |    0x0    |    0    |
<6>[ 2067.063415] gflag1|    15    |    0x0    |    0    |
<6>[ 2067.063873] gflag1|    16    |    0x0    |    0    |
<6>[ 2067.064727] gflag1|    17    |    0xa2    |    162    |
<6>[ 2067.065185] gflag1|    18    |    0x5d    |    93    |
<6>[ 2067.065673] gflag1|    19    |    0x65    |    101    |
<6>[ 2067.066528] gflag1|    20    |    0x86    |    134    |
<6>[ 2067.067016] gflag1|    21    |    0x5b    |    91    |
<6>[ 2067.067474] gflag1|    22    |    0x85    |    133    |
<6>[ 2067.068328] gflag1|    23    |    0x0    |    0    |
<6>[ 2067.068817] gflag1|    24    |    0x0    |    0    |
<6>[ 2067.069274] gflag1|    25    |    0x0    |    0    |
<6>[ 2067.070129] gflag1|    26    |    0x0    |    0    |
<6>[ 2067.070587] gflag1|    27    |    0x0    |    0    |
<6>[ 2067.071136] gflag1|    28    |    0x0    |    0    |
<6>[ 2067.071624] gflag1|    29    |    0x0    |    0    |
<6>[ 2067.072479] gflag1|    30    |    0x0    |    0    |
<6>[ 2067.072937] gflag1|    31    |    0x0    |    0    |
<6>[ 2067.073394] ----------
<6>[ 2067.077880] --> ECS_IOCTL_GET_NUMFRQ
<6>[ 2067.078399] --> ECS_IOCTL_GET_NUMFRQ #3
<6>[ 2067.078857] --------------------
<6>[ 2067.079315] |    index    |    hdata    |    ddata    |
<6>[ 2067.080169] |    0    |    0x1    |    1    |
<6>[ 2067.080657] |    1    |    0x0    |    0    |
<6>[ 2067.081298] ----------
<6>[ 2067.083892] --> ECS_IOCTL_SET_YPR #1
<6>[ 2067.084869] --------------------
<6>[ 2067.085327] |    index    |    hdata    |    ddata    |
<6>[ 2067.085815] gflag2|    0    |    0x54    |    84    |
<6>[ 2067.086700] gflag2|    1    |    0xffffffff    |    -1    |
<6>[ 2067.087158] gflag2|    2    |    0x2    |    2    |
<6>[ 2067.087615] gflag2|    3    |    0x1e    |    30    |
<6>[ 2067.088470] gflag2|    4    |    0x1    |    1    |
<6>[ 2067.088928] gflag2|    5    |    0x0    |    0    |
<6>[ 2067.089416] gflag2|    6    |    0x14    |    20    |
<6>[ 2067.090270] gflag2|    7    |    0xfffffd2b    |    -725    |
<6>[ 2067.090728] gflag2|    8    |    0x11    |    17    |
<6>[ 2067.091400] gflag2|    9    |    0x175    |    373    |
<6>[ 2067.092254] gflag2|    10    |    0xffffffe7    |    -25    |
<6>[ 2067.092742] gflag2|    11    |    0xfffffdef    |    -529    |
<6>[ 2067.093231] ----------
<6>[ 2067.093688] --> ECS_IOCTL_SET_YPR
<6>[ 2067.094543] AKECS_Report_Value: yaw = 84, pitch = -1, roll = 2
<6>[ 2067.095031]                     tmp = 30, m_stat= 1, g_stat=0
<6>[ 2067.095916]           G_Sensor:   x = 20 LSB, y = -725 LSB, z = 17 LSB
<6>[ 2067.096405]                MAG:   MAGV_X = 373, MAGV_Y = -25, MAGV_Z = -529

Index of the things to know about the different ioctl commands

Index of the files that are used by akmd or the kernel

The initialization part

Let's take a look closer at the initialization part: this concerns everything before akmd starts reporting treated values.

So first of all, we have:

<6>[ 2066.362670] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.363220] --> ECS_IOCTL_SET_MODE
<6>[ 2066.364074]  --> AKECS_MODE_E2P_READ

akmd sets the driver mode to AKECS_MODE_E2P_READ. It's not clear about why it's really necessary but it's there anyway, and it's quite easy to reproduce since there is no data treatment on that and that it's now clear that this call does not change depending of external values.

<6>[ 2066.381042] --> ECS_IOCTL_READ #1
<6>[ 2066.381317] what is in rwbuf?
<6>[ 2066.381744] --------------------
<6>[ 2066.382019] |    index    |    hdata    |    ddata    |
<6>[ 2066.382263] |    0    |    0x1    |    1    |
<6>[ 2066.382507] |    1    |    0x42    |    66    |
<6>[ 2066.382934] |    2    |    0x0    |    0    |
<6>[ 2066.383178] |    3    |    0x0    |    0    |
<6>[ 2066.383392] |    4    |    0x0    |    0    |
<6>[ 2066.383636] ----------
<6>[ 2066.384063] --> ECS_IOCTL_READ
<6>[ 2066.384979] --> ECS_IOCTL_READ #3
<6>[ 2066.385253] --------------------
<6>[ 2066.385498] |    index    |    hdata    |    ddata    |
<6>[ 2066.385925] |    0    |    0x1    |    1    |
<6>[ 2066.386169] |    1    |    0x66    |    102    |
<6>[ 2066.386383] |    2    |    0x0    |    0    |
<6>[ 2066.386627] |    3    |    0x0    |    0    |
<6>[ 2066.387054] |    4    |    0x0    |    0    |

This first part (ECS_IOCTL_READ #1) is the request (READ REQ #1) that akmd sends to the kernel and the second part (ECS_IOCTL_READ #3) is the answer (READ ASW #1) it gets. Its length is 1, so all the 0 values are not to be taken in count.
For this, the request is always { 1, 66 } but the answer may not be the same on different devices.

Though, this value seems not to be used used for any of the next requests, but it may still be the case.

<6>[ 2066.387542] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.387786] --> ECS_IOCTL_SET_MODE
<6>[ 2066.388214]  --> AKECS_MODE_POWERDOWN
<6>[ 2066.401031] --> ECS_IOCTL_GET_OPEN_STATUS
<6>[ 2066.401306] --> ECS_IOCTL_GET_OPEN_STATUS #3
<6>[ 2066.407135] --> ECS_IOCTL_INIT
<6>[ 2066.408020] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.408294] --> ECS_IOCTL_SET_MODE
<6>[ 2066.408721]  --> AKECS_MODE_E2P_READ

akmd sets the mode to AKECS_MODE_POWERDOWN, then waits for the kernel to have "open" status. This appears when the accelerometer/magnetometer is requested by the system, so if nothing requests the chip, ECS_IOCTL_GET_OPEN_STATUS
will block until the chip is requested. This also append when the phone is in "sleep" mode.

When ECS_IOCTL_GET_OPEN_STATUS is not blocking (the chip is requested by the system), akmd asks the driver to init the chip, with ECS_IOCTL_INIT. Then, akmd sets the mode to AKECS_MODE_E2P_READ. The reason of that is still unclear.

All this is already implemented in akmd-free.

<6>[ 2066.421234] --> ECS_IOCTL_READ #1
<6>[ 2066.421630] what is in rwbuf?
<6>[ 2066.422302] --------------------
<6>[ 2066.422637] |    index    |    hdata    |    ddata    |
<6>[ 2066.423004] |    0    |    0x3    |    3    |
<6>[ 2066.423339] |    1    |    0x46    |    70    |
<6>[ 2066.423950] |    2    |    0x0    |    0    |
<6>[ 2066.424285] |    3    |    0x0    |    0    |
<6>[ 2066.424621] |    4    |    0x0    |    0    |
<6>[ 2066.424957] ----------
<6>[ 2066.425567] --> ECS_IOCTL_READ
<6>[ 2066.426696] --> ECS_IOCTL_READ #3
<6>[ 2066.427062] --------------------
<6>[ 2066.427398] |    index    |    hdata    |    ddata    |
<6>[ 2066.428039] |    0    |    0x3    |    3    |
<6>[ 2066.428375] |    1    |    0x97    |    151    |
<6>[ 2066.428710] |    2    |    0x87    |    135    |
<6>[ 2066.429321] |    3    |    0x19    |    25    |
<6>[ 2066.429656] |    4    |    0x0    |    0    |
<6>[ 2066.429992] ----------

Here we have a read request, with { 3, 70 } (READ REQ #2) that returns { 3, x, y, z } (READ ASW #2). The answer elements are called x, y, z since these are not constant and my change between devices. We'll refer to these values under the names: READ ASW #2's x, READ ASW #2's y and READ ASW #2's z.

<6>[ 2066.431243] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.431915] --> ECS_IOCTL_SET_MODE
<6>[ 2066.432250]  --> AKECS_MODE_POWERDOWN
<6>[ 2066.450866] --> ECS_IOCTL_WRITE #1
<6>[ 2066.451385] what is in rwbuf?
<6>[ 2066.452239] --------------------
<6>[ 2066.452697] |    index    |    hdata    |    ddata    |
<6>[ 2066.453186] |    0    |    0x4    |    4    |
<6>[ 2066.454040] |    1    |    0xe8    |    232    |
<6>[ 2066.454498] |    2    |    0x7    |    7    |
<6>[ 2066.454956] |    3    |    0x7    |    7    |
<6>[ 2066.455413] |    4    |    0x9    |    9    |
<6>[ 2066.456268] ----------
<6>[ 2066.456726] --> ECS_IOCTL_WRITE

Here akmd sets the mode to AKECS_MODE_POWERDOWN and writes 4 numbers { 4, 232, x, y, z } to the kernel driver. rwbufr1 is always 232 but the other numbers are changing depending on READ ASW #2's values. The formula to get x, y and z from READ ASW #2's values is:
x = (READ ASW #2's x) % 16
y = (READ ASW #2's y) % 16
z = (READ ASW #2's y) % 16

The way to discover that was to determine what makes these values change and how they change depending on READ ASW #2's values. This was easy since the values are also printed in hex format, so (READ ASW #2's x) % 16 is the last number of the hex representation of READ ASW #2's x.

<6>[ 2066.457916] --> ECS_IOCTL_WRITE #1
<6>[ 2066.458374] what is in rwbuf?
<6>[ 2066.459228] --------------------
<6>[ 2066.459686] |    index    |    hdata    |    ddata    |
<6>[ 2066.460174] |    0    |    0x4    |    4    |
<6>[ 2066.460784] |    1    |    0xe5    |    229    |
<6>[ 2066.461669] |    2    |    0x89    |    137    |
<6>[ 2066.462127] |    3    |    0x0    |    0    |
<6>[ 2066.462615] |    4    |    0x89    |    137    |
<6>[ 2066.463073] ----------
<6>[ 2066.463928] --> ECS_IOCTL_WRITE
<6>[ 2066.465698] --> ECS_IOCTL_SET_MODE #1
<6>[ 2066.466186] --> ECS_IOCTL_SET_MODE
<6>[ 2066.467071]  --> AKECS_MODE_MEASURE_SNG

Here is a write request of the type { 4, 229, x, y, z }. x, y and z values seem to be written to akmd_set_values.txt when akmd quits (this should be confirmed), so on the first start of akmd, x, y and z are 0 since there was no previous session to write the numbers on akmd_set_values.txt.

Anyway, setting x, y and z to 0 doesn't prevent anything to work.

Then akmd also sets the mode to AKECS_MODE_MEASURE_SNG.


Android


AndroidSystemKeyMigration

Background information

The releases are currently signed by the individual developers with their personal gpg keys. During the installation procedure, the people installing the images are very strongly advised to check that kind of signatures. This makes sure that the images that are being installed were really made by the developers that signed them, and that they weren't modified since them. This takes care of the security while installing Replicant releases.

When installing Android applications, there is also a similar system in place, where people or organizations building applications sign their applications. When upgrading an application to a newer version, the signature is checked, and if it matches, the new application version can replace the old version and access the data of the previous application version.

Because of that, when building a Replicant release, we have to generate keys to sign the applications that we build and bundle in the Replicant images. This includes applications like the SMS application, the dialer, the launcher/desktop, etc.

What issue are we trying to solve here?

The releases of Replicant 6.0 0001, 0002 and 0003 were all signed by identical keys that were generated by Wolfgang Wiedmeyer.

We don't have access to these keys, so we needed to generate new keys during the build of the images.

However if the keys are not migrated somehow, after the installation, the first boot will never complete, and the second boot will also end up with the launcher/desktop crashing all the time, which not only blocks the usage of the device but also makes it hard to properly shut it down.

How we solved it

We wrote a tool to create a migration script that can be generated from various data (certificates from previous releases, a running image, etc) so that users running custom builds could also migrate back and forth between different images.

We tried various ways to run that script automatically during the first boot, to make it more easy for less technical users to do the key migration, but doing that in a robust way started to be complex as we either had to make the script more complex (and less robust) or lower the security of Android to enable the startup script to delete itself.

So instead we ended up making an extra -transition release to fix that:

Doing the later is really necessary as during prolonged use and testing, we found that running the migration script at every boot was unsafe: if the boot is interrupted during the migration, the file that has has the information about the keys (/data/system/applications.xml) can be corrupted. That leads to non booting devices (users would need to wipe their data to fix that issue).

How to install new Releases

If you are using replicant-6.0-0003, and want to test the Replicant 6.0 0004 release, the easiest way to do it would be to first install a replicant-6.0-0004-rc5-transition image and then a replicant-6.0-0004-rc5 image.

If you are using any Replicant 6 0004 Release candidate (RC) images you also need to do the same thing as all the images before the replicant-6.0-0004-rc5 will either not do any miration or migrate the keys on every boot.

Details on the key sets

For Replicant 6, we have now 3 key sets that have been used for official releases (including RC images):

AntiFeatures

Name Replicant Bug reports Data Scope
Phone number lookup prioviders #1827 #1903 Phone numbers being leaked Companies through Internet
Preferred Network Offload leaks known SSIDs #951 SSID being leaked ~100 meters?

ApplicationsSecurityModel

Warning

This article is a work in progress. It might (still) contain mistakes at this early stage.

Introduction

Android is an operating system currently made mainly by Google and various device manufacturers1 to make money either by selling devices2, selling applications that are not necessarily free software, violating people's right to privacy through applications or online services, etc.

Devices often come with a nonfree applications like Google Play (or equivalent software made for/by device vendors) that steer people toward installing applications, which often are nonfree. This has a huge impact on the security model of the applications.

In GNU/Linux many applications are not sandboxed by default, as most of them are free software and don't necessarily pose any threat to users, unless they are vulnerable to security issues like remote code execution. As they are trustworthy, sometimes the application sandbox themselves: at the beginning, when they start running they have access to many files and resources, and very early on once they are done with the resources (like they read the file content for instance), they sandbox themselves through mechanisms like seccomp or privilege drop. Other mechanism like stack protection implemented in compilers like GCC and in the Linux kernel (for features like ALSR) also help making GNU/Linux secure transparently as it just crash the applications when conditions that create security issues are detected, and/or make it very hard to exploit security issues. The advantage of these measures is that it's completely transparent to users and don't restrict them in any way. However they don't protect against untrustworthy application whose code is not available and malicious.

In contrast, with Android, many people run nonfree applications, some of which try to actively exploit the users through surveillance, manipulation (through advertizing or digital addictions , for instance), or even steal money for malwares that are sometimes present in app stores until they are found and removed by the company managing that appstore.

Probably because of the public pressure and to gain a market advantage, since many of the applications that people run cannot be trusted at all, the Android security model had to be adapted to that. This doesn't fix any of the issues at all but rather limits the potential for damage and the probability of such issues, which are still very present.

This has lead to the sandboxing of applications and the Android permission system which is not always clear nor fine grained enough.

As Replicant is based on Android, we inherit this security model.

Documentation and issues

Applications and keys

Android applications (including system applications like the dialer, default SMS application, etc) have an internal name (like fil.libre.repwifiapp for RepWiFi) and they are signed with keys. So the application with its internal name and its public signature gives it access to some internal storage that is dedicated to that application. This is for instance where the contacts are stored.

This has some consequences:

This also makes backuping applications data more difficult.

System applications

During the build of Replicant, some certificates are generated to sign various applications.

The issue here is that when the developer doing official builds changes, or when users want to run their own build, you end up with different signatures, and the new system applications can't access their data. This can lead to crashes. A Replicant developer verified that by removing all the checks preventing to install of a new Replicant image with system applications signed with different keys: After booting the device, the launcher always crashed, making the device unusable.

Changing signing keys.

Despite the default behavior, it is possible to change the signature expected by an application data. This enables to keep the data of an application while upgrading to a new version of this application that is signed with a new key.

Software to do that is being developed for Replicant.

References:

1 "Developer: Various (mostly Google and the Open Handset Alliance)" from Wikipedia

2 "A group of companies known as the Open Handset Alliance (OHA), led by Google, originated Android. Today, many companies—both original members of the OHA and others—have invested heavily in Android. These companies have allocated significant engineering resources to improve Android and bring Android devices to market." from https://source.android.com/setup#governance-philosophy


Artwork

Download

Replicant artwork: replicant_artwork.tar.gz

Alternatively, the Replicant artwork is also available in the replicant_artwork git repository .

License

Copyright 2011 Mirella Vedovetto
Copyright 2012 Paul Kocialkowski

This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.

Typeface

The typeface used in the Replicant logo is League Gothic, from The League of Movable Type.

Copyright (c) 2010, Caroline Hadilaksono & Micah Rich <caroline@hadilaksono, micah@micahrich.com>, with Reserved Font Name: "League Gothic".

This Font Software is licensed under the SIL Open Font License, Version 1.1.

This is art!

     ___        ___        ___        ___                  ___       ___       ___       ___
    /\  \      /\  \      /\  \      /\__\      ___       /\  \     /\  \     /\__\     /\  \
   /  \  \    /  \  \    /  \  \    / /  /     /\  \     /  \  \   /  \  \   / /| |     \ \  \
  / /\ \  \  / /\ \  \  / /\ \  \  / /  /      \ \  \   / /\ \  \ / /\ \  \ / / | |      \ \  \
 /  \ \ \  \/  \ \ \  \/  \ \ \  \/ /  /       /  \__\ / /  \ \  \  \ \ \  \ /| | |__    /  \  \
/ /\ \ \ \__\/\ \ \ \__\/\ \ \ \__\/__/     __/ /\/__// /__/ \ \__\\ \ \ \__\ | |/\__\  / /\ \__\
\/_|  \/ /  /\ \ \ \/__/  \ \/ /  /\  \    /\/ /  /   \ \  \  \/__/ \ \/ /  /_| / /  / / /  \/__/
   | |  /  /\ \ \ \__\/    \  /  /\ \  \   \  /__/     \ \  \   \/__/\  /  /  |  /  / / /  / 
   | |\/__/  \ \ \/__/      \/__/  \ \  \   \ \__\      \ \  \       / /  /   | /  /  \/__/
   | |  |     \ \__\                \ \__\   \/__/       \ \__\     / /  /   / /  /
    \|__|      \/__/                 \/__/                \/__/     \/__/    \/__/
     ___     ___       ___      ___           ___      ___      ___     ___
    /\  \   /\  \     /\  \    /\__\   ___   /\  \    /\  \    /\__\   /\  \
   /  \  \ /  \  \   /  \  \  / /  /  /\  \ /  \  \  /  \  \  / /| |   \ \  \
  / /\ \  \ /\ \  \ / /\ \  \/ /  /   \ \  \ /\ \  \/ /\ \  \/ / | |    \ \  \
 /  \ \ \  \\ \ \  \  \ \ \  \/  /    /  \__\  \ \  \ \ \ \  \/| | |__  /  \  \
/ /\ \ \ \__\\ \ \__\\ \ \ \__\_/  __/ /\/__/_/ \ \__\ \ \ \__\| |/\__\/ /\ \__\
\/_|  \/ /  / \ \/__//\ \/ /  / \ /\/ /  / \  \  \/__/\ \/ /  /| / /  / /  \/__/
   | |  /  / \ \__\//  \  /  /\  \\  /__/ \ \  \  \/__/\  /  / |  /  / /  / 
   | |\/__/ \ \/__//    \/__/\ \  \\ \__\  \ \  \      / /  /  | /  /\/__/
   | |  |  \ \__\_/           \ \__\\/__/   \ \__\    / /  /  / /  /
    \|__|   \/__/              \/__/         \/__/    \/__/   \/__/

AT

The AT protocol comes from the Hayes command set used in early Internet modems.

It has been standardized by various standard bodies like the ITU, which then handed it over to the 3GPP. It's now the 27.007 standard at the 3GPP.

In practice device manufacturers often don't respect the standard, and instead do custom changes.

However as their implementation is still based on the standard it's still relatively easy to adapt the userspace modem stack to various modem from various manufacturers.

Implementation

In the Replicant contributors meetings of July 2019, the "Replicant and modems: introduction" presentation that talks about the AT protocol.

It can be found in the Presentations section of the Replicant contributors meetings of July 2019 page.

It explains the code architecture of the reference RIL which uses AT commands, simply by following what happen in the actual code.

So it's a good idea to look at it if you intend in supporting devices that uses AT commands, if this is the only usable protocol.

As the AT command set has many limitation (which are explained in the conference as well), if the modem supports more than one protocol, it's often better to implement another protocol instead.


BackupApplications

Backup applications

Backups can be made using oandbackup or adb backup.

If you created a backup of system applications before switching from the factory image or a different Android distribution to Replicant or before an upgrade to a new major release (e.g. from Replicant 4.2 to Replicant 6.0), restoring this backup will cause issues. The installation pages require a factory reset in these cases because the data is incompatible, so a backup of the data is incompatible as well.

SMS and contacts apps usually provide ways to export contacts and messages. Using these means to backup and restore the data will likely be successful and won't result in misbehaving apps.

Syncronization applications

Another way to backup application data is to synchronize them with a remote server.

Several applications can do that: As they require a remote servers, you can either:

BackupsResearch

Introduction

The BackupTheEFS page has instructions to backup the EFS. This page instead tries to document why it is done in that way, and what are the advantages and disadvantages of various other backups methods.

This can also be useful to write more generic backup instructions to do a more complete backup.

Doing the backup of partitions or other block devices

adb shell cat pipe

Old versions of the EFS backup instructions (up to revision 17) used the following command:

adb shell "cat /dev/block/platform/*/by-name/EFS" > EFS.img

At some point or under some condition, this stopped working and the backup were corrupted.

adb shell cat adb pull

With something like that:

adb shell "cat /dev/block/platform/*/by-name/EFS > /EFS.img" 
adb pull /EFS.img ./

Two steps

Doing it in two stages like that seem to be widely used in other instructions (like the ones found in XDA forums).

The advantage is that the '*' enables to use the same command across many more devices.

And we need two steps because the '*' is not interpreted by a shell when using adb pull:

$ adb pull /dev/block/platform/*/by-name/EFS
adb: error: remote object '/dev/block/platform/*/by-name/EFS' does not exist
$ adb pull "/dev/block/platform/*/by-name/EFS" 
adb: error: remote object '/dev/block/platform/*/by-name/EFS' does not exist
$ adb pull '/dev/block/platform/*/by-name/EFS'
adb: error: remote object '/dev/block/platform/*/by-name/EFS' does not exist

See the part on adb-pull-the-block-device for more details on how to workaround the lack of expansion and have only 1 command to do the job.

This method requires the partition to be small enough. Otherwise it will create several issues:

dd

Normally cat should produce a valid backup, however it might be better to use dd for extra safety.

On Replicant 6.0 0004, at least the recoveries for the following devices have 'dd':

adb pull the block device

The following should also work:

adb pull /dev/block/mmcblk0p3 ./EFS.img

The advantage is that it can also backup huge partitions like the user data partition or Replicant system partition.

You cannot do adb pull /dev/block/platform/*/by-name/EFS as the expansion of * will fail.

There are possible workarounds:

part="`adb shell "ls /dev/block/platform/*/by-name/EFS" | head --bytes=-2`" 
adb pull "$part" ./EFS.img

Be aware of the head --bytes=-2 which is needed to get rid of the nasty 0x0d 0x0a line ending returned by adb.
(Tested on Recovery of Replicant 6.0 0003.)

Symlinks and adb push

adb push doesn't handle symlinks properly. For instance, with a Galaxy SIII (GT-I9300) with a Replicant 6 recovery, if we use:

adb pull /dev/block/platform/dw_mmc/by-name/USERDATA ./USERDATA.img

we get the following failure:
adb: error: failed to copy 'USERDATA.img' to '/dev/block/platform/dw_mmc/by-name/USERDATA': remote No space left on device
USERDATA.img: 0 files pushed. 4.3 MB/s (436154368 bytes in 96.842s)

So here no data has been being written on the data partition and it exhausted the ramdisk of the recovery.

This is because instead of writing to that partition, it deleted the /dev/block/platform/dw_mmc/by-name/USERDATA symlink and recreated a file at the same path (/dev/block/platform/dw_mmc/by-name/USERDATA) with the data from USERDATA.img.

Backup applications.

It might be a good idea to have a list of backup applications and/or to ship one with Replicant.

It might also be a good idea to understand if the backup solution chosen is sustainable in the long term: If the development stop or upstream decide to make the new version proprietary some users might have a hard time adapting to new backup applications or systems.


How to backup the data partition

/!\ Warning: Draft

This article is in draft form and is being written:

What does the data partition contains?

See DataPartition for more details.

Howto

Reserve some space

The data partition is often big as it contains space for user data. For instance on the Galaxy SIII (GT-I9300), its size is about 11.5GiB for the 16GiB versions of that device.

If you don't need to know precisely how much space it's going to take, you could make sure that you have as much space as the internal storage. For instance for a Galaxy SIII (GT-I9300) with 16GiB of internal storage, just make sure you have 16GiB of free space.

If instead you need to know the size more precisely (here 11.5GiB), you could look if your device's page has that information in its Partition section. For instance the Galaxy SIII (GT-I9300) wiki page has a Partitions section with the relevant information, but only for the 16GiB version of that device.

Setup ADB

Follow the instructions for setting up ADB on your computer so that you can access a root shell on your device.

NOTE: when prompted on your Replicant device, make sure that you check the box that says Always allow from this computer when you grant your computer USB debugging permissions. Otherwise, you will be unable to obtain root shell access on your Replicant device when you reboot it into the recovery OS to actually perform the backup.

NOTE: for security reasons, you may want to revoke these non-expiring permissions once the backup is complete.

Reboot into the recovery

To reboot in the recovery, you can follow the instructions in the RebootIntoTheRecovery wiki page.

Making sure that the data partition isn't mounted

First, you need to make sure that the data partition is not mounted.

To do that, you can run this command:

adb shell "umount -l /data" 

If the /data partition was mounted, it will unmount it, and your command and its output will look more or less like that:

$ adb shell "umount -l /data" 
$ 

If it was not mounted, it will instead show an error that we can ignore. In this case your command and its output will look more or less like that:

$ adb shell "umount -l /data" 
umount: /data: Invalid argument

Backing up the data partition

Once we verified that the data partition isn't mounted, we can finally backup the partition.

Galaxy SII (GT-I9100) and Galaxy Note (GT-N7000)

For the Galaxy SII (GT-I9100) and the Galaxy Note (GT-N7000), this can be done from your computer with this command:

adb pull /dev/block/platform/dw_mmc/by-name/DATAFS ./USERDATA.img

Galaxy S III (GT-I9300, GT-I9305), Galaxy Note II (GT-N7100) and Galaxy Note 8.0 (GT-N51xx)

For the Galaxy S III (GT-I9300), Galaxy S III 4G (GT-I9305), Galaxy Note II (GT-N7100), and Galaxy Note 8.0 (GT-N51xx) you can use the following command:

adb pull /dev/block/platform/dw_mmc/by-name/USERDATA ./USERDATA.img

Galaxy Nexus (GT-I9250)

For the Galaxy Nexus (GT-I9250), you can use the following command:

adb pull /dev/block/platform/omap/omap_hsmmc.0/by-name/userdata ./USERDATA.img

Galaxy Tab 2 (GT-P3100, GT-P3110, GT-P5100, GT-P3510)

For the Tab 2 (GT-P3100, GT-P3110, GT-P5100, GT-P3510), you can use the following command:

adb pull /dev/block/platform/omap/omap_hsmmc.1/by-name/DATAFS ./USERDATA.img

Other devices.

We don't have instructions yet for other devices yet.

Feel free to request instructions for the device you have on IRC, the mailing list, or to add the instructions here if you're confortable enough with the command line.

Using the backup

Restoring the partition

Finding the real path of the partition

Before we did command like that to backup the device:

adb pull /dev/block/platform/dw_mmc/by-name/USERDATA ./USERDATA.img

However if we use the following command:

adb push USERDATA.img /dev/block/platform/dw_mmc/by-name/USERDATA

It will fail to write any data to the partition: Instead of writing to it, it deletes the /dev/block/platform/dw_mmc/by-name/USERDATA symlink and recreate a file at the same path with the data from USERDATA.img.

Since no data is being written on the disk, it most often ends up exhausting the ramdisk of the recovery (which is smaller than the data partition) and we are left with this error:

adb: error: failed to copy 'USERDATA.img' to '/dev/block/platform/dw_mmc/by-name/USERDATA': remote No space left on device
USERDATA.img: 0 files pushed. 4.3 MB/s (436154368 bytes in 96.842s)

So to avoid that we will need to find the path that symlink points to.

The sections below documents how to do if for various devices.

You should also really not skip that part, and make sure that the commands in these sections don't output any error.

Galaxy SII (GT-I9100)

For the Galaxy SII (GT-I9100), we can get the symlink path with the following command:

adb shell "readlink /dev/block/platform/dw_mmc/by-name/DATAFS" 

On my Galaxy SII (GT-I9100), 16GiB version, it gives the following:

/dev/block/mmcblk0p10

Galaxy SIII (GT-I9300)

For the Galaxy SIII (GT-I9300), we can get the symlink path with the following command:

adb shell "readlink /dev/block/platform/dw_mmc/by-name/USERDATA" 

On my Galaxy SIII (GT-I9300), 16GiB version, it gives the following:

/dev/block/mmcblk0p12

You will then need to down the result (here /dev/block/mmcblk0p12) as we will reuse it later.

Galaxy Nexus (GT-I9250)

For the Galaxy Nexus (GT-I9250) We can get the symlink path with the following command:

adb shell "readlink /dev/block/platform/omap/omap_hsmmc.0/by-name/userdata" 

Other devices

We don't have instructions yet for other devices yet.

Feel free to request instructions for the device you have on IRC, the mailing list, or to add the instructions here if you're confortable enough with the command line.

Do not skip the sections above

If you skip the sections above and use the wrong partition, for instance if you blindly copy /dev/block/mmcblk0p12 from this tutorial instead of running the commands above and copying the result of these commands, you could end up breaking your device because some partitions are really needed for the device to work.

So make sure to do that right.

This is also why we have backup instructions (like BackupTheEFS ) to backup important partitions, however other partitions than the EFS are probably crucial too (but less susceptible to data corruption as they are not constantly written to).

Actually restoring the partition

To restore the data partition, you could use the following command:

adb push USERDATA.img /dev/block/PARTITION

Make sure to replace /dev/block/PARTITON with the data you just wrote down. The example above uses /dev/block/mmcblk0p12, but it might differ for your device, so make sure to replace /dev/block/mmcblk0p12 with the result you got on your device.

If everything goes fine, the output of the command above should look like this:

USERDATA.img: 1 file pushed. 3.6 MB/s (1760559104 bytes in 466.067s)

Restoring individual application data.

Here we will use the udisksctl command instead of the more classical mount and losetup as it integrates better with graphical environments like Gnome or KDE.

As the partition backup is now in a file, to access its data we will make it available as a partition again. This can be done with the following command:

udisksctl loop-setup -f  USERDATA.img

If that doesn't work you might need to use sudo like that:

sudo udisksctl loop-setup -f  USERDATA.img

Or you may also need to verify that your current users has the right to read and write the file that contains the partition (here USERDATA.img) file.

If this works, it should produce an output that looks more or less like that:

Mapped file USERDATA.img as /dev/loop0.

Here you can see that it made the file content available in the /dev/loop0 partition.

We can then reuse this information to mount that partition. We can do that with the following command:

udisksctl mount -b /dev/loop0 -o ro

The -o ro option will make sure that the partition is mounted in read only mode. This will make sure that we don't accidentally change its content.

The command above should produce an output that looks more or less like that:

Mounted /dev/loop0 at /run/media/gnutoo/2Of967c7-ac7e-7ae0-ef5b-30f0b6e2dc41

It most probably change a bit from the output above as:

You can write down the location of the directory where this partition is mounted (here /run/media/gnutoo/2Of967c7-ac7e-7ae0-ef5b-30f0b6e2dc41) as we will need it later on.

We will also reuse the partition location (here /dev/loop0) at the end.

Now that this partition is mounted, we will be able to use the RestoreApplicationInternalData tutorial to make a backup of the data of a specific application and restore it.

To do that, locate the following command in the Backuping Silence's data from the old device section of the RestoreApplicationInternalData wiki page:

cd /data/data

You will then need to replace it by a command that looks like that:

cd /run/media/gnutoo/2Of967c7-ac7e-7ae0-ef5b-30f0b6e2dc41/data/

In the command above, you'll need to replace /run/media/gnutoo/2Of967c7-ac7e-7ae0-ef5b-30f0b6e2dc41/ by the location of the directory where the partition is mounted.

In addition you might not have the permissions to access the applications data.

For instance we can look at the permissions of the silence data with the following command:

ls -ld org.smssecure.smssecure/

And it should give you something that looks more or less like that:

drwxr-x--x 9 10063 10063 4096 26 oct.  19:44 org.smssecure.smssecure/

See the How to find which directory holds the internal data of an application section in the RestoreApplicationInternalData wiki page for more details to understand why org.smssecure.smssecure directory has the Silence application's data.

In the output above, the first 10063 is the user ID and the second 10063 is the group id.

This is because Android sandboxes applications as part of their security model: each applications run in their own user and group ID. The result is that theses are most likely present on your phone but not on your GNU/Linux computer.

To fix that you can become root with the following command:

sudo su

Now you can then continue to follow the RestoreApplicationInternalData tutorial.

Unmount and close the loop

Once you are finished with the RestoreApplicationInternalData tutorial, it would be a good idea to umount the data partition and make it inaccessible again.

To umount the data partition we can use a command that looks like that:

udisksctl unmount -b /dev/loop0

Here the /dev/loop0 may differ, so make sure to use the partition location you used earlier.

The output of that command will look like that:

Unmounted /dev/loop0.

Once it is unmounted you can make it inaccessible again with the following command:

udisksctl unmount -b /dev/loop0

Again here may will need to replace /dev/loop0 by your partition location if it differs.

The output of that command should then show something that looks like that:

Unmounted /dev/loop0.

See also


How to backup the EFS

Many devices supported by Replicant have a partition with the modem data (IMEI, etc) which is called EFS.

It's a good idea to do a backup of this partition so that you can restore it if it becomes corrupted, which can sometimes happen with Replicant.

The actual backup process is run while the Replicant recovery is booted (rather than Replicant itself) to ensure that the modem data partition is not modified during the backup.

Prerequisites

Ensure that your device has a modem data partition

Only the following devices that are supported by Replicant have a modem data partition (EFS):

If your device is not listed above, it probably doesn't have a modem data partition. In that case, you don't need to backup something that doesn't exist, so you can ignore these instructions.

This can be the case for devices without a modem like the WiFi versions of the tablets supported by Replicant, or for future devices that aren't supported yet at the time of writing.

Setup ADB

Follow the instructions for setting up ADB on your computer so that you can access a root shell on your device.

NOTE: when prompted on your Replicant device, make sure that you check the box that says Always allow from this computer when you grant your computer USB debugging permissions. Otherwise, you will be unable to obtain root shell access on your Replicant device when you reboot it into the recovery OS to actually perform the backup.

NOTE: for security reasons, you may want to revoke these non-expiring permissions once the backup is complete.

Reboot into the recovery

To reboot in the recovery, you can follow the instructions in the RebootIntoTheRecovery wiki page.

Ensure that your device's system partition is mounted

In order to get a root shell in the recovery, your devices system partition must be mounted.

On certain devices, the system partition is already mounted, so you might already be able to get a root shell without mounting the system partition again.

In any case, it's still best to do the following to make sure that the system partition is mounted:

  1. Select Advanced.
  2. Select Mount /system.
  3. Press the back key to get back to the general menu.

Copy and pasting commands

The next sections will have commands that you can copy and paste. To ensure that they work correctly it's best to:

Also to make sure that they are really executed, you can press the 'enter' key after having pasted them.

Pressing 'enter' twice will not hurt as the command will still be executed only once.

Backup the modem data partition

First, create a directory on your computer where you will store the backup data. One way to keep this data organized is with a directory for each device named with its serial number (useful if you have more than one Replicant device):

You can do this with the following commands:

REPLICANT_EFS_BACKUP_DIR=~/replicant_devices/0123456789abcdef/backup_efs
mkdir -p $REPLICANT_EFS_BACKUP_DIR && cd $REPLICANT_EFS_BACKUP_DIR

The remaining steps you must take depends on which device you have.

Galaxy S 2 (GT-I9100), Galaxy S III (GT-I9300), Galaxy S III 4G (GT-I9305), Galaxy Note (GT-N7000), or Galaxy Note II (GT-N7100), Galaxy Note 8.0 GSM (GT-GT-N5100)

While inside the backup directory you just created, run the following commands:

adb shell "mkdir /efs" 
adb shell "mount /dev/block/platform/*/by-name/EFS /efs" 
adb pull /efs/ efs
adb shell "umount /efs" 
adb shell "rmdir /efs" 
adb shell "cat /dev/block/platform/*/by-name/EFS > /EFS.img" 
adb pull /EFS.img ./

Galaxy Nexus (GT-I9250)

While inside the backup directory you just created, run the following commands:

adb shell "mkdir /efs" 
adb shell "mount /dev/block/platform/*/*/by-name/efs /efs" 
adb pull /efs/ efs
adb shell "umount /efs" 
adb shell "rmdir /efs" 
adb shell "cat /dev/block/platform/*/*/by-name/efs > /efs.img" 
adb pull /efs.img ./

Galaxy Tab 2 7.0 (GT-P3100)

While inside the backup directory you just created, run the following commands:

adb shell "mkdir /efs" 
adb shell "mount /dev/block/platform/*/*/by-name/EFS /efs" 
adb pull /efs/ efs
adb shell "umount /efs" 
adb shell "rmdir /efs" 
adb shell "cat /dev/block/platform/*/*/by-name/EFS > /EFS.img" 
adb pull /EFS.img ./

This will create a copy of the contents of /efs in the backup directory. It will also backup the full partition.
Keep these files around as a backup in case anything goes wrong.

NOTE: if your device has an EFS and is not mentioned in the instructions above, please contact us through the mailing list so we could add instructions for your device.

Reboot your device

Once the backup is done, you can reboot your device into Replicant by one of two ways.

You can reboot by running the following command on your computer:

adb reboot

Or alternatively you can use the Replicant recovery graphical user interface to reboot by selecting Reboot system now.

Revoke USB debugging permissions

If you don't need USB debugging permissions anymore, it might be a good idea to remove them. The Revoking all computer's USB debugging permissions section in the ADB wiki page explains how to do that.

That's it! Your device's EFS partition is now backed up. Your device should be running Replicant normally again.

See also


BCM4751

corresponding feature request: #1473

Factory image files

The non-free files holding the GPS infos/code are the following:

/system/vendor/bin/gpsd
/system/vendor/lib/hw/gps.s5pc110.so
/system/vendor/etc/gps.xml
/system/etc/gps.conf

gps.xml parameters

We have tried to change some parameters in gps.xml to see how it behaves:

Parameter Original Changed to Result
acPortName /dev/s3c2410_serial1 /dev/s3c2410_serial42 The chip wasn't "booted"
gpioNStdbyPath /sys/class/sec/gps/GPS_PWR_EN/value /sys/class/sec/gps/GPS_PWR_EN/value2 The chip was booted
gpioNResetPath /sys/class/sec/gps/GPS_nRST/value /sys/class/sec/gps/GPS_nRST/value2 The chip was booted

After all, it seems that when the gpsd binary is running without the gps.s5pc110.so library, the chip isn't started (our test utility doesn't work) whereas when the library is running and connects to the socket when it is created by starting gpsd, the chip is booted.

gps.s5pc110.so will actually order bootup via the socket, when the gps is requested by the Android framework. When it's not used anymore, it will request poweroff as well.

Protocol

According to the logs obtained from gpsd, the chip seems to be using the MEIF protocol at first, then a patch is sent and it starts using another protocol, which doesn't seem related to MEIF according to the logs (there are basically no more references to MEIF after uploading the patch). However, as we have no information about what MEIF is (it's a binary proprietary undocumented protocol), these are just guesses.
We decided to implement the first protocol under the name MEIF, but it could also be some sort of BCM4751-specific bootloader protocol that is in charge of making the patch upload.

The GPSD component is in charge of translating the second protocol to standard NMEA that is sent to the gps.s5pc110.so lib via the /dev/socket/gps Unix socket, created by GPSD.

Devices

Here is a list of the devices that are known to use the BCM4751 chip:

Device Vendor BCM4751 revision
Nexus S Google/Samsung 4751A1 or 4751A2
Note N 7000 Samsung ?
Galaxy S I9000 Samsung 4751A2
Galaxy S 3 I9300 Samsung 47511A0
Galaxy Tab P1000 Samsung ?
Galaxy Tab 8.9 P7300/P7310 Samsung 4751A2
Nexus 7 Google/Asus 4751A2

The BCM4751 chip exists under the following revisions: 4751A0, 4751A1, 4751A2, 47511A0

Free software implementation

On January 2012, the work to write a free software implementation that could handle the BCM4751 chip was started.
The main target is the Nexus S, even though it should work with few changes on other BCM4751 devices.

The source code is available at: https://git.replicant.us/contrib/PaulK/bcm4751/

Current status

Part Status Comments
Serial setup DONE Magic is: termios.c_cflag = 0x800018b2;
MEIF parsing DONE
MEIF dispatch DONE
MEIF patch upload DONE Nexus S and Galaxy S patches differ

Utilities

Name Task Arguments
bcm4751_gpsd Main utility, boots the chip, send the patch, switch protocol None
bcm4751_test Deprecated utility, can be used for poweroff stop: poweroff the chip
bcm4751_hal Acts as the framework: permits to trace gps.s5pc110.so None
bcm4751_daemon Acts as (a fake) gpsd to the lib None
bcm4751_lib Acts as (a fake) lib to gpsd None

BCM4751 gpsd

This is where MEIF is implemented. It currently does the following:

Sample output log:

Turning the GPS on...
Opening the GPS serial...
Sending autobaud...
Read 17 bytes
Read 32 bytes
MEIF message: MEIF_STATE_REPORT_MSG with 18 bytes of data:
[0000]   01 00 00 00 01 00 00 00   00 00 00 00 00 00 00 00   ........ ........
[0010]   1A 00                                               ..
Got a STATE_REPORT message

Read 23 bytes
Read 32 bytes
Read 16 bytes
Read 7 bytes
MEIF message: MEIF_CONFIG_VALUES_MSG with 70 bytes of data:
[0000]   02 00 01 00 01 00 40 00   01 00 02 00 00 00 00 00   ........ ........
[0010]   01 00 02 00 00 00 00 00   00 00 06 00 81 11 00 09   ........ ........
[0020]   07 07 D9 07 42 52 4F 41   44 43 4F 4D 00 00 00 00   ....BROA DCOM....
[0030]   00 00 00 00 34 37 35 31   41 31 00 00 00 00 00 00   ....4751 A1......
[0040]   00 00 00 00 B3 05                                   ......
Got config values:
    vendor: BROADCOM
    product: 4751A1

Sending the first part of the patch...
Sending 2054 bytes!
MEIF message: MEIF_SEND_PATCH_MSG with 2046 bytes of data:

Read 14 bytes
MEIF message: MEIF_NACK_MSG with 6 bytes of data:
[0000]   03 00 03 00 0F 00                                   ......
Got a NACK message
Reason is: MEIF_NACK_GARBAGE_RECEIVED

Read 12 bytes
MEIF message: MEIF_ACK_MSG with 4 bytes of data:
[0000]   04 01 0B 00                                         ....
Got an ACK message

Sending the second part of the patch...
Sending 706 bytes!
MEIF message: MEIF_SEND_PATCH_MSG with 698 bytes of data:

Read 12 bytes
MEIF message: MEIF_ACK_MSG with 4 bytes of data:
[0000]   05 02 0D 00                                         ....
Got an ACK message

Ready to switch protocol!
Sending unknown bytes!
Read 12 bytes:
[0000]   FE 00 FD 40 00 00 F1 B1   12 20 67 FC               ........ ..g.

BCM4751 patch

In order to use the same protocol as the non-free gpsd, a patch needs to be sent. It is hardcoded in the non-free gpsd binary.
Note that we don't know what that patch exactly is nor what it does. In any case, it must be considered as the propriety of Broadcom (or Samsung maybe) and falls under the non-free gpsd license.

Here are notes on how to extract the patch from various non-free gpsd binaries:
Device Source GPSD MD5 Offset Length dd command
Nexus S CM 9.0.0 4a6c0027e530b5b8a346153a355ef8e3 0x15DDEA 2738 bytes dd skip=1433066 count=2738 if=gpsd of=bcm4751a1.fw bs=1
Galaxy S CM 9.1.0 4a6c0027e530b5b8a346153a355ef8e3 0x15E89E 6406 bytes dd skip=1435806 count=6406 if=gpsd of=bcm4751a2.fw bs=1

The bcm4751_gpsd utility will attempt to read the patch from /data/bcm4751a1.fw or /data/bcm4751a2.fw

Post protocol switching

Sending this string:
"\xfe\x00\xfd\x6f\x3a\x01\x00\x00\x00\x00\x34\xfc"
many times makes some other string appear on the serial port...

fe 00 fd 0f ff 07 06 00 00 01 54 fc
fe 00 fd 0f ff 08 06 00 00 01 1c fc

Here's the decoding of the first bytes:
ff00 = 8bytes
fe00 = 12bytes
fe01 = 16bytes
fe02 = 20bytes
fe03 = 24bytes
fe04 = 28bytes
fe05 = 32bytes
fe06 = 36bytes
fe07 = 40bytes

howto
run that python program:
print "\xfe\x00\xfd\x6f\x3a\x01\x00\x00\x00\x00\x34\xfc" 

like that
python foo.py > serial.txt

adb push serial.txt /sdcard/

on target:
hexdump -C /dev/s3c2410_serial1

cat /sdcard/serial.txt > /dev/s3c2410_serial1

BCM4751protocol

This page contains data copied from BCM4751.

Post protocol switching - receiving

Byte content
1 length 1 fe fe fe
2 length 2 00 00 00
3 fd fd fd
4 40 0f 0f
5 00 ff ff
6 sequence nr. 00 07 08
7 F1 06 06
8 B1 06 06
9 12 00 00
10 20 01 01
11 checksum 67 54 1c
12 end marker fc fc fc

Post protocol switching - sending

Byte content
1 length 1 fe
2 length 2 00
3 fd
4 6f
5 3a
6 sequence nr. 01
7 00
8 00
9 00
10 00
11 checksum 34
12 end marker fc

more details about the bytes

sequence 0 receiving

Ready to switch protocol!
Sending unknown bytes!
Read 12 bytes:
[0000]   FE 00 FD 40 00 00 F1 B1   12 20 67 FC               ........ ..g.

sequence 7,8 receiving, sending unknown string seq 01

Sending this string:
"\xfe\x00\xfd\x6f\x3a\x01\x00\x00\x00\x00\x34\xfc" 
many times makes some other string appear on the serial port, sequence 7,8.

Bootloader interfaces

Device Bootloader cmdline from boot.img cmdline from bootloader environment Compatible with upstream Linux Flashing protocols Image formats filesystems Loads a TrustZone OS
N/A upstream u-boot ? Yes Yes * DFU
* Fastboot
* Thor1
* Other?
* Android Boot.img files
* U-boot uImages
* RAW / zImage
* Other
Yes, various Not on 32bit ARM
N/A upstream Barebox ? Yes Yes * DFU
* FAstboot
* Other?
* Android Boot.img files ?
* U-boot uImages
* RAW / zImage
* Other
Yes, various Not on 32bit ARM
Galaxy S (GT-I9000) GTI9000Bootloader ? * Thor1 * RAW / zImage RAW, KERNEL partition only Probably not
Galaxy SII (GT-I9100) GTI9100Bootloader Probably not * Thor1 * RAW / zImage RAW, ? partition only Probably not
Galaxy SII (GT-I9100G_CHN_CHN) GTI9100GBootloader ? * Very unreliable2 Thor1 ? RAW, KERNEL partition only ?
Galaxy Nexus (GT-I9250) I9250Bootloader used ignored ? * Reliable3 Thor1
* Fastboot
* boot.img boot and recovery partitions only ?
Galaxy SIII (GT-I9300)
Galaxy SIII 4G (GT-I9305)
Galaxy Note II (GT-N7100)
Galaxy Note II 4G (GT-N7105)
MidasBootloader ignored used No * Somewhat reliable4 Thor1 * boot.img RAW, BOOT and RECOVERY partitions only
GT-N5100Bootloader Yes, And the OS is nonfree and signed!
Galaxy Note (GT-N7000) GTIN7000Bootloader ? * Thor1 * RAW / zImage RAW, KERNEL partition only ?
Galaxy Tab 2 7.0 GSM (GT-P3100) GalaxyTab2BootloaderInterface ignored Yes6? * Thor1 * boot.img RAW, KERNEL and RECOVERY partitions only ?
PinePhone v1.1 Braveheart (stock?[5]) u-boot PinePhoneBraveheartBootloader ? Yes Yes (u-boot) ? ? ? Probably (arm64), fully free software

1 Thor is the protocol used by Heimdall, Odin, u-boot and several nonfree bootloaders. u-boot has a free software

2 It didn't work on GNUtoo desktop computer at all, while it worked fine on his laptop. With the stock Android 2.6.3 bootloader you could also end up stuck on the PC screen without a computer where heimdall works fine.

3 Under IO (disk or SSD) load, a computer can easily flash SYSTEM or even DATA partitions with heimdall.

4 Under IO (disk or SSD) load, a computer typically fails at flashing SYSTEM or big DATA partitions with heimdall. Boot and recovery partitions are typically fine though.

5 Someone lent me a Pinephone Braveheart and beside testing many distributions, nothing low level was attempted when I got it.

6 Boots upstream with custom dts without patches, unknown if it works for all build configurations (like CONFIG_STACKPROTECTOR_PER_TASK=y)

See also


Bootloaders


Bootloaders

Introduction

In order to run free software bootloaders, we need the ability to run the code we want at boot. However in most smartphones and many tablets use code signature at boot, which prevent us to run free software bootloader.

This usually works by hardcoding the hash of a public key either in the rom code that loads the bootloader, or in one time programmable fuses that are then used by the rom code to check the bootloader.

If the signature don't match, the bootloader is not executed, so the device can't boot.

In practice:

Devices configurations

Device and documentation Bootloader freedom situation Boot order
Samsung Nexus S (GT-I902x) Proprietary, Signed on the tested devices ?->USB->?->eMMC->?
Samsung Galaxy S2 (GT-I9100) Proprietary, probably Signed ?
Samsung Galaxy S2 (GT-I9100G) Signed on some devices
No unsigned devices found yet
?
Samsung Galaxy Tab 2 Proprietary, signed ?->USB->?->eMMC->?
LG Optimus black (p970) Unsigned, can be replaced with upstream u-boot eMMC(MMC2)->USB
Galaxy SIII (I9300)
Galaxy SIII 4G (I9305)
Galaxy Note II (N7100)
Galaxy Note II 4G (N7105)
* Proprietary, Signed
* There is work in progress to understand if we can avoid bypass the signature checks
?->eMMC->?->USB->?
Golden Delicous GTA04 Unsigned, free software * Aux not pressed during boot: ?
* Aux pressed during boot: ?->SD->?->NAND
SYS_BOOT0 = 1
SYS_BOOT1 = 1
SYS_BOOT2 = 1
SYS_BOOT3 = 1
SYS_BOOT4 = 1
SYS_BOOT5 = AUX button
SYS_BOOT6 = 1
But cannot find Reference manual for the DM370
Pinephone Unsigned free software
Librem5 Unsigned bootloader, nonfree DDR4 controller firmware
Other devices with free software and unsigned bootloaders: Other:

System on a chip

SOC and documentation Freedom situation
OMAP * No known bug
* Some devices are not signed
* Undocumented? (probably a very good sign if it's the case)
Exynos 4 * Some or all devices are signed
* work in progress to understand if it's possible to bypass the signature
Exynos 8890 and 8895 * Boot from USB is possible thanks to exynos-usbdl (documentation)
BroadcomVideoCore The SOCs have the ability to check signatures
TegraBootrom * Not all devices use code signature
* Boot from USB is possible thanks to fusee_gelee
* Code can be appended to the bootrom by writing in a fuse area. Could that be used to disable code signature ?
IMX 5 and 6 * Not all devices are signed
* Thanks to Ref_QBVR2017-0001.txt it's possible to bypass signatures anyway, and maybe load code through USB too

Tools

Some of the tools below can also be used to find devices that don't have restricted boot.

Tool Uses supported hardware Pakckages Howto
omap-usb-boot * checking if the device is has restricted boot
* Loading bootloaders from USB
* booting on a different boot media
OMAP3, OMAP4, OMAP5 Parabola , Archlinux through AUR * check if the device has restricted boot through USB
omap-u-boot-utils * Loading bootloaders from USB
* Loading bootloaders from the UART
OMAP3, OMAP4 Parabola , Archlinux through AUR ?
crucible * checking fuses settings i.MX53, i.MX6DL, i.MX6DQ, i.MX6SL, i.MX6SLL, i.MX6SX, i.MX6UL, i.MX6ULL, i.MX6ULZ, i.MX7D, i.MX7ULP TODO TODO
cbootimage * Generate images
* Dump images (including signatures?)
Tegra ? Parabola , Archlinux through AUR
tegrarcm * Load bootloaders from USB Tegra ? TODO TODO
0xFFFF * Load signed bootloaders (-c) from USB OMAP3430 and OMAP3630
Might be easy to add more OMAP3 by just commenting code in cold-flash.c
TODO, patch for libusb1 TODO
sunxi-tools ? Allwinner SOCs? Parabola, Archlinux TODO
ifdtool * Check if there is a Management Engine firmware Intel x86 ? ?
intelmetool * Check if there is a Management Engine firmware, check if the BIOS region is signed (Bootguard) Intel x86 ? ?
TODO:

Links to cathegorize:

TODO

See also

BootloaderIncompatibleWithLinux

Devices with the Exynos 4412

Introduction

The bootloader of the following devices is incompatible with upstream Linux: When jumping to Linux, the booloader still has: Documentation/arm/booting.rst which is there since 2003 states that:

And upstream Linux won't accept patches to disable the MMU, or the data cache in Linux as they have very good reasons to do that, and they are supposed to be already disabled.

Supporting s-boot

To workaround that we need to: However as the kernel evolved we needed to patch it more and more:

So it's not a viable option in the long run.

Devices with the Exynos 4412

The bootloader of the following devices seems1 to be incompatible with upstream Linux:

However we don't have details yet on what is wrong there (caches, MMU, etc).

1 from #replicant on freenode: <pcercuei> I'm trying to boot a mainline kernel [on the GT-I9100], for some reason it only works if I boot it with u-boot

Longer term options

As u-boot disables the instruction cache in the boot commands before jumping to Linux, we might be able to replace the boot.img by u-boot to workaround the stock bootloader issues.

Having u-boot would also enable many benefits, such as the ability to have Replicant images that run on multiple devices.

As u-boot is capable of running in different ways, when upstreaming the code we will need to make sure that it can run as boot.img but also in other ways depending on the device.

For instance on midas, u-boot can also run with the nonfree and non-redistributable BL1. So it might be interesting to support that as well with the same code because:

We will track the upstreaming status for midas in this bug: #2050


BroadcomVideoCore

Devices

The Raspberry PI don't use code signature, but smartphones using the same SOC may have it enabled.

IRC Logs to sort

03:00 < clever> ive also cracked the signing keys on the rpi4 fully, and now know how they get generated
03:01 < clever> so i could (in theory) re-extract them from another broadcom product in the future, with less effort
[...]
03:01 < clever> assuming i get execute on the VPU somehow
[...]
03:03 < clever> basically, there is 20 bytes of "salt" in the mask rom, which gets combined with 16 bytes from the OTP, to create the real 20byte hmac-sha1 
                key
03:04 < clever> you need to understand how .data gets copied from rom->ram (since its an XIP rom), and then find the code that merges the 2, to know what 
                offset in ram to read
[...]
03:08 < clever> GNUtoo: but, ive also heard that the 2nd revision of the mask rom, has proper pub/priv RSA support
03:08 < clever> if they choose to turn that on, we are screwed
[...]
03:15 < clever> all of the broadcom chips in the pi's, have ~60 OTP registers, each 32 bits wide
[...]
03:16 < clever> got a total of ~268 bytes of OTP
03:16 < clever> for*
[...]
< clever> GNUtoo: i do also have some new info on the rpi4 mask rom boot order, that you might 
                want in the wiki
03:19 < clever> GNUtoo: the rpi4, can boot from 3 places, in this order: #1 recovery.bin on the SD card, 
                #2 a tagged blob in SPI flash, #3 usb-device boot
03:19 < clever> GNUtoo: but, you can use OTP to configure any gpio pin, to disable #1 or #2 (and you can 
                set 2 pins, one for each)
[...]
03:22 < clever> 2020-02-21 16:25:14 < clever> for extra confusion, there are 2 sets of numbers for each SoC
03:22 < clever> 2020-02-21 16:27:12 < clever> ali1234: 2838 and 2711 are both rpi4
03:22 < clever> 2020-02-21 16:27:47 < clever> ali1234: 2835 and 2708 are rpi1, i think
03:22 < clever> so the rpi4 is called both bcm2838 and bcm2711
03:22 < clever> i think one is for the base model, and then the other for this specific implementation of the silicon and package

BrokenHardware

Introduction

When certain hardware feature break (like buttons for instance), Replicant can remains perfectly usable, however if something goes wrong, it could prevent users from being able to recover their devices or data.

Volume up button

On several devices, the volume up button is used for several things:

If the volume up button is broken on a device that uses it for the things mentioned above, then it will be complicated to recover it.

Sometimes it's still possible to do it by disassembling the device and shorting the connector that is used to connect to the button.

Volume down button

On several devices, the volume down button is used to go in download mode.

So without it:

USB connector

If the USB connector cannot be used to charge anymore, it might still be possible to charge batteries with external chargers. Some phones dock for instance have that feature. We don't know if data works or not when only the charging pins are broken.

If instead the device has no working data this could lead to additional issues as it is needed for several features:

For devices that don't have a microSD slot, installing Replicant becomes even more complicated.

Galaxy Tab 2 USB cable

If your USB cable is broken it is best to replace it as you won't be able to use adb at all otherwise.

But with an USB OTG adapter and a male<->male USB cable you could at least manage to get heimdall working: Unlike Linux, the bootloader doesn't the USB port to host mode when an OTG adapter is plugged, so you could abuse that to install a Replicant recovery for instance. Still by default, Replicant recoveries will switch the port to host mode when an OTG cable is detected. So you'll probably need to modify the recovery kernel if you want adb.

Battery

Over time, batteries tend to keep less and less charge. So it last less long in hours. When that happens, they also might make the phone reboot or power off when it tires to use too much current at once.

If the phone shuts down at the wrong moment, it could be dangerous for the device:

So try to keep working batteries to avoid issues.

Display

You might be able to install a recovery image without a working display, however enabling adb in Replicant will be too complex for most people without a screen.

Howeve it's still possible to modify boot.img and recovery images to add a root shell inside it.

It might also be interesting to find out if it's possible to use some assistive technology (like text to speech) to operate a phone without a working display.


BuildEnvironments

Rationale

Each revision of Android is meant to be compiled with a specific set of dependencies. No effort is made upstream to support multiple build environments.
Building with different environments often yields build errors due to untested dependencies versions.
So we document here how to recreate these recommended build environments.

Recommended environment history

Ubuntu support:

          ,2013-10-15 - Lucid   (10.04)
2013-10-15,2015-03-16 - Precise (12.04), probably with 4.4 KitKat - https://web.archive.org/web/20131015123913/http://source.android.com/source/initializing.html
2015-03-16,           - Trusty  (14.04) https://web.archive.org/web/20150316053136/https://source.android.com/source/initializing.html

Java support:

          ,2014-03-31 - Sun JDK 5/6
2014-03-31,           - OpenJDK 7 - https://web.archive.org/web/20140331004436/https://source.android.com/source/initializing.html

Ubuntu 14.04 with LXC

lxc-create -n replicant -t download -- -d ubuntu -r trusty -a amd64

lxc-start -n replicant -d
lxc-attach -n replicant

# clean-up non-free sources
sed -i -e 's/ restricted//' -e 's/ multiverse//' /etc/apt/sources.list
apt-get update

Trisquel 6.0 Toutatis (based on Ubuntu 12.04 Precise) with LXC

wget http://archive.trisquel.info/trisquel/pool/main/d/debootstrap/debootstrap_1.0.59ubuntu0.3+7.0trisquel1.tar.gz
tar xzf debootstrap_1.0.59ubuntu0.3+7.0trisquel1.tar.gz 
cp -a debootstrap-1.0.59ubuntu0.3+7.0trisquel1/scripts/{toutatis,trisquel} /usr/share/debootstrap/scripts/
cp -a /usr/share/lxc/templates/lxc-ubuntu /usr/share/lxc/templates/lxc-trisquel
sed -i -e 's/main restricted universe multiverse/main/' \
       -e 's/.*lxcguest/#&/' /usr/share/lxc/templates/lxc-trisquel

lxc-create -n replicant -t trisquel --  -r toutatis -a amd64 --mirror http://archive.trisquel.info/trisquel/ \
  --security-mirror http://archive.trisquel.info/trisquel/

Ubuntu 12.04 Precise with LXC

lxc-create -n replicant -t download -- -d ubuntu -r precise -a amd64

lxc-start -n replicant -d
lxc-attach -n replicant

# clean-up non-free sources
sed -i -e 's/ restricted//' -e 's/ multiverse//' /etc/apt/sources.list
apt-get update

Trisquel 4.1 Taranis (based on Ubuntu 10.04 Lucid) with LXC

wget http://archive.trisquel.info/trisquel/pool/main/d/debootstrap/debootstrap_1.0.59ubuntu0.3+7.0trisquel1.tar.gz
tar xzf debootstrap_1.0.59ubuntu0.3+7.0trisquel1.tar.gz 
cp -a debootstrap-1.0.59ubuntu0.3+7.0trisquel1/scripts/{taranis,trisquel} /usr/share/debootstrap/scripts/
cp -a /usr/share/lxc/templates/lxc-ubuntu /usr/share/lxc/templates/lxc-trisquel
sed -i -e 's/main restricted universe multiverse/main/' \
       -e 's/lucid/taranis/' /usr/share/lxc/templates/lxc-trisquel

lxc-create -n replicant -t trisquel --  -r taranis -a amd64 --mirror http://archive.trisquel.info/trisquel/ \
  --security-mirror http://archive.trisquel.info/trisquel/

lxc-start -n replicant -d
lxc-attach -n replicant

# 'lxcguest' fixes a number of issues but seem to disable init..
dhclient
/etc/init.d/ssh restart

You'll need git > 1.7.2 for repo:

cd /usr/src/
apt-get install wget gcc libssl-dev zlib1g-dev libcurl4-gnutls-dev libexpat-dev gettext
wget https://www.kernel.org/pub/software/scm/git/git-2.4.6.tar.gz
tar xf git-2.4.6.tar.gz 
cd git-2.4.6/
make -j4  # ~2mn
make install prefix=/usr/local

Ubuntu 10.04 Lucid with LXC

apt-get install ubuntu-archive-keyring rsync
lxc-create -n replicant -t ubuntu -- -r lucid -a amd64

lxc-start -n replicant -d
lxc-attach -n replicant

# clean-up non-free sources
sed -i -e 's/ restricted//' -e 's/ multiverse//' /etc/apt/sources.list
apt-get update

# 'lxcguest' fixes a number of issues but seem to disable init..
dhclient
/etc/init.d/ssh restart

You'll need git > 1.7.2 for repo:

cd /usr/src/
apt-get install wget gcc libssl-dev zlib1g-dev libcurl4-gnutls-dev libexpat-dev gettext
wget https://www.kernel.org/pub/software/scm/git/git-2.4.6.tar.gz
tar xf git-2.4.6.tar.gz 
cd git-2.4.6/
make -j4  # ~2mn
make install prefix=/usr/local

LXC host environment

The simplest way to configure LXC is to combine it with libvirt.

Here are instructions tested on a Debian 8 host:

apt-get install lxc debootstrap xz-utils ca-certificates

apt-get install libvirt-bin dnsmasq ebtables
service dnsmasq stop
update-rc.d dnsmasq remove
virsh net-autostart default
service libvirtd restart
cat > /etc/lxc/default.conf <<'EOF'
lxc.network.type = veth
lxc.network.flags = up
lxc.network.link = virbr0
EOF

You now can run the LXC containers instructions above.

Non-privileged user setup

This can be used in any environment to prepare a non-root user dedicated to builds.

# prepare build user
apt-get install openssh-server
useradd replicant --shell /bin/bash --create-home
mkdir -p -m 700 ~replicant/.ssh
cat <<EOF >> ~replicant/.ssh/authorized_keys
your public key
EOF
chown -R replicant: ~replicant


Building

Main build instructions for Replicant images: Distributions used for building: Other build instructions:

CellularModem

If you are new to modems, or to the hardware and software architecture used in smartphones and tablets, it's a good idea to start from the freedom-privacy-security-issues article .

Once this is done, there are more documentation on various aspects of the Cellular modem, from the protocol to implementations details.


CellularModemPrivacyIssues


CommunityAndContact

The Replicant community has several places where people interact together.

Mailing list

Most Replicant developers are on the mailing list, as it is also used to review patches. Many non-developers that are contributors or that don't contribute to Replicant are also on the mailing list.

It's being used for many things:

The volume is moderate but there are sometimes spikes due to the to a huge patch set being sent.

To register you can use the Mailman interface .

Archives

The Mailman interface has a non-searchable archive of the list: Replicant Archives

There are independent projects that keep an archive of the list in a searchable format:

Forums

The Replicant forums are used for similar things than the mailing list, however:

IRC

Most Replicant developers and contributors, as well as people who are interested in our project, are present on the Replicant IRC channel(s). People from other communities are also there as we collaborate on various things, like adding support for devices in Upstream Linux.

IRC, or Internet Relay Chat, is our most ephemeral communication platform, in the sense that we do not publish message logs of the channel, nor are we aware of anyone else that unofficially does so. It is, however, common for channel participants to collect and store IRC message logs on their local machines or a VPS to catch up on recently missed conversations and search older messages by keyword to help remember details of past discussions. As the #replicant channels are public, sometimes conversations with important technical information are saved mostly as-is in bug reports or on the Replicant wiki.

In practice, Replicant has three IRC channels hosted on three separate IRC chat servers, but it appears as through there is only one channel since they are all bridged together. Bridged means that a user can join only one of the channels and send and receive messages with users on all the other channels because all messages are forwarded across every channel.

Our three IRC Channels are:

Replicant has taken a number of steps in order to ensure that Tor users who want to connect to our IRC channel are not discriminated against.

Due to Libera Chat's policies, users who wish to regularly connect and engage with our Libera Chat IRC channel via Tor need to use the SASL (Simple Authentication and Security Layer) framework for authentication every time they connect to Libera Chat's server and comply with a couple other restrictions that Freenode outlines here. Additionally, they require all new Libera Chat accounts to be created over the clearnet, which allows them to tie their user's personal IP addresses to every account on their network. Since the personal identity of a user can often be determined simply by acquiring that user's IP address, we recommend that users who want to preserve their anonymity not create a Freenode account.

Even though the Freenode IRC channel was our first IRC channel, and that at the time it had similar policies than thoses of Libera, at that time, we decided that Freenode's policies against Tor users didn't meet all of our users' anonymity needs. In order to address this, Replicant created a second IRC channel on the OFTC chat server. As they clearly state here, OFTC "does not require users to first connect in the clear and register with services to allow connecting via Tor". While OFTC was an improvement in some ways over Freenode, OFTC doesn't have an officially supported Tor onion service, so Tor users that require the utilization of such a feature can't connect to OFTC's server.

Since the HackInt IRC server allows anonymous connections via their officially supported Tor onion services and also allows users to register accounts while using theese official Tor onion services, we recently created a bridged IRC channel on their server as well. As an added benefit, HackInt also utilizes a privacy preserving Hashcash implementation instead of a CAPTCHA in their account creation process, as is explained here.

Since then, Freenode has been the victim of a "hostile takeover" according to their former volounteer staff members, we are now in the process of closing the #replicant channel on Freenode. See the Wikipedia page about this issue for more details and for references.

Matrix room

There is a Matrix room which is bridged to all three of our IRC channels.

Our Matrix room is:

The room was first created in 2015 through a partnership between Freenode and Matrix.org, which you can read about in this blog post.

A Matrix client is needed in order to connect to Replicant's Matrix room.

Please note that while Replicant's Matrix room name above, when clicked, links to Matrix.org's hosted instance of the Element web client, it does not mean that the Replicant project endorses this Matrix client or Matrix server host above any other Matrix client or Matrix server host.

XMPP Multi-User Chat

There is an XMPP MUC which is bridged to our Freenode IRC channel.

The bridged XMPP MUC is:

Private contact address

We also have a private contact address for the project, for inquiries that are private / confidential.

Very few people receive that list, and the ones that do tend to be very busy. So if your question can be answered on the mailing list, please use the mailing list. Unless you are writing about an explicitly private matter, we will likely advise you to write to the mailing list as we want to respond publicly when answering inquires as often as possible. We also won't forward your mail to the mailing list ourselves as otherwise we could mistakenly publish information that you wanted to keep private. See the PrivateContact page for use case and on how to use such contact address.

If you didn't manage to register to the mailing list, or if it doesn't work for you for some reasons, it's still possible to send a mail to the mailing list address without being registered. In that case we will be notified about it and we will be able to make it go through by manually going to the mailing list interface.


Instructions to run and collect results of the android Compatibility Test Suite for Replicant 4.2

Installation

Device preparation

Running CTS

It runs in the background and takes about 8 hours. It will display results as they become available. See the usage documentation for more information.

# ./android-cts/tools/cts-tradefed
cts-tf > run cts --plan CTS --disable-reboot

The test results are in ./android-cts/repository/results/ and the logs in ./android-cts/repository/logs/

Note: the --disable-reboot is necessary because of a cm-10.1.3 bug


Replicant contributors meeting - July 27-28 2019, Paris, France

Date

The meeting took place the 27 and 28 July 2019.

Location

The event took place in the April office. April is an association for the defense and promotion of free software.

Precise location: April, 44/46 rue de l'Ouest, bâtiment 8, 75014 Paris (It's accesible through the "place de la Catalogne", on the left of the "Biocoop" supermarket). Select "April" on the intercomm.
map: https://www.agendadulibre.org/events/19754
Phone number of the April office: 01 78 76 92 80.

The April office is relatively close to the Gare Montparnasse railway station.

In addition to trains, Gare Montparnasse railway station has also, in the same building, there is a metro station where you can access the metro lines 4, 6, 12 and 13.

Related events

On Friday, a dinner took place.

Dinner meeting time: From 18h30 to 18h45
Dinner meeting location: Near the Montparnasse tower . The Montparnasse tower is very close to the Montparnasse railway station.

At 18h45 we planned to try to find a restaurant nearby.

Airports

The two main airports near Paris are the Roissy Charles de Gaulle International Airport and the Paris Orly Airport.

Roissy Charles de Gaulle International Airport <-> Gare Montparnasse railway station

To get to the Gare Montparnasse railway station from the Roissy Charles de Gaulle International Airport by public transportation, you can take the RER B metro line up to the Denfert-Rochereau station where you can take the line 6 up to the Gare Montparnasse railway station.

Paris Orly Airport <-> Gare Montparnasse railway station

To get to the Gare Montparnasse railway station from the Paris Orly Airport by public transportation, you can take the Orlyval up to the Antony stop, and from there take the RER B metro line up to the Denfert-Rochereau station where you can take the line 6 up to the Gare Montparnasse railway station.

More information

Wikivoyage has a page on Paris and France which have many practical information such as:

It also has pages on the Roissy Charles de Gaulle International Airport and the Paris Orly Airport with more details on the public transportation lines to use to go to Paris, which tickets to buy, etc.

Contacting the organizers

You could use the Replicant private contact mail address in advance to obtain the cellphone number of an organizer to be able to use it in case of issue (like being lost, not finding the location of the meeting, etc).

Presentations

Topic Source code Slides Video Rationale of the talk
Replicant history
$ git clone --recursive https://git.replicant.us/GNUtoo/presentations.git
$ cd path/to/presentation
$ make
pdf 720p ogv The borders had to be cut to preserve the privacy of people passing by in the street. It was also encoded 3 times instead of 2 to save human time. * Has some context that might be useful for new Replicant contributors
* Has information on the relationship between Replicant and GNU/Linux
Replicant and bootloaders pdf 720p webm * The Galaxy SIII (and similar devices) bootloader status is complicated and relevant to Replicant 9
Replicant and modems: introduction pdf 720p webm * Meant to enable new contributors to work on the modem part
Replicant and modems: Samsung IPC pdf 720p webm
Replicant and oFono based Java RIL pdf 720p webm
Porting AOSP for a new device Made with Libreoffice which leaks metadata pdf Not recorded
Graphics acceleration on Replicant
$ git clone https://git.replicant.us/hominoid/graphics-presentation.git
$ cd graphics-presentations
$ make
pdf 720p webm * Explains why Replicant needs special care on the graphics stack.
* Introduces both graphics' hardware and software architecture.
* Dives into the implementation decisions.
* Lays out future plans.

License: CC-BY-SA 4.0 International

Planned discussions

The discussions were not recorded for privacy/intimacy reasons but a sumary of some of the important ones are available below on this page.

Topic Time and dependencies Status Rationale
Discussions on the bootloader situation on the Galaxy SIII and similar smartphones After the talk on the bootloaders
Discussions on minimal requirement to accept a device in Replicant:
* Do we still accept devices with modems that are not isolated?
* Do we have plan to require free software bootloaders?
* Do we require replacable batteries?
After the talk on modems and bootloaders
Discussions on the future of Replicant:
* Which devices do we target
* Do we continue focusing on devices with signed bootloaders
* Allwinner tablets, upstream Linux, and scalability
* Devices with non-replacable batteries
After the talk on Replicant history
Discussion about Upstream components, design choices, and cultural re-appropriation of technology
* Upstream
* Issues when combining together different build systems (Example: Android build system with Kconfig)
* Sharing work with GNU/Linux to enable more political control and cultural re-appropriation of mobile device in the long run, and the risk associated with it
* Android upstream anti-features and political design choices
* How subjective security is, threat models, and the difference between free software and device maker point of view
Please take a look at Upstream before attending if possible.

Known schedule constraints

Available hardware

Devices

Good practices:
Person Hardware Comments Usage
GNUtoo Galaxy SIII (I9300) with the stock bootloader
Galaxy SIII 4G (I9305) with the stock bootloader
Galaxy SIII 4G (I9305) with u-boot
Galaxy Nexus (I9250) with the stock bootloader
Galaxy SII (I9100) with the stock bootloader
GTA04 A3
GTA04 A4
Optimus black (P970)
GTA01 Used in a presentation about Replicant history
GTA02
HTC Dream
N900 Testing the battery charger driver is still needed but require a heavy PSU
Fil Galaxy Note 2 (N7100) stock bootloader [Working] Available for non-critical tests * Test the upstream touchkey driver
=> TODO:
* Bring a Parabola microSD (GNUtoo)
* Test the patch with an I9300
* Rebase the patch on master or linux-next
Galaxy SIII (I9300) stock bootloader [Working] Test Subject available for any experiment
Galaxy SIII (I9300) stock bootloader [Bricked] available for hardware hacking * Test fixing the phone
Galaxy Tab 2 7.0 (GT P3100) Property of the Replicant Project * Add support for it in the BackupTheEFS instructions
Paulk Galaxy Note (N7000) * Add support for it in the BackupTheEFS instructions
Galaxy Tab 2 10.1 (P5100) * Add support for it in the BackupTheEFS instructions
Looking for a Galaxy Note 8.0 (N5100) * Add support for it in the BackupTheEFS instructions

Debug utilities

Person Hardware Comments Usage
GNUtoo Serial port cable with variable resistors
Multimeter
Simtrace 1: Can get the dialog between the modem and the SIM card in wireshark
SIM card that is not recognized in Replicant (STK related?) Test on Replicant 4.2 and on Replicant 6.0
SIM card + phone that can trigger the audio call issue
Sigrok compatible adjustable power supply Not sure to bring it (heavy)
Fil SIM card that is not recognized in Replican 6

Discussion results

Do we care about supporting devices with non-removable batteries?

Points that were mentioned or discussed: Consensus in that meeting:

Do we require free software bootloaders ?

Points that were mentioned or discussed: Consensus in that meeting:

Do we require isolated modems ?

Points that were mentioned or discussed: Consensus in that meeting:

How to handle the various keys used to sign releases, and other related things and should the recovery check signatures

Points that were mentioned or discussed: Consensus in that meeting:

Improve information for current and potential Replicant users

Points that were mentioned or discussed:

Improving the Replicant website

Points that were mentioned or discussed: Consensus in that meeting:

Making it easier for anyone to contribute to Replicant

Points that were mentioned or discussed: Consensus in that meeting:

Funding work on f-droid

Consensus in that meeting:

Using oFono RIL

Points that were mentioned or discussed: Consensus in that meeting:

FSDG compliance and How to moderate the forums

Points that were mentioned or discussed:

People in this discussion realized that the forum is relatively small so it's doable to have it moderated.

Plan of action:

Do we ship some external applications in Replicant

Points that were mentioned or discussed:

Using wayland for the graphic stack?

Points that were mentioned or discussed:

AOSP vs LineageOS

Points that were mentioned or discussed: Consensus in that meeting:

Android upstream vs GNU/Linux upstream

Consensus in that meeting:

Video encoding

Sound

The microphone was mono, with only a channel from the left. So we need to create mono audio files from the videos.

To make the sound go in both channel, do the following in Audacity:

Video

The videos were recorded with some equipement that was lent to us:

=> Next time ask if they have a second microphone available for questions.

Kdenlive is being used for that.

Using kdenlive with Nouveau (with default settings), xfce4 under Parabola manage to freeze the screen (there are some messages like "nouveau: kernel rejected pushbuf: Cannot allocate memory" that can be observed when launching kdenlive through SSH).

To workaround that the following was used:

=> It's still slow while zomming in the timeline but it manage not to freeze the whole graphics stack.

To edit a video with kdenlive: Once that is done you can remove the part before the presentation this way:

Files


DangerousBatteryChargerExperiments

Messing with batteries is dangerous

Messing with battery charging is very dangerous:

So really make sure you know what you're doing if you mess with that.

This is not the usual warning that is there just because of legal requirements, in order to prevent potential lawsuits, and that tells you that the documentation may eat your cat.

Batteries issues are real.

Read the Wikipedia page on the Galaxy Note 6 for a famous examples of a battery issue.

Here the cause was due to the fact that the battery was non-removable and that the case didn't have enough extra space for the battery.

It's also a well known fact that messing with the battery charging values can make the battery explode or catch fire.

Other warnings

You may also break your phone's electronics if you mess up with battery charging values. However, compared to the danger of an explosion or fire, ending up with a bricked phone is just a minor issue.

Why this page was made

We lack documentation for the Max77693 PMIC (Power Management IC).

The thing we tried enabled us to gain more insights into how it worked.

In order to make things safer, we added the issues our experiments here so you don't need to reproduce them, and can just use the information we gathered with the results of the experiments.

Attempts to Disable charging through I2C

The max77693 driver in the Replicant 6 kernel has a function to enable and disable charging

As this driver is used on a Galaxy SIII we tried to disable the charging by setting the last bit of the MAX77693_CHG_REG_CHG_CNFG_00 register to 0.

# i2cget -f 17 0x66 0xB7
i2cget: WARNING! This program can confuse your I2C bus
Continue? [y/N] y
0x05
# i2cset -f 17 0x66 0xB7 0x4
i2cset: WARNING! This program can confuse your I2C bus
Continue? [y/N] y

This made it stop charging:

# grep POWER_SUPPLY_STATUS /sys/class/power_supply/battery/uevent
POWER_SUPPLY_STATUS=Discharging

We did that while the driver is running, as it is necessary to disable the charger register protection.

However we didn't check if the driver was using that same register while we were trying the i2cset command.

Such could lead to a race condition, where we read a value (e.g. 0x05) and then the driver does some stuff and changes it to 0xf5 for instance, after that we would set it as 0x04, messing up things.

So don't reproduce that experiment if you don't know what you are doing.

We also didn't get any review of what we were doing here, and humans do mistakes.

Also note that we don't have a datasheet for either the battery or the battery charger chip, so doing such experiments is very error prone.

How to properly disable charging

In order to minimize the risk it would be best to have the upstream kernel review the process involved.

To enable it for your device, first you need it to be ported to Replicant 9.

The Galaxy SIII already boots under Replicant 9 and uses a kernel that is very closely based on upstream. So we can even test under GNU/Linux with Replicant 9 kernel.

You can then take advantage of the Linux review process to be extra sure that you didn't mess up.

The max77693_charger driver available upstream already has a function to disable charging (max77693_enable_charger) but it has no way to directly enabled disable charging through a sysfs node.

Finding a way to disable charging through existing sysfs and/or adding a new sysfs node would allow userspace to easily stop the charging process with way less risks.

Note that upstream still requires you to test (and probably understand) the code you are writing, so you still need to know what you are doing.

If you don't know what you are doing, try instead to find someone who does and who is willing to do it for you.

Making batteries last longer

Lithium-ion batteries do break when the charge level is too low. So if you de-charge completely the battery and don't recharge it afterward, you could break it.

The same risk exists if you completely de-charge a battery (because you use you phone while not connected to a power supply) and don't charge again the battery for a long time.

Note that keeping charging the battery all the time also breaks it very fast.

This is why, when the battery reach 100%, it stops being charged.

If it's not possible to power the device from the power supply and leave the battery unconnected, the charging procedure has to let the battery decharge (up to some threshold like 80% for instance) and recharge again.

If the threshold is too high (like 99%), the battery would break very very fast. If the threshold is too low, the battery last less hours if it's at 80% when unconnected.

That process is typically transparent to users, so many users don't know about it.


DataPartition

/!\ Warning: Draft

This article is in draft form and is being written:

What does the data partition contain?

It probably depends on the devices and the Android versions.

On Replicant 6.0, it contains at least the application internal data: When various applications are installed, they have access to some storage where they can read and write data that is only visible to them and not to other applications. This is part of the Android security model that doesn't trust applications even if they are fully free software. This has serious usability consequences for users as it makes backuping and restoring the application data way more complicated than it should be: this data is tied to the application signatures, so because of that it's not easily portable across different Replicant versions. When application signatures changes (like between Replicant 6.0 0003 and 6.0 0004), the data needs to be migrated from the old signatures to the new ones.

In addition, on some devices it also contains the users data. This location and external microSD cards is where users typically their files like Music, photos, etc. This data is made accessible to the users in various location through a mechanism called fuse. In Replicant 6, this data is stored in the media directory in the data partition. Unlike application data, this data is not tied to any Android version or application signatures, so it can be moved, backed up, restored relatively easily across different devices and operating systems. It uses a similar file permission system than with GNU/Linux (unix DAC + Selinux).

Known data location:

Location Content
/data/app/<application name>/ Application apk, native libraries, java cache (base.odex)?
/data/data/<application name>/ Application internal data
/data/media/ User accessible storage to store music, photos, etc
Also mounted in /storage/emulated with fuse
/data/system/packages.xml Application and signing key, uid, etc mapping
/data/system/appops.xml Application permissions
For Silence:
Location Content
/data/data/org.smsecure.smssecure/ Silence data
/data/data/org.smsecure.smssecure/messages.db Silence (encrypted?) messages database (sqlite3)

TODO

Here's where the sdcard user accessible storage comes from:

/sdcard -> /storage/self/primary [1]
/storage/self/primary -> /mnt/user/0/primary [2]
/mnt/user/0/primary -> /storage/emulated/0 [3]

root@i9300:/ # readlink /sdcard                                                                                                                            
/mnt/user/0/primary
root@i9300:/ # readlink /storage/self/primary                                                                                                              
/mnt/user/0/primary
root@i9300:/ # readlink /mnt/user/0/primary                                                                                                                  
/storage/emulated/0
root@i9300:/ # mount | grep "/storage/emulated"                                                                                                              
/dev/fuse on /storage/emulated type fuse (rw,nosuid,nodev,noexec,noatime,user_id=1023,group_id=1023,default_permissions,allow_other)
TODO:

Concerns about the application internal data

TODO:

Datasheets

Introduction

This page is for linking to public datasheets and documentation.

If you find confidential markings on a public datasheet it would be very interesting to mention it in the LegalResearch page as we are making a list of such document there in order to show that many legitimate and public document still has such markings.

If the documentation is not under a free software license, it's best not to copy it to the Replicant wiki but only link to it.

It would also be a good idea to archive them with https://archive.org/web as sometimes crucial datasheet disappear.

If we manage to switch to mediawiki, there are bots to do the archival on archive.org automatically, but until then it's probably better to make sure that the document are publically archived by archive.org.

We would also need to research a bit on how to put such datasheets links on wikidata and retrieve that on a mediawiki compatible wiki. This way the link will appear where we need it in the wiki, without having to copy it around many times.

Links


Debugging

More advanced topics:

Dependencies

Stub

This page is a stub, feel free to improve it

Replicant 6.0

Dependency Working version Potentially compatible versions Debian 9 Guix PureOS Parabola Trisquel 7 Trisquel 8 Trisquel 91
Android SDK:
API Level 23 (Android 6)
* android-sdk(25.0.0)
* android-sdk-platform-23(6.0.1)
? OK Absent (NDK only) as October 2018) OK Absent as October 2018 ? * android-sdk(24.3.3)
* no android-sdk-platform-23 (why? needed?)
?
gcc * gcc(6.3.0) ? OK:gcc(6.3.0) OK: gcc 4-9, with gcc-5 the default OK:gcc-6(6.4.0) ? ? * gcc-5
* gcc-4.9
* gcc-4.8
* gcc-4.7
?
Java (jdk and jre) * openjdk-8-jdk
* openjdk-8-jre
7 OK:openjdk 8 OK: Icedtea 1-3 (=OpenJDK 6-7), OpenJDK 9-11 OK:openjdk 8 openjdk 7, 8, 10 7, 8 8, 9 ?
i686 packages feed support * zlib1g-dev:i386 ? OK ? No 32bit packages ? ? ? ?
32bit libc * libc6-dev-i386
* libc6-i386
? OK OK: glibc defined in gnu/packages/base.scm OK ? ? ? ?
lib32 packages * lib32z1-dev
* lib32readline-dev
* lib32ncurses5-dev
? OK ? OK ? ? ? ?
? libemma-java ? OK ? missing package (why?) ? ? ? ?
? * libandroidsdk-ddmlib-java
* libandroidsdk-sdklib-java
? OK ? missing package (why?) ? ? ? ?
? libgradle-android-plugin-java:2.2.2-1 ? OK ? ? Missing Missing Missing ?
Status Working but not FSDG compliant No SDK (NDK only) Few missing packages No SDK, no NDK Based on Ubuntu 14.04 which can build AOSP 6 The toolchain builds with lots of hacks ?

1 Trisquel 9 Pre-built Images

AOSP 6.0

Dependency Version Providers
Java 7.0 Debian 9
GNU/Linux distribution Ubuntu 14.04 Trisquel 7.0

Distributions

Debian 9 packages versions

Debian 'build' dependencies:

Dependency Version
gcc
binutils
llvm-defaults
Debian dependencies:
Dependency Version
gcc-arm-none-eabi
cmake
python-dev
swig
ant
bc
proguard
maven-debian-helper
libemma-java
libasm4-java
libguava-java
libnb-platform18-java
libnb-org-openide-util-java
libandroidsdk-ddmlib-java
libmaven-source-plugin-java
libfreemarker-java
libmaven-javadoc-plugin-java
ca-cacert
curl
gawk
libgmp3-dev
libmpfr-dev
libmpc-dev
git-core
gperf
libncurses-dev
squashfs-tools
pngcrush
zip
zlib1g-dev
lzma
libc6-dev-i386
g++-multilib
lib32z1-dev
lib32readline-dev
lib32ncurses5-dev
zlib1g-dev:i386
xsltproc
python-mako
schedtool
gradle
dirmngr
libandroidsdk-sdklib-java
eclipse-jdt
libgradle-android-plugin-java 2.2.2-1
android-sdk-build-tools
android-sdk-platform-23
aapt
lzop

Gradle

TODO:

Answers from a Guix perspective:

1 A debian build log of gradle "Merged Build-Depends: [...] gradle (>= 3.4)[...]"

References


Building JVending

Check out the source


h2. Set up mvn repo

Install the jaxb and jaxme libraries into your local maven repo:
<pre>
cd jvending/scripts
./install.sh
cd ..
</pre>

h2. Build JVending

Run:
<pre>
  mvn install
</pre>
This will build jvending. You will find the WAR file that you need to deploy to tomcat or jetty at provisioning-portal/target/provisioning.war 

h1. Deploying JVending

Set up a tomcat server and place the war file in the tomcat/webapps directory.

Go to http://localhost:8080/provisioning to verify the installation. You should see "Welcome to a J2EE Content Provisioning Portal".

h1. Stocking JVending with Android Apps

JVending requires that you package your content into a provisioning archive.

The following would be a valid provisioning.xml file for stocking of OMA OTA content.The descriptor-file references the dd2 file relative to the root of the jar (you may also use an http or https URI).

<pre>
<?xml version="1.0" encoding="ISO-8859-1"?>

<provisioning-archive xmlns="http://java.sun.com/xml/ns/j2ee-cp" 
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee-cp Provisioning_1_0.xsd">
   <client-bundle>
      <content-id>
         http://code.google.com/pg/jvending:1
      </content-id>
      <bundle-type>
         APPLICATION
      </bundle-type>
      <descriptor-file mime-type="application/vnd.oma.dd2+xml">
         /sample.dd2
      </descriptor-file>
      <user-descriptions>
         <display-name>
            Sample game
         </display-name>
         <description>
            My description to display
         </description>
         <icon>
            /app.png
         </icon>
      </user-descriptions>
   </client-bundle>
</provisioning-archive>
</pre>

The sample.dd2 contains the relative URI of a deliverable object, which in this case references an Android application. The objectURI/server attribute should reference the apk file relative to the root of the par file.

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<media DDVersion="2.0" xmlns="urn:oma:xml:dl:dd:2.0">
   <product>
      <mediaObject>
         <meta>
            <name>Sam Application Manager</name>
         </meta>
         <size>2226</size>
         <type>application/x-android</type>
         <objectID>cid:android@jvending.org</objectID>
         <objectURI>
            <server>sam-1.0.apk</server>
         </objectURI>
      </mediaObject>
   </product>
</media>
</pre>

The basic structure of the par file (this is just a zipped archive) is

<pre>
+ app.png
+ sam-1.0.apk
+ sam-1.0.dd2
+ META-INF/provisioning.xml
</pre>

Package this into say, sam.par and submit it to the JVending Server. You should see the content appear under the catalog view.

h2. Stocking Android Content

If you want to stock Android content and have it be compatible with the SAM application manager on an Android client, you will need to include more information in the provisioning.xml file. Note that Android apks are delivered over OMA OTA, so will also need to include a dd2 file.

<pre>
<?xml version="1.0" encoding="ISO-8859-1"?>

<provisioning-archive xmlns="http://java.sun.com/xml/ns/j2ee-cp" 
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee-cp Provisioning_1_0.xsd">
    <client-bundle>
        <content-id>
            google-android:apidemos
        </content-id>
        <version>1.5_r3</version>
        <bundle-type>
            APPLICATION
        </bundle-type>
        <descriptor-file mime-type="application/vnd.oma.dd2+xml">
            /apidemos.dd2
        </descriptor-file>
        <user-descriptions>
            <display-name>
                Android API Demos
            </display-name>
            <description>
                A demonstration of many of the Android APIs and most of them even work.
            </description>
            <icon>
                /android.png
            </icon>
        </user-descriptions>
        <vendor-info>
            <vendor-name>Google</vendor-name>
            <vendor-url>http://google.com</vendor-url>
            <vendor-description/>
        </vendor-info>
        <copyright>All Rights Reserved</copyright>
        <catalog-property>
            <property-name>Price</property-name>
            <property-value>Free</property-value>
        </catalog-property>
        <catalog-property>
            <property-name>Category</property-name>
            <property-value>Developer</property-value>
        </catalog-property>
        <catalog-property>
            <property-name>Short Description</property-name>
            <property-value>A demonstration of many of the Android APIs.</property-value>
        </catalog-property>
    </client-bundle>
</provisioning-archive>
</pre>

Edit:
We have now a temporary git repository at gitorious:
http://gitorious.org/replicant

Before starting

Setting up the build environment and getting source code

These instructions assume that you are building replicant in your home directory (~). If you are building it in another directory, modify path names accordingly.

Get the repo tool

repo is a front-end to git which is used to manage several git repositories.

 mkdir bin
 cd bin
 wget http://android.git.kernel.org/repo
 chmod a+x repo
 cd ..

Check out the Replicant repository

This step will download the Android source (minus the kernel) and the Replicant patches.

 mkdir replicant
 cd replicant
 ../bin/repo init -u git://gitorious.org/replicant/manifest.git -b replicant
 ../bin/repo sync

Optional: building the kernel and wireless LAN driver

By default, the Android build system uses a pre-compiled kernel and wireless driver rather than compiling these components from scratch. If you want to compile your own copy of either of these components, you have to compile both: the wireless driver sources included with Android are incompatible with the pre-compiled kernel.

Get the kernel source

To download the kernel sources, create a file in your replicant/.repo directory called "local_manifest.xml" containing the following:

<?xml version="1.0" encoding="UTF-8"?>
 <manifest>
  <project path="kernel" name="kernel/msm" revision="refs/heads/android-msm-2.6.27"/>
 </manifest>

Then from the ~/replicant/ directory, run:

../bin/repo sync

This will create a directory called replicant/kernel and download the kernel sources to it.

Build the kernel

To build the kernel:

cd ~/replicant/kernel
export ARCH=arm
export CROSS_COMPILE=arm-eabi-
export PATH=$PATH:~/replicant/prebuilt/linux-x86/toolchain/arm-eabi-4.2.1/bin
cp arch/arm/configs/msm_defconfig .config
make oldconfig && make

Wait several hours.

Point the build system to your kernel

Create a file called ~/replicant/buildspec.mk containing the following:

TARGET_PRODUCT:=htc_dream
TARGET_PREBUILT_KERNEL:=kernel/arch/arm/boot/zImage

This will instruct the build process to use your kernel rather than the pre-compiled kernel.

Build the wifi module

To build the wifi module:

cd ~/replicant/system/wlan/ti/sta_dk_4_0_4_32
export KERNEL_DIR=~/replicant/kernel/
make

(If make can't find your compiler, re-run same PATH export command you ran before compiling the kernel.)

Replace the pre-built wifi module with the one you just built:

cp wlan.ko ~/replicant/vendor/htc/dream-open

Build the firmware

Change the build scripts to include some important missing packages

(This section will be removed once these changes are committed to the replicant repository)

<pre>
 PRODUCT_PACKAGES := \
 Calculator \
 Email \
 [[ImProvider]] \
 [[SdkSetup]] \
 [[VoiceDialer]]
</pre>

This will include packages in the build which would otherwise be missing (including the [[SdkSetup]] package, which will enable incoming calls).

<pre>
cd ~/replicant
make
</pre>

Wait and wait and wait.

h2. Flashing the new firmware

[to be written]

h2. Building individual pieces

h3. Each time you want to build something

* open a new console
* Then type:
<pre>
 cd ~/replicant
 source build/envsetup.sh
 export ANDROID_JAVA_HOME=$JAVA_HOME
 lunch htc_dream-eng
 make
</pre>
* The files to flash are in ~/replicant/out/target/product/dream,flash them and then clear the cache
* boot and push the wifi firmware if you want it

h3. If you want to build a particular project

* open a new console
* build everything if it was not done before
* Then type:
<pre>
 cd ~/replicant
 source build/envsetup.sh
 export ANDROID_JAVA_HOME=$JAVA_HOME
 lunch htc_dream-eng
 #go into the directory containing an Android.mk
 mm
</pre>

h2. error workarrounds ==
 hyts_Foo.c ===
if you have:
<pre>
target Java: [[SettingsProvider]] (out/target/common/obj/APPS/SettingsProvider_intermediates/classes)
target Java: Settings (out/target/common/obj/APPS/Settings_intermediates/classes)
java.util.zip.ZipException: duplicate entry: hyts_Foo.c
    at java.util.zip.ZipOutputStream.putNextEntry(ZipOutputStream.java:192)
    at java.util.jar.JarOutputStream.putNextEntry(JarOutputStream.java:109)
    at sun.tools.jar.Main.addFile(Main.java:731)
    at sun.tools.jar.Main.update(Main.java:585)
    at sun.tools.jar.Main.run(Main.java:220)
    at sun.tools.jar.Main.main(Main.java:1167)
make: *** [out/target/common/obj/JAVA_LIBRARIES/core-tests_intermediates/javalib.jar] Error 1
make: *** Deleting file @out/target/common/obj/JAVA_LIBRARIES/core-tests_intermediates/javalib.jar'
make: *** Waiting for unfinished jobs....
Note: frameworks/base/packages/SettingsProvider/src/com/android/providers/settings/DatabaseHelper.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
</pre>

do that:
<pre>
rm -f dalvik/libcore/luni/src/test/resources/hyts_Foo.c
</pre>
And it will continue to build

Note that that:
<pre>
rm -rf dalvik/libcore/dom/src/test/resources/*
rm -rf dalvik/libcore/xml/src/test/resources/*
</pre>
didn't work

The workarrounds came from "here":http://groups.google.com/group/android-porting/browse_thread/thread/c51d436b2b1edc8d/b320ee78b2ddd0e4 and "here":http://lazyhack.net/tag/emulator/

h3. No rule to make target @development/data/etc/apns-conf_sdk.xml'

if you have:
<pre>
make: *** No rule to make target @development/data/etc/apns-conf_sdk.xml', needed by @out/target/product/dream-open/system/etc/apns-conf.xml'.  Stop.
make: *** Waiting for unfinished jobs....
</pre>
simply re-type make and it should continue

FDroid

History background

When we first started to work on Replicant, we were looking for a free market replacement app for Android in order to create a Replicant Software Center. Replicant Software Center was to be a fully free software market application to download and manage free software apps on Replicant.

You can still build these apps: see FLOSSDispenserBuild and SlideMeBuild.

FDroid client

We are now using FDroid client. It comes with the latest Replicant images. If you want to install it manually, you can download a compiled libre apk here: http://f-droid.org/FDroid.apk

Replicant repository for FDroid

By default, FDroid downloads libre apps from its own repository. We are working together with our friend Ciaran, the main FDroid developer, to perhaps establish a Replicant repository in the future.
The applications on the list of all known Free Software applications for the Android platform should be incorporated into that.


HOWTO build FLOSS Dispenser

Install Maven

On Debian/Ubuntu (as root):

 apt-get install maven2

Download the Android SDK

Unfortunately, the most convenient way to get the SDK is distributed by the Android Open Source Project, but that copy contains proprietary Google code and is wrapped in a restrictive proprietary license agreement. You can obtain a free SDK by following the directions in our wiki.

Install maven-android-sdk-deployer

This will allow us to set up a Maven dependency for particular versions of Android.

Add SDK tools/ directories to PATH

Add the Android SDK's primary and platform tools directories to your path (to give mvn access to aapt and apkbuilder). Currently, the build process targets Android 1.5, but if you've changed it to target a different platform, use that one in the second export command.

export PATH=${PATH}:<your_sdk_dir>/tools
export PATH=${PATH}:<your_sdk_dir>/platforms/android-1.5/tools

Get FLOSS Dispenser sources

mkdir fd-readonly
cd fd-readonly
git clone git://gitorious.org/replicant/floss-dispenser.git

Download necessary libraries and build FLOSS Dispenser

mvn clean install

Galaxy S Proprietary

This is the list of the proprietary libraries, binaries and firmwares shipped with cyanogenmod or the factory images on the Galaxy S and the status of their replacement.

Note on shipping non-free programs

Note that we don't ship any proprietary binary, library or firmware.
First because our goal is to reach a 100% free Android distribution and also because sometimes, these are not even distributables.

Libraries

Library location Function Can be replaced or avoided?
/system/vendor/lib/hw/gps.aries.so GPS library (sends NMEA output to framework) Easy to rewrite, doesn't deal with hardware at all
/system/lib/libril.so RIL Lib Default libril works fine with replacement
/system/lib/libsecril-client.so RIL client (used by libaudio) Replaced by samsung-ril-client
/system/lib/libsec-ril.so RIL Replaced by samsung-ril
/system/lib/libsamsungcamera.so dlopened camera lib Camera is v4l2 and there is a free replacement for ics available
/system/lib/egl/libGLES_android.so graphics PowerVR-related
/system/vendor/lib/egl/libEGL_POWERVR_SGX540_120.so graphics PowerVR-related
/system/vendor/lib/egl/libGLESv1_CM_POWERVR_SGX540_120.so graphics PowerVR-related
/system/vendor/lib/egl/libGLESv2_POWERVR_SGX540_120.so graphics PowerVR-related
/system/vendor/lib/hw/gralloc.aries.so graphics PowerVR-related
/system/vendor/lib/libakm.so compass lib there is libakm_free but it doesn't support this compass
/system/vendor/lib/libglslcompiler.so ? can be avoided
/system/vendor/lib/libIMGegl.so graphics PowerVR-related
/system/vendor/lib/libpvr2d.so graphics PowerVR-related
/system/vendor/lib/libpvrANDROID_WSEGL.so graphics PowerVR-related
/system/vendor/lib/libPVRScopeServices.so graphics PowerVR-related
/system/vendor/lib/libsrv_init.so ? can be avoided
/system/vendor/lib/libsrv_um.so ? can be avoided
/system/vendor/lib/libusc.so ? can be avoided
/system/vendor/lib/libsensor_yamaha_test.so sensors can be avoided
/system/vendor/lib/libsensorservice.so sensors can be avoided
/system/lib/libActionShot.so camera-related ?
/system/lib/libarccamera.so camera-related ?
/system/lib/libcamera_client.so camera-related ?
/system/lib/libcamerafirmwarejni.so camera-related ?
/system/lib/libcameraservice.so camera-related ?
/system/lib/libCaMotion.so camera-related ?
/system/lib/libcaps.so ? ?
/system/lib/libPanoraMax1.so ? ?
/system/lib/libPlusMe.so ? ?
/system/lib/libs3cjpeg.so jpeg-related should be free software
/system/lib/libseccamera.so camera-related ?
/system/lib/libseccameraadaptor.so camera-related ?
/system/lib/libsecjpegencoder.so jpeg-related ?
/system/lib/libtvout.so graphics (tv out) ?
/system/lib/lib_tvoutengine.so graphics (tv out) ?
/system/lib/libtvoutfimc.so graphics (tv out) ?
/system/lib/libtvouthdmi.so graphics (tv out) ?
/system/lib/libtvoutservice.so graphics (tv out) ?
/system/lib/libQmageDecoder.so decoder ? ?

Binaries

Binary location Function Can be replaced or avoided?
/system/vendor/bin/gpsd non-free gpsd needs to eb replaced to have working gps
/system/bin/rild ril daemon it's there to run the RIL as root, was replaced easily
/radio/modem.bin modem binary we don't want to deal with it
/system/vendor/bin/pvrsrvinit graphics can be avoided with our gralloc
/system/vendor/bin/orientationd sensors must be replaced by libakm_free
/system/vendor/bin/geomagneticd must be replaced by libakm_free
/system/bin/tvoutserver graphics ?
/system/bin/charging_mode ? ?
/system/bin/playlpm play nice images when charging the phone was replaced

Configuration files

File location Function What depends on it?
/system/etc/gps.conf gps conf non-free gps module?
/system/vendor/etc/gps.xml gps conf non-free gpsd
/system/cameradata/datapattern_420sp.yuv camera-related non-free camera lib
/system/cameradata/datapattern_front_420sp.yuv camera-related non-free camera lib
/system/media/battery_charging_10.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_100.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_15.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_20.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_25.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_30.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_35.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_40.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_45.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_5.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_50.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_55.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_60.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_65.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_70.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_75.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_80.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_85.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_90.qmg charging mode screen charging mode (but was replaced)
/system/media/battery_charging_95.qmg charging mode screen charging mode (but was replaced)
/system/media/chargingwarning.qmg charging mode screen charging mode (but was replaced)
/system/media/Disconnected.qmg charging mode screen charging mode (but was replaced)

Firmwares

Firmware location Function What depends on it?
/system/vendor/firmware/bcm4329.hcd wifi/bt firmware wifi/bt chip
/system/vendor/firmware/nvram_net.txt wifi/bt firmware wifi/bt chip
/system/vendor/firmware/cypress-touchkey.bin ? ?
/system/vendor/firmware/samsung_mfc_fw.bin MFC hardware video decoding
/system/vendor/firmware/CE147F02.bin ? ?
/system/firmware/CE147F00.bin ? ?
/system/firmware/CE147F01.bin ? ?
/system/firmware/CE147F02.bin ? ?
/system/firmware/CE147F03.bin ? ?

References


GalaxyTab 2 10.1

Variant Replicant compatible versions SoC Bootloader Modem link Modem protocol RAM
Galaxy Tab 2 10.1 (GT-P5100) Replicant 4.0, 4.2, 6.0 OMAP 4430 Signed Isolated (MIPI) samsung-ipc 1G
Galaxy Tab 2 10.1 WiFi (GT-P5110) Replicant 4.0, 4.2, 6.0 OMAP 4430 Signed No modem 1G

TODO


Galaxy Tab 2 10.1 (P51xx) Build

This explains how to build Replicant for the Galaxy Tab 2 10.1.

Prerequisites

Before building, you must make sure that:

Warning

Do not build as root, always build as user.

Building

P5100

Setup the build environment:

source build/envsetup.sh
lunch replicant_p5100-userdebug
export ANDROID_JAVA_HOME=$JAVA_HOME

P5110

Setup the build environment:

source build/envsetup.sh
lunch replicant_p5110-userdebug
export ANDROID_JAVA_HOME=$JAVA_HOME

Start the build:

parallel_tasks=$(echo "$(grep 'processor' /proc/cpuinfo | wc -l ) + 1" | bc)
make -j$parallel_tasks bacon

The -jn argument is to indicate the number of parallel tasks during the build.
You can remove it from the command line to have only one task at a time. With fast hardware, best results will come with -j9, -j16 and -j32.

Output files

The produced files are located at:

Galaxy Tab 2 10.1 (P51xx) Installation

Warning: installing an operating system, such as Replicant, may void your device's warranty and will erase the data stored on the device.

Prerequisites

In order to install Replicant on your device, it is assumed that you have a computer running a GNU/Linux operating system and everything necessary to connect your device to the computer through USB available. Moreover, it is assumed that anyone performing the installation knows how to use command lines in a terminal and has basic knowledge about it.

Downloading the files

The first step in the installation process is to download and set up the files that will be used to install Replicant to the device. The files must be downloaded on your computer first.

1. Find out what the latest image is: check out the Last image part of the general table on GalaxyTab2101P51xx
2. Download all the files listed for the device (including the checksum and the signatures) on ReplicantImages for the latest image
2. Make sure you have added the Replicant release key to your GPG keyring
3. Check the signature of the files:

gpg --armor --verify path/to/replicant-4.2-p5100.zip.asc path/to/replicant-4.2-p5100.zip

or
gpg --armor --verify path/to/replicant-4.2-p5110.zip.asc path/to/replicant-4.2-p5110.zip

gpg --armor --verify path/to/recovery.img.asc path/to/recovery.img

4. Make sure the check succeeds, do not install anything if it doesn't!
5. Check the checksum of the files:
md5sum -c p5100.md5

or
md5sum -c p5110.md5

6. Make sure the check succeeds, do not install anything if it doesn't!

Installing heimdall

The heimdall tool is required to flash the recovery image to the device.
Instructions to install heimdall: ToolsInstallation

Copying the files to the device

There are two means of pushing the system zip to the device:

Using the storage of the device

You can either complete this step by using the device's internal storage or by using an external microSD card.

Using the internal storage

1. Make sure the device is started up and has an Android system running
2. Connect the USB cable to both the computer and the device
3. Enable USB mass storage on the device
4. Mount the mass storage on the computer
5. Copy the replicant-4.2-p5100.zip or replicant-4.2-p5110.zip file at the origin of the mass storage
6. Safely unmount the mass storage on the computer
7. Disable USB mass storage on the device

Using a microSD card

1. Connect the microSD card to the computer (e.g. using an USB card reader)
2. Mount the microSD card on the computer
3. Copy the replicant-4.2-p5100.zip or replicant-4.2-p5110.zip file at the origin of the microSD card
4. Safely unmount the microSD card on the computer
5. Disconnect the microSD card from the computer
6. Insert the microSD card in the device (make sure it is turned off before inserting the card)

Installing ADB

Instructions to install ADB: ToolsInstallation

Preparing the device

The next step in the installation process is to prepare the device for heimdall mode.

1. Make sure the device is completely turned off and the USB cable is disconnected from the device
2. Start the device by holding the following key combination: Volume up, Power
3. Hold the key combination until the device shows a Warning message
4. Confirm that you want to download a custom OS (using volume up)
5. Make sure the device is in Downloading mode
4. Connect the USB cable to both the computer and the device

Installing the images

Now that both the computer and the device are set up, it is time to actually install the images to the device.

1. Install the recovery image to the device:

heimdall flash --KERNEL path/to/recovery.img --RECOVERY path/to/recovery.img

2. Make sure the device reboots to recovery
3. Select install zip (using the volume keys to navigate and the power key to select)

Using the storage of the device

Using the internal storage

4. Select install zip from sdcard
5. Select the system zip: replicant-4.2-p5100.zip or replicant-4.2-p5110.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
6. Confirm the installation

Using a microSD card

4. Select install zip from external sdcard
5. Select the system zip: replicant-4.2-p5100.zip or replicant-4.2-p5110.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
6. Confirm the installation

Using ADB sideload

4. Select install zip from sideload
5. Back to the host computer, load the system zip with sideload:

adb sideload path/to/replicant-4.2-p5100.zip

or
adb sideload path/to/replicant-4.2-p5110.zip

6. Make sure the file is being transfered

Completing the installation

8. Select Go Back (if necessary) to get back to the general menu
8. Select wipe data/factory reset
9. Confirm the data wipe by selecting Yes -- delete all user data
10. Select Reboot system now to reboot the device

Your device should now be running Replicant!


Galaxy Tab 2 10.1 (P51xx) Firmwares

Some hardware functionalities require firmwares to be functional.
If you are interested in writing free software replacements for these firmware files, please contact us.
Firmwares are programs that do not run on the main CPU: instead, they run on separate chips. Some firmwares come pre-installed on the chip and some others need to be loaded by the CPU.

Since these firmwares are non-free software, we do not recommend using them nor do we distribute them.

Firmware location Related chip Function
/system/vendor/firmware/bcmdhd_sta.bin BCM4330 Wi-Fi
/system/vendor/firmware/bcmdhd_mfg.bin BCM4330 Wi-Fi
/system/vendor/firmware/bcmdhd_apsta.bin BCM4330 Wi-Fi Host
/system/vendor/firmware/bcmdhd_p2p.bin BCM4330 Wi-Fi Direct
/system/vendor/firmware/nvram_net.txt BCM4330 Wi-Fi
/system/vendor/firmware/nvram_mfg.txt BCM4330 Wi-Fi
/system/vendor/firmware/BCM4330.hcd BCM4330 Bluetooth
/system/vendor/firmware/ducati-m3.bin Ducati M3 Hardware media encoding/decoding, Camera

Galaxy Tab 2 7.0 Build (P31xx)

This explains how to build Replicant for the Galaxy Tab 2 7.0 (P31xx).

Prerequisites

Before building, you must make sure that:

Warning

Do not build as root, always build as user.

Building

P3100

Setup the build environment:

source build/envsetup.sh
lunch replicant_p3100-userdebug
export ANDROID_JAVA_HOME=$JAVA_HOME

P3110

Setup the build environment:

source build/envsetup.sh
lunch replicant_p3110-userdebug
export ANDROID_JAVA_HOME=$JAVA_HOME

Start the build:

parallel_tasks=$(echo "$(grep 'processor' /proc/cpuinfo | wc -l ) + 1" | bc)
make -j$parallel_tasks bacon

The -jn argument is to indicate the number of parallel tasks during the build.
You can remove it from the command line to have only one task at a time. With fast hardware, best results will come with -j9, -j16 and -j32.

Output files

The produced files are located at:

Galaxy Tab 2 7.0 (P31xx) Installation

Warning: installing an operating system, such as Replicant, may void your device's warranty and will erase the data stored on the device.

Prerequisites

In order to install Replicant on your device, it is assumed that you have a computer running a GNU/Linux operating system and everything necessary available to connect your device to the computer through USB. Moreover, it is assumed that anyone performing the installation knows how to use a terminal and has basic knowledge about command line commands.

Downloading the files

The first step in the installation process is to download and set up the files that will be used to install Replicant to the device. The files must be downloaded on your computer first.

1. Find out what the latest image is: check out the Last image part of the general table on GalaxyTab270P31xx
2. Download all the files listed for the device (including the checksum and the signatures) on ReplicantImages for the latest image
2. Make sure you have added the Replicant release key to your GPG keyring
3. Check the signature of the files:

gpg --armor --verify path/to/replicant-4.2-p3100.zip.asc path/to/replicant-4.2-p3100.zip

or
gpg --armor --verify path/to/replicant-4.2-p3110.zip.asc path/to/replicant-4.2-p3110.zip

gpg --armor --verify path/to/recovery.img.asc path/to/recovery.img

4. Make sure the check succeeds, do not install anything if it doesn't!
5. Check the checksum of the files:
md5sum -c p3100.md5

or
md5sum -c p3110.md5

6. Make sure the check succeeds, do not install anything if it doesn't!

Installing heimdall

The heimdall tool is required to flash the recovery image to the device.
Instructions to install heimdall: ToolsInstallation

Copying the files to the device

There are two means of pushing the system zip to the device:

Using the storage of the device

You can either complete this step by using the device's internal storage or by using an external microSD card.

Using the internal storage

1. Make sure the device is started up and has an Android system running
2. Connect the USB cable to both the computer and the device
3. Enable USB mass storage on the device
4. Mount the mass storage on the computer
5. Copy the replicant-4.2-p3100.zip or replicant-4.2-p3110.zip file at the origin of the mass storage
6. Safely unmount the mass storage on the computer
7. Disable USB mass storage on the device

Using a microSD card

1. Connect the microSD card to the computer (e.g. using an USB card reader)
2. Mount the microSD card on the computer
3. Copy the replicant-4.2-p3100.zip or replicant-4.2-p3110.zip file at the origin of the microSD card
4. Safely unmount the microSD card on the computer
5. Disconnect the microSD card from the computer
6. Insert the microSD card in the device (make sure it is turned off before inserting the card)

Installing ADB

Instructions to install ADB: ToolsInstallation

Preparing the device

The next step in the installation process is to prepare the device for heimdall mode.

1. Make sure the device is completely turned off and the USB cable is disconnected from the device
2. Start the device by holding the following key combination: Volume down, Power
3. Hold the key combination until the device shows a Warning message
4. Confirm that you want to download a custom OS (using volume up)
5. Make sure the device is in Downloading mode
4. Connect the USB cable to both the computer and the device

Installing the images

Now that both the computer and the device are set up, it is time to actually install the images to the device.

1. Install the recovery image to the device:

heimdall flash --KERNEL path/to/recovery.img --RECOVERY path/to/recovery.img

2. Make sure the device reboots to recovery
3. Select install zip (using the volume keys to navigate and the power key to select)

Using the storage of the device

Using the internal storage

4. Select install zip from sdcard
5. Select the system zip: replicant-4.2-p3100.zip or replicant-4.2-p3110.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
6. Confirm the installation

Using a microSD card

4. Select install zip from external sdcard
5. Select the system zip: replicant-4.2-p3100.zip or replicant-4.2-p3110.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
6. Confirm the installation

Using ADB sideload

4. Select install zip from sideload
5. Back to the host computer, load the system zip with sideload:

adb sideload path/to/replicant-4.2-p3100.zip

or
adb sideload path/to/replicant-4.2-p3110.zip

6. Make sure the file is being transfered

Completing the installation

8. Select Go Back (if necessary) to get back to the general menu
8. Select wipe data/factory reset
9. Confirm the data wipe by selecting Yes -- delete all user data
10. Select Reboot system now to reboot the device

Your device should now be running Replicant!


Galaxy Tab 2 7.0 (P31xx) Firmwares

Some hardware functionalities require firmwares to be functional.
If you are interested in writing free software replacements for these firmware files, please contact us.
Firmwares are programs that do not run on the main CPU: instead, they run on separate chips. Some firmwares come pre-installed on the chip and some others need to be loaded by the CPU.

Since these firmwares are non-free software, we do not recommend using them nor do we distribute them.

Firmware location Related chip Function
/system/vendor/firmware/bcmdhd_sta.bin BCM4330 Wi-Fi
/system/vendor/firmware/bcmdhd_mfg.bin BCM4330 Wi-Fi
/system/vendor/firmware/bcmdhd_apsta.bin BCM4330 Wi-Fi Host
/system/vendor/firmware/bcmdhd_p2p.bin BCM4330 Wi-Fi Direct
/system/vendor/firmware/nvram_net.txt BCM4330 Wi-Fi
/system/vendor/firmware/nvram_mfg.txt BCM4330 Wi-Fi
/system/vendor/firmware/BCM4330.hcd BCM4330 Bluetooth
/system/vendor/firmware/ducati-m3.bin Ducati M3 Hardware media encoding/decoding, Camera

GeeksPhone One Proprietary

This is the list of the proprietary libraries, binaries and firmwares shipped on the GeeksPhone One and the status of their replacement.

Note on shipping non-free programs

Note that we don't ship any proprietary binary, library or firmware.
First because our goal is to reach a 100% free Android distribution and also because sometimes, these are not even distributables.

Libraries

Radio functions (Phone related)

Library name Location
libcm.so /system/lib/
libdsm.so /system/lib/
libdss.so /system/lib/
libgsdi_exp.so /system/lib/
libgstk_exp.so /system/lib/
libmmgsdilib.so /system/lib/
libnv.so /system/lib/
liboem_rapi.so /system/lib/
liboncrpc.so /system/lib/
libqmi.so /system/lib/
libqueue.so /system/lib
libril-qc-1.so /system/lib
libwms.so /system/lib/
libwmsts.so /system/lib/
libsnd.so /system/lib/

Camera control and encoding libraries

Library name Location
libmmcamera.so /system/lib/
libmmcamera_target.so /system/lib/
libmmjpeg.so /system/lib/

Media libraries

Library name Location
libmm-adspsvc.so /system/lib/
libOmxH264Dec.so /system/lib/
libOmxMpeg4Dec.so /system/lib/
libOmxVidEnc.so /system/lib/

Bluetooth helpers

Library name Location
hci_qcomm_init /system/bin/

Firmwares

Wifi AR6002 firmware file location

Firmware location Function What depends on it?
/system/etc/wifi/fw/athwlan.bin.z77 Wifi AR6002 (cat /sys/module/ar6000/parameters/tgt_fw)
/system/etc/wifi/fw/data.patch.hw2_0.bin Wifi AR6002 (cat /sys/module/ar6000/parameters/tgt_patch)
/system/etc/wifi/fw/eeprom.bin Wifi AR6002 (cat /sys/module/ar6000/parameters/eeprom_bin)

Note: in /sys/module/ar6000/parameters/ you can change debug level for the driver with the debuglevel parameter.
Here is a link with information about the AR600X architecture, pointing to use ath6kl driver and a new firmware (I've done md5sum on the files on the phone, and on the new firmware and aren't the same files). Please note that AR6002 and AR6001 are not supported by this driver (ath6kl).

References


Google Apps Free Replacements

Here is a list of FLOSS replacements for the non-free apps that are part of the Google experience. Note that these are not part of Android itself.

Google app FLOSS replacement License Website Installed in Replicant Available in F-Droid?
Android Market F-Droid GPLv2+ http://f-droid.org/ Yes Yes
Aptoide GPLv2 http://aptoide.org/trac No No
GMail Android Mail Apache 2 http://source.android.com/ Yes No
K9 Apache 2 http://code.google.com/p/k9mail/ No Yes
Google Maps OsmAnd GPLv3 http://osmand.net/ No Yes
gvSIG Mini Maps GPLv2 https://confluence.prodevelop.es/display/GVMN/Home No Yes
OsmDroid LGPL http://code.google.com/p/osmdroid/ No Yes
Navit GPLv2 http://wiki.navit-project.org/index.php/Navit_on_Android No Yes
RMaps GPLv3 http://robertdeveloper.blogspot.com/2009/08/rmaps.html No Yes
Google Talk CSipsimple (SIP) GPLv3 http://code.google.com/p/csipsimple/ No Yes
Sipdroid (SIP) GPLv3 http://code.google.com/p/sipdroid/ No Yes
Linphone (SIP) GPLv2+ http://www.linphone.org/ No Yes
Beem (XMPP) GPLv3+ http://beem-project.com/ No Yes
Gibberbot (XMPP) Apache 2 https://guardianproject.info/apps/gibber/ No Yes
YouTube YouTube mobile website Not an app http://m.youtube.com/ Yes No
Genie Widget, News/Weather widget Weather notification GPLv2 http://code.google.com/p/weather-notification-android/ No Yes
Forecast widgets Apache 2 http://code.google.com/p/android-sky/ No Yes
Umbrella Today BSD https://github.com/bostonandroid/UmbrellaToday No Yes

GTA04 Kernel

This page documents the various tried to get a working kernel for the GTA04 with ICS userspace.

Notes: Resources:

Rowboat kernel

The TI porting guide for AM37x devices advices to use the rowboat tree with the rowboat-ics.xml manifest.
The kernel in that tree is branch rowboat-ics-kernel-2.6.37 from the rowboat kernel.

Porting the GTA04 board and drivers to this kernel seems possible, however this is a very old kernel revision.
The gta04 kernel based on rowboat kernel is at: http://git.paulk.fr/gitweb/?p=replicant/kernel-gta04.git;a=shortlog;h=refs/heads/rowboat-gta04

Status matrix:

Component Status
Board file OK (boots normally)
RS232 OK
Modem Missing
Power off/reboot Reboot works, poweroff leaves led on, power button won't start it after poweroff
GPS Missing
WiFi/Bluetooth Missing
LCD OK
Graphics (fb) OK, fast
Touch screen OK
Backlight Missing
Sensors Missing
Audio Missing
Headset Missing
USB OK, automatic OTG host/device, issue at suspend
microSD OK
Buttons Missing
LEDs Missing
Battery Missing

Omapzoom kernel

Omapzoom (where TI pushes code for Android) has an omap3 kernel that should match ICS userspace.
However, when running on the GTA04, serious power management issues caused characters to be dropped on serial after not touching the phone for a couple of seconds as well as IRQ interrupts being dropped, which caused the touchscreen to not work properly. Suspend/resume and earlysuspend works perfectly though. Maybe this kernel wasn't designed for AM37x OMAP3 devices but another kind of OMAP3 SoCs: there is no support for Android Beagleboard.

AOSP's 3.4 common kernel merged with Neil Brown's 3.4 gta04 kernel

Merging AOSP's 3.4 common kernel on top of Neil Brown's 3.4 gta04 kernel and adding the Android options to the defconfig resulted in a non-working kernel where input events didn't seem to be reported correctly to userspace (even with an USB mouse, click events seemed dropped).

Kernels on Gitorious/Replicant:

The repository is here,

Status matrix:

Component Status
Board file OK (boots normally)
RS232 OK
Modem Untested, should work
Power off/reboot Reboot works, poweroff crashes with adb
GPS Untested, should work
WiFi/Bluetooth Untested, should work
LCD OK, looks strange after suspend
Graphics (fb) OK, fast
Touch screen OK
Backlight Working
Sensors Untested, should work
Audio Untested, should work
Headset Untested, probably needs to be adapted to android
USB OK, adb works but doesn't shut down properly
microSD OK
Buttons works
LEDs Untested, should work
Battery Untested, should work
frequency scaling not working in neil's kernel, waiting for a fix

h3. Issues

Both branches seem to make trebuchet freeze, on the system log there is:
I/WindowManager( 191): Input event dispatching timed out sending to Keyguard


Heimdall/Recovery Installation

Warning: flashing another operating system like Replicant may void your warranty and will erase the data stored on the device.

This guide assumes your phone is supported by Heimdall and installation is to be done using recovery.

Download the files

Copy the files to the device

Using the internal memory

  1. Mount usb storage from the current system of your phone
  2. Create a directory at the root of the usb storage
  3. Copy the downloaded images and md5 checksum to this directory

Using a µSD card

  1. Mount the µSD card, make sure it's fat32
  2. Create a directory at the root of the µSD card
  3. Copy the downloaded images and md5 checksum to this directory

Device specificities table

Each device has its own set of keys to enter different boot modes and specific partition names.
Moreover, a specific partition name has to be specified to heimdall when flashing.

Device Keys for Download mode Keys for recovery mode Kernel partition Recovery partition
Galaxy S Volume-, Select, Power Not available kernel Not available
Galaxy S2 Volume-, Select, Power Not available kernel Not available
Galaxy S3 Volume-, Select, Power Volume+, Select, Power BOOT RECOVERY
Galaxy Tab 2 10.1 Volume+, Power Volume-, Power kernel recovery
Galaxy Tab 2 7.0 Volume- Volume+, Power kernel recovery

Prepare the phone

  1. Turn the phone off, disconnect any USB cable
  2. Hold the key combination for Download mode (release only when in Download mode)
  3. You should be in Download mode. If not, remove the battery and retry the steps above
  4. You might need to confirm that you want to download a custom OS
  5. Once the Download screen is waiting, plug the USB cable

Flash the images

  1. Flash the recovery image using heimdall:
    If the recovery partition is available for your device, you can install recovery to the recovery partition:
    heimdall flash --[RECOVERY PARTITION] path/to/recovery.img
    

    If it is not available, flash recovery on the kernel partition:
    heimdall flash --[KERNEL PARTITION] path/to/recovery.img
    
  2. The phone should reboot and heimdall indicate that the operation was successful
  3. If you flashed to the recovery partition, hit the recovery mode keys quickly, or you'll have to power off the phone and hit the recovery mode keys then
  4. Wait until recovery boots
  5. You should be in recovery mode. If not, remove the battery and retry the steps above
  6. Select flash images
  7. Choose the location of the images (internal sdcard is the phone's internal memory, sdcard is the µSD card)
  8. Confirm flash
  9. Get back to the general menu
  10. Select wipe data/factory reset
  11. Confirm wipe
  12. Get back to the general menu
  13. Reboot

Your device should now be running Replicant!


Introduction

Here's a tutorial that covers the installation of a previously built or downloaded Free Android Image,we will assume that:

Howto


Installation

Detailed instructions to install Replicant

Make sure your phone is supported

Replicant only supports a few phones. Make sure the phone you want to install Replicant on is on the ReplicantStatus list. If it's not, you won't be able to install Replicant on your device without at least a bit of software hacking.

Make sure your phone allows non-official images

Some phones come with software that allows the user to flash the memory (replace the content of the memory partitions, like the system or the kernel one), but it's not always the case. Google-branded phones (Nexus One and Nexus S) come with this allowed but for some other devices, you'll certainly have to do some more operations to make this possible (it's required to flash Replicant).

Please, refer to the CyanogenMod wiki to find and follow the instructions to root the phone. Note that instructions for Replicant 2.2 correspond to CyanogenMod 6 and Replicant 2.3 correspond to CyanogenMod 7.

For instance on the HTC Dream page, you'll need to follow the instructions to root the phone and to install DangerSPL.

Note: all the radio images and bootloader images that are provided on these pages are not free software.

Download the Replicant images and tools for your phone

Find the codename of your phone

Find the latest usable Replicant image

Find the base location of the tools/images for your device

For instance, if the phone is HTC Dream and the latest image Replicant 2.2 preview 0009, the base location will be: http://ftp.osuosl.org/pub/replicant/images/replicant-2.2/preview/0009/.

Download the tools to flash your device

Download the Replicant images for your device

Setup the computer to flash Replicant

If you have downloaded the files in any other place, change ~/Downloads by the location where you downloaded the files.

This will ask you to type your password. Note that in most cases, the letters you type won't be shown.

Keep this terminal open during the next step.

Setup the device to flash Replicant

Flash Replicant images

WARNING: This step will erase every data stored on the phone, make sure you copied the data if you don't want to lose it.

Your device should reboot with Replicant running. Now you are done, Replicant is installed on your device!

Summary of the instructions to install Replicant

Requirements

Installation

Put the phone in fastboot mode (by holding the Camera button and the Power button, then following on-screen instructions), make sure it's connected to your computer, and run the following commands on your computer. You may need to use sudo.

Note, if you don't have instructions for entering fastboot mode, you may need to install DangerSPL using the CyanogenMod instructions.

Note that it will erase everything on the phone

./fastboot flash system system.img
./fastboot flash boot boot.img
./fastboot flash userdata userdata.img 
./fastboot erase cache
./fastboot reboot


Get the video

The video can be downloaded at http://download.paulk.fr/replicant/introducing_replicant/introducing_replicant_web.webm .

Its quality is bad but unfortunately, I can't provide videos of an higher size (I have a very limited upload bandwidth).

A 720p version of the video exists and has a better quality but weights 100Mio. The exact format and quality for the video should be defined.

What it shows

This video shows basic replicant usage: calls, sms, internet, some android standard apps, fdroid, some featured fdroid apps like OsmAnd, terminal emulator.

Note that at some moments, what I'm trying to show doesn't work at first time (multi-touch, URL typing errors, etc) but well, it's part of the game ;)

Subtitles

It's probably better to distribute the subtitles .srt files instead of hard-writing the text in the video: doing things that way permits to have the subtitles in different languages.


Feel free to suggest modifications to the subtitles while these are not approved. 

h3. English version

*Approved*: not yet

<pre>
1
00:00:15,840 --> 00:00:20,680
Boot time

2
00:00:20,680 --> 00:00:21,680
0:00

3
00:00:21,680 --> 00:00:22,680
0:01

4
00:00:22,680 --> 00:00:23,680
0:02

5
00:00:23,680 --> 00:00:24,680
0:03

6
00:00:24,680 --> 00:00:25,680
0:04

7
00:00:25,680 --> 00:00:26,680
0:05

8
00:00:26,680 --> 00:00:27,680
0:06

9
00:00:27,680 --> 00:00:28,680
0:07

10
00:00:28,680 --> 00:00:29,680
0:08

11
00:00:29,680 --> 00:00:30,680
0:09

12
00:00:30,680 --> 00:00:31,680
0:10

13
00:00:31,680 --> 00:00:32,680
0:11

14
00:00:32,680 --> 00:00:33,680
0:12

15
00:00:33,680 --> 00:00:34,680
0:13

16
00:00:34,680 --> 00:00:35,680
0:14

17
00:00:35,680 --> 00:00:36,680
0:15

18
00:00:36,680 --> 00:00:37,680
0:16

19
00:00:37,680 --> 00:00:38,680
0:17

20
00:00:38,680 --> 00:00:39,680
0:18

21
00:00:39,680 --> 00:00:40,680
0:19

22
00:00:40,680 --> 00:00:41,680
0:20

23
00:00:41,680 --> 00:00:42,680
0:21

24
00:00:42,680 --> 00:00:43,680
0:22

25
00:00:43,680 --> 00:00:44,680
0:23

26
00:00:44,680 --> 00:00:45,680
0:24

27
00:00:45,680 --> 00:00:46,680
0:25

28
00:00:46,680 --> 00:00:47,680
0:26

29
00:00:47,680 --> 00:00:48,680
0:27

30
00:00:48,680 --> 00:00:49,680
0:28

31
00:00:49,680 --> 00:00:50,680
0:29

32
00:00:50,680 --> 00:00:51,680
0:30

33
00:00:51,680 --> 00:00:52,680
0:31

34
00:00:52,680 --> 00:00:53,680
0:32

35
00:00:53,680 --> 00:00:54,680
0:33

36
00:00:54,680 --> 00:00:55,680
0:34

37
00:00:55,680 --> 00:00:56,680
0:35

38
00:00:56,680 --> 00:00:57,680
0:36

39
00:00:57,680 --> 00:00:58,680
0:37

40
00:00:58,680 --> 00:00:59,680
0:38

41
00:00:59,680 --> 00:01:00,680
0:39

42
00:01:00,680 --> 00:01:01,680
0:40

43
00:01:01,680 --> 00:01:02,680
0:41

44
00:01:02,680 --> 00:01:03,680
0:42

45
00:01:03,680 --> 00:01:04,680
0:43

46
00:01:04,680 --> 00:01:05,680
0:44

47
00:01:05,680 --> 00:01:06,680
0:45

48
00:01:06,680 --> 00:01:07,680
0:46

49
00:01:07,680 --> 00:01:08,680
0:47

50
00:01:08,680 --> 00:01:09,680
0:48

51
00:01:09,680 --> 00:01:10,680
0:49

52
00:01:10,680 --> 00:01:11,680
0:50

53
00:01:11,680 --> 00:01:12,680
0:51

54
00:01:12,680 --> 00:01:13,680
0:52

55
00:01:13,680 --> 00:01:20,680
52 seconds to boot replicant from cold start

56
00:01:20,680 --> 00:01:24,000
Incoming call, using a free Radio Interface Layer (RIL)

57
00:01:24,000 --> 00:01:32,000
Ringtone

58
00:01:32,000 --> 00:01:40,000
Missed call notification

59
00:01:40,000 --> 00:01:55,000
Outgoing call, using a free RIL

60
00:02:03,000 --> 00:02:12,000
Call log

61
00:02:12,000 --> 00:02:16,000
Fast-access icons to call and send SMS

62
00:02:16,000 --> 00:02:22,000
Composing text messages (SMS)

63
00:02:22,000 --> 00:02:25,000
On-screen keyboard

64
00:02:25,000 --> 00:02:28,500
Sending SMS using, a free RIL 

65
00:02:28,500 --> 00:02:33,000
Sending SMS using, a free RIL: delivery report

66
00:02:38,000 --> 00:02:48,000
Running the music app

67
00:02:48,000 --> 00:02:54,000
Playing music encoded in the free OGG Vorbis format

68
00:02:54,000 --> 00:03:01,000
Seeking the track

69
00:03:01,000 --> 00:03:06,000
Playing music in background

70
00:03:06,000 --> 00:03:09,000
Clock app

71
00:03:09,000 --> 00:03:11,000
Alarm app

72
00:03:11,000 --> 00:03:18,000
Alarm app: creating a new alarm

73
00:03:23,000 --> 00:03:29,000
Apps launcher

74
00:03:29,000 --> 00:03:35,000
Calculator app

75
00:03:37,000 --> 00:03:50,000
Running the web browser

76
00:04:00,000 --> 00:04:06,000
Connecting to the Internet using USB networking

77
00:04:06,000 --> 00:04:10,000
Zooming using multi-touch

78
00:04:10,000 --> 00:04:23,000
Moving on the web page

79
00:04:23,000 --> 00:04:26,000
Zooming using touble-tap

80
00:04:26,000 --> 00:04:35,500
Scrolling the web page

81
00:04:38,000 --> 00:04:46,500
Using the hardware keyboard

82
00:05:20,000 --> 00:05:26,500
Watching [[YouTube]] videos with a free video decoder

83
00:05:26,500 --> 00:05:45,000
Seeking the video

84
00:06:06,000 --> 00:06:12,000
Using FDroid, the free software apps repository client

85
00:06:12,000 --> 00:06:20,000
The list of avilable free software is quite long!

86
00:06:20,000 --> 00:06:39,500
Let's select one to install

87
00:06:39,500 --> 00:06:43,000
Installed!

88
00:06:43,000 --> 00:07:06,000
Installed and running!

89
00:07:12,000 --> 00:07:18,000
[[OsmAnd]]: the featured free maps app using [[OpenStreetMap]] data

90
00:07:18,000 --> 00:07:22,000
GPS gets activated and works (with a free library)

91
00:07:55,000 --> 00:08:02,000
The terminal emulator app allows you to use command line…

92
00:08:02,000 --> 00:08:06,000
… and get root!

93
00:08:14,000 --> 00:08:20,000
Linux localhost 2.6.35.9-cyanogenmod #4 PREEMPT Thu Jun 23 12:41:17 CEST 2011 armv6l GNU/Linux
</pre>


List of known free software apps

We would like to list here all known Free Software applications that can be installed on Android devices.

General

Application name Description Website Apk Market Sources License API Note/Replicant Status
Desk Clock Clock Desk Clock apk market git
SayMyName reads out caller's name roadtoadc
ZXing Barcode reader ZXing
Openintents PIM applications(I didn't check all of them) openintents /!\ WARNING not all openintents applications are free software,some have an EULA
SuperGenPass Password hasher SuperGenPass apk [git://staticfree.info/git/SuperGenPass/ git] GPLv3
Wiki Dici Wiktionary Wiki Dici
APN Apndroid
Spell Dial spelldial
Astrid Task recording Astrid
android-metronome Metronome android-metronome
ringdroid ringdroid
SMS Popup android-smspopup
mandelbrot Fractal Viewer mandelbrot
CellFinder Cell Network Finder CellFinder
geobeagle geobeagle
CIDR Calculator CIDR subnet calculator CIDR Calculator
DiskUsage Disk Usage Viewer DiskUsage
Contact Owner Contact Owner
cyanogen-updater CM Updater
pmix MPD client pmix apk Android 1.5+ Works with replicant
FBReaderJ e-book reader (fbreader's port) http://fbreader.org/FBReaderJ/ apk [market://search?q=pname:org.geometerplus.zlibrary.ui.android market] zip GPL Android 1.5+ Works on replicant
AnkiDroid Flashcard (spaced-)repetition AnkiDroid apk market git GPLv3 Android 1.5+
Mnemododo Flashcard (spaced-)repetition mnemododo no here GPLv2
Tippy Tipper tip calculator tippytipper here Apache 2
Proxoid http proxy for Android Proxoid [] Apache 2
android-wifi-tether Wireless Tether for Root Users android-wifi-tether Apache 2
android-moderator A Google Moderator client for Android android-moderator Apache 2
Pedometer A Pedometer for android Pedometer GPL3
WebSMS web sms app WebSMS GPL3
chrometophone Google Chrome to Phone Extension chrometophone Apache 2 I am sure we can use it on chromium too but I see "Chrome to Phone is powered by the Android Cloud to Device Messaging (C2DM) service". Should we list this?
TomDroid note taking TomDroid GPLv3

Also, WordPlayer is a free-as-in-beer e-book reader that interfaces with the (free-as-in-freedom) calibre e-book manager. Although it does not strictly belong on this list, the developer of WordPlayer has expressed interest in freeing the code if enough developers show interest in contributing.

Applications pack

Application name Description Website Apk Market Sources License API Note/Replicant Status
apps for android Various free software apps pack: apps-for-android apps-for-android

News apps

Application name Description Website Apk Market Sources License API Note/Replicant Status
BBC News BBC News BBC News Apache License 2.0. Source code is I here under NewsWidget
NPR News NPR News (National Public Radio) NPR News Apache License 2.0

Communication

Application name Description Website Apk Market Sources License API Note/Replicant Status
Yaaic IRC Client Yaaic GNU GPL
Sipdroid SIP client Sipdroid apk [market://search?q=pname:org.sipdroid.sipua market] svn GPLv3 Android 1.5+ look here for making it work with asterisk instead of the default provider
K9 Email Client K9 apk [market://search?q=pname:com.fsck.k9 market] svn Apache 2.0 Android 1.5+
Funambol Android Sync Client Funambol Client for Android apk [market://search?q=pname:com.funambol.android market] svn aGPLv3 Android 2.0+
ConnectBot SSH client ConnectBot apk [market://search?q=pname:org.connectbot market] svn Apache 2.0 Android 1.5+
Libredroid Libre.fm client Release Blog Post apk [market://search?q=pname:fm.libre.droid market]
Mustard Identi.ca client Mustard
Denta Identi.ca client Denta
Exchange OWA Mail client ExchangeIt
yaaic IRC client yaaic apk on github GPLv3
APG Android Privacy Guard APG apk [market://search?q=pname:org.thialfihar.android.apg market] svn Apache 2.0 Android 1.5+

Games

Application name Description Website Apk Market Sources License API Note/Replicant Status
Tux Rider Tux Rider can't find its license
Fire Taps music Fire Taps GNU GPLv3
Missile Intercept action Missile Intercept GNU GPLv3
Replica Island platform Replica Island Apache License 2.0
Frozen Bubble Frozen Bubble port Frozen Bubble GNU GPL2
!CuckooChess chess game CuckooChess GNU GPL3
Open WordSearch rod search game Open WordSearch GNU GPL3
GL ES Quake Quake port to OpenGL ES GL ES Quake GPLv2
Doom Doom port doom-for-android
Solitaire Collection solitaire-for-android Apache License 2.0
Robotic Space Rock Robotic Space Rock Robotic Space Rock Apache License 2.0
TiltMazes TiltMazes New BSD License
Scrambled Net Scrambled Net GPLv2 with LGPL components
Lexic Lexic GPLv3
Alien Blood bath Alien Blood Bath GPLv3
asquare asqare GPLv3
Android Puzzles Android Puzzles Expat License
Knave Arthur's Sword proof-of-concept 2-player augmented reality swordfighting (virtual swords clink when they intersect) https://launchpad.net/asword OpenSourceTownLicense
robotfindskitten robotfindskitten apk [git://staticfree.info/git/robotfindskitten/ git] GPLv3
Guess the Number A mind game for Android Guess the Number Apache License 2.0
Line Follower Line Follower Line Follower GPL3

Sudoku

Application name Description Website Apk Market Sources License API Note/Replicant Status
Androku Andoku GPLv3
opensudoku OpenSudoku GPLv3

Emulators

Application name Description Website Apk Market Sources License API Note/Replicant Status
Scummvm Scummvm port " Android 1.5+
Twisty z-machine emulator [http://code.google.com/p/twisty/ Twisty":http://sites.google.com/site/scummvmandroid/dev] GPLv3

GPS

Application name Description Website Apk Market Sources License API Note/Replicant Status
!OsmAnd Gps navigation program OsmAnd " LGPL Not supported under Replicant (we have no gps yet)
open-gpstracker A GPS tracking Android App [https://code.google.com/p/open-gpstracker/ open-gpstracker":https://code.google.com/p/osmand/source/checkout] GPL3 Not supported under Replicant (we have no gps yet)
GeoBeagle GeoBeagle: an Android app for geocaching and letterboxing geobeagle Apache 2 Not supported under Replicant (we have no gps yet)
Andnav Gps navigation program http://www.andnav.org/ http://code.google.com/p/andnav/ svn GPLv3 Android 1.6+ Not supported under replicant (we have no gps yet), was liberated Dec '09
!MyTracks Gps tracking http://code.google.com/p/mytracks/ apk [market://search?q=pname:com.google.android.maps.mytracks market] mercurial Apache 2.0 Android 1.5+ No GPS on replicant yet
Mixare Augmented Reality Engine http://www.mixare.org/ http://code.google.com/p/mixare/ apk_list [market://search?q=pname:org.mixare market] git GPLv3 Android 1.5+ Not supported under replicant (we have no gps yet)

The OpenStreetMap wiki has a "list of "open source Android applications that support OpenStreetMap.

Libraries

Application name Description Website Apk Market Sources License API Note/Replicant Status
eyes-free text-to-speech library eyes-free

Le Wiki Koumbit also has a list of free/libre apps for Android.


Proposed Logos

Graziano proposed this logo of a rollerskating android for Replicant, signifying what a carefree, freedom-loving Replicant looks like.

aaronw counterproposes this logo. aaronw's logo is an Android dressed as Pris, a replicant from the movie Bladerunner. In the movie, Pris is a replicant built by the huge, sinister Tyrell corporation. Tyrell has built an army of androids for a life of servitude: hard out-colony labor, combat, and prostitution. Pris, a "pleasure" model, falls in with a small band of renegade replicants which has escaped the colonies and traveled to Earth, seeking freedom. Hunted by a society that misunderstands her, and betrayed by the company that made her, Pris kicks a whole bunch of ass before ultimately dying for her cause.

aaronw proposes this banner for the Replicant project's Trac site.


Replicant Native 64 Bit Build

This page is not ready to be used yet!

This page explains how to configure a 64b native build. The goal is to build Replicant without the need of 32b compatibility libs and to produce 64b host binaries (adb, fastboot, emulator, etc).

Note: This is a quite experimental and long process. Although you don't risk any damage to your computer while trying to set this up, you should better already have basic knowledge about building gcc, dealing with Makefiles and other related stuff, since some errors may append.

Note for the whole page: when a line is prefixed with #, that means that you have to run the command as root. Don't copy the # on the shell.

Required tools

Before building, you must make sure:

Building the toolchain

Downloading the files

First, you'll need to download binutils, gcc-core, gcc-g++, gmp and mpfr:

mkdir replicant-toolchain
cd replicant-toolchain
wget http://ftp.gnu.org/gnu/binutils/binutils-2.21.tar.bz2
wget http://ftp.gnu.org/gnu/gcc/gcc-4.4.3/gcc-core-4.4.3.tar.bz2
wget http://ftp.gnu.org/gnu/gcc/gcc-4.4.3/gcc-g++-4.4.3.tar.bz2
wget http://ftp.gnu.org/gnu/gmp/gmp-4.3.2.tar.bz2
wget http://ftp.gnu.org/gnu/mpfr/mpfr-3.0.1.tar.bz2
tar -xf binutils-2.21.tar.bz2
tar -xf gcc-core-4.4.3.tar.bz2
tar -xf gcc-g++-4.4.3.tar.bz2
tar -xf gmp-4.3.2.tar.bz2
tar -xf mpfr-3.0.1.tar.bz2
mv gmp-4.3.2 gcc-4.4.3/
mv mpfr-3.0.1 gcc-4.4.3/

Now, you have to build binutils and gcc for the arm-eabi target.

Building binutils

cd binutils-2.21
./configure --target=arm-eabi --prefix=/usr/local
make
# make install

Building gcc

cd ../gcc-4.4.3
mkdir build
cd build
../configure --target=arm-eabi --prefix=/usr/local --with-mpfr=../mpfr-3.0.1/ --with-gmp=../gmp-4.3.2/ --enable-shared
make
# make install

Modifying the files for 64b

Now that your toolchain is in place, you need to configure your build for 64b. Here is the list of the modifications you should do:

build/core/combo/

sed "s/-m32/-m64/g" -i HOST_linux-x86.mk
sed "s/-m32/-m64/g" -i TARGET_linux-x86.mk
sed "s|prebuilt/\$(HOST_PREBUILT_TAG)/toolchain/i686-unknown-linux-gnu-4.2.1/bin/i686-unknown-linux-gnu-|/usr/local/bin/arm-eabi-|g" -i TARGET_linux-x86.mk
sed "s|prebuilt/\$(HOST_PREBUILT_TAG)/toolchain/arm-eabi-4.4.0/bin/arm-eabi-|/usr/local/bin/arm-eabi-|g" -i TARGET_linux-arm.mk

external/qemu/

sed "s/-m32/-m64/g" -i Makefile.android

Nexus S Proprietary

This is the list of the proprietary libraries, binaries and firmwares shipped with cyanogenmod or the factory images on the Nexus S and the status of their replacement.

Note on shipping non-free programs

Note that we don't ship any proprietary binary, library or firmware.
First because our goal is to reach a 100% free Android distribution and also because sometimes, these are not even distributables.

Libraries

Library location Function Can be replaced or avoided?
/system/lib/libsecril-client.so client to Samsung's non-free RIL probably useless when we use another RIL (like a free replacement)
/system/vendor/bin/gpsd GPS daemon has to be replaced to have working GPS
/system/vendor/bin/pvrsrvinit PowerVR server initializer, 3d-related can be avoided
/system/vendor/lib/egl/libEGL_POWERVR_SGX540_120.so PowerVR 3d lib can be avoided
/system/vendor/lib/egl/libGLESv1_CM_POWERVR_SGX540_120.so PowerVR 3d lib can be avoided
/system/vendor/lib/egl/libGLESv2_POWERVR_SGX540_120.so PowerVR 3d lib can be avoided
/system/vendor/lib/hw/gps.s5pc110.so GPS lib has to be replaced to have working GPS
/system/vendor/lib/hw/gralloc.s5pc110.so gralloc lib cannot be avoided but was replaced by a (free) modified version of AOSP's gralloc
/system/vendor/lib/libakm.so accelerometer + compass can be avoided but a free replacement (libakm_free) already works with the accelerometer and the magnetic field (compass) will be supported soon
/system/vendor/lib/libglslcompiler.so ? seems graphics-related can be avoided
/system/vendor/lib/libIMGegl.so ? seems graphics-related can be avoided
/system/vendor/lib/libpvr2d.so ? seems graphics-related can be avoided
/system/vendor/lib/libpvrANDROID_WSEGL.so ? seems graphics-related can be avoided
/system/vendor/lib/libPVRScopeServices.so ? seems graphics-related can be avoided
/system/vendor/lib/libsec-ril.so Samsung's RIL has to be replaced to have working telephony and SMS (and data too)
/system/vendor/lib/libsrv_init.so ? can be avoided
/system/vendor/lib/libsrv_um.so ? can be avoided
/system/vendor/lib/libusc.so ? can be avoided

Configuration files

File location Function What depends on it?
/system/vendor/etc/gps.xml gps configuration file GPS. A (free) rewrite of this would probably conclude to producing almost the same file.

Firmwares

Firmware location Function What depends on it?
/system/vendor/firmware/fw_bcm4329.bin wifi firmware wifi
/system/vendor/firmware/fw_bcm4329_apsta.bin wifi AP firmware wifi access point
/system/lib/libpn544_fw.so NFC firmware Near Field Communication
/system/vendor/firmware/bcm4329.hcd bluetooth firmware bluetooth
/system/vendor/firmware/nvram_net.txt wifi-related firmware wifi
/system/vendor/firmware/samsung_mfc_fw.bin MFC firmware Multi Format Codec (hardware video encoding/decoding)

References


"
We believe that the following license meets the criteria in
www.opensource.org/docs/osd as well as https://help.launchpad.net/Legal/ProjectLicensing ; however, as of this writing, neither of these authorities have certified this license.


Opensourcetown license

VENUES: Android Market.

If the source code was published (i.e. checked into a public source code repository) more than two years ago, than it is under the Affero GPL 3.0 (with none of the clauses mentioned below added).

Otherwise, if the code is more recent, than it is available under a license which is similar to the Affero GPL 3.0 but with the following additional restrictions. These restrictions are not considered to be "further restrictions" as defined in the Affero GPL 3.0, and may not be removed; it is as if they are added as an item (g) in the list in section 7 of that document.

ATTRIBUTION: Descriptions or advertisments of your product in any of the venues listed above ("VENUES:") must contain a prominent note stating that it is based upon our product, clearly stating the name or identifier of our product in that venue so that an unsophisticated reader will understand how to find our product and acquire it in that venue.

EXECUTABLE PRICE RESTRICTION:

If all of the following conditions are true:

In any case, you may (and must, if you distribute your product) still distribute the source code for free in any venue, provided that it is made available only under this license.

RATIONALE:

The idea is that you are not able to just copy our code, compile it, and offer it for sale (or for free). If we only prohibited outright copying, you could make a few quick changes in the code and then claim it was different. Therefore, we require your product to be substantially different from or better than ours.

We don't want to prevent you from improving on our product, or from using our code in other products, so if your product is substantially different from or better than ours, the price restriction doesn't apply.

Although we want to prevent you from depriving us of the profits of our work, we don't want to prevent you from selling modified versions of our product, so this is allowed provided that the price of the modified version is greater than ours, and that you let customers know about our cheaper product before they purchase yours.

This restriction makes the license incompatible with the Affero GPL 3.0. So, for any given piece of code, the extra restrictions expire after two years.

EXAMPLE 1:

For example, if this application is a swordfight game offered for sale in Android Market, and you create a swordfight game by re-skinning our game and adding one or two minor features, and then you offer it for sale in Android Market, the price of your swordfight app must be at least the price of ours, and the description of your game must state that it is based upon ours, using the name of our app as it appears in the Market, and state the price of our game.

EXAMPLE 2:

For example, if this application is a swordfight game offered for sale in Android Market, and you create a swordfight game which, in our opinion (or the opinion of the arbiter's, if you choose that), is a major improvement over ours, then the EXECUTABLE PRICE RESTRICTION doesn't apply.

EXAMPLE 3:

For example, if this application is a swordfight game offered for sale in Android Market, and you take the networking code out of it and reuse it in a different sort of game, then the EXECUTABLE PRICE RESTRICTION doesn't apply.

EXAMPLE 4:

Your product contains only code from our product which is more than two years old. Even if your product is similar to our product, the EXECUTABLE PRICE RESTRICTION doesn't apply.
"


I made up this license. Comments, concerns? -- BayleShanks


Porting Guide: MSM/QSD

Introduction

Many people bought many different phones, and some of them whish to help replicant and/or to port replicant to their phones or devices.
This guide will show what was done for the htc dream, so these people can understand the process better.
When talking about porting, this page talks about re-using existing product definitions. You will not learn how to
build Android for a device not currently supported by Android. Instead, you will learn how to build a version of
[Cyanogenmod http://www.cyanogenmod.com/] without proprietary parts.
To gain more insight in the Android build system, refer to Android Build System documentation which is part of
Android Platform Developer's Guide. You should find an answer there if you have any questions about the Makefiles referenced in this document.

Note: The Android Build System documentation above has been removed. You can find a mirror of the (outdated) documentation here and here.

Terminology

The RIL is the radio interface library, that is to say, a library that talks to the modem, usually (but not always) trough AT commands.
Basically the modem runs on a separate CPU,and there is some sort of communication needed between the main CPU and the modem CPU to make telephony work. For instance, the modem must tell you when you've got a call, and you must tell the modem that you want to call someone.
TODO: point to 0707 standard or newer

Help with source code

Keep in mind that on most devices, the full source code of the kernel is released.
However, some userspace libraries, or dlopened libraries (libraries loaded at runtime after the application started) are proprietary software,
so if you're porting to a new CPU/SOC keep in mind that you have the source code to the kernel interfaces.
That can help a lot, and sometimes there is even some sort of documentation in the headers.

Build the source

The first thing to do is to download the replicant sources:
BuildDream can be used as a reference: download and build the sources for your device.
Let's say the user has a HTC Wildfire. It is useful to know the codename of the device in question, which is "Buzz" in case
of the Wildfire.

You need to configure the build tree for our device. By default, a generic image
for the Android emulator will be built.
In BuildDream, you would use the following command to set up the build:

lunch cyanogen_dream_sapphire-eng 

Now, since you are not building for the HTC dream, you need to identify the right command that corresponds to your device.
In order to do that, run the following command and look at its output.
$ source build/envsetup.sh
including device/geeksphone/one/vendorsetup.sh
including device/htc/ace/vendorsetup.sh
including device/htc/bravoc/vendorsetup.sh
including device/htc/bravo/vendorsetup.sh
including device/htc/buzz/vendorsetup.sh
including device/htc/glacier/vendorsetup.sh
including device/htc/heroc/vendorsetup.sh
including device/htc/inc/vendorsetup.sh
including device/htc/legend/vendorsetup.sh
including device/htc/liberty/vendorsetup.sh
including device/htc/supersonic/vendorsetup.sh
including device/htc/vision/vendorsetup.sh
including device/motorola/sholes/vendorsetup.sh
including device/nvidia/harmony/vendorsetup.sh
including vendor/cyanogen/vendorsetup.sh

The last line is important:
$ cat vendor/cyanogen/vendorsetup.sh
add_lunch_combo cyanogen_ace-eng
add_lunch_combo cyanogen_bravo-eng
add_lunch_combo cyanogen_bravoc-eng
add_lunch_combo cyanogen_buzz-eng
add_lunch_combo cyanogen_dream_sapphire-eng
add_lunch_combo cyanogen_espresso-eng
add_lunch_combo cyanogen_glacier-eng
add_lunch_combo cyanogen_harmony-eng
add_lunch_combo cyanogen_hero-eng
add_lunch_combo cyanogen_heroc-eng
add_lunch_combo cyanogen_inc-eng
add_lunch_combo cyanogen_legend-eng
add_lunch_combo cyanogen_liberty-eng
add_lunch_combo cyanogen_one-eng
add_lunch_combo cyanogen_passion-eng
add_lunch_combo cyanogen_sholes-eng
add_lunch_combo cyanogen_supersonic-eng
add_lunch_combo cyanogen_vibrant-eng
add_lunch_combo cyanogen_vision-eng
add_lunch_combo cyanogen_z71-eng

PATH=$PATH:$PWD/vendor/cyanogen/tools ; export PATH

The output include the list of supported (by cyanogenmod) devices.
For instance if you have the Wildfire (codename 'buzz') phone do:
lunch cyanogen_buzz-eng

Then build the source, backup what's on your device, including the operating system, and flash the new replicant image.

Then test what works and what doesn't.

The images are located in

out/target/product/dream_sapphire

in the case of the HTC Dream. You need to look in the path that corresponds to your device.

Trying free replacements

The source code you just built contains some free replacements for the proprietary
libraries shipped by your phone vendor with the default firmware.

A list of proprietary libraries is available in

device/htc/dream_sapphire/extract-files.sh

Note: don't run this file, just look at it. If you run it, the proprietary files will be copied from your phone into the build tree. A build containing proprietary files would put you and
your users at risk. Additionally, it is illegal to redistribute such build, because the libraries are not redistributable(the copyright owner didn't allow you to redistribute them).

RIL test

I will take the example of how to use the free RIL (Radio Interface Library) to see if it works fine without modifications:
The proprietary RIL library (which you don't have in the phone) location is found looking at the extract-files.sh
here's a part of extract-files.sh:

adb pull /system/lib/libhtc_ril.so ../../../vendor/htc/$DEVICE/proprietary/libhtc_ril.so

Note: don't run this command, just look at it. If you run it, the proprietary files will be copied from your phone into the build tree. A build containing proprietary files would put you and
your users at risk. Additionally, it is illegal to redistribute such build, because the libraries are not redistributable(the copyright owner didn't allow you to redistribute them).

So looking at the above line the proprietary RIL is located here on the phone:
/system/lib/libhtc_ril.so

while the free ril is located here (known fact):
/system/lib/libreference-ril.so

In order to test the free RIL you could be tempted to do that:
# ./adb remount
# ./adb shell
mv /system/lib/libreference-ril.so /system/lib/libhtc_ril.so

But that wouldn't work as it wouldn't be using the right serial port, the correct way to try that is to use getprop/setprop:
# ./adb shell
# setprop
usage: setprop <key> <value>

What you can do to set the libre RIL is - possibly - this:
./adb shell
setprop rild.libpath /system/lib/libreference-ril.so
setprop rild.libargs -d/dev/smd0

Here's how it looks on a working replicant on the HTC Dream:
# ./adb shell
# getprop | grep ril
[ro.ril.hsxpa]: r2
[ro.ril.gprsclass]: r10
[rild.libpath]: [/system/lib/libreference-ril.so]
[rild.libargs]: [-d/dev/smd0]
[init.svc.ril-daemon]: [running]
[ro.ril.def.agps.mode]: r2
[gsm.version.ril-impl]: [android reference-ril 1.0]

Then, you can kill the ril daemon:

./adb shell killall rild

Then try the reference RIL. You can see debugging things and such by doing:
./adb logcat -b radio

That's also tested and worked on the gtklocker's HTC Hero, so I suppose it will work for the most HTC devices out there. If your device isn't listed anywhere, don't dare to try it.

Replacing proprietary libraries for real

On the HTC Dream the following proprietary libraries were replaced:
(Refer to ProprietaryHtcDreamLibsReplacement for more up to date details(or fix it if it's less recent))

The first thing you will have to do is to modify the build system.
The key thing to do is to change

RIL

Android Reference RIL

If the RIL you previously tried works fine, why not switching to it...directly in the build system.
Here's the diff between A working RIL and a non-working RIL for the htcdream:

android_device_htc_dream_sapphire$ git diff 5593d2899203ec378c306701788f1c43af9a6935 -- full_dream_sapphire.mk
diff --git a/full_dream_sapphire.mk b/full_dream_sapphire.mk
index 9ec7feb..eb1b956 100644
--- a/full_dream_sapphire.mk
+++ b/full_dream_sapphire.mk
@@ -40,7 +40,8 @@ PRODUCT_PROPERTY_OVERRIDES := \
     ro.media.dec.jpeg.memcap=10000000

 PRODUCT_PROPERTY_OVERRIDES += \
-    rild.libpath=/system/lib/libhtc_ril.so \
+    rild.libpath=/system/lib/libreference-ril.so \
+    rild.libargs=-d/dev/smd0 \
     wifi.interface=tiwlan0

 # Time between scans in seconds. Keep it high to minimize battery drain.


Note that full_dream_sapphire.mk is located here:
device/htc/dream_sapphire/full_dream_sapphire.mk

The diff is self-explanatory and how to do the change is left as an exercise to the reader.

In case the RIL need to be modified the sources are in :

hardware/ril/reference-ril

They are written in C.

HTC Generic RIL

Another RIL has been written for MSM devices originally running Windows Mobile and is used on the Replicant project as it works better than the Android reference RIL on most devices.

hardware/ril/libhtcgeneric-ril/Android.mk :

BUILD_HTCGENERIC_RIL := false

ifeq ($(TARGET_BOARD_PLATFORM),qsd8k)
  BUILD_HTCGENERIC_RIL := true
else ifeq ($(TARGET_BOARD_PLATFORM),msm7x30)
  BUILD_HTCGENERIC_RIL := true
else ifeq ($(TARGET_BOARD_PLATFORM),msm7k)
  BUILD_HTCGENERIC_RIL := true
endif

Then, on your device configuration, switch:

rild.libpath=/system/lib/libreference-ril.so
to:
rild.libpath=/system/lib/libhtcgeneric-ril.so

Audio libraries

On the HTC dream the audio libraries were modified.
If your device is an msm7k "CPU" (in reality it's called a SOC, or system on a chip), it already contain the routing fix.
Note several things on the commit:

On the nexus one the proprietary libacoustic libraries are only used for bluetooth(all the rest works if you pushed the firmwares).

On the dream (msm7k), libacoustic has been fully replaced, see "it loads the values from the /system/etc/AudioPara4.csv CSV file to MSM shared memory, which fixes in-call volume regulation and adds support for No Mic Wired Headset. It should also add support for other other things (probably including bluetooth devices) but this has not been tested yet.
The existing replacement code (hardware/msm7k/libaudio/AudioAcoustic.cpp) should work for your msm7k device but it has only been tested on the Dream.

*Note that (even if unconfirmed) it should more likely work the same way for every msm7k device, so try the code without any modification first and do the following steps only if the code does not work for your msm7k device! *

If it does not work, check that your device contains the /system/etc/AudioPara4.csv CSV file. If it does not, the file may have another name, then you should modify replicant code to use the filename of your device and test if it works.

If you don't see any CSV file anywhere, then your device must not work like HTC Dream and you'll probably have to write the code to support acoustic or find another working replacement. You can read jbruneaux's work on audio acoustic for WinCE devices from git://gitorious.org/~jbruneaux/xdandroid/hardware_msm7k_libacoustic.git (userland) and git://gitorious.org/linux-on-qualcomm-s-msm/linux-msm-home-work.git branch htc-msm-2.6.27-libacoustic (kernel-space). Note that audio acoustic is not absolutely necessary to make audio work, it'll just cause some minor issues as written above.

To make sure it parses the CSV file, run adb logcat | grep Audio and find the following lines:

D/AudioAcousticMSM72XX(  122): Successfully opened /system/etc/AudioPara4.csv
D/AudioAcousticMSM72XX(  122): CSV Header: Dream_TMU_20090305
D/AudioAcousticMSM72XX(  122): Read:
D/AudioAcousticMSM72XX(  122): 24 Audio_Path_Table entries
D/AudioAcousticMSM72XX(  122): 24 Audio_Path_Uplink_Table entries
D/AudioAcousticMSM72XX(  122): 35 Phone_Acoustic_Table entries
D/AudioAcousticMSM72XX(  122): 35 BT_Phone_Acoustic_Table entries
D/AudioAcousticMSM72XX(  122): 24 HTC_VOC_CAL_CODEC_TABLE_Table entries
D/AudioAcousticMSM72XX(  122): 0 CE_Acoustic_Table entries

Then, if it parses the file but does not work, it's probably because the addresses (or the size) where the tables must be written in MSM shared memory are not the same for the Dream and for your device.
In order to find the correct addresses, you'll have to use CyanogenMod code with the non-free libhtc_acoustic.so lib that you can get from CyanogenMod downloadable zip for your device.
move the hardware/msm7k/ directory to another place '''not in the build tree''' or it'll fail ( mv hardware/msm7k/ ../msm7k .
Then download CyanogenMod code:
git clone git://github.com/CyanogenMod/android_hardware_msm7k.git -b froyo-stable hardware/msm7k/

Now you need to modify the kernel-side driver to print some useful infos on file kernel-msm/arch/arm/mach-msm/htc_acoustic.c, function acoustic_mmap(), add the following code:

D(" -- vma dump start --\n");

D("vm_start=%x (%d)\n", vma->vm_start, vma->vm_start);
D("vm_end=%x (%d)\n", vma->vm_end, vma->vm_end);
D("vm_page_prot=%x (%d)\n", vma->vm_page_prot,vma->vm_page_prot);
D("vm_flags=%x (%d)\n", vma->vm_flags, vma->vm_flags);
D("vm_pgoff=%x (%d)\n", vma->vm_pgoff, vma->vm_pgoff);

D(" -- vma dump end --\n");

Then build the code (make -j9 bootimage && make-j9 systemimage), and flash system.img and boot.img to your device, boot it, copy the libhtc_acoustic.so lib to /system/lib/ (you need to remount /system using adb remount to write under /system) and check the kernel logs with adb shell dmesg | grep acoustic. You should see something like:

<6>[   22.250274] htc-acoustic: open
<6>[   22.252716] htc-acoustic: mmap
<6>[   22.253265] htc-acoustic:  -- vma dump start --
<6>[   22.254028] htc-acoustic: vm_start=4010c000 (1074839552)
<6>[   22.254699] htc-acoustic: vm_end=40119000 (1074892800)
<6>[   22.255310] htc-acoustic: vm_page_prot=38f (911)
<6>[   22.256011] htc-acoustic: vm_flags=400844ff (1074283775)
<6>[   22.256622] htc-acoustic: vm_pgoff=1f4a (8010)
<6>[   22.257293] htc-acoustic:  -- vma dump end --
<6>[   22.742675] htc-acoustic: ioctl
<6>[   22.743103] htc-acoustic: ioctl: ACOUSTIC_ARM11_DONE called 123.
<6>[   22.746612] htc-acoustic: ioctl: ONCRPC_ACOUSTIC_INIT_PROC success.
<6>[   22.747344] htc-acoustic: release

Now you can get the size of the dedicated memory area: vm_end - vm_start = 0x40119000 - 0x4010c000 = 0xd000.
Then, you'll have to dump the entire memory to a file that you need to create: adb shell touch /data/dump. Add a function to AudioHardware.cpp :

void acoustic_mmap_dump(void)
{
    uint8_t *test_map_base;
    uint8_t *ptr, nval;
    int fd, fdd=0;
    off_t [[TargetAddr]];
    int len;

    fd = open("/dev/htc-acoustic", O_RDWR | O_SYNC);
    fdd = open("/data/dump", O_RDWR | O_TRUNC | O_CREAT);

    test_map_base = (uint8_t *)
        mmap(0, 0xd000, PROT_READ | PROT_WRITE, MAP_SHARED, fd,
         0);
//    test_virt_base = test_map_base + (TargetAddr & MAP_MASK);
//    LOGD("virtual base at %p (phys=0x%X)\n", test_virt_base, [[TargetAddr]]);

    LOGD(" -- htc-acoustic memory read -- \n");
    LOGD("beginning adress is@%p\n", test_map_base);
          for (len = 0; len < 0xd000; len++)
        {
            if( write(fdd, test_map_base, sizeof(uint8_t) ) < 0)
            {
                LOGE("write failed");
                break;
            }
            //LOGD("0x%x (%d) @%p",  *(test_map_base), *(test_map_base), test_map_base);
          test_map_base++;
        }

    munmap(test_map_base, 0xd000);
    close(fdd);
    close(fd);
}

replace 0xd000 by the size you found out and call it after int rc = set_acoustic_parameters(); on the AudioHardware::AudioHardware() function.
Build the code (make -j9 systemimage), flash system.img to your device and get /data/dump: adb pull /data/dump. This should copy dump to your current directory. You can try to load that file in MSM shared memory at the exact place where you dumped it. To do that, add the following functions to AudioHardware.cpp (don't forget to replace the size, 0xd000 if it's different for your device):

#define ACOUSTIC_IOCTL_MAGIC 'p'
#define ACOUSTIC_NOTICE        _IOW(ACOUSTIC_IOCTL_MAGIC, 42, unsigned int)
#define ACOUSTIC_ARM11_DONE    _IOW(ACOUSTIC_IOCTL_MAGIC, 22, unsigned int)

void acoustic_mmap(void)
{
    char *test_map_base;
    volatile int *ptr, nval;
    int fd, fdd;
    off_t [[TargetAddr]];
    int len;

    fd = open("/dev/htc-acoustic", O_RDWR | O_SYNC);
    fdd = open("/data/dump", O_RDWR);

    test_map_base = (char *)
        mmap(0, 0xd000, PROT_READ | PROT_WRITE, MAP_SHARED, fd,
         0);
//    test_virt_base = test_map_base + (TargetAddr & MAP_MASK);
//    LOGD("virtual base at %p (phys=0x%X)\n", test_virt_base, [[TargetAddr]]);

    LOGD(" -- htc-acoustic memory write -- \n");
          for (len = 0; len < 0xd000; len++)
        {
          read(fdd, test_map_base, sizeof(char) );
          test_map_base++;
        }

    munmap(test_map_base, 0xd000);
    close(fdd);
    close(fd);
}

void acoustic_done(void)
{
     int fd;
           fd = open("/dev/htc-acoustic",O_RDWR);

               if (fd < 0) {
                LOGE("Cannot open htc-acoustic device");
                close(fd);
                return;
               }

       ioctl(fd,ACOUSTIC_ARM11_DONE, NULL);
       close(fd);
}

Now replace:

    set_acoustic_parameters = (int (*)(void))::dlsym(acoustic, "set_acoustic_parameters");
    if ((*set_acoustic_parameters) == 0 ) {
        LOGE("Could not open set_acoustic_parameters()");
        return;
    }

    int rc = set_acoustic_parameters();
    if (rc < 0) {
        LOGE("Could not set acoustic parameters to share memory: %d", rc);
//        return;
    }

with:

acoustic_mmap();
acoustic_done();

Build system.img: make -j9 systemimage and flash it to your device. Now '''audioacoustic should work''' but it's not a clean way to make it work: the clean way is to parse the CSV file and load it to MSM shared memory with free code. If it does not work, then your device is definitely not working like the Dream and you'll have to find another way to make it work.

Replace the hardware/msm7k/ folder by the replicant one. The next step is to find the right addresses to write the tables in MSM shared memory. To find this out, you have to read the dump and understand where each table begins. So first, you have to hexdump the dump:
hexdump -C dump > dump.txt. This will create dump.txt, containing the hexedacimal values of dump as text. So now you should be able to understand where each table begins. As an example, here's how it was done with the dream values: consider the following as the beginning of the dump.txt file:

00000000  35 71 36 61 37 00 38 00  39 03 3a 00 3b 00 3c 00  |5q6a7.8.9.:.;.<.|
00000010  3d 00 3e 00 3f 00 40 00  41 1c 42 00 43 00 44 00  |=.>.?.@.A.B.C.D.|
00000020  45 00 46 00 47 00 48 00  49 00 4a 01 4b 00 4c 00  |E.F.G.H.I.J.K.L.|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
00000080  35 71 36 61 37 00 38 00  39 03 3a 00 3b 00 3c 00  |5q6a7.8.9.:.;.<.|
00000090  3d 00 3e 00 3f 00 40 00  41 1c 42 00 43 00 44 00  |=.>.?.@.A.B.C.D.|
000000a0  45 00 46 00 47 00 48 00  49 00 4a 01 4b 00 4c 00  |E.F.G.H.I.J.K.L.|
000000b0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

it's the 2 first elements of the table we want to find the address (which will be 00000000, the beginning of the table). Now read AudioPara4.csv. On the dream, you can read:

A0,HTC_VOC_CODEC_EARCUPLE_VOICE,35,71,36,61,37,0,38,0,39,3,3A,0,3B,0,3C,0,3D,0,3E,0,3F,0,40,0,41,1C,42,0,43,0,44,0,45,0,46,0,47,0,48,0,49,0,4A,1,4B,0,4C,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
A1,HTC_VOC_CODEC_EARCUPLE_MIDI,35,71,36,61,37,0,38,0,39,3,3A,0,3B,0,3C,0,3D,0,3E,0,3F,0,40,0,41,1C,42,0,43,0,44,0,45,0,46,0,47,0,48,0,49,0,4A,1,4B,0,4C,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

you can see that 35 71 36 61 37 00 38 00 39 03 3a 00 3b 00 3c 00 is the same as 35,71,36,61,37,0,38,0,39,3,3A,0,3B,0,3C,0, so 35 71 36 61 37 00 38 00 39 03 3a 00 3b 00 3c 00 is the beginning of the first element of table A. So table A starts at 0.

Now if you read the ParseAudioParaLine function from AudioAcoustic.cpp (on the already existing free audio acoustic code), you can see:

        case 'A':
[…]
            while ( (token = strtok(NULL, ",")) ) {
                Audio_Path_Table[table_num].array[field_count++] = strtol(token, &ps, 16);
            };
            break;

So "A" is for the Audio_Path_Table table.
Now you have to do the same work for every table. You can see that another tables begins when the table-specific characters change e.g.:

00001780  35 00 36 00 37 ff 38 00  39 00 3a 00 3b 00 3c c4  |5.6.7.8.9.:.;.<.|
00001790  3d c4 3e 08 3f 80 40 05  41 00 42 00 43 00 44 00  |=.>.?.@.A.B.C.D.|
000017a0  45 00 46 00 47 00 48 00  49 00 4a 00 4b 00 4c 00  |E.F.G.H.I.J.K.L.|
000017b0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
00001800  00 00 00 40 13 20 00 00  b2 7f fd 23 00 00 33 2d  |...@. .....#..3-|
00001810  00 00 80 0c 9a ff 80 1d  33 f3 ec 01 ee ff 0a 20  |........3...... |
00001820  65 7f 00 00 00 ed 00 00  00 00 d9 3f 00 00 80 0c  |e..........?....|
00001830  9a ff 0c 1b 33 f3 ec 01  ee ff 0a 20 65 7f ff 7f  |....3...... e...|
00001840  00 08 ff 7f 9f 14 00 00  14 00 00 08 00 20 00 20  |............. . |
00001850  fa 00 46 00 02 00 ff 02  40 00 20 00 50 46 40 00  |..F.....@. .PF@.|
00001860  a0 41 00 08 63 00 ff 4d  ff 4d 02 00 00 3f d0 07  |.A..c..M.M...?..|
00001870  00 00 00 00 00 01 00 01  00 02 50 00 00 03 50 01  |..........P...P.|
00001880  64 00 a8 1c c2 01 e0 2e  a0 0f ff ff 00 00 00 00  |d...............|
00001890  00 00 00 00 00 00 00 00  00 40 00 00 00 00 00 00  |.........@......|
000018a0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

You can see that a new table begins at 0x1800.
Note that some tables may not start at easy-to-find addresses such as 0x1800 but may start at in the middle of an hexdump line (so it makes the task even harder).

When you have found all the correct addresses for every table in your CSV file, you should check that your tables have the same size than the tables you got from the dump. If it's not, adjust the tables defined in AudioAcoustic.h and the tables defined at the top of AudioAcoustic.cpp.
When all that stuff is ok, it's possible that there is a necessary footer to make it work. On the Dream, it is:

0000c8e0  78 56 34 12 00 00 00 00  00 00 00 00 00 00 00 00  |xV4.............|

(present at the end of the dump file).

Now that you found out the size of the memory map, the address of each table, adjusted the size of the tables and found the footer, it's time to put the remaining infos on the free code.
Modify with the values you found out, on the file hardware/msm7k/libaudio/AudioAcoustic.cpp:

static int mmap_size = 0xd000;
static int mmap_address_audio_path_table = 0x0;
static int mmap_address_audio_path_uplink_table = 0xc00;
static int mmap_address_phone_acoustic_table = 0x1800;
static int mmap_address_bt_phone_acoustic_table = 0x4a00;
static int mmap_address_htc_voc_cal_codec_table_table = 0xc700;
static int mmap_address_htc_acoustic_end = 0xc8e0;

and adapt the array sizes both on the top of AudioAcoustic.cpp and AudioAcoustic.h (if you didn't do it already).

Then build an image (make -j9 systemimage) and it should work. If it does not, please check that you successfully passed all the required steps.
But the fact is that you replaced Dream values with the correct values for your device, so it will break audio acoustic for Dream.
The solution would be to write a set_device_configuration() which selects the good values for the device we build replciant for and the appropriated tables.
Nothing like that has been written yet since replicant AudioAcoustic hasn't been ported to any other device yet. Please notify replicant developers to write such a function (or do it yourself) before you send the code.

GPS

Two GPS libraries exist:

libgps

For adding support to libgps you need to enable it like in this commit:
add the following(or modify if it's already there but holds another value) in device/htc/dream_sapphire/BoardConfig.mk (replace dream_saphire by your device code) :

BOARD_HAVE_GPS_HARDWARE := true
BOARD_GPS_LIBRARIES := libhardware

I'm not sure if the "BOARD_HAVE_GPS_HARDWARE := true" is really needed.

If your device is different from the htc dream you may have to modify the GPS library code to match your device,
Here's the adaptation made for the htc dream:

hardware/libhardware_legacy/gps$ diff -u ../../../../repos_external/phh_libhardware_legacy/gps/gps-rpc.c ./gps-rpc.c 
--- ../../../../repos_external/phh_libhardware_legacy/gps/gps-rpc.c    2010-08-15 11:35:03.210095153 +0200
+++ ./gps-rpc.c    2011-01-06 16:46:45.417685002 +0100
@@ -464,8 +464,8 @@
 }

 int init_gps6125() {
-    struct CLIENT *clnt=clnt_create(NULL, 0x3000005B, 0, NULL);
-    struct CLIENT *clnt_atl=clnt_create(NULL, 0x3000001D, 0, NULL);
+    struct CLIENT *clnt=clnt_create(NULL, 0x3000005B, 0x90380d3d, NULL);
+    struct CLIENT *clnt_atl=clnt_create(NULL, 0x3000001D, 0x51c92bd8, NULL);
     int i;
     _clnt=clnt;
     SVCXPRT *svc=svcrtr_create();
@@ -538,33 +538,21 @@

 int init_gps_rpc() {
-    int fd=open("/sys/class/htc_hw/amss", O_RDONLY);
-    char bufr32;
-    bzero(buf, 32);
-    read(fd, buf, 32);
-    if(strncmp(buf, "6125", 4)==0)
-        amss=A6125;
-    else if((strncmp(buf, "5225", 4)==0) || (strncmp(buf, "6150", 4)==0))
-        amss=A5225;
-    else
-        amss=A6125; //Fallback to 6125 ATM
-    if(amss==A6125)
-        init_gps6125();
-    else if(amss==A5225)
-        init_gps5225();
+    amss=A6125;
+    init_gps6125();
     return 0;
 }

 void gps_get_position() {
     int i;
-    for(i=5;i;--i) if(!can_send) sleep(1);//Time out of 5 seconds on can_send
+    for(i=3;i;--i) if(!can_send) sleep(1);//Time out of 5 seconds on can_send
     can_send=0;
     pdsm_get_position(_clnt, 0, 0, 1, 1, 1, 0x3B9AC9FF, 1, 0,0,0,0,0, 0,0,0,0,0, 0,0,0,0,0, 0,0,1,32,2,client_IDsr2);
 }

 void exit_gps_rpc() {
-    if(amss==A6125)
-        pdsm_client_end_session(_clnt, 0, 2);
+    //if(amss==A6125)
+    //    pdsm_client_end_session(_clnt, 0, 2);
     //5225 doesn't seem to like end_session ?
     //Bah it ends session on itself after 10seconds.
 }

so let's go step by steps on that diff:
First we see that:

+    struct CLIENT *clnt=clnt_create(NULL, 0x3000005B, 0x90380d3d, NULL);
+    struct CLIENT *clnt_atl=clnt_create(NULL, 0x3000001D, 0x51c92bd8, NULL);

This corresponds to some devices nodes:

# ls -l /dev/oncrpc
crw-rw----    1 radio    system    253,   0 Jan  6 16:43 00000000:0
crw-rw----    1 radio    system    253,  11 Jan  6 16:43 30000000:5a10cf88
crw-rw----    1 radio    system    253,   9 Jan  6 16:43 30000002:aa2b1a44
crw-rw----    1 radio    system    253,   4 Jan  6 16:43 30000003:94103dec
crw-rw----    1 radio    system    253,  30 Jan  6 16:43 3000000a:71d1094b
crw-rw----    1 radio    system    253,  28 Jan  6 16:43 3000000e:2bf06595
crw-rw----    1 radio    system    253,  26 Jan  6 16:43 3000000f:46d257e5
crw-rw----    1 radio    system    253,  23 Jan  6 16:43 30000013:e94e8f0c
crw-rw----    1 radio    system    253,  22 Jan  6 16:43 30000014:7cfcd2c6
crw-rw----    1 radio    system    253,  21 Jan  6 16:43 30000016:c713bd79
crw-rw----    1 radio    system    253,  19 Jan  6 16:43 30000019:acb4a896
crw-rw----    1 radio    system    253,  18 Jan  6 16:43 3000001b:97d7b24a
crw-rw----    1 radio    system    253,  12 Jan  6 16:43 3000001d:51c92bd8
crw-rw----    1 radio    system    253,   8 Jan  6 16:43 30000021:f330a24e
crw-rw----    1 radio    system    253,  14 Jan  6 16:43 3000003c:03d4377c
crw-rw----    1 radio    system    253,  29 Jan  6 16:43 30000048:0da5b528
crw-rw----    1 radio    system    253,  17 Jan  6 16:43 30000059:00000000
crw-rw----    1 radio    system    253,  16 Jan  6 16:43 3000005a:00000000
crw-rw----    1 radio    system    253,  13 Jan  6 16:43 3000005b:90380d3d
crw-rw----    1 radio    system    253,   7 Jan  6 16:43 3000005f:95d1d9f5
crw-rw----    1 radio    system    253,   5 Jan  6 16:43 30000060:bcfb5d63
crw-rw----    1 radio    system    253,   2 Jan  6 16:43 30000061:fb837d0b
crw-rw----    1 radio    system    253,  31 Jan  6 16:43 30000066:1f4b343e
crw-rw----    1 radio    system    253,  27 Jan  6 16:43 3000006b:0aabc7a4
crw-rw----    1 radio    system    253,  25 Jan  6 16:43 3000006c:00000000
crw-rw----    1 radio    system    253,  20 Jan  6 16:43 30000075:f708938d
crw-rw----    1 radio    system    253,  15 Jan  6 16:43 30000079:00000000
crw-rw----    1 radio    system    253,   1 Jan  6 16:43 30000081:ccc5b439
crw-rw----    1 radio    system    253,  24 Jan  6 16:43 3000fe00:00000000
crw-rw----    1 radio    system    253,  10 Jan  6 16:43 3000fffe:00000000
crw-rw----    1 radio    system    253,   6 Jan  6 16:43 30100001:00000000
crw-rw----    1 radio    system    253,   3 Jan  6 16:43 30100002:00000000

Theses 2 lines should ring a bell:

crw-rw----    1 radio    system    253,  13 Jan  6 16:43 3000005b:90380d3d
crw-rw----    1 radio    system    253,  12 Jan  6 16:43 3000001d:51c92bd8

Next there is that line:

+    for(i=3;i;--i) if(!can_send) sleep(1);//Time out of 5 seconds on can_send

This is the time between 2 requests, if you put it too low it can reboot your phone(it will crashes and reboot)

libloc_api

For adding support for libloc_api you need to modify the BOARD_GPS_LIBRARIES variable

That repository should have newer devices support(like in AOSP) and older too(like rmcc's commits)

testing

cd hardware/libhardware_legacy/tests/gpstest/
mm

gives you a gpstest binary, copy it to the device and run it, it'll tell you if it has a fix

Note on the GPS

Note that messing with GPS can reboot(that is to say your phone crashes and reboots because of that) your phone on certain devices(like the htc dream or the nexus one).

The GPS is attached to the modem on the htc dream and the nexus one.
The only way to request a fix or to activate it is trough a rpc mecanism that is between the modem and the CPU that runs Android.
That RPC mecanism uses shared memory between the modem and the CPU that runs Android.

On the htcdream and the nexusone a serial line is emulated on top of the RPC mecanism: the serial lines can be accesed at /dev/smd0 for the modem(AT commands) and /dev/smd27 for the GPS NMEA.
So compatibility with applications that understand NMEA is garanteed.

Note that the GPS parsing library doesn't require to use NMEA, it could also uses the RPC directly(to be verified)

Sensors

Devices with an hardware keyboard slide can rotate with the slide of the keyboard, so accelerometers are not strictly necessary. Examples of such device include the HTC dream.
Other devices lack that hardware keyboard, and so the only way to rotate is trough theses accelerometers. Examples of such device include the nexus one.

The nexusone has akmd.free which is the free implementation of akmd, the sensor daemon(which handle rotation)

akmd.free

akmd.free is located in:

hardware/akmd_free

it has currently(at the time of writing) support for akm8973+bma150 based sensors.
akmd.free was made specifically for the htc hero by its authors.
The device supported include the nexus one(tested) and the HTC hero(not tested,not activated).

In order to activate the support for it you must add that in your BoardConfig.mk

BUILD_AKMD := true

If you need to add support for other akm sensors you could modify hardware/akmd_free/jni/Android.mk, for instance the nexusone had an issue with rotation beeing done in the reverse sense, so I did that:

+#ifdef TARGET_DEVICE_NEXUSONE
+    abuf[index] = Vector(-bma150_datar0, -bma150_datar1, bma150_datar2);
+#else
     abuf[index] = Vector(bma150_datar0, -bma150_datar1, bma150_datar2);
+#endif

And that:
ifeq ($(TARGET_DEVICE),passion)
  LOCAL_CFLAGS += -DTARGET_DEVICE_NEXUSONE
endif

Slowness issues

If the device is too slow without non-free libs, there can still be some workarounds: The commits with these fixes for Nexus One are:

Re-using source code

The previous source code re-used some public source code that was licensed under the Apache 2.0 license.
The ril will also re-use some public source code licensed under Apache 2.0.
That is the advised way to do it as it save some time and is easier to do, however proper credit must be attributed, at least in the commit message.
It is even advised to look at the public apache 2.0 source code of other rils libraries or components of android.

Ril

Source organization and commit access

Until now we made some changes in the tree, but we want the changes to land upstream in replicant.
For instance let's say we modified only the ril path like in the ril section in

device/htc/dream_sapphire/full_dream_sapphire.mk 

first we save our modifications:

cd device/htc/dream_sapphire/
git diff > git_diff.patch

then we find where is the root of the git repository we are in:

cd replicant-2.2 #top replicant directory where everything is in
cd .repo
cat manifest.xml

and we find that:

  <project path="device/htc/buzz" name="CyanogenMod/android_device_htc_buzz" remote="github" />

so...now our repository is in device/htc/buzz
We will now look where the source repository is:

cd device/htc/buzz
cd .git
cat config

We find that:

    url = git://github.com/CyanogenMod/android_device_htc_buzz.git

Then create a directory, not under the replicant-2.2 directory that will contain your repositories:

mkdir repo
cd repo

and clone the source:

git clone git://github.com/CyanogenMod/android_device_htc_buzz.git
cd android_device_htc_buzz

apply the previous patch:

git apply path/to/git_diff.patch

commit locally the result:

git commit -s

Note that the commit message should have the following format:
The first line should be a summary
Followed by a linebreak
And then the details explaining the commit
If you made an error writing the commit message do

git commit --amend

TODO: complete for sending the git patch(git format-patch -1,git send-email)

Pushing to replicant

TODO: git remote add+git push


PortingGuideS5PC110

This guide assumes your phone has a S5PC110/Exynos 3110 SoC

Prerequisites

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

Investigating the phone hardware

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.

Getting everything ready

In order to prepare everything for the Replicant port:

Cloning the device files

Once your Replicant tree is ready, you can start by adding the necessary repos for your device.
That means cloning the necessary repos in the right place. These repos are:
Android version CyanogenMod version Kernel version
Android 2.3 CM 7.x 2.6.35
Android 4.0 CM 9.x 3.0.8
Android 4.1 CM 10 3.0.31
Android 4.2 CM 10.1 3.4
Sometimes, these repos aren't held in CyanogenMod repos but instead in some other projects repos, such as:

Generally speaking, it is a good idea to ask the members of the CyanogenMod community where to find what (especially for kernel sources and for which branch to use).

Clone these repos in the correct locations and remove the prefix (e.g. android_device_samsung_crespo must be cloned in device/samsung/ and renamed to crespo).

Creating the kernel repo

If the kernel repo is nowhere to be found, you'll need to get the kernel source directly from the vendor, especially if your device is supported by a 3rd party CyanogenMod fork.
Keep in mind that the Linux kernel is GPLv2, so vendors have the legal obligation to release the modified kernel sources as soon as they sell you the device.
That means the kernel sources will be available online. Here are some websites where such releases are done:

Once you have the kernel sources, read the instructions to find out which defconfig to use.

Since manufacturers usually don't release the git history along with the files, you'll need to recreate a git repo:

Now that you have a git repo, you can move it to the Replicant code tree, under the name: kernel/vendor/devices (e.g. kernel/samsung/aries).
Make sure to make the devices name match the devices in android_device_vendor_devices-common if the kernel is shared across these devices or to match the device in android_device_vendor_device.

In case of a prebuilt kernel

Some devices are still using a prebuilt kernel. Even though the CyanogenMod team is trying to avoid that, it remains in many repos.
For such devices, you will need to remove the prebuilt binaries and the instructions to copy the prebuilt kernel and its modules.

In the device repository (device/vendor/device) and common repository for your device (if any), remove the prebuilt kernel and modules (usually called kernel and module.ko (replace module with the name of a module) or a modules directory).
Remove the instructions to copy these prebuilts on the makefiles. Remove instructions such as:

PRODUCT_COPY_FILES += \
    $(LOCAL_KERNEL):kernel

LOCAL_KERNEL := $(LOCAL_PATH)/kernel

and anything regarding TARGET_PREBUILT_KERNEL as well as the instructions to copy the prebuilt modules.

The BoardConfig.mk (or BoardConfigCommon.mk in the common directory for your device) will most likely hold a line like:

TARGET_PREBUILT_KERNEL := device/samsung/p5/kernel

you must remove this line.

Now that the device repository has no prebuilt instructions, you can add the instructions to build the kernel. In the BoardConfig.mk file, add the following lines:

TARGET_KERNEL_SOURCE := kernel/samsung/p3
TARGET_KERNEL_CONFIG := samsung_p5_defconfig

and make sure to replace the location and defconfig by the correct values for your devices (being the location of the device kernel tree and the appropriate defconfig).

Building the correct kernel image format

There are different types of kernel images:

You need to find out which type of kernel image your device uses. Asking people who know about that is the best idea.

Android image

This is the easiest case to handle: just make sure the CONFIG_INITRAMFS_SOURCE option in the kernel defonfig is left blank or undefined:

CONFIG_INITRAMFS_SOURCE="" 

zImage with built-in initramfs

Building a zImage with a built-in initramfs requires the following steps:
In the kernel defconfig, define the CONFIG_INITRAMFS_SOURCE option that way:

CONFIG_INITRAMFS_SOURCE="../../root" 

Once this is done, duplicate the defconfig and add the _recovery prefix before the _defconfig ending (e.g. herring_recovery_defconfig), edit that file and replace CONFIG_INITRAMFS_SOURCE with:

CONFIG_INITRAMFS_SOURCE="../../recovery/root" 

Back to the device repository, edit the BoardConfig.mk file and add the following line:

TARGET_KERNEL_RECOVERY_CONFIG := samsung_p5_recovery_defconfig

and make sure to replace the defconfig by the appropriate defconfig you just cloned (the one with the _recovery_defconfig ending).

Still in the device repository, create a bootimg.mk file containing the following:

LOCAL_PATH := $(call my-dir)

$(INSTALLED_BOOTIMAGE_TARGET): $(INSTALLED_KERNEL_TARGET)
    $(ACP) $(INSTALLED_KERNEL_TARGET) $@

$(INSTALLED_RECOVERYIMAGE_TARGET): $(INSTALLED_RECOVERY_KERNEL_TARGET)
    $(ACP) $(INSTALLED_RECOVERY_KERNEL_TARGET) $@

Edit the BoardConfig.mk file and add the following line:

BOARD_CUSTOM_BOOTIMG_MK := device/vendor/device/bootimg.mk

and make sure to replace device/vendor/device/ to the correct path to your device's repository.

uImage with built-in initramfs

Follow the previous instructions (zImage with built-in initramfs) and set the BOARD_USES_UBOOT variable in the BoardConfig.mk file:

BOARD_USES_UBOOT := true

Adding the device to the build targets

Now that the repos are cloned, you need to modify some makefiles to cope with Replicant paths.
In the device repository (device/vendor/device), modify the file called cm.mk and replace the vendor/cm/ occurrences by vendor/replicant/. Other makefiles may need that as well (in any case, build will fail very early if you missed one). In that same cm.mk file, change the PRODUCT_NAME variable by repalcing the cm prefix with replicant (e.g. change PRODUCT_NAME := cm_crespo to PRODUCT_NAME := replicant_crespo).

Now that your device files are ready, you can declare a new build target: these are held in vendor/replicant/jenkins-build-targets.
Modify that file and add a line (at the end) with the PRODUCT_NAME you set and the -eng suffix (e.g. replicant_crespo-eng).

Setting up the build environment

From now on, everything should be ready to start a build. To check for errors or missed occurrences, start a terminal in the Replicant tree root and lunch:

source build/envsetup.sh
lunch replicant_device-eng

Adapt replicant_device-eng from what you added to the jenkins-build-target (e.g. replicant_crespo-eng).
If an error occurs, it will explicitly report it and you'll need to fix it before doing anything.
If everything works correctly, you should see something like:

============================================
PLATFORM_VERSION_CODENAME=REL
PLATFORM_VERSION=4.0.4
TARGET_PRODUCT=replicant_crespo
TARGET_BUILD_VARIANT=eng
TARGET_BUILD_TYPE=release
TARGET_BUILD_APPS=
TARGET_ARCH=arm
TARGET_ARCH_VARIANT=armv7-a
HOST_ARCH=x86
HOST_OS=linux
HOST_BUILD_TYPE=release
BUILD_ID=IMM76L
============================================

You must repeat these steps everytime before building anything on a freshly-opened terminal.
Remember:

source build/envsetup.sh
lunch replicant_device-eng

(make sure to replace device by your device's product name).

Building the kernel

Once the devices repos are in place and the build target is configured, you are now able to start building things and the first thing to build is obviously the kernel.

Once your terminal is correctly setup (the lunch command worked correctly), you can start building the kernel:

make -j9 bootimage

It will take a couple of minutes, depending on how fast your setup is. At the end, it should create a boot.img file in out/target/product/device (replace device with your device's product name).
If not, an error will be shown and you'll have to fix it.

Building recovery

Building the kernel with success is a great step, but it is hard to make any use of it (unless your userspace matches the initramfs, but that's not always the case).
That's why you'll have to build recovery next. Furthermore, some devices only allow flashing via recovery, so this is fundamental.

Various hardware and software fixes to get things working.

To get software video decoding (OMX stuff):


Porting Replicant to Android 10

This page contains old build instructions for Replicant 10. The source code is kept to do regression testing. Active development has moved into Replicant 11.

Replicant 9 source code and build instruction have been kept to do regression tracking: Porting Replicant to Android 9.

Precautions

See RunningReplicant11 before installing Replicant 10 on your device to not break it.

Building Replicant 10

Source code

$ repo init -u https://git.replicant.us/replicant-next/manifest.git -b replicant-10-dev
$ repo sync

Alternatively a shallow copy of the source tree can be fetched in order to save on disk space:

$ repo init -u https://git.replicant.us/replicant-next/manifest.git -b replicant-10-dev --depth=1
$ repo sync -c

To unshallow a specific module:

$ cd path/to/module
$ git fetch --unshallow <remote>

Build dependencies

For Trisquel 8

sudo apt-get install bc bison build-essential bsdmainutils ccache curl flex g++-multilib gcc-multilib gettext git gnupg gperf imagemagick lib32ncurses5-dev lib32readline-dev lib32z1-dev liblz4-tool libncurses5-dev libsdl1.2-dev libssl-dev libwxgtk3.0-dev libxml2 libxml2-utils lzop python-mako pngcrush rsync schedtool squashfs-tools xsltproc zip zlib1g-dev
sudo apt-get install gcc-5-arm-linux-gnueabi

Fixing the build environment

Allow system binaries for building

By default, the Android 10 build system can only use the prebuilt binaries it ships.

While having binary toolchains is better for reproducible builds, and that the binaries are free software, this creates a number of issues:

As GNU/Linux distribution's tools can be rebuilt and are easier to trust, we are using that for now.

Setting the following envrionment variable allows to use your distribution tools:

$ export TEMPORARY_DISABLE_PATH_RESTRICTIONS=true

Note that setting this variable does not automatically make the build system use only system binaries: if a prebuilt binary exist, it will use it, if not, it will use your system binary.

Lots of further effort must be put into transitioning to the system binaries and/or creating a scripts that would build all the required tools.

Mako (Python) for Mesa

To avoid the following error:

16:20:13 See https://android.googlesource.com/platform/build/+/master/Changes.md#PATH_Tools for more information.
[  3% 2585/70375] build out/target/product/i9305/gen/STATIC_LIBRARIES/libmesa_nir_intermediates/nir/nir_builder_opcodes.h
FAILED: out/target/product/i9305/gen/STATIC_LIBRARIES/libmesa_nir_intermediates/nir/nir_builder_opcodes.h
/bin/bash -c "python external/mesa3d/src/compiler/nir/nir_builder_opcodes_h.py external/mesa3d/src/compiler/nir/nir_opcodes.py > out/target/product/i9305/gen/STATIC_LIBRARIES/libmesa_nir_intermediates/nir/nir_builder_opcodes.h" 
Traceback (most recent call last):
  File "external/mesa3d/src/compiler/nir/nir_builder_opcodes_h.py", line 106, in <module>
    from mako.template import Template
ImportError: No module named mako.template
16:20:20 ninja failed with: exit status 1

You need to run the following command:

$ cd prebuilts/build-tools/path/linux-x86/
$ rm python && ln -s /usr/bin/python python

Java heap space

The Java heap size is automatically set according to the available system memory. On machines with 8 GB or less RAM, it is set to a value which is too low, and will result in the following error during the build:

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

The heap size can be increased with an envirnoment variable:

$ export _JAVA_OPTIONS="-Xmx3g" 

Reduce parallel jobs to avoid killed processes

Increasing the Java heap space is not enough to get a successful build on machines with 8 GB or less RAM. It is also necessary to reduce the number of parallel jobs, to avoid processes from being killed due to lack of memory. This typically happens during the build of frameworks/base components.

For greater speed, you may let your build run with the defaults, wait for it to fail due to killed processes, and then relunch the build with:

$ make -j1

By default, Ninja, the underlaying build system for Android, used when you run make bacon, computes the number of parallel jobs according to the number of CPUs on your machine (typically #CPUs + 2 parallel jobs).

Launching the build

$ source build/envsetup.sh
$ lunch lineage_i9305-eng
$ make

Install the images

From scratch

$ cd out/target/product/i9305
$ sudo heimdall flash --BOOT boot.img --USERDATA userdata.img --SYSTEM system.img 

Update previous installation

adb remount
adb sync

Get adb

As the device IDs are the ones given by the Linux kernel, they are not in the adb udev rules, so for now it requires to run adb as root:

$ sudo adb shell
* daemon not running; starting now at tcp:5037
* daemon started successfully
i9305:/ #                                 
$ sudo adb kill-server
$ adb shell
* daemon not running; starting now at tcp:5037
* daemon started successfully
error: no devices/emulators found

So make sure to kill the adb-server and run it as root:
$ adb kill-server
$ sudo adb shell
* daemon not running; starting now at tcp:5037
* daemon started successfully
i9305:/ # 

Boot progress

You can also follow the boot progress with adb:

adb logcat
adb logcat -b main

Note that the device can go into suspend at any time, so adb might be interrupted. That looks like that:
First you get a shell

$ sudo adb shell
i9305:/ #

Then the connection is interrupted:

$ adb shell
i9305:/ # [randomdev@fullyfreelaptop ]$                                                                                                     

The effect with adb logcat is similar.

Getting the latest changes

Build VM

If you use Parabola, you may be interested in running Trisquel 8 in LXC.

To do that first debootstrap a Trisquel 8 rootfs.

Parabola's debootstrap does support Trisquel 8 and its manual has an example on how to do that:

$ man debootstrap
[...]
# debootstrap flidas flidas-root http://archive.trisquel.info/trisquel

Then you can use virt-manager to setup the LXC instance.

The advantages of this solution are that: The disadvantage of this solution are that:

Cleanups to be done

Upstreaming status

Graphics status

Progress of the graphics related tasks is tracked at GraphicsReplicant10.

Modem status

libsamsung-ipc: libsamsung-ril:

Modem status TODO

TODO

First month of full time equivalent work:

Time estimation Task Comments
DONE boot a device under AOSP9 Only boots with graphics, not much more
7h DONE build it under a FSDG compliant distribution like Trisquel8 WIP for AOSP, It's difficult to do precise time estimations as it could work out of the box or require one full time month of work depending on how much issues are encountered
Builds under Trisquel8
21h DONE * port the changes from AOSP9 to LineageOS 16
* cleanup the code
* build the kernel from the Android build system
* make sure it builds with an FSDG compliant distribution
* document the build procedure

Status:
* Boots with adb.
* Has ultra slow graphics
14h find, remove and document proprietary software in LineageOS 16
21h find, remove and document privacy issues in LineageOS 16
7h Add support for the touch keys driver in the galaxy-s3 dts applied
7h upstream the AAT1290 flash led Linux dts for the galaxy-s3 boards Now in 5.3
7h rebrand LineageOS as Replicant
70h port and cleanup the the Galaxy SIII (i9300) modem Linux driver from 4.16 to 5.0 See the modem status for more details
Total: 147h (~1 month)
Second month of full time equivalent work:
* port libsamsung-ril and libsamsung-ipc to Android 9
* Make the modem driver and libsamsung-ipc work together
157h See the modem status for more details
Total 157h ~1 month
Third month of full time equivalent work:
Task Time estimation Comments
port the sensors libraries and other device specific libraries
Look which sensor libraries can be used
70h Already done by the unofficial LineageOS port of the Galaxy SIII (i9300), needs testing
add support for Audio with the upstream kernel driver 70h Might be way faster, depending on what Android 9 uses
See also this bugreport
add partial (no modem) support for the Galaxy SIII 4G (i9305) and factorize the code with i9300 14h * The source code on which the work was based changed from AOSP to an unofficial LineageOS port to a port of i9305 support for AOSP by Joonas to the official LineageOS so it's now supported by default
* The work to factorize the code between the i9300 and i9305 still need to be done
Total 154h ~1 month
Task Time estimation Comments
create a recovery 21h
add internal WiFi support and validate the functionality 6h
add external WiFi dongles support 20h External dongles support might be tricky
create new update the install and upgrade instructions 35h Our current install instructions don't scale as we have one copy for each device.
We also created generic instructions but they tend to be harder to follow1 than the device specific ones.
This will be made in a modular format (for instance in LaTeX) that enables to generate per device install instructions without requiring to have multiples copy of the same text.
The instructions will need to be able to be modified and compiled on an FSDG compliant distribution.
Mostly done:
* The installation instructions are now generic enough.
* Some long standing TODO were also done along the way like adding backup instructions for the EFS.
* The current instructions are still for Replicant 6.0 and will need to be updated for Replicant 9.0
Task Time estimation Comments
Estimate the amount of work to Reduce the attack surface ?
Estimate the amount of work to add in-system upgrades ?

1 The generic instructions were tested at Install parties in Paris

Devices support:

Easy, because it's similar enough to the Galaxy SIII (I9300)

Galaxy Note II (N7100)
Task Time estimation Comments
port the EA8061 LCD Linux driver 35h
port the S6EVR02 LCD Linux driver 35h
port the MAX77693 flash led Linux driver 7h
android: add support for the Note II (N7100) and factorize the code with Galaxy SIII (i9300) and Galaxy SIII 4G (i9305) 14h Should be similar to the Galaxy SIII
port the sensors libraries and other device specific libraries 70h It's difficult to evaluate how much time it could take
add support for Audio with the upstream kernel driver 14h Should be similar to the Galaxy SIII
Galaxy Note 8.0 (N5100) and 8.0 WiFi (N5110)
Task Time estimation Comments
Evaluate the time required to do the port 14h TODO

Needs more work and unknown upstream Linux status

Device Time estimation Comments
Galaxy S II (i9100) Linux: devboard dts upstream? unknown status
Galaxy Note (N7000) unknown Linux upstream status
Galaxy Nexus (I9250) OMAP4, no dts upstream
Galaxy Tab 2 7.0 (P3100), 7.0 WiFi (P3110), 10.1 (P5100), 10.1 WiFi (P5110)
GTA04 >= A4 TODO: a RIL needs to be written, userspace GPS support is missing, audio scenarios, etc

Documentation

Replicant 6.0 changes

See Replican6Changes.

Other rebases

See the Samsung-ipc page.

Other attempts

Device(s) Repository status Comments
i9300 CustomROMs * February 8 2020 Pie release
i9300 Team InFusion * August 20 2019 Pie release Issues: * Uses a Samsung kernel
* Uses too many nonfree libraries
=> Probably nothing we could reuse from its code
n7100 ComicoTeam * January 4 2020 Pie release
i9100 rINanDO * March 20 2020 Pie release
* July 19 2020 Android 10 release

Links for other attempts

CustomROMs i9300 components

Repository Tree path Dependencies Function Comments
https://github.com/CustomROMs/android_hardware_samsung
lineage-16.0 branch
hardware/samsung/macloader Loads the MAC Address of the WiFi network interface Might be useful
hardware/samsung/wifiloader Loads the wifi kernel module (like modprobe) and setup firmware filesystems permissions May be useful
hardware/samsung/audio seems to contains ril related stuff as well Look if the ril stuff is required, go for standard audio
hardware/samsung/lineagehw/hidl/livedisplay livedisplay is a feature similar to what redshift does on GNU/Linux Not sure if it works with mainline
hardware/samsung/exynos/multimedia/utils/ seem meant for audio/video decoding offload assembly obtimized color conversion and resize code check assembly code license, not sure if useful
all other directories in hardware/samsung/exynos/ nonfree firmwares, nonfree software?, smdk kernel? audio/video decoding offload Avoid using that
hardware/samsung/exynos3 nonfree firmwares?, nonfree software?, smdk kernel? some light libraries, display stuff (gralloc, etc), 2D acceleration (FIMG), camera (FIMC), 3D acceleration, etc Avoid using that for now
hardware/samsung/exynos4

Known error messages that are safe to ignore

Links


Porting Replicant to Android 9

This page contains old build instructions for Replicant 9. The source code is kept to do regression testing. Active development has moved into Replicant 11.

Precautions

See RunningReplicant11 before installing Replicant 9 on your device to not break it.

LineageOS 16 (Android 9)

Repositories and changes for LineageOS 16

Building LineageOS 16 version

Source code

$ repo init -u https://git.replicant.us/contrib/replicant-next/manifest.git -b replicant-9-dev
$ repo sync

Alternatively a shallow copy of the source tree can be fetched in order to save on disk space:

$ repo init -u https://git.replicant.us/replicant-next/manifest.git -b replicant-9-dev --depth=1
$ repo sync -c

To `unshallow` a specific module:

$ cd path/to/module
$ git fetch --unshallow <remote>

For Trisquel 8

sudo apt-get install bc bison build-essential bsdmainutils ccache curl flex g++-multilib gcc-multilib gettext git gnupg gperf imagemagick lib32ncurses5-dev lib32readline-dev lib32z1-dev liblz4-tool libncurses5-dev libsdl1.2-dev libssl-dev libwxgtk3.0-dev libxml2 libxml2-utils lzop python-mako pngcrush rsync schedtool squashfs-tools xsltproc zip zlib1g-dev
sudo apt-get install gcc-5-arm-linux-gnueabi

Launching the build

Follow the i9300 manifest instructions:

$ subject='/C=US/ST=California/L=Mountain View/O=Android/OU=Android/CN=Android/emailAddress=android@android.com'
$ mkdir .android-certs
$ for x in releasekey platform shared media testkey; do \
  ./development/tools/make_key .android-certs/$x "$subject"; \
  done
$ parallel_tasks=$(echo "$(grep 'processor' /proc/cpuinfo | wc -l ) + 1" | bc)
$ source build/envsetup.sh
$ lunch lineage_i9305-eng
$ make -j${parallel_tasks} bacon

The images can then be flashed with heimdall. They are then in:

  out/target/product/i9305/obj/PACKAGING/target_files_intermediates/lineage_i9305-target_files-eng.replicant/IMAGES/

Getting lastest changes

Install the images

$ sudo heimdall flash --BOOT out/target/product/i9305/obj/PACKAGING/target_files_intermediates/lineage_i9305-target_files-eng.replicant/IMAGES/boot.img --USERDATA out/target/product/i9305/obj/PACKAGING/target_files_intermediates/lineage_i9305-target_files-eng.replicant/IMAGES/userdata.img --SYSTEM out/target/product/i9305/obj/PACKAGING/target_files_intermediates/lineage_i9305-target_files-eng.replicant/IMAGES/system.img 

Get adb

As the device IDs are the ones given by the Linux kernel, they are not in the adb udev rules, so for now it requires to run adb as root:

$ sudo adb shell
* daemon not running; starting now at tcp:5037
* daemon started successfully
i9305:/ #                                 
$ sudo adb kill-server
$ adb shell
* daemon not running; starting now at tcp:5037
* daemon started successfully
error: no devices/emulators found

So make sure to kill the adb-server and run it as root:
$ adb kill-server
$ sudo adb shell
* daemon not running; starting now at tcp:5037
* daemon started successfully
i9305:/ # 

Booting

At some point during boot, the device goes into suspend, so you will need to press some buttons like the power or volume button to make the boot continue until the graphical interface.

You can also follow the boot progress with adb:

adb logcat
adb logcat -b main

Note that the device can go into suspend at any time, so adb might be interrupted. That looks like that:
First you get a shell

$ sudo adb shell
i9305:/ #

Then the connection is interrupted:

$ adb shell
i9305:/ # [randomdev@fullyfreelaptop ]$                                                                                                     

The effect with adb logcat is similar.

Using SwiftShader instead of Mesa3D llvmpipe for software rendering

To use SwifShader you need a kernel that supports UDIV/SDIV emulation, you can checkout the branch GNUtoo/udiv-emulation for kernel/replicant/linux. After doing that that run the following commands to use SwiftShader:

$ adb remount
$ adb shell
i9305:/ # rm vendor/lib/egl/libGLES_mesa.so # or move it somewhere safe meanwhile you test SwiftShader
i9305:/ # nano system/build.prop # set ro.hardware.hwcomposer=ranchu and ro.hardware.gralloc=default
$ adb reboot

AOSP 9

Status with AOSP 9

Repositories and changes

Building AOSP version

Source code

First get the source code:

$ repo init -u git://git.putti.eu/aosp/manifest_i9305.git -b android-9.0.0

For Trisquel 8

sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev libgl1-mesa-dev libxml2-utils xsltproc unzip bc python-mako gcc-5-arm-linux-gnueabi

Building it

Once this is done, see the device/putti/i9305/README.md for the build instructions.


PrivateMailContact

If your inquiry has to be secret or private, you can contact us directly at: contact@replicant.us
Otheriwse don't contact us trough this mail.
Instead use the mailing list, the forums, or the IRC where you have way more probability of getting help.


Introcution

The bootloader is signed, and if you flash a modified bootloader(for instance using a recovery) it see that it has been modified and that the signature doesn't match and stop during boot as soon as it finds the modified bootloader(so it won't try other boot sources such as usb, or other devices).

I did exactly that(I tought that it would try other boot methods instead because a user reported that it did that when his NAND was damanged) and I bricked my device.

The recovery

In order to recovery I removed the xOM5 resistor and didn't do anything else hardware related, then I remounted my phone and used hummingbird-hibl to resurect my phone, this time it worked(with the resistor removed).

The issue with it

According to Rebellos on older revisions of the s5pc110 such thing(removing the resistor and not putting it back) can cause issues such as hanging the CPU.(it's unknown if newer revisions have a protection against that...).


Device 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:

A general good advice when porting a new device to Replicant is to look at how things are done on other devices and look at the commits that were made.

Prerequisites

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

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

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 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 or on CyanogenMod download page. For instance, the Nexus S codename is: crespo.

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), 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.

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.

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 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:
  1. 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.
  2. 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.

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

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.

Getting started with Replicant development

In order to prepare everything for the Replicant port:

Cloning the device files

Once your Replicant tree is ready, you can start adding the necessary repos for your device.
That means cloning the necessary repos in the right place. These repos are:

You can find the device-specific repo from the device's page on the CyanogenMod Wiki.
Make sure you check out the branches that match the CM 9.0 version (the branch may be called ics).

Once you have cloned the device-specific repo for your device and checked out the correct branch, refer to the cm.dependencies file to find what repos are left to clone.
Clone these repos in the correct locations and remove the prefix (e.g. android_device_samsung_crespo must be cloned in device/samsung/ and renamed to crespo).

If your cloned the kernel source for your device, it is likely that the kernel build is already integrated, so you can skip the next sections below.

In case of a missing kernel repository

If the kernel repo is nowhere to be found (make sure you've asked the CyanogenMod team), you'll need to get the kernel source directly from the vendor, especially if your device is supported by a 3rd party CyanogenMod fork.
Keep in mind that the Linux kernel is GPLv2, so vendors have the legal obligation to release the modified kernel sources as soon as they sell you the device.
That means the kernel sources will be available online. Here are some websites where such releases are done:

Once you have the kernel sources, read the instructions to find out which defconfig to use.

Since manufacturers usually don't release the git history along with the files, you'll need to recreate a git repo:

Now that you have a git repo, you can move it to the Replicant code tree, under the name: kernel/vendor/devices (e.g. kernel/samsung/aries).
Make sure to make the devices name match the devices in android_device_vendor_devices-common if the kernel is shared across these devices or to match the device in android_device_vendor_device.

In case of a prebuilt kernel

Some devices are still using a prebuilt kernel. Even though the CyanogenMod team is trying to avoid that, it remains in many repos.
For such devices, you will need to remove the prebuilt binaries and the instructions to copy the prebuilt kernel and its modules.

In the device repository (device/vendor/device) and common repository for your device (if any), remove the prebuilt kernel and modules (usually called kernel and module.ko (replace module with the name of a module) or a modules directory).
Remove the instructions to copy these prebuilts on the makefiles. Remove instructions such as:

PRODUCT_COPY_FILES += \
    $(LOCAL_KERNEL):kernel

LOCAL_KERNEL := $(LOCAL_PATH)/kernel

and anything regarding TARGET_PREBUILT_KERNEL as well as the instructions to copy the prebuilt modules.

The BoardConfig.mk (or BoardConfigCommon.mk in the common directory for your device) will most likely hold a line like:

TARGET_PREBUILT_KERNEL := device/samsung/p5/kernel

you must remove this line.

Now that the device repository has no prebuilt instructions, you can add the instructions to build the kernel. In the BoardConfig.mk file, add the following lines:

TARGET_KERNEL_SOURCE := kernel/samsung/p3
TARGET_KERNEL_CONFIG := samsung_p5_defconfig

and make sure to replace the location and defconfig by the correct values for your devices (being the location of the device kernel tree and the appropriate defconfig).

Building the correct kernel image format

There are different types of kernel images:

You need to find out which type of kernel image your device uses. Asking people who know about that is the best idea.

Android image

This is the easiest case to handle: just make sure the CONFIG_INITRAMFS_SOURCE option in the kernel defonfig is left blank or undefined:

CONFIG_INITRAMFS_SOURCE="" 

zImage with built-in initramfs

Building a zImage with a built-in initramfs requires the following steps:
In the kernel defconfig, define the CONFIG_INITRAMFS_SOURCE option this way:

CONFIG_INITRAMFS_SOURCE="../../root" 

Once this is done, duplicate the defconfig and add the _recovery prefix before the _defconfig ending (e.g. herring_recovery_defconfig), edit that file and replace CONFIG_INITRAMFS_SOURCE with:

CONFIG_INITRAMFS_SOURCE="../../recovery/root" 

Back to the device repository, edit the BoardConfig.mk file and add the following line:

TARGET_KERNEL_RECOVERY_CONFIG := samsung_p5_recovery_defconfig

and make sure to replace the defconfig by the appropriate defconfig you just cloned (the one with the _recovery_defconfig ending).

Still in the device repository, create a bootimg.mk file containing the following:

LOCAL_PATH := $(call my-dir)

$(INSTALLED_BOOTIMAGE_TARGET): $(INSTALLED_KERNEL_TARGET)
    $(ACP) $(INSTALLED_KERNEL_TARGET) $@

$(INSTALLED_RECOVERYIMAGE_TARGET): $(INSTALLED_RECOVERY_KERNEL_TARGET)
    $(ACP) $(INSTALLED_RECOVERY_KERNEL_TARGET) $@

Edit the BoardConfig.mk file and add the following line:

BOARD_CUSTOM_BOOTIMG_MK := device/vendor/device/bootimg.mk

and make sure to replace device/vendor/device/ to the correct path to your device's repository.

uImage with built-in initramfs

Follow the previous instructions (zImage with built-in initramfs) and set the BOARD_USES_UBOOT variable in the BoardConfig.mk file:

BOARD_USES_UBOOT := true

Setting up the build environment

Now that the repos are cloned, you need to modify some makefiles to cope with Replicant paths.
In the device repository (device/vendor/device), modify the file called cm.mk and replace the vendor/cm/ occurrences by vendor/replicant/. Other makefiles may need that as well (in any case, build will fail very early if you missed one). In that same cm.mk file, change the PRODUCT_NAME variable by replacing the cm prefix with replicant (e.g. change PRODUCT_NAME := cm_crespo to PRODUCT_NAME := replicant_crespo).

Now that your device files are ready, you can declare a new build target: these are held in vendor/replicant/jenkins-build-targets.
Modify that file and add a line (at the end) with the PRODUCT_NAME you set and the -eng suffix (e.g. replicant_crespo-eng).

From now on, everything should be ready to start a build. To check for errors or missed occurrences, start a terminal in the Replicant tree root and lunch:

source build/envsetup.sh
lunch replicant_device-eng

Adapt replicant_device-eng from what you added to the jenkins-build-target (e.g. replicant_crespo-eng).
If an error occurs, it will explicitly report it and you'll need to fix it before doing anything.
If everything works correctly, you should see something like:

============================================
PLATFORM_VERSION_CODENAME=REL
PLATFORM_VERSION=4.0.4
TARGET_PRODUCT=replicant_crespo
TARGET_BUILD_VARIANT=eng
TARGET_BUILD_TYPE=release
TARGET_BUILD_APPS=
TARGET_ARCH=arm
TARGET_ARCH_VARIANT=armv7-a
HOST_ARCH=x86
HOST_OS=linux
HOST_BUILD_TYPE=release
BUILD_ID=IMM76L
============================================

You must repeat these steps everytime before building anything on a freshly-opened terminal.
Remember:

source build/envsetup.sh
lunch replicant_device-eng

(make sure to replace device by your device's product name).

Building a recovery image

Now that everything is set-up, you can build the first image to test on your device: the recovery image.

The build target is recoveryimage, so all you have to do is:

make -j9 recoveryimage

This should trigger the kernel build and the recovery initramfs build and in the end, produce the out/target/product/device/recovery.img file.
Once your image is built (it takes some time), flash it to the recovery partition of your device (if any). It's a good idea to look at the CyanogenMod installation guide to find out how to install that recovery image.

There is usually also a key combination to hold to boot directly to recovery: hopefully, your recovery image will start.

Building the system

It is time to build a complete set of Replicant images. This includes at least the system and kernel images. Depending on the installation method, an userdata image might be needed too.

Building the kernel

Let's start by building the boot image, that is both the kernel and the Android initramfs. The build target is bootimage:

make -j9 bootimage

In the end, the out/target/product/device/boot.img file will be produced.

Setting up the system image format

It is time for you to take a good look at the installation process. Mainly, about whether the images will be flashed using the bootloader or recovery.
Since CyanogenMod uses the zip installation method, that we do not want to use, you're on your own here.

Finding the appropriate filesystem

It will be easy to find out the filesystem for the different partitions if the device already runs CyanogenMod:

$ adb shell mount
rootfs / rootfs ro,relatime 0 0
tmpfs /dev tmpfs rw,nosuid,relatime,mode=755 0 0
devpts /dev/pts devpts rw,relatime,mode=600 0 0
proc /proc proc rw,relatime 0 0
sysfs /sys sysfs rw,relatime 0 0
none /acct cgroup rw,relatime,cpuacct 0 0
tmpfs /mnt/asec tmpfs rw,relatime,mode=755,gid=1000 0 0
tmpfs /mnt/obb tmpfs rw,relatime,mode=755,gid=1000 0 0
none /dev/cpuctl cgroup rw,relatime,cpu 0 0
/dev/block/mtdblock2 /system yaffs2 ro,relatime 0 0
/dev/block/mtdblock3 /cache yaffs2 rw,nosuid,nodev,relatime 0 0
/dev/block/mtdblock5 /radio yaffs2 rw,relatime 0 0
/dev/block/mmcblk0p2 /data ext4 rw,nosuid,nodev,noatime,nodiratime,barrier=1,data=ordered,noauto_da_alloc 0 0
/dev/block/mtdblock6 /datadata yaffs2 rw,relatime 0 0
/dev/block/mtdblock4 /efs yaffs2 rw,relatime 0 0
/sys/kernel/debug /sys/kernel/debug debugfs rw,relatime 0 0
/dev/block/vold/179:1 /mnt/sdcard vfat rw,dirsync,nosuid,nodev,noexec,relatime,uid=1000,gid=1015,fmask=0702,dmask=0702,allow_utime=0020,codepage=cp437,iocharset=iso8859-1,shortname=mixed,utf8,errors=remount-ro 0 0
/dev/block/vold/179:1 /mnt/secure/asec vfat rw,dirsync,nosuid,nodev,noexec,relatime,uid=1000,gid=1015,fmask=0702,dmask=0702,allow_utime=0020,codepage=cp437,iocharset=iso8859-1,shortname=mixed,utf8,errors=remount-ro 0 0
tmpfs /mnt/sdcard/.android_secure tmpfs ro,relatime,size=0k,mode=000 0 0

So we can deduce that system is yaffs2 and data is ext4. Don't bother about the other partitions and mount-points, only /system and /data matter for now.

Changing the images format for bootloader installation

You have to modify the BoardConfig.mk file on the main device repository (it might be delegated to BoardConfigCommon.mk on the common repos).

To build ext4 system and userdata images, make sure you have:

TARGET_USERIMAGES_USE_EXT4 := true

To build yaffs2 system and userdata images, make sure you have:
TARGET_USERIMAGES_USE_EXT4 := false

Changing the images format for recovery installation

If the images have to be flashed using recovery, you must make sure they are built in yaffs2 format, with the default page and spare sizes.
Make sure to remove the following lines from BoardConfig.mk (even though the values might be different):

BOARD_NAND_PAGE_SIZE := 4096
BOARD_NAND_SPARE_SIZE := 128

Add the following to have yaffs2 images:
TARGET_USERIMAGES_USE_EXT4 := false

Even though the images are built as yaffs2, it doesn't mean that the filesystem on the device will be yaffs2: you have to set the correct filesystem, amongst: ext4, yaffs2 in the built image file name.
That means you have to change the target images names. This is done by adding the following line (adapted for your device) on BoardConfig.mk:

BOARD_CUSTOM_USERIMG_MK := device/vendor/device/userimg.mk

You need to create the userimg.mk file on the device main repository, with the following contents (adapt the target name):

INSTALLED_SYSTEMIMAGE_TARGET := $(PRODUCT_OUT)/system.ext4.img

$(INSTALLED_SYSTEMIMAGE_TARGET): $(INSTALLED_SYSTEMIMAGE)
    @echo -e ${CL_INS}"Install system fs image: $@"${CL_RST}
    $(hide) mv $(INSTALLED_SYSTEMIMAGE) $(INSTALLED_SYSTEMIMAGE_TARGET)

systemimage: $(INSTALLED_SYSTEMIMAGE_TARGET)

Building the system image

Building the system is the longest task. The build target is systemimage:

make -j9 systemimage

You might encounter build errors due to the lack of non-free libs. You'll need to find clean workarounds for that. Removing options from BoardConfig.mk can help solve the situation.
For instance, the following error:

make: *** No rule to make target `out/target/product/i9300/obj/lib/libTVOut.so', needed by `out/target/product/i9300/obj/EXECUTABLES/mediaserver_intermediates/LINKED/mediaserver'.  Stop.

Was solved by turning BOARD_USE_SECTVOUT to false:
BOARD_USE_SECTVOUT := false

Once the systemimage is built, you have to build the userdataimage if you're going to flash using the bootloader:

make -j9 userdataimage

When all the images are built, you're ready for flashing the images.
Some more steps are required for recovery flashing:
  1. Create a md5sum of the images: md5sum system.ext4.img boot.img > checksum.md5
  2. Create a directory on the root of the usb storage (or sdcard) of the phone
  3. Copy the images and the md5 checksum to the newly-created directory
  4. Install the images using the flash images menu
  5. Wipe data using wipe data/factory resert
  6. Reboot the device: reboot system now

If everything was correctly setup, this should succeed. The best way to make sure it booted is to run adb logcat and wait for an output.
That early, it is very likely that graphics will be broken, so don't expect anything to show up on the screen: only adb is a reliable way of knowing whether it worked.

Android development tips

Keep in mind that all the make (and such) commands must be run in a terminal where lunch has been executed before.

Once you have a Replicant image installed on the device, there is no need to rebuild a whole image everytime you make a change (but it's a good idea to do it from time to time): you can instead rebuild only a single module by using (where module is the module's name):

make module

Even better, you can build the module that sits in the current directory by simply using mm. To push the new library to the device, use adb push (you'll need to adb remount the first time).

Moreover, instead of rebooting, you can kill the Android applications (zygote, surfaceflinger, rild) depending on what you are working on.
For instance for audio:

adb shell killall zygote

For graphics:
adb shell killall surfaceflinger

For the RIL:
adb shell killall rild

Be sure to always look what's going on in logs.
For the main buffer:

adb logcat

For the radio (RIL) buffer:
adb logcat -b radio

Graphics

Once Replicant booted on the phone, it's time to get graphics working. Several components are involved with graphics on android:

Generally speaking, libEGL is non-free while gralloc and hwcomposer might be free software (but they often rely on non-free blobs). On most Replicant-supported phones, we use the default gralloc, the software libEGL and no hwcomposer. We modified the gralloc so that is uses RGB565 on framebuffer, which turns out to be faster than any other format we tried.

However, to have a fluid-enough experience, you need to disable most hardware-accelerated features of Android to enable Software GL.
This is done by modifying the cm.mk Makefile on the device repository. Add the following lines after the others inherit calls:

# Inherit Software GL configuration.
$(call inherit-product, vendor/replicant/config/software_gl.mk)

Moreover, you might need to add the Software GL configuration on the egl.cfg file, that is located somewhere in the device repository (perhaps under config/).
Add the following line at the beginning of the file (if it's not there already):

0 0 android

This will prevent surfaceflinger from doing a SEGFAULT.

Audio

If there is no audio support with free software on CyanogenMod, you'll have to find out details about how audio works on your device. There are mainly 3 different cases:

To find out whether your device uses ALSA or not, look if you have the /dev/snd/pcmC0D0c and /dev/snd/pcmC0D0p nodes available. A non-standard interface aside might be indicated by the presence of the /dev/snd/hwC0D0 node.

If your device is standard ALSA, you can use the tinyalsa-audio library (located under hardware/tinyalsa-audio) with a configuration file (an example of such a file is available at device/samsung/galaxys2/configs/tinyalsa-audio.xml). You can find the propers controls to set on which scenario by running tinymix (found under external/tinyalsa) with the non-free blob in place in the different scenarios.

If your device involves a non-standard interface or if it completely relies a non-standard interface, there is no readily available guide to find out how it works, but you can start by looking at the kernel driver and adding debug prints (with printk) there and figure out what is going on.

Remember to add the working audio module to the build targets (on the makefiles in the device repo).

Modem

In order to support telephony, messaging (SMS) and other network-related features (data as well), you need to make the modem work with Replicant. The modem is often called the radio in Android terminology.

The modem uses a protocol to communicate with the CPU. You need to find out which protocol the modem for your device is using. There are several possible cases:

To find out which protocol your phone uses, it is a good idea to look at the radio log buffer in CyanogenMod and try to find out from the messages (it may be verbose).
The protocol itself is implemented in the RIL (Radio Interface Layer): it is a good idea to take a look at the non-free ril the device uses (get its path with getprop rild.libpath).

If the modem uses the AT protocol, there are many available RIL implementations out there: Android has a reference-ril (hardware/ril/reference-ril) that implements AT and there is the hayes-ril library (located under hardware/ril/hayes-ril/) that makes it easier for you to add support for your device. Though, it is possible that the modem of your device implements undocumented commands, so you'll have to figure these out: the radio log might help a lot if it's verbose, else you'll have to trace the RIL somehow.

If the protocol is not AT, it might still be supported: the FreeSmartphone.Org (FSO) project implements some undocumented protocols. You can also look at oFono.
If your phone was manufactured by Samsung, there is a very good chance that it uses the Samsung-IPC protocol, which is implemented in libsamsung-ipc and Samsung-RIL. You will need to add support for your device in libsamsung-ipc (Samsung-RIL is device-independent: all the abstraction is done by libsamsung-ipc), which may be more or less easy depending on whether your modem type is already supported. In any case, you'll need to trace the RIL to find out. There may also be a separate daemon (often called cbd) that is in charge of the modem bootup (that's the biggest part you need to figure out), so that's the thing to trace.

If the protocol implementation is nowhere to be found, you'll have to write a free implementation yourself if you want to have free software support for the modem. It's a good idea to ask around whether other people from other communities, such as XDA or CyanogenMod, would be interested in helping you.

After finding a RIL that may work, add it to the build targets (in the device makefiles) and specify the path to the RIL with rild.libpath (it is often already declared in system.prop in the device repo).

Once the RIL is working, you may need the audio module cooperation to have sound during calls. For instance with Samsung-RIL, you need to use an Audio-RIL-Interface that implements the Samsung-RIL-Socket interface.

Sensors

When adding support for sensors, look at exactly what you will need to replace. There are several possible scenarios:

Note that sensors may require daemons aside, such as orientationd, geomagneticd, etc. You will most likely need to replace these as well.

If the implementation is incomplete, you will have to write a replacement for the non-free library that is used. For instance, samsung-sensors replaces the non-free libakm and provides free software acceleration sensor results for many Samsung devices.

If there is nothing available, you will have to write a sensors module for you device. You can reuse one from another device and add support for your sensors there.
For instance, here is a reference commit of the Galaxy S3 Exynos Sensors module that you may reuse.

Remember to add the working sensors module to the build targets (on the makefiles in the device repo) like it is done on the reference commit.

Figuring out the magic in sensors

When there is no free software for your sensors, you have to figure out: how to enable/disable the sensor and set the poll delay (it's often done via sysfs or via ioctl on a dev node). Reading the kernel-side driver of the sensor is a very good idea, you can add debug prints and force values there. You can also find datasheets about your sensor online, which may help you understanding how it works.

The really big part is to figure out how to convert the values that are out of the device (and generally passed through by the kernel driver) into the standard units that the Android framework requires.
An effective way to do this is to print the values passed by the kernel driver and look what the non-free sensors module returns. Better yet, you can also trace the non-free module and see exactly what it does, though that won't give you the details of the maths involved.

To find out the maths, open a spreadsheet software, then add the matching kernel values and the one out of the non-free module and try to find an equation that gives the values in standard units from the one returned by the kernel driver. For instance, you might find something like (this is for the LSM330DLC accelerometer):

f(x)=0,0095768072 * x 

Once you have this, you may want to find out where that value comes from. In that case, we can see that:

0,0095768072 = 9.80665 / 1024

With 9.80665 being the standard gravity on Earth. Hence, we have:
f(x)=x * GRAVITY_EARTH / 1024

We can guess that 1024 is the resolution of the ADC that provides the sensor value.

Once you have this equation figured out, you're ready to implement this in your free sensors module!

Camera

When adding support for the camera, you need to look at what is already there in CyanogenMod:

In the first case, you will only have to adjust the preview format to RGB565 and it is also a good idea to lower the preview frame rate. Depending on whether the library already has code to handle RGB565, the difficulty of doing this will change. Here are reference commits that introduce these changes for the Nexus S: libcamera: Use RGB565 preview format libcamera: Set preview framerate to 20fps
We cannot use YUV formats directly because the Android software EGL implementation used in Replicant only supports dealing with the first YUV plane: thus, preview would be black and white only, and probably slower than RGB565.

If there is wrapper, you'll need to replace it by an actual camera module that works. Depending on your hardware, there may be different cases:

In both cases, you'll need to add lots of debug prints to the relevant kernel drivers to figure out how it works. It will be easier if it uses V4L2, as you can already find many implementations of V4L2 out there, but it will very likely need a custom procedure and controls. In the case of a non-standard interface, you're on your own, except if you can find an implementation for a similar interface used on another other device.

Here is a reference commit of the Galaxy S3 Exynos Camera module that uses the Samsung FIMC engine. While it uses V4L2, it needs a custom procedure and custom controls to work properly.

Beware: some camera drivers require the cooperation of the GPU (that seems to be the case on OMAP4). In that case, even a free camera module implementation cannot work on Replicant. Camera drivers may also need to load a non-free firmware, that cannot be distributed with Replicant: hence, you must make sure that the driver will use the pre-installed version of the firmware (if any), burnt on the camera chip in the case loading the non-free firmware from the system fails.

Dealing with loaded firmwares

It is very likely that your device requires loaded firmwares for some components of the hardware. These are non-free programs that run separately from the CPU, on other chips. Since Replicant respects its users' freedom, no non-free firmwares are shipped with Replicant. It is possible that CyanogenMod includes shareable non-free firmwares in its tree: you must remove them.

Sometimes, components will crash (and may restart in an endless loop) when attempting to load a firmware that is not shipped with Replicant: you have to spot the code that loads the firmware and make it properly handle the case where the firmware is not available.

Though, you should keep in mind that some users may want to use that firmware, so you have to make the firmware loading possible. There are some exceptions to this however, especially when this involves blocking a free software alternative (this is the case with OMX media decoding). Moreover, firmwares should always be located under /system/vendor/firmware/ so that they are easy to spot and remove when the user decides to get rid of them (after installing them previously).

For instance, the Wi-Fi firmwares path (often declared in the BoardConfig.mk file) have to be changed with the /system/vendor/firmware prefix. The bluetooth firmware path is often declared in the init files (such as init.herring.rc). Make sure to document the new firmwares locations on the wiki: see the Developer guide.

Dealing with the kernel firmwares

The Linux kernel comes with its own share of firmware: you have to get rid of them too. Mostly, this is about removing the firmwares directory and modifying the Makefile to make it avoid firmwares.
Since the procedure is nearly exactly the same on all kernels, here is a reference commit for the changes to add to Makefile: Removed non-free firmwares and related instructions

Software media decoding

Most of the time, there is a chip dedicated to decoding media files (audio and video) and it very often requires a non-free loaded firmware. Moreover, it prevents software-only solutions from working, so you need to get rid of the libraries (even though they may be free software) that handle hardware media decoding. This is implemented in the OMX and stagefrighthw libraries. You need to spot and remove these products from the build targets of your device (in the device makefiles).

For reference, here is the commit that removes hardware media decoding on Nexus S (crespo): OMX: Disable SEC OMX libraries to permit software decoding

Bottomline

Not every hardware feature can be supported by Replicant: there are some areas where there is simply no free software available. If this is about a critical component (audio, graphics too slow, telephony) and there is no solution in sight, you might as well consider the port a failure. On the other hand, there are lacks we can leave with, for instance 3D, camera or GPS support: don't let that get in the way of releasing images for your device!

Pushing your work to Replicant repositories

Once your device works, or during the development process (it is recommended to do it as soon as it appears that the port will be successful), you have to push all your work to Replicant repositories.
You need to ask for commit access to our repositories to be allowed to push your work. This means creating the repositories for your device, pushing your work to these and to the other repositories you modified and adding the new repositories to the manifest.

The Developer guide hold all the rules for naming repositories: make sure to act accordingly with these requirements!

The manifest holds the list of the repositories we use in each Replicant version. Its syntax is xml, so it's easy to add your new repositories.

Adding documentation about your device

Once your device is usable, you have to create documentation on the Replicant wiki to let others know about relevant material concerning the device, especially build and installation instructions. This is absolutely required before we can publish any image for your device!

The process is described in the Developer guide.


Build the Android Development Tools for Eclipse (ADT) with Replicant 4.2

See feature #657 for the discussion about a ADT for Replicant and this page.

Principle of operation

The Android 4.2 source code ships a sdk/eclipse/ directory with ADT build scripts.
The build script will also download Eclipse 3.6.2 files as build dependencies.

Note: as of 2015-07, ADT is deprecated in favor of Android Studio, based on IntelliJ.

Recreate matching build environment

Replicant 4.2 is based on CyanogenMod 10.1 which is based on AOSP 4.2.2, released 2013-02.
The build environment used by NDK release managers should be Ubuntu LTS 10.04.

To recreate it easily with LXC, follow:

Build dependencies

# Based on https://web.archive.org/web/20121201011547/http://source.android.com/source/initializing.html
# git recompiled manually, mingw32 dropped
apt-get install wget gnupg flex bison gperf build-essential \
  zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs \
  x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev \
  libgl1-mesa-dev g++-multilib python-markdown \
  libxml2-utils xsltproc
apt-get install openjdk-6-jdk libasm-java

Preparing the sources

Login as user replicant and prepare the Replicant 4.2 source code as described in ReplicantSourceCode.
.

Building ADT 21

. build/envsetup.sh
cd sdk/eclipse/

# Complies with setup_eclipse.sh and fix download URL
sudo mkdir -p /buildbot/eclipse-android
sudo chown replicant /buildbot/eclipse-android
sed -i -e '/eclipse-rcp-helios-SR2/ s/download.eclipse.org/archive.eclipse.org/' \
  scripts/setup_eclipse.sh
# Note: I tried with 'apt-get install eclipse-rcp eclipse-pde' and ECLIPSE_HOME=/usr/lib/eclipse
# but it lacks org.eclipse.wst.* plugins aka eclipse-wtp-xmltools

mkdir ~/adt/
scripts/build_server.sh ~/adt
# 15mn with 4 cores, 32GB (inc. 17GB .repo)

The ADK release is in ~/adt/android-eclipse-v201507252158.zip :)

Signing ADT

By default, Eclipse display on install:

Warning: You are installing software that contains unsigned content.
The authenticity or validity of this software cannot be established. Do
you want to continue with the installation?

Let's sign the package.
Make sure you have keytool (openjdk-6-jre-headless) and jarsigner (openjdk-6-jdk), and:

# generate self-signed certificate
keytool -genkey -dname 'cn=Builder,ou=ADT,o=Replicant,c=FR' -keystore ~/adt/cacerts -validity 3650 -storepass 'changeme' -keypass 'changeme' -alias 'replicant'
# sign the JARs and repack
unzip -d t/ android-eclipse-v201507261317.zip
find t/features/ t/plugins/ -name "*.jar" -exec jarsigner -keystore ~/adt/cacerts -storepass 'changeme' -verbose {} 'replicant' \;
(cd t/ && zip -r ../android-eclipse-v201507261317.zip *)
rm -rf t/

At install time, Eclipse will ask the user if she trusts "Builder; ADT; Replicant".

Testing

See the nice Eclipse tutorial at SDK.

TODOs


Build dependencies installation

Replicant can only be built on 64 bit x86 architectures, building on 32 bit x86 systems is no longer supported.
However, some prebuilt tools are still 32 bit x86 executables and some host tools are generated as 32 bit x86 executables.

Replicant 6.0

Debian-based systems

Debian 9

Packages installation:

dpkg --add-architecture i386 ; apt-get update
apt-get build-dep gcc binutils llvm-defaults
apt-get install gcc-arm-none-eabi cmake python-dev swig ant bc proguard maven-debian-helper libemma-java libasm4-java libguava-java libnb-platform18-java libnb-org-openide-util-java libandroidsdk-ddmlib-java libmaven-source-plugin-java libfreemarker-java libmaven-javadoc-plugin-java repo curl gawk libgmp3-dev libmpfr-dev libmpc-dev git-core gperf libncurses-dev squashfs-tools pngcrush zip zlib1g-dev lzma libc6-dev-i386 g++-multilib lib32z1-dev lib32readline-dev lib32ncurses5-dev zlib1g-dev:i386 xsltproc python-mako schedtool gradle dirmngr libandroidsdk-sdklib-java eclipse-jdt libgradle-android-plugin-java android-sdk-build-tools android-sdk-platform-23 aapt lzop

Replicant 4.2

Debian-based systems

Trisquel 7.0

Packages installation:

apt-get install git gnupg flex bison gperf build-essential zip curl openjdk-7-jre openjdk-7-jdk libc6-dev libncurses5-dev:i386 x11proto-core-dev libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc zlib1g-dev:i386

Debian 8

Packages installation:

dpkg --add-architecture i386 ; apt-get update
apt-get install  bison flex git-core gperf libncurses-dev build-essential curl squashfs-tools openjdk-7-jre openjdk-7-jdk pngcrush wget zip zlib1g-dev lzma libxml2-utils libc6-dev-i386 g++-multilib lib32z1-dev lib32readline-gplv2-dev lib32ncurses5-dev zlib1g-dev:i386 xsltproc

Tweaks

Arch Linux-based systems

Parabola

Base packages (from the Parabola repositories) installation:

pacman -S --needed core/bison core/flex core/make core/ncurses core/xz core/zlib extra/bc extra/git extra/gperf extra/gperftools libre/jdk7-openjdk extra/openjdk7-src libre/jre7-openjdk extra/wget extra/zip community/squashfs-tools community/pngcrush libre/unzip

Some additional repositories are required to retrieve some of the build dependencies.

To enable those repositories, the following should be added to /etc/pacman.conf:

[libre-multilib]
Include = /etc/pacman.d/mirrorlist

[multilib]
Include = /etc/pacman.d/mirrorlist

For these changes to take effect, the packages database should be updated:

pacman -Syu

Additional packages installation:

pacman -S --needed multilib/lib32-glibc multilib/gcc-multilib multilib/lib32-readline multilib/lib32-ncurses multilib/lib32-zlib

Tweaks


Developer guide

Prerequisites

Developing on Replicant isn't much harder than developing on any other free software project as it doesn't require specific knowledge. In fact, you'll probably learn a lot along the way regarding how hardware works, how the Android system is composed, how the kernel works, etc, but you don't need to know all of this to start. However a basic set of skills is required, among which:

If you think you can cope with the requirements, then developing on Replicant should cause you no particular issue.

Notes on writing free software replacements

Writing free software replacements for non-free components may require more skills depending on what you're trying to achieve, though there may be people with the adequate knowledge to help you and from whom you will likely learn a lot.

Code hosting and submitting patches

Replicant's source code is hosted at git.replicant.us. If you plan to regularly contribute to Replicant and if you don't yet have a code hosting provider that satisfies your needs, you are welcome to host your Replicant-related projects there under your own username, You only need to contact one of Replicant's developers and ask for an account. Please include in your request the name, username and Email address that should be used for creating your account.

Replicant currently doesn't accept merge requests. There are two ways to get your patches included: You can either send them to the mailing list or open an issue on the issue tracker and attach the patches to the issue. Replicant developers will then review your changes.

See the Git documentation for creating a patch. Patches can be send with git send-email. If it's too much hassle for you to set up git send-email, sending the patches with your favorite mail client should be fine, too.

Repositories

When working with Replicant repos, make sure to avoid breaking things. For instance, if you push a commit introducing a compilation error, it will break the whole build process.
It is better to create separate branches (that are not used by the official manifest branches) when your work is still in progress.
Creating branches that add debug infos on a particular topic is usually a good idea since it will save you time next time you want to debug the same component.

When creating a repository

In order to keep repo naming consistent, please name repositories by their name on the tree, replacing the / by _.
For instance, when forking the LineageOS repo: android_device_samsung_crespo, rename it to device_samsung_crespo on the Replicant repos.
This creates a more consistent way of naming repositories and makes it easier when pushing: just look at the location in the source tree and replace / by _.

When creating a branch

Official Replicant branches are named the following way:

Such as: replicant-2.3 This should be used on the projects repositories as well as the manifest repository.
Any other branch should be considered as Work In Progress (WIP) and thus not be part of any official branch of the manifest.

There is although one exception, with the master branch, that can be used by any project and be in any manifest given that the code held in the master branch will work on any Replicant version.

Upstreaming work

It is generally a good idea to send some changes back to upstream, assuming that they will benefit from it as well.

When it is about the replacement of a non-free component present in the upstream systems, make sure that your replacement is reliable and complete.
Contact the interested developers on the upstream projects before attempting to send your replacement.

LineageOS

The LineageOS team uses Gerrit to manage patch submissions. The process to get your patch included in LineageOS repos is explained on their wiki: Gerrit

You can also push directly using git using the following scheme (untested):

git push ssh://<sshusername>@review.lineageos.org:29418/LineageOS/<projectname> HEAD:refs/for/<branchname>

AOSP

The Android Open Source Project uses Gerrit to manage patch submissions. Some information about submitting patches to AOSP is available: https://source.android.com/source/submit-patches.html

You can push to AOSP's review using:

git push https://android-review.googlesource.com/platform/system/core HEAD:refs/for/master

Writing free software replacements

Here are some tips that may help you achieving a free software replacement for a specific component (some may be more or less relevant regarding the nature of what the component does):

Wiki guidelines

In order the keep the wiki simple and consistent, a few guidelines must be followed when editing.

Regarding the content: Regarding the writing style: Regarding the naming of pages: Regarding the naming of devices:

Commonly-used terminology

In order to keep everything clear and consistent, we use the following terms with a precise meaning in mind:

New images release

  1. Modify the changelog in the vendor files:
    cd path/to/replicant-6.0/vendor/replicant
    edit CHANGELOG.mkdn
    git add CHANGELOG.mkdn
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/vendor_replicant.git replicant-6.0
    
  2. Increment the release in the release scripts:
    cd path/to/release-scripts
    edit release.sh
    edit releasetag.sh
    git add release.sh releasetag.sh
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/release-scripts.git replicant-6.0
    
  3. Tag all the repositories with the release tag script:
    path/to/release-scripts/releasetag.sh path/to/replicant-6.0
    
  4. Tag the manifest:
    cd path/to/manifest
    git tag -u 16D1FEEE4A80EB23 -s replicant-6.0-0001 -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/manifest.git replicant-6.0-0001
    
  5. Update prebuilts and start the build (with the Replicant keys and certificates installed)
  6. Release the images with the release script:
    mkdir -p path/to/images/replicant-6.0/0001
    path/to/release-scripts/release.sh path/to/replicant-6.0 path/to/images/replicant-6.0/0001
    
  7. Sign the binaries with the release script:
    path/to/release-scripts/release.sh path/to/replicant-6.0 path/to/images/replicant-6.0/0001 signatures
    
  8. Compress the release files
    cd path/to/images/replicant-6.0
    tar -cjf 0001.tar.bz2 0001
    
  9. Upload the release to OSUOSL:
    scp 0001.tar.bz2 replicant@ftp-osl.osuosl.org:/home/replicant/data/images/replicant-6.0/
    
  10. Unpack the release on OSUOSL, ensure permissions are correct
  11. Update ReplicantImages with the release
  12. Update each device's page with the release
  13. Update ReplicantStatus with the latest status
  14. Announce the release on the blog
  15. Update the release on the website and IRC topic

New device documentation

1. Create the device main page, following the naming guidelines applied to other devices (e.g. the Samsung Galaxy S II GT-I9100 is called Galaxy S 2 (I9100) and its page is GalaxyS2I9100)
2. Create all the related sub-pages (build guide, install guide and firmwares list at least), following the naming guidelines applied to other devices (e.g. GalaxyS2I9100Build, GalaxyS2I9100Installation and GalaxyS2I9100Firmwares)
3. Link the sub-pages to the main page in the index
4. Update the ReplicantStatus page of the wiki with the current status of the device
5. Modify the WikiStart page of the wiki and add the new device in the following sections:

6. Add new issues categories to the Replicant project Redmine


Galaxy Note 2 (N7100)

Device Galaxy Note 2 (N7100)
Manufacturer Samsung
Release date September 2012
Codename n7100
Status Maintained
Maintainer(s) Paul Kocialkowski
Wolfgang Wiedmeyer
Supported models GSM: N7100
Latest images Replicant 4.2 0004

Replicant status

Replicant status for the Galaxy Note 2 (N7100): ReplicantStatus Replicant 6.0

Replicant installation

Replicant installation for the Galaxy Note 2 (N7100): Replicant60GalaxyNote2N7100Installation

Replicant usage

Replicant build

Replicant build for the Galaxy Note 2 (N7100): Replicant60GalaxyNote2N7100Build

Replicant development

Freedom and privacy/security issues

Freedom issues on the Galaxy Note 2 (N7100):

Privacy/security issues on the Galaxy Note 2 (N7100): GalaxyNote2N7100PrivacySecurityIssues


Galaxy Note 2 (N7100) Build

This explains how to build Replicant for the Galaxy Note 2 (N7100).

Prerequisites

Before building, you must make sure that:

Warning

Do not build as root, always build as user.

Building

First, the toolchain needs to be built:

./vendor/replicant/build-toolchain

If you have executed any of the commands below and you want to run the toolchain build again, you will need to open a new shell.

Then, prepare the shell environment for the Replicant build:

. build/envsetup.sh
lunch replicant_n7100-userdebug

Start the build:

parallel_tasks=$(echo "$(grep 'processor' /proc/cpuinfo | wc -l ) + 1" | bc)
make -j$parallel_tasks bacon

The -jn argument is to indicate the number of parallel tasks during the build.
You can remove it from the command line to have only one task at a time. With fast hardware, best results will come with -j9, -j16 and -j32.

Finally, sign the resulting images:

./vendor/replicant/sign-build n7100

The first time you run the script, it will ask you a few questions that are needed to generate the necessary signing keys.

Output files

The produced files are located at:

Galaxy Note 2 N7100 Installation

Warning: installing an operating system, such as Replicant, may void your device's warranty and will erase the data stored on the device.

Prerequisites

In order to install Replicant on your device, it is assumed that you have a computer running a GNU/Linux operating system and everything necessary to connect your device to the computer through USB available. Moreover, it is assumed that anyone performing the installation knows how to use command lines in a terminal and has basic knowledge about it.

Downloading the files

The first step in the installation process is to download and set up the files that will be used to install Replicant to the device. The files must be downloaded on your computer first.

1. Find out what the latest image is: check out the Last image part of the general table on Replicant60GalaxyNote2N7100
2. Download all the files listed for the device (including the checksum and the signatures) on ReplicantImages for the latest image
2. Make sure you have added the Replicant release key to your GPG keyring
3. Check the signature of the files:

gpg --armor --verify path/to/replicant-6.0-n7100.zip.asc path/to/replicant-6.0-n7100.zip
gpg --armor --verify path/to/recovery-n7100.img.asc path/to/recovery-n7100.img

4. Make sure the check succeeds, do not install anything if it doesn't!
5. Check the checksum of the files:
sha256sum -c n7100.sha256

6. Make sure the check succeeds, do not install anything if it doesn't!

Installing heimdall

The heimdall tool is required to flash the recovery image to the device.
Instructions to install heimdall: ToolsInstallation

Copying the files to the device

There are two means of pushing the system zip to the device:

Using the storage of the device

You can either complete this step by using the device's internal storage or by using an external microSD card.

Using the internal storage

1. Make sure the device is started up and has an Android system running
2. Connect the USB cable to both the computer and the device
3. Enable USB mass storage on the device
4. Mount the mass storage on the computer
5. Copy the replicant-6.0-n7100.zip file at the origin of the mass storage
6. Safely unmount the mass storage on the computer
7. Disable USB mass storage on the device

Using a microSD card

1. Connect the microSD card to the computer (e.g. using an USB card reader)
2. Mount the microSD card on the computer
3. Copy the replicant-6.0-n7100.zip file at the origin of the microSD card
4. Safely unmount the microSD card on the computer
5. Disconnect the microSD card from the computer
6. Insert the microSD card in the device (make sure it is turned off before inserting the card)

Installing ADB

Instructions to install ADB: ToolsInstallation

Preparing the device

The next step in the installation process is to prepare the device for heimdall mode.

1. Make sure the device is completely turned off and the USB cable is disconnected from the device
2. Start the device by holding the following key combination: Volume down, Select, Power
3. Hold the key combination until the device shows a Warning message
4. Confirm that you want to download a custom OS (using volume up)
5. Make sure the device is in Downloading mode
4. Connect the USB cable to both the computer and the device

Installing the images

Now that both the computer and the device are set up, it is time to actually install the images to the device.

1. Install the recovery image to the device:

heimdall flash --BOOT path/to/recovery-n7100.img --RECOVERY path/to/recovery-n7100.img

2. Make sure the device reboots to recovery

Factory reset

A factory reset is necessary if you switch from the factory image or a different Android distribution to Replicant. You also need to do a factory reset when upgrading to a new major release (e.g. from Replicant 4.2 to Replicant 6.0). Only when updating to a new minor release (e.g. from Replicant 6.0 0001 to Replicant 6.0 0002), a factory reset is usually not required.

3. Select Factory reset
4. Select Wipe data (keep media)
5. Confirm the data wipe by selecting Yes
6. Press the back key (if necessary) to get back to the general menu

7. Select Apply update

Using the storage of the device

Using the internal storage

8. Select Choose from emulated
9. Select the system zip: replicant-6.0-n7100.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
10. Confirm the installation

Using a microSD card

8. Select Choose from sdcard1
9. Select the system zip: replicant-6.0-n7100.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
10. Confirm the installation

Using ADB sideload

8. Select Apply from ADB
9. Back to the host computer, load the system zip with sideload:

adb sideload path/to/replicant-6.0-n7100.zip

10. Make sure the file is being transfered

Completing the installation

11. Press the back key (if necessary) to get back to the general menu
12. Select Reboot system now to reboot the device

Your device should now be running Replicant!


Galaxy S 2 (I9100)

Device Galaxy S 2 (I9100)
Manufacturer Samsung
Release date May 2011
Codename i9100
Status Maintained
Maintainer(s) Paul Kocialkowski
Wolfgang Wiedmeyer
Supported models GSM: I9100
Latest images Replicant 4.2 0004

Replicant status

Replicant 6.0 status

Replicant installation

Galaxy S 2 (I9100) installation

Replicant usage

Replicant build

Galaxy S 2 (I9100) build

Replicant development

Freedom and privacy/security issues

Galaxy S 2 (I9100) freedom issues:

Galaxy S 2 (I9100) Privacy/security issues

Research

Hardware table

Component Name Source Status
SoC Samsung Exynos 4210 Linux kernel Linux kernel support
GPU Mali 400 https://secure.wikimedia.org/wikipedia/en/wiki/Exynos Linux kernel support, proprietary userspace
Audio Codec Yamaha MC1N2 Linux kernel Linux kernel support (ALSA), free userspace: Yamaha-MC1N2-Audio/Tinyalsa-Audio
Modem XMM6260 Linux kernel Free userspace implementation: Samsung-RIL/libsamsung-ipc
Wi-Fi BCM4330 Linux kernel Linux kernel support, proprietary loaded firmware
Bluetooth BCM4330 Linux kernel Linux kernel support, proprietary loaded firmware
NFC PN544 Linux kernel Linux kernel support
GPS GSD4t http://www.csr.com/news/pr/release/455/en Proprietary userspace, no free implementation: GSD4t
Accelerometer K3DH Linux kernel Linux kernel support, free userspace
Compass AKM8975 Kernel sources Linux kernel support, free userspace
Light Capella CM3663 Linux kernel support, free userspace
Proximity Capella CM3663 Linux kernel support, free userspace
FM Radio SI4709 Linux kernel Linux kernel support
Camera (back) Fujitsu M5MO Linux kernel support, free userspace
Camera (front) Samsung S5K5BAFX Linux kernel support, free userspace
Touchscreen Atmel MXT224 Linux kernel support
Display LD9040 Linux kernel support

References

These documents are the propriety of Samsung Electronics and are not hosted by the Replicant project.


Galaxy S 2 (I9100) build

Prerequisites

The following are required to build Replicant for the Galaxy S 2 (I9100):

Build

There is no need to build as root, building as a regular user should be preferred.

All of the following build commands need to be run in the source tree root folder.

First, the toolchain needs to be built:

./vendor/replicant/build-toolchain

If you have executed any of the commands below and you want to run the toolchain build again, you will need to open a new shell.

Then, prepare the shell environment for the Replicant build:

. build/envsetup.sh
lunch replicant_i9100-userdebug

Now you can start the build:

parallel_tasks=$(echo "$(grep 'processor' /proc/cpuinfo | wc -l ) + 1" | bc)
make -j$parallel_tasks bacon

The -jn argument indicates the number of parallel tasks during the build (you can remove it from the command line to have only one task at a time).
$parallel_tasks holds an optimized number of parallel tasks for your hardware. You may want to reduce this number if e.g. the computer runs out of RAM during the build.

Finally, sign the resulting images:

./vendor/replicant/sign-build i9100

The first time you run the script, it will ask you a few questions that are needed to generate the necessary signing keys.

Produced binaries

The produced binaries are located at:

Galaxy S 2 (I9100) Installation

Warning: installing an operating system, such as Replicant, may void your device's warranty and will erase the data stored on the device.

Prerequisites

In order to install Replicant on your device, it is assumed that you have a computer running a GNU/Linux operating system and everything necessary to connect your device to the computer through USB available. Moreover, it is assumed that anyone performing the installation knows how to use command lines in a terminal and has basic knowledge about it.

Downloading the files

The first step in the installation process is to download and set up the files that will be used to install Replicant to the device. The files must be downloaded on your computer first.

1. Find out what the latest image is: check out the Last image part of the general table on Replicant60GalaxyS2I9100
2. Download all the files listed for the device (including the checksum and the signatures) on ReplicantImages for the latest image
2. Make sure you have added the Replicant release key to your GPG keyring
3. Check the signature of the files:

gpg --armor --verify path/to/replicant-6.0-i9100.zip.asc path/to/replicant-6.0-i9100.zip
gpg --armor --verify path/to/recovery-i9100.img.asc path/to/recovery-i9100.img

4. Make sure the check succeeds, do not install anything if it doesn't!
5. Check the checksum of the files:
sha256sum -c i9100.sha256

6. Make sure the check succeeds, do not install anything if it doesn't!

Installing heimdall

The heimdall tool is required to flash the recovery image to the device.
Instructions to install heimdall: ToolsInstallation

Copying the files to the device

There are two means of pushing the system zip to the device:

Using the storage of the device

You can either complete this step by using the device's internal storage or by using an external microSD card.

Using the internal storage

1. Make sure the device is started up and has an Android system running
2. Connect the USB cable to both the computer and the device
3. Enable USB mass storage on the device
4. Mount the mass storage on the computer
5. Copy the replicant-6.0-i9100.zip file at the origin of the mass storage
6. Safely unmount the mass storage on the computer
7. Disable USB mass storage on the device

Using a microSD card

1. Connect the microSD card to the computer (e.g. using an USB card reader)
2. Mount the microSD card on the computer
3. Copy the replicant-6.0-i9100.zip file at the origin of the microSD card
4. Safely unmount the microSD card on the computer
5. Disconnect the microSD card from the computer
6. Insert the microSD card in the device (make sure it is turned off before inserting the card)

Installing ADB

Instructions to install ADB: ToolsInstallation

Preparing the device

The next step in the installation process is to prepare the device for heimdall mode.

1. Make sure the device is completely turned off and the USB cable is disconnected from the device
2. Start the device by holding the following key combination: Volume down, Select, Power
3. Hold the key combination until the device shows a Warning message
4. Confirm that you want to download a custom OS (using volume up)
5. Make sure the device is in Downloading mode
4. Connect the USB cable to both the computer and the device

Installing the images

Now that both the computer and the device are set up, it is time to actually install the images to the device.

1. Install the recovery image to the device:

heimdall flash --KERNEL path/to/recovery-i9100.img

2. Make sure the device reboots to recovery

Factory reset

A factory reset is necessary if you switch from the factory image or a different Android distribution to Replicant. You also need to do a factory reset when upgrading to a new major release (e.g. from Replicant 4.2 to Replicant 6.0). Only when updating to a new minor release (e.g. from Replicant 6.0 0001 to Replicant 6.0 0002), a factory reset is usually not required.

3. Select Factory reset
4. Select Wipe data (keep media)
5. Confirm the data wipe by selecting Yes
6. Press the back key (if necessary) to get back to the general menu

7. Select Apply update

Using the storage of the device

Using the internal storage

8. Select Choose from sdcard0
9. Select the system zip: replicant-6.0-i9100.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
10. Confirm the installation

Using a microSD card

8. Select Choose from sdcard1
9. Select the system zip: replicant-6.0-i9100.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
10. Confirm the installation

Using ADB sideload

8. Select Apply from ADB
9. Back to the host computer, load the system zip with sideload:

adb sideload path/to/replicant-6.0-i9100.zip

10. Make sure the file is being transfered

Completing the installation

11. Press the back key (if necessary) to get back to the general menu
12. Select Reboot system now to reboot the device

Your device should now be running Replicant!


Galaxy S 3 (I9300)

Device Galaxy S 3 (I9300)
Manufacturer Samsung
Release date May 2012
Codename i9300
Status Maintained
Maintainer(s) Paul Kocialkowski
Wolfgang Wiedmeyer
Supported models GSM: I9300
Latest images Replicant 4.2 0004

Replicant status

Replicant status for the Galaxy S 3 (I9300): ReplicantStatus Replicant 6.0

Replicant installation

Replicant installation for the Galaxy S 3 (I9300): Replicant60GalaxyS3I9300Installation

Replicant usage

Replicant build

Replicant build for the Galaxy S 3 (I9300): Replicant60GalaxyS3I9300Build

Replicant development

Freedom and privacy/security evaluation

See GalaxyS3I9300PrivacySecurityEvaluation for more details.

Research

Hardware table

Component Name Source Status
SoC Samsung Exynos 4412 iFixit Linux kernel support
GPU Mali 400 https://secure.wikimedia.org/wikipedia/en/wiki/Exynos Linux kernel and secret userspace
Audio Codec WM8994 Linux kernel Linux kernel support (ALSA)
Modem XMM6260 Linux kernel Free userspace implementation: Samsung-RIL/libsamsung-ipc
Wi-Fi BCM4334 Linux kernel Linux kernel support, proprietary loaded firmware
Bluetooth BCM4334 Linux kernel Linux kernel support, proprietary loaded firmware
NFC PN544 Linux kernel Linux kernel support
GPS BCM4751 iFixit Proprietary userspace, no free implementation: BCM4751
Accelerometer LSM330DLC Linux kernel Linux kernel support, free userspace
Compass AKM8975 Kernel sources Linux kernel support, free userspace
Light/proximity sensor CM36651 Kernel sources Linux kernel support, free userspace
Gyroscope LSM330DLC Kernel sources Linux kernel support, free userspace
Barometer LPS331AP Kernel sources Linux kernel support, free userspace
Camera (back) S5C73M3 Linux kernel Linux kernel support, free userspace
Camera (front) S5K6A3 Linux kernel Linux kernel support, free userspace, proprietary loaded firmware

Galaxy S 3 (I9300) Build

This explains how to build Replicant for the Galaxy S 3 (I9300).

Prerequisites

Before building, you must make sure that:

Warning

Do not build as root, always build as user.

Building

All of the following build commands need to be run in the source tree root folder.

First, the toolchain needs to be built:

./vendor/replicant/build-toolchain

If you have executed any of the commands below and you want to run the toolchain build again, you will need to open a new shell.

Then, prepare the shell environment for the Replicant build:

. build/envsetup.sh
lunch replicant_i9300-userdebug

Start the build:

parallel_tasks=$(echo "$(grep 'processor' /proc/cpuinfo | wc -l ) + 1" | bc)
make -j$parallel_tasks bacon

The -jn argument is to indicate the number of parallel tasks during the build.
You can remove it from the command line to have only one task at a time. With fast hardware, best results will come with -j9, -j16 and -j32.

Finally, sign the resulting images:

./vendor/replicant/sign-build i9300

The first time you run the script, it will ask you a few questions that are needed to generate the necessary signing keys.

Output files

The produced files are located at:

Galaxy S 3 (I9300) Installation

Warning: installing an operating system, such as Replicant, may void your device's warranty and will erase the data stored on the device.

Prerequisites

In order to install Replicant on your device, it is assumed that you have a computer running a GNU/Linux operating system and everything necessary to connect your device to the computer through USB available. Moreover, it is assumed that anyone performing the installation knows how to use command lines in a terminal and has basic knowledge about it.

Downloading the files

The first step in the installation process is to download and set up the files that will be used to install Replicant to the device. The files must be downloaded on your computer first.

1. Find out what the latest image is: check out the Last image part of the general table on Replicant60GalaxyS3I9300
2. Download all the files listed for the device (including the checksum and the signatures) on ReplicantImages for the latest image
2. Make sure you have added the Replicant release key to your GPG keyring
3. Check the signature of the files:

gpg --armor --verify path/to/replicant-6.0-i9300.zip.asc path/to/replicant-6.0-i9300.zip
gpg --armor --verify path/to/recovery-i9300.img.asc path/to/recovery-i9300.img

4. Make sure the check succeeds, do not install anything if it doesn't!
5. Check the checksum of the files:
sha256sum -c i9300.sha256

6. Make sure the check succeeds, do not install anything if it doesn't!

Installing heimdall

The heimdall tool is required to flash the recovery image to the device.
Instructions to install heimdall: ToolsInstallation

Copying the files to the device

There are two means of pushing the system zip to the device:

Using the storage of the device

You can either complete this step by using the device's internal storage or by using an external microSD card.

Using the internal storage

1. Make sure the device is started up and has an Android system running
2. Connect the USB cable to both the computer and the device
3. Enable USB mass storage on the device
4. Mount the mass storage on the computer
5. Copy the replicant-6.0-i9300.zip file at the origin of the mass storage
6. Safely unmount the mass storage on the computer
7. Disable USB mass storage on the device

Using a microSD card

1. Connect the microSD card to the computer (e.g. using an USB card reader)
2. Mount the microSD card on the computer
3. Copy the replicant-6.0-i9300.zip file at the origin of the microSD card
4. Safely unmount the microSD card on the computer
5. Disconnect the microSD card from the computer
6. Insert the microSD card in the device (make sure it is turned off before inserting the card)

Installing ADB

Instructions to install ADB: ToolsInstallation

Preparing the device

The next step in the installation process is to prepare the device for heimdall mode.

1. Make sure the device is completely turned off and the USB cable is disconnected from the device
2. Start the device by holding the following key combination: Volume down, Select, Power
3. Hold the key combination until the device shows a Warning message
4. Confirm that you want to download a custom OS (using volume up)
5. Make sure the device is in Downloading mode
4. Connect the USB cable to both the computer and the device

Installing the images

Now that both the computer and the device are set up, it is time to actually install the images to the device.

1. Install the recovery image to the device:

heimdall flash --BOOT path/to/recovery-i9300.img --RECOVERY path/to/recovery-i9300.img

2. Make sure the device reboots to recovery

Factory reset

A factory reset is necessary if you switch from the factory image or a different Android distribution to Replicant. You also need to do a factory reset when upgrading to a new major release (e.g. from Replicant 4.2 to Replicant 6.0). Only when updating to a new minor release (e.g. from Replicant 6.0 0001 to Replicant 6.0 0002), a factory reset is usually not required.

3. Select Factory reset
4. Select Wipe data (keep media)
5. Confirm the data wipe by selecting Yes
6. Press the back key (if necessary) to get back to the general menu

7. Select Apply update

Using the storage of the device

Using the internal storage

8. Select Choose from emulated
9. Select the system zip: replicant-6.0-i9300.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
10. Confirm the installation

Using a microSD card

8. Select Choose from sdcard1
9. Select the system zip: replicant-6.0-i9300.zip
Note: if your device was running Android 4.2 and later, it may be located in the 0 directory
10. Confirm the installation

Using ADB sideload

8. Select Apply from ADB
9. Back to the host computer, load the system zip with sideload:

adb sideload path/to/replicant-6.0-i9300.zip

10. Make sure the file is being transfered

Completing the installation

11. Press the back key (if necessary) to get back to the general menu
12. Select Reboot system now to reboot the device

Your device should now be running Replicant!


Updated wiki pages for Replicant 6.0

A few wiki pages need to be updated for Replicant 6.0 and updating these pages would overwrite information for the current release Replicant 4.2. Such pages are listed on this page. The workflow for updating a page is as follows:

  1. Copy/paste the page content of the page that needs updates to a new page with the same name plus the prefix "Replicant60".
  2. Save the paste as first edit.
  3. Do the necessary updates.
  4. Link the page on this page under the same menu entry as on the wiki index.

After the release of Replicant 6.0, the original pages can be overwritten with the content from the pages linked below and all pages with the prefix "Replicant60" can be renamed by adding the prefix Deprecated.

TODO


Replicant source code

Browsing the source code

The Replicant source code is currently hosted by the FSF at: git.replicant.us

There is one branch per Replicant version, such as replicant-2.2.

Disk space

Before downloading the Replicant source code, make sure there is a considerable amount of disk space left on the drive you intend to build Replicant on.
It is advised to have 60-70GiB available for the Replicant source code and the produced files for one device. If you intend to build for multiple devices, every additional device will need ca. 17GiB.

Source tree root folder

The path to the source tree root folder must not contain spaces.

Installing the repo tool

To be able download the complete source code, the repo tool needs to be installed. The distribution you are using may already have the tool packaged and it may already been installed as part of the Build dependencies installation.

If the repo tool is not available on your system, you can download and install it locally:

mkdir tools
cd tools
wget https://commondatastorage.googleapis.com/git-repo-downloads/repo
chmod a+x repo
cd ../

In the following, the local installation in ../tools/repo is assumed. If you have installed repo from your system's package manager, replace

../tools/repo

with just

repo

at the beginning of the following commands.

Initializing the repository

The source manifest is the list of all the git repositories that are present in the Replicant tree.
Each Replicant version has a dedicated branch with the proper source manifest.

Replicant 6.0 release version

mkdir replicant-6.0
cd replicant-6.0
../tools/repo init -u https://git.replicant.us/replicant/manifest.git -b replicant-6.0

Replicant 6.0 development version

mkdir replicant-6.0-dev
cd replicant-6.0-dev
../tools/repo init -u https://git.replicant.us/replicant/manifest.git -b replicant-6.0-dev

Replicant 4.2

mkdir replicant-4.2
cd replicant-4.2
../tools/repo init -u https://git.replicant.us/replicant/manifest.git -b replicant-4.2

Replicant 4.0

mkdir replicant-4.0
cd replicant-4.0
../tools/repo init -u https://git.replicant.us/replicant/manifest.git -b replicant-4.0

Replicant 2.3

mkdir replicant-2.3
cd replicant-2.3
../tools/repo init -u https://git.replicant.us/replicant/manifest.git -b replicant-2.3

Replicant 2.2

mkdir replicant-2.2
cd replicant-2.2
../tools/repo init -u https://git.replicant.us/replicant/manifest.git -b replicant-2.2

Downloading/Updating the source code

Now that you have configured repo, you can start downloading Replicant sources for the desired version.

This step is very long and can take hours to complete!

../tools/repo sync

Once the source code is ready, you need to get the prebuilt applications (they are downloaded from F-Droid). Since Replicant 6.0, the prebuilt applications are checked if they were signed with the F-Droid signing key. The signing key can be retrieved and added to your GPG keyring using:

gpg --recv-key 7A029E54DD5DCE7A

Then you can download the prebuilts:

vendor/replicant/get-prebuilts

You must redo these steps each time you want to sync your tree, in order to keep it up to date. Future syncs are faster than the first one.


Replicant USB Networking

This page explains how to connect your Replicant device to the Internet via an USB connection to a computer connected to the Internet.

Replicant 6.0

Replicant USB Networking requires a script: usb_networking_device.sh
Make sure to have ADB installed and to have the host daemon running as root.

Preparing the device

Push the script on the device, make it executable and run the first part of the script:

adb push usb_networking_device.sh /data/
adb shell chmod a+x /data/usb_networking_device.sh
adb shell /data/usb_networking_device.sh start1

Setting up the connection on the PC

The network manager applet on your PC (usually accessible through the network icon on your taskbar) should now display the device as a new wired interface. Below the name of the device should be a list of available connections. Depending on your network configuration, the list might be empty or offers one or more entries.

If your PC is connected to the Internet via Ethernet, a connection with the name "Auto-Ethernet" or a similar name could be available. Selecting this option should be enough to configure the connection and you can skip most of the steps below and continue with step 5. If there are issues with your connection, you will have to start again and do the rest of the steps, too.

If your PC uses Wi-Fi and Ethernet-based connections are suggested for your device, selecting one of them will likely not work. You will have to set up a new Ethernet-based connection.

The following steps are required to set up a new network connection for the device:

1. In the network manager applet, create a new "Ethernet" or "Wired" connection.
2. In the tab for IPv4 settings, select the method "Shared to other computers".
3. Save the connection, preferably with a distinguishable name (The name can be changed at the top of the edit window).
4. Select this connection for your device.
5. Now run the second part of the script on the device:

adb shell /data/usb_networking_device.sh start2

The connection should now work.

The new connection is saved on your PC and you don't have to recreate it when connecting the device again. It is then only necessary to run the first part of the script, selecting the network connection for the device in case it is not auto-selected and to run the second part of the script.

Stopping the network connection

To disconnect the device, run:

adb shell /data/usb_networking_device.sh stop

Known issues

Some apps won't connect to the Internet if cellular data is disabled. In other apps, like in the latest version of F-Droid, some parts of the app connect to the internet, while other parts of it do not. (see this issue). A workaround is to enable cellular data before doing the configuration steps for usb tethering. The previously described configuration steps will overwrite the cellular data connection and the connection via USB tethering will be used.

If you are not able to enable cellular data, you will have to downgrade F-Droid to version 0.101 to make it usable.

Replicant 4.2

Using reverse_tether.sh

The reverse_tether.sh script is part of AOSP and can be downloaded from: reverse_tether.sh
In order to start basic NAT networking between the host and the device, make sure to have installed ADB and to have the host daemon running as root. Then, use reverse_tether.sh the following way:

./reverse_tether.sh rndis
./reverse_tether.sh nat

Using the Replicant USB Networking scripts

Replicant USB Networking requires two scripts: usb_networking_device.sh usb_networking_host.sh
However, you can avoid the host part if your network manager can manage a shared connection.

Make sure to have installed ADB and to have the host daemon running as root.

Push the device part on the device and make it executable:

adb push usb_networking_device.sh /data/
adb shell chmod a+x /data/usb_networking_device.sh

Using a network manager shared connection

1. On your Linux PC, in the network manager applet (where you normally set up wired or wireless network connections), create a new "Shared" "Wired" connection, with default settings (connection type = Shared). (This is independent of the device, and only needs to be created once.)
2. Disconnect any other network connections (Wifi, 3G data) on the device.
3. Run the first part of the device-side script:

adb shell /data/usb_networking_device.sh start1 dhcp

4. The device should appear in the host's network manager applet as a new "wired" network connection. Connect this to the "Shared" connection that you created above (it should be in the list of choices given by the applet).
5. Now run the second part of the script on the device:
adb shell /data/usb_networking_device.sh start2 dhcp

The connection should now work. To disconnect the device, run:

adb shell /data/usb_networking_device.sh stop

Using the host script

1. Disconnect any other network connections (Wifi, 3G data) on the device.
2. Run the first part of the device-side script:

adb shell /data/usb_networking_device.sh start1 static

3. Wait for the interface to show up
4. Configure the device interface:
adb shell /data/usb_networking_device.sh start2 static

5. Configure the host interface:
sudo ./usb_networking_host.sh start

The connection should now work. To disconnect the device, run:

adb shell /data/usb_networking_device.sh stop

Cleanup the host:
sudo ./usb_networking_host.sh stop


Google Nexus One

Was to be the next default device to port Replicant to.

bug 11829 need to be solved before continuing

Sim unlocked.
Obtaining full root privilegies is possible using a command but will VOID THE WARRANTY.

This is the phone where Google suggest you to do your development now.

Google ADP1

The current default device to test Replicant.
Sim unlocked, full root privilegies by default.
You can buy it after paying 25$ fee to subscribe to the Android Developer Program.

Google ADP2

Sim unlocked, full root privilegies by default.
You can buy it after paying 25$ fee to subscribe to the Android Developer Program.

HTC Dream

In Europe it is sim unlocked but it LACKS root privilegies.
On some versions you can obtain them with an hack.

HTC Magic

In Europe it is sim unlocked but it LACKS root privilegies.
On some versions you can obtain them with an hack.

Geeksphone

Very similar to the htcdream, has a different wifi chip and driver.


HOWTO build FLOSS Dispenser

Install Maven

On Debian/Ubuntu (as root):

 apt-get install maven2

Download the Android SDK

Unfortunately, the most convenient way to get the SDK is distributed by the Android Open Source Project, but that copy contains proprietary Google code and is wrapped in a restrictive proprietary license agreement. You can obtain a free SDK by following the directions in our wiki.

Install maven-android-sdk-deployer

This will allow us to set up a Maven dependency for particular versions of Android.

Add SDK tools/ directories to PATH

Add the Android SDK's primary and platform tools directories to your path (to give mvn access to aapt and apkbuilder). Currently, the build process targets Android 1.5, but if you've changed it to target a different platform, use that one in the second export command.

export PATH=${PATH}:<your_sdk_dir>/tools
export PATH=${PATH}:<your_sdk_dir>/platforms/android-1.5/tools

Get FLOSS Dispenser sources

mkdir fd-readonly
cd fd-readonly
git clone git://gitorious.org/replicant/floss-dispenser.git

Download necessary libraries and build FLOSS Dispenser

mvn clean install

*This is a basic replicant test plan. Use this as a checklist to test Replicant builds. *

AUDIO

VIBRATOR

RIL

SMS

DATA

WIFI

USB NETWORKING

APPLICATION INSTALL

BLUETOOTH

GPS

ACCELEROMETER / ROTATION

CAMERA

FM RADIO (N1)


Wiki Relicensing

We are relicensing the wiki to the Creative Commons BY-SA license (http://creativecommons.org/licenses/by-sa/3.0/)

Pages not yet fully CC BY-SA

Users agreements

GNUtoo

Mean of communication:
Proof: By editing this page and adding himself here.

Broam/Benanov

Mean of communication: private mail
Proof:

[…]
On Mon, 2011-02-28 at 00:25 +0100, Denis 'GNUtoo' Carikli wrote:
> Hi,
> I discovered that the wiki has no license.
> 
> I propose choosing the same license than wikipedia:
> http://creativecommons.org/licenses/by-sa/3.0/
> 
> What do you think?

No complaints. Consider my stuff relicensed (users "Broam" or "Benanov",
I tend to use them interchangably).
[…]

johnsu01

Mean of communication: Replicant IRC channel
Proof:

Mar 30 23:18:05 <GNUtoo>    hi johnsu01 did you agree for cc-by-sa?
Mar 30 23:18:11 <GNUtoo>    I can't find the agreement
Mar 30 23:18:24 <GNUtoo>    (relicense your wiki edits to cc-by-sa)
Mar 30 23:18:25 <johnsu01>    GNUtoo: I did in the channel, do I need to put it somewhere else?
Mar 30 23:18:34 <GNUtoo>    no need 
Mar 30 23:18:51 <johnsu01>    okay

aarown

Mean of communication: Replicant IRC channel
Proof:

Feb 28 22:46:41 *       aaronw (~aaronw@2001:470:8a52:67:216:d3ff:fe35:aa9f) has joined #replicant
Feb 28 22:47:03 <GNUtoo|laptop> aaronw, hi
Feb 28 22:47:09 <aaronw>        hi GNUtoo|laptop
Feb 28 22:47:15 <GNUtoo|laptop> aaronw, 2 things:
Feb 28 22:47:27 <GNUtoo|laptop> *)we've got phone calls working in US but not DATA yet
Feb 28 22:47:48 <aaronw>        great!
Feb 28 22:47:48 <GNUtoo|laptop> *)we've a *little* cough....problem with the wiki....
Feb 28 22:47:58 <GNUtoo|laptop> no license was added at the beginning
Feb 28 22:48:06 <GNUtoo|laptop> so I'm seeking for everybody's agreement
Feb 28 22:48:20 <aaronw>        Right, ok
Feb 28 22:48:23 <GNUtoo|laptop> everybody seem to want CC-BY-SA
Feb 28 22:48:28 <GNUtoo|laptop> I'm ok with it
Feb 28 22:48:30 <aaronw>        Sounds good to me.
Feb 28 22:48:34 <GNUtoo|laptop> there is a mail thread about it
Feb 28 22:48:34 <aaronw>        I agree.
Feb 28 22:48:37 <GNUtoo|laptop> ok thanks

graziano

Mean of communication: Replicant IRC channel
Proof:

Mar 31 13:46:35 <GNUtoo>    hi graziano 
Mar 31 13:46:59 <GNUtoo>    did you already accept the relicensing of your replicant wiki editions to cc-by-sa? 
Mar 31 13:47:57 <graziano>    I think I did it here on IRC, do you need me to do something else?
Mar 31 13:49:00 <graziano>    I am Graziano Sorbaioli, "graziano" on the Replicant wiki and I accept the relicensing of all my replicant wiki editions to cc-by-sa
Mar 31 13:50:03 <GNUtoo>    ok thianks

laga

Mean of communication: Replicant IRC channel
Proof:

Mar 31 21:22:17 <GNUtoo>    laga, hi
Mar 31 21:22:22 <GNUtoo>    1)how
Mar 31 21:22:39 <GNUtoo>    2) did you agree to relicenses your replicant wiki edits under cc-by-sa?
Mar 31 21:22:45 <Broam>    http://trac.osuosl.org/trac/replicant/wiki/TestReplicant
Mar 31 21:22:48 <laga>    no
Mar 31 21:22:53 <laga>    2) how do i do that
Mar 31 21:23:15 <GNUtoo>    just tell here that you agree or add yourself to the agree wiki page
Mar 31 21:23:20 <laga>    i agree
Mar 31 21:23:24 <GNUtoo>    ok thanks


Replicant Wiki

Introduction

Welcome to the Replicant project wiki, that provides information about Replicant, supported devices and some research about other mobile devices and platforms.

You can request wiki editor privileges if you wish to edit pages, but please bear in mind that Replicant is a free software project. In addition, make sure to read, understand and follow our wiki guidelines

Unless specified otherwise, the information displayed in this wiki is only relevant to the latest Replicant version. Do not assume backwards compatibility of the instructions with old versions of Replicant.

Replicant Status

Installing Replicant

Detailed instructions:

Using Replicant

Building Replicant

Detailed instructions:

Technical infos on the devices

HTC Dream/HTC Magic

Nexus One

Nexus S (I902x)

Galaxy S (I9000)

Galaxy S 2 (I9100)

Galaxy Note (N7000)

Galaxy Nexus (I9250)

Galaxy Tab 2 7.0 (P31xx)

Galaxy Tab 2 10.1 (P51xx)

Galaxy S 3 (I9300)

Galaxy Note 2 (N7100)

GTA04

Developing on Replicant

Guides to port Replicant to a new device:

List of tasks to improve Replicant: Tasks

Contact

Licenses and credits

Useful links


Developer guide

Prerequisites

Developing on Replicant isn't much harder than developing on any other free software project as it doesn't require specific knowledge. In fact, you'll probably learn a lot along the way regarding how hardware works, how the Android system is composed, how the kernel works, etc, but you don't need to know all of this to start. However a basic set of skills is required, among which:

If you think you can cope with the requirements, then developing on Replicant should cause you no particular issue.

The porting guides provide instructions for porting a new device to Replicant and also offer some tips for developing on Replicant.

Have a look at the Tasks page and feel free to ask around for help to get started.

Notes on writing free software replacements

Writing free software replacements for non-free components may require more skills depending on what you're trying to achieve, though there may be people with the adequate knowledge to help you and from whom you will likely learn a lot.

Code hosting

Replicant's source code is hosted at git.replicant.us. If you plan to contribute to Replicant, you are welcome to host your Replicant-related projects there under your own username. You only need to contact one of Replicant's developers and ask for an account. Please include the name, username and email address that should be used to create your account. Your repos will then show up on the contributor repos page.

Requirements for submitting patches

There are two ways to get your patches included:

Replicant developers will then review your changes on the mailing list.

There are many ways to send patches to the mailing list As there are many git repositories in Replicant, it's also best if you indicate in one way or in another to which repository the patch applies, and for which Replicant version the patch is. This can also be done in many ways:

How to make patches

Creating and sending patches can be hard the first time.

While there is a recording of talk on the topic on how to do it right, for Replicant you don't need to do it right the first time.

When you have done some modification that you want to be integrated in Replicant, if you're not confident enough with git, make a copy of the repository with the changes in some safe place.

We will take a real example on how to do a modification. For that we will use the Replicant www.replicant.us git repository.

The replicant.us website source code and content is in git. It contains the following:

Let's suppose that a new Replicant 6.0 release is out but that everybody forgot to send a patch to the website and that the website has the following:

Latest images: Replicant 6.0 0003. Replicant supports up to 13 different devices!

and that instead we want to have the following:

Latest images: Replicant 6.0 0004. Replicant supports up to 13 different devices!

So the first thing to do would be to verify both on the bug tracker and on the mailing list that there isn't already a patch for that. If there isn't any we can safely go on.

To do the patch, we need to get the source code. This can be done with the following command:

git clone https://git.replicant.us/infrastructure/www.replicant.us

We then go into the website directory that has all the source code:

cd www.replicant.us

We then look where the text we want to modify is:

git grep "Replicant 6.0 0003." 

It can potentially return many lines, but it will have somewhere a line that looks like this one:

index.php:      <div class="alert alert-success" role="alert">Latest images: <strong>Replicant 6.0 0003</strong>. Replicant supports up to <strong>13</strong> different devices!</div>

We can open this index.php file with a text editor and change "Replicant 6.0 0003" to "Replicant 6.0 0004".

We can see that git know that we modified the index.php file:

git diff

It will then have something like that:

diff --git a/index.php b/index.php
index 080510a..fd6a8c9 100644
--- a/index.php
+++ b/index.php
@@ -2,7 +2,7 @@
 <?php include_once("include/autoloader.php"); ?>

 <div class="container" role="main">
-       <div class="alert alert-success" role="alert">Latest images: <strong>Replicant 6.0 0003</strong>. Replicant supports up to <strong>13</strong> different devices!</div>
+       <div class="alert alert-success" role="alert">Latest images: <strong>Replicant 6.0 0004</strong>. Replicant supports up to <strong>13</strong> different devices!</div>
        <div class="row">
                <div class="col-md-8">
                        <div class="panel panel-default">

However even if git know about it, we still need to make it record the modification in what is called a commit.

A commit contains a record of what has been changed, along with an explanation of why the change was necessary.

To create a commit, the 'git commit' command can be used, however since we're going to write an explanation of why the change was necessary we will first need to tell git which text editor to use for that.

To do that you can do something like that in the command line:

export GIT_EDITOR=your-favorite-editor

For instance if you like gedit, you can do something like that to make git use gedit in the current shell:

export GIT_EDITOR=gedit

We also need to give git a valid email and a name. Both will appear in the commit.

Else git will refuse to create the commit message and will output an error that looks like this one:

*** Please tell me who you are.

Run

  git config --global user.email "you@example.com" 
  git config --global user.name "Your Name" 

to set your account's default identity.
Omit --global to set the identity only in this repository.

So we then need to run something like that:

  git config --global user.email "you@example.com" 
  git config --global user.name "Your Name" 

Then in the same shell you can run the following command:

git commit -s

It will then open the text editor you choose and let you write text that describes why the change was necessary.

The convention is to have a first line that is not too long which summarize why that change is needed.

Then you can write longer text to describe the change details or have more in depth argumentation of why the change is needed.

Since here Replicant releases have already been made in the past, it's very likely that similar changes have already been made before.

We will take advantage of that and look what message the previous contributor wrote.

To do that, we can open a new shell, and go in the www.replicant.us directory and run the 'git log' command in there:

git log

This will show many commits. You can navigate with the keyboard arrows and quit by pressing the 'q' key.

Among the many commits you can see this one:

commit 526edccd8d688544602ae3da1c4d9c5ffdc058ca
Author: Denis 'GNUtoo' Carikli <GNUtoo@no log.org>
Date:   Thu Dec 14 12:37:21 2017 +0100

    index: Replicant 6.0 0003 images have been released

    Signed-off-by: Denis 'GNUtoo' Carikli <GNUtoo@no log.org>

The sumarry is this line:

index: Replicant 6.0 0003 images have been released

And it doesn't contain a more in depth explanation because it was not deemed necessary.

The line with "Signed-off-by: Denis 'GNUtoo' Carikli <GNUtoo@no log.org>" has been automatically generated by git when using '-s' in the 'git commit -s' command.

It means that you certify that you have the (legal) right to publish the patch.

For more details on it, you can see the "Developer's Certificate of Origin" in the Linux kernel documentation on submirting patches

So you can write something like "index: Replicant 6.0 0004 images have been released" to tell that the change is needed because new images have been released.

After saving and closing your text editor, git has now a new commit.

You can now generate a file from it with

git format-patch -1

The easiest way is then to write an email to the mailing list and attaching the patch in it.

As Replicant has many many git repository it's also good not to forget to mention for which repository is the patch. Here the patch is for the www.replicant.us git repository.

An email like that would be good enough for that:

Hi,

I've here's a patch that I attached for the www.replicant.us repository.

As there are sometimes different versions of Replicant being worked on in parallel it's also a good idea to also mention the version it is meant for, when it is relevant.

For instance here as there isn't one website per Replicant version it's not relevant here.

What happens after sending the patch?

Once the patch has been sent you will need to wait for people to review it. You can also try to find people on IRC that are willing to review your patch to speed things up.

As Replicant contributors are sometime very busy it can take some time.

If you get no response in one week, you can try to respond to your patch asking again people to review it.

If you get some response, you will typically get some comments on the patch.

This usually mean that your patch is good and that people are interested in it, but that you still need to fixes some things before it can be integrated in Replicant.

Once you fixed what needed to be fixed, you then need to send a second version of the patch with the fixes inside.

When doing that it's best to try to indicate in some way that the patch you send is the second version.

You could for instance mention it in the mail subject for instance.

The patch will then need to be reviewed again, and if everything is good it will be merged. If not you will probably get some more comments that you need to address in a third version of the patch.

Pushing patches

If you already have the ability to push patches into the main Replicant repositories, you still need to send your patches to the mailing list if they are to be applied on a Replicant version that is currently supported, or if they apply to the Replicant website.

You will then need to wait either for:

Writing free software replacements

Here are some tips that may help you achieving a free software replacement for a specific component (some may be more or less relevant regarding the nature of what the component does):

Upstreaming work

It is generally a good idea to send some changes back to upstream, assuming that they will benefit from it as well.

When it is about the replacement of a non-free component present in the upstream systems, make sure that your replacement is reliable and complete.
Contact the interested developers on the upstream projects before attempting to send your replacement.

LineageOS

The LineageOS project has a checklist of requirements for adding support for a device.

As the LineageOS developers have to make sure that the checklist requirements are met, make sure that your replacement is complete enough to either meet the checklist requirements, or that the LineageOS developers are interested in working together with you to make sure that the free software replacement meets such requirements.

The LineageOS team uses Gerrit to manage patch submissions. The process to get your patch included in LineageOS repos is explained on their wiki: Gerrit

You can also push directly using git using the following scheme (untested):

git push ssh://<sshusername>@review.lineageos.org:29418/LineageOS/<projectname> HEAD:refs/for/<branchname>

AOSP

The Android Open Source Project uses Gerrit to manage patch submissions. Some information about submitting patches to AOSP is available: https://source.android.com/source/submit-patches.html

You can push to AOSP's review using:

git push https://android-review.googlesource.com/platform/system/core HEAD:refs/for/master

Commonly-used terminology

In order to keep everything clear and consistent, we use the following terms with a precise meaning in mind:

Wiki guidelines

In order the keep the wiki simple and consistent, a few guidelines must be followed when editing.

Regarding the content: Regarding the writing style: Regarding the naming of pages: Regarding the naming of devices:

Repositories

When working with Replicant repos, make sure to avoid breaking things. For instance, if you push a commit introducing a compilation error, it will break the whole build process.
It is better to create separate branches (that are not used by the official manifest branches) when your work is still in progress.
Creating branches that add debug infos on a particular topic is usually a good idea since it will save you time next time you want to debug the same component.

See SourceCodeRepositories for more details about how to create or mirror repositories on Replicant server.

When creating a repository

In order to keep repo naming consistent, please name repositories by their name on the tree, replacing the / by _.
For instance, when forking the LineageOS repo: android_device_samsung_crespo, rename it to device_samsung_crespo on the Replicant repos.
This creates a more consistent way of naming repositories and makes it easier when pushing: just look at the location in the source tree and replace / by _.

Renaming a repository

You need to ask someone with SSH access to git.replicant.us to do that.

Creating a symlink has several side effects:

So instead it's better to edit the /etc/apache2/sites-enabled/git.replicant.us.conf configuration file.

For instance if you want to rename user-scripts.git in vendor_replicant-scripts.git (because some of the scripts will start being shipped on the devices), you can run mv user-scripts.git vendor_replicant-scripts.git and then add the following line in the git.replicant.us.conf apache configuration file:

Redirect /replicant/user-scripts.git /replicant/vendor_replicant-scripts.git

When creating a branch

Official Replicant branches are named the following way:

Such as: replicant-2.3 This should be used on the projects repositories as well as the manifest repository.
Any other branch should be considered as Work In Progress (WIP) and thus not be part of any official branch of the manifest.

There is although one exception, with the master branch, that can be used by any project and be in any manifest given that the code held in the master branch will work on any Replicant version.

New images release

  1. Modify the changelog in the vendor files:
    cd path/to/replicant-6.0/vendor/replicant
    edit CHANGELOG.mkdn
    git add CHANGELOG.mkdn
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/vendor_replicant.git replicant-6.0
    
  2. Increment the release in the release scripts:
    cd path/to/release-scripts
    edit releasevars.sh
    git add releasevars.sh
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/release-scripts.git replicant-6.0
    
  3. Tag all the repositories with the release tag script:
    path/to/release-scripts/releasetag.sh path/to/replicant-6.0
    
  4. In the manifest repo, merge the replicant-6.0-dev branch into the replicant-6.0 branch and increment the release in the manifest:
    cd path/to/manifest
    git checkout replicant-6.0
    git merge replicant-6.0-dev
    edit default.xml
    git add default.xml
    git commit -sS -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/manifest.git replicant-6.0
    
  5. Tag the manifest:
    git tag -u 5816A24C10757FC4 replicant-6.0-0001 -m "Replicant 6.0 0001 images release" 
    git push git@git.replicant.us:replicant/manifest.git replicant-6.0-0001
    
  6. Verify all tags:
    cd .repo/manifests
    git verify-tag $(git describe)
    cd ../..
    repo forall -ec ' { echo "Verifying $REPO_PROJECT" && git verify-tag $(git describe) 2>/dev/null; } || { echo "Error: verification failed!" && exit 1; } '
    
  7. Update prebuilts and start the build (in a newly opened shell with the Replicant keys and certificates installed):
    path/to/release-scripts/releasebuild.sh path/to/replicant-6.0
    
  8. Release the images with the release script:
    rm -rf path/to/images/replicant-6.0/0001
    mkdir -p path/to/images/replicant-6.0/0001
    path/to/release-scripts/release.sh path/to/replicant-6.0 path/to/images/replicant-6.0/0001
    
  9. Sign the binaries with the release script:
    path/to/release-scripts/release.sh path/to/replicant-6.0 path/to/images/replicant-6.0/0001 signatures
    
  10. Compress the release files
    cd path/to/images/replicant-6.0
    tar -cjf 0001.tar.bz2 0001
    
  11. Upload the release to OSUOSL:
    rsync -P -4 -ze ssh 0001.tar.bz2 replicant@ftp-osl.osuosl.org:/home/replicant/data/images/replicant-6.0/
    
  12. Unpack the release on OSUOSL, ensure permissions are correct and run the trigger-replicant script
  13. Update ReplicantImages with the release
  14. Update each device's page with the release
  15. Update ReplicantStatus with the latest status
  16. Verify if other wiki pages need to be updated due to changes introduced by the release (e.g. build pages or ToolsInstallation)
  17. Announce the release on the blog
  18. Update the release on the website and IRC topic

New device documentation

1. Create the device main page, following the naming guidelines applied to other devices (e.g. the Samsung Galaxy S II GT-I9100 is called Galaxy S 2 (I9100) and its page is GalaxyS2I9100)
2. Create all the related sub-pages (build guide, install guide and firmwares list at least), following the naming guidelines applied to other devices (e.g. GalaxyS2I9100Build, GalaxyS2I9100Installation and GalaxyS2I9100LoadedFirmwares)
3. Link the sub-pages to the main page in the index
4. Update the ReplicantStatus page of the wiki with the current status of the device
5. Modify the Index page of the wiki and add the new device in the following sections:

6. Add new issues categories to the Replicant project Redmine

7. Add the device to the Supported devices page on the website


DeviceDocumentationChecklist

Introduction

There is a lot of data and information on supported devices that is scattered around the Repicant wiki, git repositories and even Wikidata. So it's a good idea to have a checklist on what to add.

When we will have migrated to Mediawiki, we could automatically generate part of that list as we will be able to tag pages with Cathegories.

Checklist

Not everyone has all the Replicant supported devices, and at some point you might want to add support for a new device that no one else will have. In that case it's best to at least fill up the following pages as having the devices make it way easier to fill in the information:

In addition if you can send a patch for the data repository to add the PIT if your device has a PIT. Additionally you can just push the commit if you have push access.

It would be a really good idea to try to look if there is some unknown data at the end of the PIT like for the GT-I9300 and the GT-I9305. We found this issue thanks to people that uploaded their PIT in that repository. The issue with unknown data is that it could contain privacy sensitive data. It could also be a legal issue if it contain code but it's way more likely to contain data. Some devices like the GT-I9100 don't have that issue.

For instance you can easily check the GT-I9100 with the following command:

hexdump -C PIT/GT-I9100/stock/16G.pit  | tail -n 8

And that gives:

00000710  00 00 00 00 68 69 64 64  65 6e 2e 69 6d 67 00 00  |....hidden.img..|
00000720  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
00000750  00 00 00 00 01 00 00 00  01 00 00 00 09 00 00 00  |................|
00000760  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
000007d0  00 00 00 00 00 00 00 00                           |........|
000007d8

Here we see that the address of last where data is being displayed is 0x00000750, and that it only contains 00. The asterisk and the 0x000007d0 address is a notation that express the fact that between 0x00000760 and 0x000007d0, there are only 00.

If your device (also) has more classical partition tables like GPT or MBR, it is also a good idea to send a patch adding them to this repository as well. With the PIT, GPT and/or MBR anyone can write documentation on the partition table of the device. In the future that documentation could even be generated from that data.

In addition it might be a good idea to boot that device under Replicant and publish the output of the mount command as root. This way we will know for sure which partitions are mounted, which is important for debugging boot issues and checking if there aren't obvious security issues that could happen if partitions that should not be mounted are mounted in the wrong location. We can also find out that information by looking at various fstab files in the Replicant source code but as it is scattered around, it is faster and more reliable to just run the mount command as root to find out how partitions are mounted.

If your device has a modem and has a modem data partition, it is also a good idea to add the list of files and their permissions to the wiki like in the GT-I9300EFSContent page. This enables to restore the file permissions. Note that while publishing the file names and permissions look safe, the file content might contain privacy or security sensitive information like the IMEI.

It might also be a good idea to contribute to ImagesIdentification page that explains how to identify various Replicant releases for specific devices. Earlier Replicant images don't have the Replicant stored anywhere. Because of that users might know they are running Replicant 6.0 but will not know if they run Replicant 6.0 0001, Replicant 6.0 0002 or Replicant 6.0 0003. However these older images export some information like the build date, so it's possible to correlate that information to the precise Replicant release. Helping filling the missing information for the Replicant 6.0 0003 release would help users understand if they are running the latest version or if they can/should upgrade. Older releases than that are less important.

Additionally some projects

Devices donations

Introduction

While Replicant has some money to buy devices, and from time to time does use it to do that, it's very time consuming to look and find the devices we are looking for.

Giving devices directly to Replicant's (paid and volunteer) developers enables them to focus as much of their time as possible on development instead.

To this end, we very much welcome device donations.

Since we spend a lot of time researching which devices would be good for our project to port to, the types of devices we are interested in obtaining is somewhat limited.

If you have any of the devices below, please contact the Replicant project or developers.

Contacting the Replicant project or developers

Replicant developers can typically be found on the #replicant IRC channel on Freenode, or in the mailing list. It's a good idea to contact them through such means to donate devices. We also have a contact address for the project but it's often better to post to the mailing list, as more people might be interested in specific devices for doing specific work, especially when some Replicant developers already have the device you want to donate.

As Replicant developers also go to conferences, it's also possible to meet them there and give the devices directly. This saves time and money, as it can avoid shipping the devices.

Devices

As the Replicant project evolves, and developers comes and leave, it is hard to precisely predict in advance which device models we will need and how many we need at a given point in time. However, it's still possible to have a rough idea of which devices are needed or might be useful.

Maintained device

To make a Replicant release, it's a very good idea to make sure that at least one developer that is actively working on the release has at least every supported devices.
Without that we would need to wait (potentially indefinitely) for someone to test the release before it's released, or hope that the other devices are similar enough and that everything will work fine.

A list of maintained devices is available on the supported-devices page

Denis 'GNUtoo' Carikli still lacks the following devices:

However this is not crucial as he already has a Galaxy Tab 2 7.0 (P3100) and a Galaxy Note 8.0 (GT-N5100).

Device variants for porting or testing Replicant

Replicant has been tested on very few variants of a given device. For instance for the Galaxy Note II, we only support the GT-N7100 variant. Having more variants would enable us to test Replicant on them, and if some more work is needed and that we can find the time to do it, to also port Replicant to them. Though right now most people are probably busy with Replicant 6.0 or Replicant 10.

Samsung Galaxy S3

In addition to the GT-I9300 variant which is already supported by Replicant, Replicant developers are lacking the following variants of the Galaxy SIII:

Some Replicant developers also probably lack the Galaxy SIII 4G (GT-I9305) and are really needing one to work on the Replicant 10 port and/or the modem.

Samsung Galaxy Note II

In addition to the GT-N7100 variant which is already supported by Replicant, Replicant developers are lacking the following variants of the Galaxy Note II:

Broken devices with Exynnos 4412

Two new Replicant developers (juri and clever) are working to understand if we can find a way to run fully free software bootloaders on the devices that have an Exynos 4412 like the Galaxy SIII (GT-I9300). Even devices with broken screens or completely broken devices are useful for them.

In addition, Denis 'GNUtoo' Carikli would also be interested if the devices PCB are working (no screen needed) and already have wires soldered to get a direct UART and a JTAG connection, as, unlike the two new developers, he's not confident enough with micro-soldering to try that (the connections are really tiny).

Single Board Computers with Exynos4412

In our research to understand if it's possible to run fully free bootloaders on devices with the Exynos 4412, it would be interesting to be able to use the JTAG to understand if code is being run or not at very early stages.

The following Single Board Computers have an Exynos 4412 and seem to have a connector for the JTAG:

References:

1 https://wiki.odroid.com/old_product/odroid-x_u_q/odroid-xq

2 http://odroid.us/mediawiki/index.php?title=ODROID-Q2

Phones devkits

Phone devkits might be useful to Denis 'GNUtoo' Carikli in the future (once Replicant 10 is ready) to do tests on modem isolation:

Both devkits have an mPCIe connector, which enables to test way more easily the modem isolation by replacing the modem with an mPCIe to USB adapter and plugging various peripherals like a keyboard for instance.

GNU/Linux smartphones, tablets and PDAs

Once Replicant 10 will be ready we will be able to add support for new devices.

We're really interested in the following devices:

Some developers are probably interested in getting them before having a Replicant 10 release as it's possible to add support for them in parallel.

The following developers are also interested in getting them after the Replicant 10 release:

Sending them before the release also works, but the work will probably not start before the release.

No longer supported devices

While Replicant decided to stop supporting devices with RAM between the modem and the main System-On-a-Chip, it might nevertheless still be a good idea to keep the following devices working in libsamsung-ipc:

The Galaxy S (GT-I9000) and the Nexus S (GT-I902x) are supported by Replicant 4.2 that still builds with Trisquel7.

This could help testing libsamsung-ipc with such devices.

Denis 'GNUtoo' Carikli is interested in getting the following devices, but it's not crucial as he will get a Galaxy S (GT-I9000) that will most probably be sufficient for testing.

Requesting devices

When the devices are paid for by Replicant's money, it is common practice to ship devices to people that are already working on Replicant or related projects, to limit the risk of not having any work done.

However, if the devices are donated by individuals or companies, it's up to them to decide whom to give the device to.

Insurgo

If you need a device to work on specific tasks, you can ask packetup[m] from Insurgo on the #replicant IRC channel. It's however up to packetup[m] to decide if it's worth spending time and money to find, buy and ship the device(s).

The advantage of this method is that it saves Replicant developers lot of time.

Replicant

It's also possible to use Replicant funds to buy devices as it was done before.

The people on the Steering Committee have to approve the usage of the funds for that.

Once it is approved there are several possibilities:

Adding yourself to that page.

If it's not urgent, you could also add yourself to that page stating why you need the devices (so the donors would be able to decide if it's worth shipping / giving the device or not): We occasionally have some people that want to donate specific devices to Replicant, but we don't always need them. Lately (Around 2019/2020) we had offers on the mailing list for a tablet with 512M of RAM, non replaceable battery but a free bootloader and a Galaxy Note II (I think it was a N7100), but no one was interested as most people already working on Replicant seemed to already have enough Galaxy Note II (for instance I've already got one and I don't need a second one for working on Replicant so far), and for the tablet people seemed busy with other tasks already.


DeviceEncryption

Limitations

Full encryption

While that Android feature is called "Device encryption", it doesn't encrypt everything.

For instance, on a Galaxy SIII, enabling "Device encryption" only encrypts the USERDATA partition.

As the encrypted partitions have to be opened, and that the user need to type a password, code has to run to prompt user for the password and open the encrypted partition. That code cannot come from within the encrypted partition.

This is why "full disk encryption" or "device encryption" schemes often have parts that are unencrypted.

Setting a device encryption password separate from the lockscreen password

By default on Android, the encryption password is the same as the lockscreen password. As users tend to use a simple PIN, password or pattern for the lockscreen, the encryption can be easily circumvented with a brute-force attack.

Replicant allows to set an encryption password that is not tied to the lockscreen:
  1. Encrypt your device (In the settings: Security -> Encrypt phone)
  2. After the phone has rebooted and the encryption is set up, select Change encryption password in the Security menu of the settings
  3. Choose a strong passphrase. You will only have to enter this passphrase once when the device boots. There is a section below that elaborates more on how to choose a strong passphrase.
  4. Reboot the device and verify that the encryption works properly by entering the previously chosen passphrase

If a separate encryption password is in place and a PIN or password is set for the lockscreen, another security measure is active: After five unsuccessful attempts to unlock the screen, the device is rebooted and the attacker is faced with the much stronger encryption passphrase. This makes brute-force attacks on the lockscreen much harder.

Choosing a strong passphrase

As Android uses cryptsetup, most or all the Cryptsetup FAQ also apply to Replicant as well.

That FAQ has a Security Aspects section where it details the cost of breaking a passphrase in a table like this one:

Passphrase entropy Cost to break
50 bit EUR/USD 600k
55 bit EUR/USD 20M
70 bit EUR/USD 600B
75 bit EUR/USD 20T

Be sure to look at the FAQ for potentially more up to date figures and the details that goes with them.

As for calculating the passphrase entropy, tools like keepassxc (which is available in Parabola) have a password generator that is able to calculate the entropy. At the time of writing, in keepassxc, this can be found in Tools->Password generator.

Real example of a bad password

For instance if we use Replicant as a password is a very bad idea for several reasons:

Other tips


Device Porting Guide

This guide is a step-by-step explanation of the process of porting a new device to Replicant 6.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:

A general good advice when porting a new device to Replicant is to look at how things are done on other devices and look at the commits that were made, especially in the device-specific repositories that are prefixed with "device_".

Prerequisites

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

If your device fails to comply with one of the last two requirements, it won't be possible to port Replicant to it. If one of the first two requirements can't be fulfilled, porting the device to Replicant will be very hard.

You can search the XDA forum for non-official LOS 13 ports. Usually, the developers put a link to the source code of their port in their post. If not, you will have to ask them for the source code.

If your device is supported by a different LineageOS release or an older version of CyanogenMod and there is no non-official LOS 13 port, a port is still possible, but you will have to do the extra work of making your device compatible with LineageOS 13 first. Many parts of this guide will help you for this task, too.

If you don't know whether your device complies or not, you will probably learn it along the way.

Discovering the phone's hardware and associated blobs

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 usually has that information on the device's article. For instance, the codename for the European version of the Galaxy Nexus given by Samsung is i9250. This codename will help in the process of getting information 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 LineageOS, you can find it out from the LineageOS Wiki or on the LineageOS download page. For instance, the Galaxy Nexus codename is: maguro.

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 LineageOS 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), 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.

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 LineageOS port will probably know that information. It's a good idea to just ask them.

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 LineageOS Wiki has install guides for the supported devices and you'll probably find install guides for non-official LOS 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:
  1. 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.
  2. 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.

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 LineageOS.
The easiest way to do this is to spot the device repository in LineageOS repos and look for the proprietary-files.txt or extract-files.sh file on the cm-13.0 branch.
There is usually a link to the device repository from the device's build page in the LineageOS Wiki. There may not be a proprietary-files.txt file, but there should be a file with a similar name that lists the non-free blobs.
Some devices share additional common device repositories with other devices. You can identify these by looking at the lineage.dependencies file. These have their own proprietary-files.txt or extract-files.sh files. You will also have to look at these to get a full picture of all the used non-free components.

For instance, the list of non-free components for the Galaxy Nexus is device-proprietary-files.txt
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.

Getting started with Replicant development

In order to prepare everything for the Replicant port:

Cloning the device files

Once your Replicant tree is ready, you can start adding the necessary repos for your device.
That means cloning the necessary repos in the right place. These repos are:

You can find the device-specific repo from the device's page on the LineageOS Wiki.
Make sure you check out the branches that match the LOS 13.0 version (cm-13.0).

Once you have cloned the device-specific repo for your device and checked out the correct branch, refer to the lineage.dependencies file to find what repos are left to clone.
Clone these repos in the correct locations and remove the prefix (e.g. android_device_samsung_maguro must be cloned in device/samsung/ and renamed to maguro).

If you cloned the kernel source for your device, it is likely that the kernel build is already integrated, so you can skip the next sections below and continue with setting up the build environment.

In case of a missing kernel repository

If the kernel repo is nowhere to be found (make sure you've asked the LineageOS team), you'll need to get the kernel source directly from the vendor, especially if your device is supported by a 3rd party LineageOS fork.
Keep in mind that the Linux kernel is GPLv2, so vendors have the legal obligation to release the modified kernel sources as soon as they sell you the device.
That means the kernel sources will be available online. Here are some websites where such releases are done:

Once you have the kernel sources, read the instructions to find out which defconfig to use.

Since manufacturers usually don't release the git history along with the files, you'll need to recreate a git repo:

Now that you have a git repo, you can move it to the Replicant code tree, under the name: kernel/vendor/devices (e.g. kernel/samsung/aries).
Make sure to make the devices name match the devices in android_device_vendor_devices-common if the kernel is shared across these devices or to match the device in android_device_vendor_device.

In case of a prebuilt kernel

Some devices may still use a prebuilt kernel.

For such devices, you will need to remove the prebuilt binaries and the instructions to copy the prebuilt kernel and its modules.

In the device repository (device/vendor/device) and common repository for your device (if any), remove the prebuilt kernel and modules (usually called kernel and module.ko (replace module with the name of a module) or a modules directory).
Remove the instructions to copy these prebuilts on the makefiles. Remove instructions such as:

PRODUCT_COPY_FILES += \
    $(LOCAL_KERNEL):kernel

LOCAL_KERNEL := $(LOCAL_PATH)/kernel

and anything regarding TARGET_PREBUILT_KERNEL as well as the instructions to copy the prebuilt modules.

The BoardConfig.mk (or BoardConfigCommon.mk in the common directory for your device) will most likely hold a line like:

TARGET_PREBUILT_KERNEL := device/samsung/p5/kernel

you must remove this line.

Now that the device repository has no prebuilt instructions, you can add the instructions to build the kernel. In the BoardConfig.mk file, add the following lines:

TARGET_KERNEL_SOURCE := kernel/samsung/p3
TARGET_KERNEL_CONFIG := samsung_p5_defconfig

and make sure to replace the location and defconfig by the correct values for your devices (being the location of the device kernel tree and the appropriate defconfig).

Building the correct kernel image format

There are different types of kernel images:

You need to find out which type of kernel image your device uses. Asking people who know about that is the best idea.

Android image

This is the easiest case to handle: just make sure the CONFIG_INITRAMFS_SOURCE option in the kernel defonfig is left blank or undefined:

CONFIG_INITRAMFS_SOURCE="" 

zImage with built-in initramfs

Building a zImage with a built-in initramfs requires the following steps:
In the kernel defconfig, define the CONFIG_INITRAMFS_SOURCE option this way:

CONFIG_INITRAMFS_SOURCE="../../root" 

Once this is done, duplicate the defconfig and add the _recovery prefix before the _defconfig ending (e.g. herring_recovery_defconfig), edit that file and replace CONFIG_INITRAMFS_SOURCE with:

CONFIG_INITRAMFS_SOURCE="../../recovery/root" 

Back to the device repository, edit the BoardConfig.mk file and add the following line:

TARGET_KERNEL_RECOVERY_CONFIG := samsung_p5_recovery_defconfig

and make sure to replace the defconfig by the appropriate defconfig you just cloned (the one with the _recovery_defconfig ending).

Still in the device repository, create a bootimg.mk file containing the following:

LOCAL_PATH := $(call my-dir)

$(INSTALLED_BOOTIMAGE_TARGET): $(INSTALLED_KERNEL_TARGET)
    $(ACP) $(INSTALLED_KERNEL_TARGET) $@

$(INSTALLED_RECOVERYIMAGE_TARGET): $(INSTALLED_RECOVERY_KERNEL_TARGET)
    $(ACP) $(INSTALLED_RECOVERY_KERNEL_TARGET) $@

Edit the BoardConfig.mk file and add the following line:

BOARD_CUSTOM_BOOTIMG_MK := device/vendor/device/bootimg.mk

and make sure to replace device/vendor/device/ with the correct path to your device's repository.

uImage with built-in initramfs

Follow the previous instructions (zImage with built-in initramfs) and set the BOARD_USES_UBOOT variable in the BoardConfig.mk file:

BOARD_USES_UBOOT := true

Setting up the build environment

Now that the repos are cloned, you need to modify some makefiles to cope with Replicant paths.
In the device repository (device/vendor/device), modify the file called lineage.mk and replace the vendor/cm/ occurrences by vendor/replicant/. Other makefiles may need that as well (in any case, build will fail very early if you missed one). In that same lineage.mk file, change the PRODUCT_NAME variable by replacing the lineage prefix with replicant (e.g. change PRODUCT_NAME := lineage_maguro to PRODUCT_NAME := replicant_maguro).

Now that your device files are ready, you can declare a new build target: these are held in vendor/replicant/targets.
Modify that file and add a line (at the end) with the PRODUCT_NAME you set and the -userdebug suffix (e.g. replicant_maguro-userdebug).

From now on, everything should be ready to start a build. All of the following build commands need to be run in the source tree root folder.

First, the toolchain needs to be built:

./vendor/replicant/build-toolchain

If you have executed any of the commands below and you want to run the toolchain build again, you will need to open a new shell.

To check for errors or missed occurrences in your device config, start a terminal in the Replicant tree root and lunch:

. build/envsetup.sh
lunch replicant_device-userdebug

Adapt replicant_device-userdebug from what you added to the targets (e.g. replicant_maguro-userdebug).
If an error occurs, it will explicitly report it and you'll need to fix it before doing anything.
If everything works correctly, you should see something like:

============================================
PLATFORM_VERSION_CODENAME=REL
PLATFORM_VERSION=6.0.1
REPLICANT_VERSION="replicant-6.0" 
TARGET_PRODUCT=replicant_n7100
TARGET_BUILD_VARIANT=userdebug
TARGET_BUILD_TYPE=release
TARGET_BUILD_APPS=
TARGET_ARCH=arm
TARGET_ARCH_VARIANT=armv7-a-neon
TARGET_CPU_VARIANT=cortex-a9
TARGET_2ND_ARCH=
TARGET_2ND_ARCH_VARIANT=
TARGET_2ND_CPU_VARIANT=
HOST_ARCH=x86_64
HOST_OS=linux
HOST_OS_EXTRA=Linux-4.9.0-2-grsec-amd64-x86_64-with-debian-9.0
HOST_BUILD_TYPE=release
BUILD_ID=MOB31K
OUT_DIR=/home/wolfi/replicant/6.0-romsrc-official/out
WITH_SU=true
============================================

This is the output for the Galaxy Note 2 (n7100).

You must repeat these steps everytime before building anything on a freshly-opened terminal.
Remember:

. build/envsetup.sh
lunch replicant_device-userdebug

(Make sure to replace device by your device's product name)

Building a recovery image

Now that everything is set-up, you can build the first image to test on your device: the recovery image.

The build target is recoveryimage, so all you have to do is:

mka -j9 recoveryimage

This should trigger the kernel build and the recovery initramfs build and in the end, produce the out/target/product/device/recovery.img file.
Once your image is built (it takes some time), flash it to the recovery partition of your device (if any). It's a good idea to look at the LineageOS installation guide to find out how to install that recovery image.

There is usually also a key combination to hold to boot directly to recovery: hopefully, your recovery image will start.

Building the system

It is time to build a complete set of Replicant images. This includes the system and kernel images.

Building the kernel

Let's start by building the boot image, that is both the kernel and the Android initramfs. The build target is bootimage:

mka -j9 bootimage

In the end, the out/target/product/device/boot.img file will be produced.

Building the system image

Building the system is the longest task. The build target is systemimage:

mka -j9 systemimage

You might encounter build errors due to the lack of non-free libs. You'll need to find clean workarounds for that. Removing options from BoardConfig.mk can help solve the situation.
For instance, the following error:

make: *** No rule to make target `out/target/product/i9300/obj/lib/libTVOut.so', needed by `out/target/product/i9300/obj/EXECUTABLES/mediaserver_intermediates/LINKED/mediaserver'.  Stop.

Was solved by turning BOARD_USE_SECTVOUT to false:
BOARD_USE_SECTVOUT := false

Installation

When all the images are built, you're ready to install your Replicant build to the device. Create a flashable zip:

make -j9 bacon

The final zip is located at out/target/product/device/replicant-6.0.zip

There are several ways to install the zip in the recovery:

Make sure to do a factory reset before rebooting.

If everything was correctly setup, this should succeed. The best way to make sure it booted is to run adb devices and see if the device is listed.
That early, it is very likely that graphics will be broken, so don't expect anything to show up on the screen: only adb is a reliable way of knowing whether it worked.

It is possible to access adb logcat without fully booting the device and enabling ADB access in the developer settings. However, changes to the build properties of the device and possibly source code changes are needed.

If you can't manage to access the device with ADB, you will need to figure out how a serial console via UART can be established.

Android development tips

Keep in mind that all the make (and such) commands must be run in a terminal where lunch has been executed before.

Once you have a Replicant image installed on the device, there is no need to rebuild a whole image everytime you make a change (but it's a good idea to do it from time to time): you can instead rebuild only a single module by using (where module is the module's name):

make module

Even better, you can build the module that sits in the current directory by simply using mm. To push the new library to the device, use adb push (you'll need to adb root and adb remount the first time).

Moreover, instead of rebooting, you can kill the Android applications (zygote, surfaceflinger, rild) depending on what you are working on.
For instance for audio:

adb shell killall zygote

For graphics:
adb shell killall surfaceflinger

For the RIL:
adb shell killall rild

Be sure to always look what's going on in logs.
For the main buffer:

adb logcat

For the radio (RIL) buffer:

adb logcat -b radio

See BuildTips for more tips.

Graphics

Once Replicant booted on the phone, it's time to get graphics working. Several components are involved with graphics on Android:

Generally speaking, libEGL is non-free while gralloc and hwcomposer might be free software (but they often rely on non-free blobs). On most Replicant-supported phones, we use the default gralloc, the software libEGL (libagl) and no hwcomposer. We modified the gralloc so that is uses RGB565 on framebuffer, which turns out to be faster than any other format we tried.

To have a fluid-enough experience, you need to disable most hardware-accelerated features of Android and enable Software GL.
In BoardConfig.mk (or BoardConfigCommon.mk in the common directory for your device), you may find the following lines:

USE_OPENGL_RENDERER := true
BOARD_EGL_NEEDS_HANDLE_VALUE := true
TARGET_REQUIRES_SYNCHRONOUS_SETSURFACE := true

Set USE_OPENGL_RENDERER to false and remove the other lines. There may be more settings related to GPU-accelerated Graphics. You will need to remove these, too.

Replicant 6.0 has experimental support for a more complete software renderer implementation: llvmpipe from Mesa. To be able to use llvmpipe, add this line to the BoardConfig.mk (or BoardConfigCommon.mk in the common directory for your device):

BOARD_GPU_DRIVERS := swrast

Audio

If there is no audio support with free software on LineageOS, you'll have to find out details about how audio works on your device. There are mainly 3 different cases:

To find out whether your device uses ALSA or not, look if you have the /dev/snd/pcmC0D0c and /dev/snd/pcmC0D0p nodes available. A non-standard interface aside might be indicated by the presence of the /dev/snd/hwC0D0 node.

If your device is standard ALSA, you can use the tinyalsa-audio library (located under hardware/tinyalsa-audio) with a configuration file (an example of such a file is available at device/samsung/galaxys2-common/configs/tinyalsa-audio.xml). You can find the proper controls to set on which scenario by running tinymix (found under external/tinyalsa) with the non-free blob in place in the different scenarios.

If your device involves a non-standard interface or if it completely relies on a non-standard interface, there is no readily available guide to find out how it works, but you can start by looking at the kernel driver and adding debug prints (with printk) and figure out what is going on.

Remember to add the working audio module to the build targets (on the makefiles in the device repo).

Modem

In order to support telephony, messaging (SMS) and other network-related features (data as well), you need to make the modem work with Replicant. The modem is often called the radio in Android terminology.

The modem uses a protocol to communicate with the CPU. You need to find out which protocol the modem for your device is using. There are several possible cases:

To find out which protocol your phone uses, it is a good idea to look at the radio log buffer in LineageOS and try to find out from the messages (it may be verbose).
The protocol itself is implemented in the RIL (Radio Interface Layer): it is a good idea to take a look at the non-free RIL the device uses (get its path with getprop rild.libpath). If LineageOS developers have implemented a wrapper for the proprietary RIL, you will get the path of the wrapper. Look at the RIL wrapper source code in the device repo to find out the path to the non-free RIL.

If the modem uses the AT protocol, there are many available RIL implementations out there: Android has a reference-ril (hardware/ril/reference-ril) that implements AT and there is the hayes-ril library that makes it easier for you to add support for your device. Though, it is possible that the modem of your device implements undocumented commands, so you'll have to figure these out: the radio log might help a lot if it's verbose, else you'll have to trace the RIL somehow.

If the protocol is not AT, it might still be supported: the FreeSmartphone.Org (FSO) project implements some undocumented protocols. You can also look at oFono.
If your phone was manufactured by Samsung, there is a very good chance that it uses the Samsung-IPC protocol, which is implemented in libsamsung-ipc and Samsung-RIL. You will need to add support for your device in libsamsung-ipc (Samsung-RIL is device-independent: all the abstraction is done by libsamsung-ipc), which may be more or less easy depending on whether your modem type is already supported. In any case, you'll need to trace the RIL to find out. There may also be a separate daemon (often called cbd) that is in charge of the modem bootup (that's the biggest part you need to figure out), so that's the thing to trace.

If the protocol implementation is nowhere to be found, you'll have to write a free implementation yourself if you want to have free software support for the modem. It's a good idea to ask around whether other people from other communities, such as XDA or LineageOS, would be interested in helping you.

After finding a RIL that may work, add it to the build targets (in the device makefiles) and specify the path to the RIL with rild.libpath (it is often already declared in system.prop in the device repo).

Once the RIL is working, you may need the audio module cooperation to have sound during calls. For instance with Samsung-RIL, you need to use an Audio-RIL-Interface that implements the Samsung-RIL-Socket interface.

Sensors

When adding support for sensors, look at exactly what you will need to replace. There are several possible scenarios:

Note that sensors may require daemons aside, such as orientationd, geomagneticd, etc. You will most likely need to replace these as well.

If the implementation is incomplete, you will have to write a replacement for the non-free library that is used.

If there is nothing available, you will have to write a sensors module for you device. You can reuse one from another device and add support for your sensors there.
For instance, here is a reference commit of the SMDK4x12 Sensors module that you may reuse.

Remember to add the working sensors module to the build targets (on the makefiles in the device repo) like it is done on the reference commit.

Figuring out the magic in sensors

When there is no free software for your sensors, you have to figure out: how to enable/disable the sensor and set the poll delay (it's often done via sysfs or via ioctl on a dev node). Reading the kernel-side driver of the sensor is a very good idea, you can add debug prints and force values there. You can also find datasheets about your sensor online, which may help you understanding how it works.

The really big part is to figure out how to convert the values that are out of the device (and generally passed through by the kernel driver) into the standard units that the Android framework requires.
An effective way to do this is to print the values passed by the kernel driver and look what the non-free sensors module returns. Better yet, you can also trace the non-free module and see exactly what it does, though that won't give you the details of the maths involved.

To find out the maths, open a spreadsheet software, then add the matching kernel values and the one out of the non-free module and try to find an equation that gives the values in standard units from the one returned by the kernel driver. For instance, you might find something like (this is for the LSM330DLC accelerometer):

f(x)=0,0095768072 * x 

Once you have this, you may want to find out where that value comes from. In that case, we can see that:

0,0095768072 = 9.80665 / 1024

With 9.80665 being the standard gravity on Earth. Hence, we have:
f(x)=x * GRAVITY_EARTH / 1024

We can guess that 1024 is the resolution of the ADC that provides the sensor value.

Once you have this equation figured out, you're ready to implement this in your free sensors module!

Camera

When adding support for the camera, you need to look at what is already there in LineageOS:

In the first case, you will only have to adjust the preview format to RGB565 and it may also a good idea to lower the preview frame rate. Depending on whether the library already has code to handle RGB565, the difficulty of doing this will change. Here are reference commits that introduce these changes for the Nexus S: camera: RGB565 preview format
We cannot use YUV formats directly because the Android software EGL implementation used in Replicant does not support it.

If there is a wrapper, you'll need to replace it by an actual camera module that works. Depending on your hardware, there may be different cases:

In both cases, you'll need to add lots of debug prints to the relevant kernel drivers to figure out how it works. It will be easier if it uses V4L2, as you can already find many implementations of V4L2 out there, but it will very likely need a custom procedure and controls. In the case of a non-standard interface, you are on your own, except if you can find an implementation for a similar interface used on an other device.

Here is a reference commit of the SMDK4x12 Camera module that uses the Samsung FIMC engine. While it uses V4L2, it needs a custom procedure and custom controls to work properly.

Beware: some camera drivers require the cooperation of the GPU (that seems to be the case on OMAP4). In that case, even a free camera module implementation cannot work on Replicant. Camera drivers may also need to load a non-free firmware, that cannot be distributed with Replicant: hence, you must make sure that the driver will use the pre-installed version of the firmware (if any), burnt on the camera chip in the case loading the non-free firmware from the system fails.

Dealing with loaded firmwares

It is very likely that your device requires loaded firmwares for some components of the hardware. These are non-free programs that run separately from the CPU, on other chips. Since Replicant respects its users' freedom, no non-free firmwares are shipped with Replicant. It is possible that LineageOS includes shareable non-free firmwares in its tree: you must remove them.

Sometimes, components will crash (and may restart in an endless loop) when attempting to load a firmware that is not shipped with Replicant: you have to spot the code that loads the firmware and make it properly handle the case where the firmware is not available.

Though, you should keep in mind that some users may want to use that firmware, so you have to make the firmware loading possible. There are some exceptions to this however, especially when this involves blocking a free software alternative (this is the case with OMX media decoding). Moreover, firmwares should always be located under /system/vendor/firmware/ so that they are easy to spot and remove when the user decides to get rid of them (after installing them previously).

For instance, the Wi-Fi firmwares path (often declared in the BoardConfig.mk file) have to be changed with the /system/vendor/firmware prefix. The bluetooth firmware path is often declared in the init files (such as init.herring.rc). Make sure to document the new firmwares locations on the wiki: see the Developer guide.

Dealing with the kernel firmwares

The Linux kernel comes with its own share of firmware: you have to get rid of them too. Mostly, this is about removing the firmwares directory and modifying the Makefile to make it avoid firmwares.
Since the procedure is nearly exactly the same on all kernels, here is a reference commit for the changes to add to Makefile: Get rid of proprietary firmwares and related instructions

Software media decoding

Most of the time, there is a chip dedicated to decoding media files (audio and video) and it very often requires a non-free loaded firmware. Moreover, it prevents software-only solutions from working, so you need to get rid of the libraries (even though they may be free software) that handle hardware media decoding. This is implemented in the OMX and lstagefrighthw libraries. You need to spot and remove these products from the build targets of your device (in the device makefiles).

For reference, here is the commit that removes hardware media decoding on Nexus S (crespo): Disable hardware video encoding/decoding

Bottomline

Not every hardware feature can be supported by Replicant: there are some areas where there is simply no free software available. If this is about a critical component (audio, graphics too slow, telephony) and there is no solution in sight, you might as well consider the port a failure. On the other hand, there are lacks we can leave with, for instance 3D, camera or GPS support: don't let that get in the way of releasing images for your device!

Pushing your work to Replicant repositories

Once your device works, or during the development process (it is recommended to do it as soon as it appears that the port will be successful), you have to push all your work to Replicant repositories.
You need to ask for commit access to our repositories to be allowed to push your work. This means creating the repositories for your device, pushing your work to these and to the other repositories you modified and adding the new repositories to the manifest.

The Developer guide hold all the rules for naming repositories: make sure to act accordingly with these requirements!

The manifest holds the list of the repositories we use in each Replicant version. Its syntax is xml, so it's easy to add your new repositories.

Adding documentation about your device

Once your device is usable, you have to create documentation on the Replicant wiki to let others know about relevant material concerning the device, especially build and installation instructions. This is absolutely required before we can publish any image for your device!

The process is described in the Developer guide.


Devices

Device pages

Not all the devices in this pages are supported by Replicant.

However it's still useful to keep track of some devices characteristics and information for various reasons.

Vendor Product Formfactor
Goldelico GTA04 Smartphone
Hardkernel Odroid U3 Exynos4412 devboard
LG OptimusBlack Smartphone
Necunos Necuno_NX_1 PDA (Smartphone without a modem)
Pine64 Pinephone Smartphone
Purism Librem5 Smartphone
Samsung Galaxy S Smartphone
Galaxy S II Smartphone
Galaxy S III Smartphone
Galaxy Note Smartphone
Galaxy Note II Smartphone
Galaxy Nexus Smartphone
Galaxy Tab Tablet
Galaxy Tab 2 Tablet
Galaxy Note 8.0 Tablet
Nexus S Smartphone

Structure

This page lists device pages which in turn point to the different variant or versions of the device.

Example of Device: Galaxy SIII
Example of Device variant: Galaxy SIII (GT-I9300)

TODO

See also


DevicesPictures

Device Location Picture or link License Comments
Galaxy SII (GT-I9100) Bottom PCB GT-I9100G_PCB_BACK CC-BY-SA Medium resolution
Galaxy SIII (GT-I9300) Bottom PCB i9300_pcb_bottom CC-BY-SA * PNG, Very high resolution
* Components marking not easy to see
* Made with a scanner
Galaxy SIII (GT-I9300) Top PCB upload TODO
Galaxy Note II (GT-N7100) Bottom PCB n7100_pcb_bottom
Galaxy Note II (GT-N7100) Top PCB n7100_pcb_top
Galaxy Note II 4G (GT-N7105) Bottom PCB n7105_pcb_bottom
Galaxy Note II 4G (GT-N7105) Top PCB n7105_pcb_top

Devices status

Maintained versions

Replicant 11.0

A port of Replicant to Android 11 is being worked on.

See the PortingToAndroid11 wiki page for more in depth technical details and progress.

Potentially supported devices:

Replicant 6.0

Most problematic usability issues that need to be fixed: Most problematic Freedom issues that are being fixed: Most problematic security issues that need to be fixed:
Device 2D graphics 3D graphics Audio Telephony Mobile data Wi-Fi Bluetooth NFC GPS Sensors Camera Hardware media encoding/decoding
Galaxy S 2 (I9100) Working, fast Missing Working, except Bluetooth and USB audio Working Missing without non-free firmwares1 Working? (bug #1928) Missing Missing Working Working Missing without non-free firmware
Galaxy Note (N7000) Working Working, except Bluetooth and USB audio Missing Working Missing
Galaxy Nexus (I9250) Working Missing without non-free firmwares Working Missing Missing
Galaxy Tab 2 7.0 (P31xx) N/A Missing Missing
Galaxy Tab 2 10.1 (P51xx) N/A Missing Missing
Galaxy S 3 (I9300) Working Working (back) Missing without non-free firmware
Missing without non-free firmwares (front)
Galaxy Note 2 (N7100) Working Working (back) Missing
Missing without non-free firmwares (front)
Galaxy Note 8.0 (N51xx) N/A Working Missing without non-free firmware
Galaxy S 3 4G (I9305) Missing Working Working (back) Missing without non-free firmware
Missing without non-free firmwares (front)

1 Wi-Fi can be enabled using a USB Wi-Fi adapter.

Unmaintained versions

Replicant 4.2

Device 2D graphics 3D graphics Audio Telephony Mobile data Wi-Fi Bluetooth NFC GPS Sensors Camera Hardware media encoding/decoding
Nexus S (I902x) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Working Missing Working Working Missing
Galaxy S (I9000) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares N/A Missing Working Working Missing
Galaxy S 2 (I9100) Working, fast Missing Working, except Bluetooth and USB audio Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Missing Working Working Missing
Galaxy Note (N7000) Working, slow Missing Working, except Bluetooth and USB audio Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Missing Working Working Missing
Galaxy Nexus (I9250) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Working Missing Working Missing Missing
Galaxy Tab 2 7.0 (P31xx) Working, fast Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares N/A Missing Working Missing Missing
Galaxy Tab 2 10.1 (P51xx) Working, slow Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares N/A Missing Working Missing Missing
Galaxy S 3 (I9300) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Working Missing Working Working (back) Missing
Missing without non-free firmwares (front)
Galaxy Note 2 (N7100) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Working Missing Working Working (back) Missing
Missing without non-free firmwares (front)
GTA04 Working Missing Working Missing Missing Missing without non-free firmwares Broken N/A Working Missing Missing Missing

Replicant 4.0

Device 2D Graphics 3D Graphics Audio Telephony Mobile data Wi-Fi Bluetooth GPS Sensors Camera Hardware media encoding/decoding
Nexus S (I902x) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working (light, proximity, accelerometer, gyroscope) Working Missing
Missing (magnetic field, orientation)
Galaxy S (I9000) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working (light, proximity, accelerometer) Working Missing
Missing (magnetic field, orientation)
Galaxy S 2 (I9100) Working, fast Missing Working, except Bluetooth and USB audio Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working (magnetic field is unreliable) Working Missing
Galaxy Note (N7000) Working Missing Working, except Bluetooth and USB audio Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working (magnetic field is unreliable) Working Missing
Galaxy Nexus (I9250) Working, fast Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working Missing Missing
Galaxy S 3 (I9300) Working, fast Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working Working (back) Missing
Missing without non-free firmwares (front)
Galaxy Tab 2 7.0 (P31xx) Working, fast Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working Missing Missing
Galaxy Tab 2 10.1 (P51xx) Working Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working Missing Missing

Replicant 2.3

Device 2D graphics 3D graphics Audio Telephony Mobile data Wi-Fi Bluetooth GPS Sensors Camera Hardware media encoding/decoding
Nexus One Working, fast Missing Missing without non-free firmwares Working (calls depend on audio) Untested Missing without non-free firmwares Missing without non-free firmwares Working, without AGPS Working (accelerometer, proximity, light) Missing Missing
Untested (magnetometer)
Nexus S (I902x) Working, fast Missing Working Working Working Missing without non-free firmwares Missing without non-free firmwares Missing Working (accelerometer, gyroscope, proximity, light) Working (black and white preview) Missing
Missing (magnetometer)
GTA04 Working, fast Missing Working Missing Missing Missing Missing Missing Missing Missing Missing

Replicant 2.2

Device 2D graphics 3D graphics Audio Telephony Mobile data Wi-Fi Bluetooth GPS Sensors Camera Hardware media encoding/decoding
Dream/Magic Working, fast Missing Working Working Broken Missing without non-free firmwares Missing without non-free firmwares Working, without AGPS Working (accelerometer) Missing Missing
Missing (magnetometer)
Nexus One Working, fast Missing Missing without non-free firmwares Working (calls depend on audio) Broken Missing without non-free firmwares Missing without non-free firmwares Working, without AGPS Working (accelerometer, proximity, light) Missing Missing
Untested (magnetometer)

Dream/Magic

Device Dream/Magic
Manufacturer Google/HTC
Release date October 2008
Codename dream_sapphire
Status Unmaintained
Supported models ADP1, G1, Dream, Magic 32B
Latest images Replicant 2.2 0009

Replicant status

Replicant status for the Dream/Magic: ReplicantStatus Replicant 2.2

Status of efforts to replace proprietary libraries, binaries and firmwares: NexusOneProprietary: HTCDreamHTCMagicProprietary

Replicant installation

Replicant installation for the Dream/Magic: DreamMagicInstallation

Replicant build

Replicant build for the Dream/Magic: HTCMagicBuild

Freedom and privacy/security issues

Freedom issues on the Dream/Magic:

Privacy/security issues on the Dream/Magic: DreamMagicPrivacySecurityIssues


HTC Dream/HTC Magic Installation

Warning: flashing another operating system like Replicant may void your warranty and will erase the data stored on the device.

Prerequisites

If your device is a T-Mobile G1, a Google ADP1 or an HTC Magic, you can switch to flashing the images right away.

On the other hand, if it's an HTC Dream, you will need to flash a particular bootloader (DangerSPL) and a matching radio image.
These files are non-free and the procedure to install them on your device is out of the scope of the Replicant project. However, flashing them are required for Replicant to work.

You can find the files to download and instructions on the CyanogenMod wiki: https://web.archive.org/web/20160607055054/https://wiki.cyanogenmod.org/w/Dream_sapphire_Info

Flashing the images

Follow the procedure described in: FastbootInstallation


EMMCFirmwareBugs

Data corruption

Several devices have fixes or workarounds in vendor kernels for data corruptions in the eMMC. This can lead to non-working devices as it could potentially corrupt the bootloaders for instance.

The bug #2104 has more details for the Galaxy SIII.

Affected devices

VTU00M

Affected devices: Some Galaxy SIII (GT-I9300)
Vendor kernel patch: mmc: Soft-patch MoviNAND VTU00M (16GB) eMMC failure
Upstream status: not upstream
Replicant >=9 status: In Replicant 11 only

How to check

As this patch shows:

+    if (!strncmp(host->card->cid.prod_name, "VTU00M", 6) &&
+        (host->card->cid.prod_rev == 0xf1) &&
+        (mmc_start_movi_smart(host->card) == 0x2))
+        host->card->movi_ops = 0x2;

With Replicant > 6 we can find the eMMC name like that:

$ adb root
$ adb shell
i9300:/ # cat /sys/bus/mmc/devices/mmc2:0001/name
VTU00M

As for the prod_rev, we have this code in the Replicant 6 kernel:

case 4: /* MMC v4 */
        [...]
        card->cid.prod_rev    = UNSTUFF_BITS(resp, 48, 8);
        [...]
        break;

So it's a MMC v4 and uses UNSTUFF_BITS(resp, 48, 8);

In upstream Linux we have that instead:

    case 4: /* MMC v4 */
        [...]
        card->cid.prv        = UNSTUFF_BITS(resp, 48, 8);
        [...]

So we should be able to get the revision in this way:

$ adb root
$ adb shell
i9300:/ # cat /sys/bus/mmc/devices/mmc2:0001/prv
0xf7

Here I've the 0xf7 revision and not the problematic 0xf1 revision, so I should probably be ok.

Here this has been tested with a GT-I9300 with a work in progress Replicant 10 image that uses a kernel closely based on upstream Linux.

Vendor kernel workaround analysis

The mmc: Soft-patch MoviNAND VTU00M (16GB) eMMC failure patch patches the eMMC firmware at runtime (it patches the firmware in RAM).

The eMMC firmware patch makes the eMMC hang when a corruption is about to happen.

See also

Other devices

See also
TODO

EnablingRootAccess

Introduction

Giving root access to an application enables that application to do almost anything on your device. So it's a very bad idea to do that if you do not trust that application. Giving root access to applications is sometimes necessary because certain operating system features are not available by default to applications that don't run as root.

For instance applications there are applications that emulates mass storage USB devices with your smartphone, or applications that use a firewall to block or redirect other applications (to use Tor for instance).

Enabling users to get a root shell is also very useful as they can therefor access all their data.

Enabling root access

To allow root access, open the Developer options in the settings. There, press Root access. In the pop-up menu, select either Apps only, ADB only or Apps and ADB, depending on how you want to restrict root access. See ADB for more information about root access with ADB.


EthernetAdapter

Status for Replicant 6.0

This was tested with an USB Ethernet adapter compatible with the asix Linux driver.

It probably works with more adapters as more drivers were enabled .
It probably also work with cdc_ethernet, as the drivers for that are also enabled. If it works, it should also be compatible with other Replicant smartphones (with the USB tethering), Single board computers having USB OTG ports, etc.

When everything works fine, and that an Ethernet cable is connected, the GUI will show a new icon and the Android system will automatically do a DHCP on the ethernet interface. The icon is like "<--->" but with small dots instead of dashes.

Device Cable Comments
Galaxy S 2 (GT-I9100) Standard micro-USB host cable
Galaxy S 3 (GT-I9300)
Galaxy S 3 4G (GT-I9305)
Galaxy Note (GT-N7000)
Galaxy Note 2 (GT-N7100)
Galaxy Nexus (GT-I9250) * Ethernet works with the GUI, but seem to require to be plugged at boot
* It also probably works through the command line
Galaxy Tab 2 7.0 (GT-P3100) Device specific adapter
Galaxy Tab 2 10.1 (GT-P5100)
Galaxy Tab 2 7.0 Wi-Fi (GT-P3110)
Galaxy Tab 2 10.1 Wi-Fi (GT-P5110)
Galaxy Note 8.0 (GT-N5100) ?
Galaxy Note 8.0 Wi-Fi (GT-N5110)

Exynos4412 Devices

Since the initial Replicant 9 port will include a number of devices based on Exynos4412 this page has been created to evaluate whether or not we can reuse this work on devices with the same SoC and, if so, what modifications would need to be made to add these other devices.

The content of this page might be more properly located in Upstream but is being added here first, while it is still a "work in progress" stage.

These resources were used to make this chart:

Galaxy SIII with an Exynos 4412 SoC

S3 devices that don't have the Exynos4412 SoC were intentionally left off the list

GT-i9300 GT-i9305 SHV-E210K SHV-E210L SHV-E210S SCH-i939D SGH-N035 (SC-03E) GT-I9308 SCH-I939 GT-i9305T GT-i9305N
Codename m0 m3 c1ktt c1lgt c1skt m0ctcduos (Duos) m3dcm (Alpha Gravity Quad) ? m0ctc m3 m3
Board Family Midas ? ? ?
RAM 1GB 2GB 1GB 2GB
CPU speed 1.4GHz 1.6GHz 1.4GHz
Firmware
3G Bands
4g Bands NA 3, 7, 20 3 1, 5 5 NA 1, (21?) NA NA 3, 7 3, 7, 8
Carriers
Countries International South Korea ? Japan China, Japan? China, Taiwan Australia Sweden
NFC
Compass
Touchscreen MMS114 ? ? ? ? ? ?
LCD S6E8AA0 ? ? ? ? ? ?
MHL supported in upstream Linux (name?) ? ? ? ?
Magnetometer AK8975 ? ? ? ? ? ?
Accelerometer/Gyroscope LSM330DLC ? ? ? ? ? ?
Proximity/Light sensor CM36651 ? ? ? ? ? ?
Barometer LPS331 ? ? ? ? ? ?
MFD MAX77693 ? ? ? ? ? ?
Fuelgauge MAX17047 ? ? ? ? ? ?
Touchkey Cypress ??? ? ? ? ? ? ?
Audio Codec WM1811 ? ? ? ?
WiFi/BT BCM4334 ? ? ? ? ? ?
Cell Modem / GPS XMM6262 MDM9615 CMC221 ? ? ? ? ? ?
Notification LED AN30259A ? ? ? ? ? ?
Rear Camera S5C73M3 ? ? ? ? ? ?
Front Camera S5K6A3 ? ? ? ? ? ?
Flash LED AAT1290 ? ? ? ? ? ?
Notes

Galaxy SIII with other SOCs

This is a list of Galaxy SIII that don't use an Exynos 44121:

TODO: Add other devices variants from https://en.wikipedia.org/wiki/Galaxy_SIII#Model_variants

1 This enables to check rapidly if a given device variant has an Exynos 4412, or if it's not documented yet here.

2 https://www.gsmarena.com/samsung_galaxy_s_iii_cdma-4799.php

Galaxy Note II

Note II devices that didn't have an Exynos4412 SoC were intentionally left off

GT-N7100 GT-N7105 SCH-i605 SCH-R950 SGH-i317 SGH-i317M SGH-T889 SGH-T889V SPH-L900 SCH-N719 GT-N7102 GT-N7108 GT-N7108D SGH-N025 (SC-02E) SHV-E250K SHV-E250L SHV-E250S GT-N7105T
Codename t03g t0lte t0ltevzw t0lteusc t0lteatt t0ltecan t0ltetmo t0ltecan t0ltespr t03gctc t03gchnduos t03gcmcc t0ltecmcc t0ltedcm (Sailor) t0ltektt t0ltelgt t0lteskt t0lte
Board Family midas t0ltecdma ? LOS Kernel
RAM 2GB
CPU speed 1.6
Firmware
3G Bands
4g Bands NA 3, 7, 20 13 NA 2, 4, 5, 17 4, 5, 17 4, 17 4, 17 25 NA NA NA 3, 7, 39, 40, 41 1, 21 3, 8 3, 5 3, 5 3, 7
Carriers Verizon US Cellular ATT ? T-Mobile ? Sprint
Countries EU USA Canada USA Canada USA
NFC
Compass
Touchscreen MMS152 MELFAS_NOTE?
LCD S6EVR02
MHL SII9244BO SII9244BO
Magnetometer AK8963C AK8963C
Accelerometer/Gyroscope LSM330DLC LSM330DLC
Proximity/Light sensor CM36651
Barometer
MFD MAX77686 MAX77686
Fuelgauge MAX17047 MAX17047? MAX14607? MAX14607
Touchkey Cypress??
Audio Codec WM1811 ? WM1811
WiFi/BT BCM4334
Cell Modem / GPS XMM6262 MDM9615 MDM9X15? MDM9215M v4 ? MDM8215M ? ? ? ? ? ? ? ? ? ? ?
Notification LED AN30259A AN30259A
Rear Camera S5C73M3 S5C73M3
Front Camera S5K6A3
Flash LED MAX77693 MAX77693
Notes midas on mainline midas on mainline FCC Schematics FCC Schematics Factory kernel dump

Galaxy Note 8.0

GT-N5100 GT-N5105 GT-N5110 GT-N5120 SGH-i467 SGH-i467M SHW-M500W
Codename kona3g kona3g konawifi konalte konalteatt konaltecan konawifiany
Board Family kona
RAM
CPU speed
Firmware
3G Bands NA NA
4g Bands NA 7, 20 NA 3, 7, 8, 20 2, 4, 5, 17 4, 5, 7, 17 NA
Carriers ATT
Countries USA Canada
NFC
Compass
Touchscreen S7301 S7301
LCD NT71391
MHL SII9244BO SII9244BO
Magnetometer YAS532B YAS532?
Accelerometer/Gyroscope K2DHTR K2DH?
Proximity/Light sensor K3DH?
Barometer YAS532?
MFD MAX77686? MAX77686? or MAX77693?
Fuelgauge MAX17047_C
Touchkey
Audio Codec WM1811 WM1811
WiFi/BT BCM4334 BCM4334
Cell Modem XMM6262 NA MDM9X15
GPS BCM4752 BCM4752
Notification LED
Rear Camera ISX012
Front Camera SR130PC20
Flash LED MAX77693 MAX77693
Notes LOS kernel LOS kernel

Galaxy Note 10.1 (2012 Edition)

GT-N8000 GT-N8005 GT-N8010 GT-N8013 GT-N8020 SCH-I925 SCH-I925U SPH-P600 SHW-M480W SHW-M480S SHW-M480K SHV-E230S SHV-E230K SHV-E230L SHW-M485W SHW-M486W
Codename p4noterf p4noterf p4notewifiww p4notewifi p4notelte p4noteltevzw p4notelteusc p4noteltespr p4notewifiany p4noterfskt p4noterfktt p4notelteskt p4noteltektt p4noteltelgt p4notewifiktt p4notewifi43241any
Board Family p4note
RAM 2GB
CPU speed 1.4 GHz
Firmware
3G Bands ? ? NA NA ? ? ? ? NA ? ? ? ? ? NA NA
4g Bands NA NA NA NA ? 13 NA 25 NA NA NA 3, 5 3, 8 1, 5 NA NA
Carriers Verizon US Cellular Sprint *1 KT Roaming *1 KT Roaming LG U+ KT Roaming
Countries International Turkey International USA International USA USA USA South Korea South Korea South Korea South Korea South Korea South Korea South Korea
NFC NA
Compass AKM AK8975C
Touchscreen ATMEL_MXT1664S
LCD SEC LTL101AL01-002/003
MHL SII9244
Magnetometer
Accelerometer/Gyroscope STM LSM330DLC
Proximity/Light sensor ROHM BH1721FVC / LIGHTON AL3201?
Barometer NA
MFD MAX77686
Fuelgauge MAX17042
Touchkey
Audio Codec WM1811
WiFi/BT BCM4334
Cell Modem XMM6262 XMM6262? NA NA ? MDM9X15 XMM6262 QC USB serial QC USB serial QC USB serial
GPS BCM47511 BRCM_475X BRCM_475X BRCM_475X NA NA NA
Notification LED NA
Rear Camera ISX012
Front Camera S5K6A3
Flash LED
Notes LOS Kernel OFW has no
voice calls
LOS kernel LOS kernel

Galaxy Camera 2 -

EK-GC100 EK-GC110 EK-GC120 EK-GC200
Codename gd1 gd1wifi gd1ltevzw sf2wifi
Board Family
RAM
CPU speed
Firmware
3G Bands
4g Bands
Carriers
Countries
NFC
Compass
Touchscreen
LCD
MHL
Magnetometer
Accelerometer/Gyroscope
Proximity/Light sensor
Barometer
MFD
Fuelgauge
Touchkey
Audio Codec
WiFi/BT
Cell Modem / GPS
Notification LED
Rear Camera
Front Camera
Flash LED
Notes

Hardkernel ODROID and ORIGEN

1 https://wiki.odroid.com/old_product/odroid-x_u_q/odroid-xq
fn2. http://odroid.us/mediawiki/index.php?title=ODROID-Q2

ODROID-Q ODROID-Q2 ODROID-U2 ODROID-U3 ODROID-X ODROID-X2 Origen 4 Quad
RAM 2G 1G 2G 1G
WiFi/BT both
eMMC odroid? connector yes
SD microSD SD
JTAG Yes Yes No ? ? yes
UART * specific connector for console Settings: ttySAC1, 115200 8N1 * Header for a second UART Settings: ttySAC0 yes
Linux dts Not upstream Not upstream exynos4412-odroidu3.dts exynos4412-odroidx.dts exynos4412-odroidx2.dts exynos4412-origen.dts
Linux defconfigs
u-boot defconfig Unsure which ODROID devices this is for https://gitlab.denx.de/u-boot/u-boot/blob/master/configs/odroid_defconfig
Documentation wiki liliputing

Galaxy Win

Galaxy Pop

Galaxy Light

Galaxy Grand

Lenovo P700i

Hyundai T7 Tablet

GT-B9388

SCH-2013

Galaxy NX

Meizu MX2

UT4412BV03 Exynos4412 A9 4 Core Development Board


Exynos4 Bootrom

Background information

The Replicant project wants to support devices with free software bootloaders, but most/all the smartphones and tablets supported by Replicant do check the signature of the first stage bootloader.

A presentation on the situation of some of the devices supported by Replicant was made at the Replicant contributors meeting in July 2019. The presentation slides and video are available.

Exynos 4 signature check

The Exynos4 bootrom has a strange way to check the signatures:

Attempts

xboot

xboot is an OS that is supposed to run as the BL1 on a board that has the the Exynos 4412.

There is an attempt to port it and run it on the Galaxy SIII but it didn't succeed yet.

func_ptr_BaseAddr

If the xboot attempt doesn't work we could also try to understand with qemu2 or a developement board that has JTAG, if func_ptr_BaseAddr is somehow used by the bootrom when verifying the BL1.

Testing with qemu2 is probably way more easy than using the JTAG.

If it is we might be able to replace the bootrom check function.

1 https://fredericb.info/2018/03/emulating-exynos-4210-bootrom-in-qemu.html

2 https://github.com/frederic/qemu-exynos-bootrom

JTAG, fuses and EMMC RPMB

According to a post on the gsmhosting.com forum :

 Threr are 2 types of devices exist.

1. EXYNOS Devices with JTAG Disabled ( GT-I9300,GT-I9500,GT-N7100 etc.)

    KNOX Warranty bit are stored inside of RPMB area in eMMC
    Downgrade protection byte are stored in RPMB.

So if that's true for most common devices and that we don't find a way to re-enable the JTAG we probably cannot use it to load bootloaders and/or to experiement with the hardware on these devices.

However it's probably still possible to use JTAG on some devboards.

The thing we can learn from this post is also that unlocking the device probably don't change the Exynos 4 fuses. I wonder why it is implemented this way when other devices use fuses. And for the devices that use fuses, what is the fuse bit used for? Is it to prevent the fuses to have all bits be modified to zero or 1 and which would make it easier to compute the private key? Does the Qualcomm SOCs have a more granular approach to fuses? How does the Management Engine which also burn fuses at runtime handle that?

Other tests to attempt

Other

Running the GT-I9100 bootrom in qemu

There has been some work from new Replicant contributor to package a qemu version that can run the Galaxy SII (GT-I9100) bootrom.

It's a docker file based on Ubuntu 16.04 LTS (Xenial Xerus), but it's probably possible to use Trisquel 8.0 LTS (Flidas) instead.

See the Emulating Exynos 4210 BootROM in QEMU for more background information on the topic.

Rebooting to u-boot

On several SOCs families you can override the boot pins through register writes.

For instance on the OMAP 3630 you have a register for that at 0x48002910 which is publicly documented in its technical reference manual.

Not all the system on a chip have something like that.

If registers to do that are found for the Exynos 4412, rebooting directly to u-boot from s-boot should be pretty easy to do.

The i9300_emmc_toolbox project can execute code in s-boot, and we can easily write C code to be executed in it.

Some examples are provided in the shellcode directory.

So it would be trivial to write to a register and use the already provided reboot function.

TODO:

Note that this has not been seen in use yet, including in the Galaxy SIII repair manual , which shorts a resistor to change the boot modes. Though the Samsung branch that does the smartphones and tablets is separate from the branch doing the System on a chip. So for instance the System on a chip branch was providing SOCs to Apple for its Iphones while consumer electronics branch was at (legal) war against Apple.

HOWTO

Loading a bootloader from SD

When booting Parabola with a Replicant 10 kernel on a Galaxy SIII (i9300), it is possible to erase the bootloader to make the device boot from the microSD instead.

This could be used to do some testing, for instance to see if the BL1 signature can somehow be bypassed, however as no free software bootloaders do exist yet (u-boot relies on nonfree and non-redistributable software), this is not very useful yet.

If you really want to erase the bootloader (your device will be broken and will never boot anymore), you could run the following:

# echo 0 > /sys/class/block/mmcblk2boot0/force_ro
# ddrescue -f /dev/zero /dev/mmcblk2boot0
GNU ddrescue 1.24
Press Ctrl-C to interrupt
     ipos:    4194 kB, non-trimmed:        0 B,  current rate:   4194 kB/s
     opos:    4194 kB, non-scraped:        0 B,  average rate:   4194 kB/s
non-tried:    9223 PB,  bad-sector:        0 B,    error rate:       0 B/s
  rescued:    4194 kB,   bad areas:        0,        run time:          0s
pct rescued:    0.00%, read errors:        0,  remaining time:         n/a
                              time since last successful read:         n/a
Copying non-tried blocks... Pass 1 (forwards)
ddrescue: Write error: No space left on device

And then verify that it's erased:

# hexdump -C /dev/mmcblk2boot0
00000000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
00400000

Also verify that the following partitions are also erased:

I'm not sure what BOTA0 and BOTA1 are but they were already blank in my case.

Recovering from a bad bootloader

Note that I didn't manage yet to go from u-boot to s-boot.

Requirements: HOWTO:

You then should have u-boot running which can boot Parabola, so you can then easily recover.

Note that to run Parabola you need to make sure that you use an MBR and no gpt as u-boot is to be put at the second 512B block.


Exynos modem isolation

This article talks about a very serious freedom, privacy and security issue we found during Replicant development on several devices.

On some devices, we found that the modem wasn't isolated and was potentially able to read and write part of the RAM used by Replicant.

Note that the versions of Replicant that are still being maintained don't support any of the affected devices anymore.

However some of these devices are still supported in libsamsung-ipc as Replicant has to maintain libsamsung-ipc and that other projects are interested in supporting such devices.

There also might be a way to completely prevent the issue, by making sure that the RAM chip shared with the modem is not used for other things than communicating with the modem, but so far no one succeded yet.

Affected devices:

At least the following devices are affected:

Other similar devices that are not supported by Replicant are probably affected as well.

Hardware design matrix

Chip Controlled by the CPU Controlled by the modem Connected to the modem
GPS Yes No No?
Audio CODEC Yes No Yes
NAND Yes No No
RAM Yes Yes (96Mib at least) Yes
WiFi/Bluetooth Yes No No
Sensors Yes No No
NFC Yes No No
Camera Yes No No

Modem isolation

The modem (XMM 6160) is separated from the System on a chip and communicates with it over 16Mib of shared memory that comes from a 96MiB RAM chip.

The issue is that the remaining 80M of this RAM chip are also used as normal RAM by the CPU running Replicant.

Because of that, we don't have any assurance that the modem cannot read and write all the memory in that RAM chip, enabling it to either passively monitor what is going on, and/or to take control of the CPU running Replicant.

While the hardware design could ensure that only some lines of the data address are made accessible to the modem, we don't have enough documentation to verify that, and even if it was the case it couldn't be guaranteed for every single device used with Replicant.

This is bad: it means that RAM in general is potentially compromised.

Regarding audio, the modem is connected to the CODEC but cannot control it (the SoC has to enable routing from/to the modem).
There is no evidence that the GPS is connected to the modem, but since we cannot check on the hardware, there is no proof it's not connected to it either. The SoC is able to control the GPS power though, so we can keep it off.
Since the SoC has to load the modem firmware over the (fake) serial, and following the datasheets, the modem is not connected to the NAND.

The modem is potentially able to read and write (at least) 96 Mib of the main memory. So far, we cannot tell:

The Linux kernel is being loaded at the beginning of the shared memory bank (0x30000000), however the kernel should be off when it loads.

Nexus S (GT-I902x) Kernel details

In kernel-crespo/arch/arm/mach-s5pv210/dev-herring-phone.c we have:

static struct resource mdmctl_res[] = {
[...]
        [2] = {
                .name = "onedram",
                .start = (S5PV210_PA_SDRAM + 0x05000000),
                .end = (S5PV210_PA_SDRAM + 0x05000000 + SZ_16M - 1),
                .flags = IORESOURCE_MEM,
        },
};

static struct platform_device modemctl = {
        .name = "modemctl",
        .id = -1,
        .num_resources = ARRAY_SIZE(mdmctl_res),
        .resource = mdmctl_res,
        .dev = {
                .platform_data = &mdmctl_data,
        },
};

And in the board file, in kernel-crespo/arch/arm/mach-s5pv210/mach-herring.c we have:

static void __init herring_fixup(struct machine_desc *desc,
                struct tag *tags, char **cmdline,
                struct meminfo *mi)
{
        mi->bank[0].start = 0x30000000;
        mi->bank[0].size = 80 * SZ_1M;
        mi->bank[0].node = 0;
        [...]
}

So for this RAM chip we have:

CPU physical address range Usage
0x30000000 -> 0x30000000 + 80MiB -1 System RAM
0x30000000 + 80MiB -> 0x30000000 + 80MiB + 16MiB - 1 Modem shared memory

So we can suppose that there is at least one ram chip that is shared between the modem and the main CPU. Avoiding the use of this memory bank would result in loosing at least 80Mib of memory.

Galaxy S (GT-I9000) Kernel details

In arch/arm/mach-s5pv210/dev-s1-phone.c we have:

static struct resource onedram_res[] = {
[...]
    [0] = {
        .start = (S5PV210_PA_SDRAM + 0x05000000),
        .end = (S5PV210_PA_SDRAM + 0x05000000 + SZ_16M - 1),
        .flags = IORESOURCE_MEM,
        },
};

static struct platform_device onedram = {
        .name = "onedram",
        .id = -1,
        .num_resources = ARRAY_SIZE(onedram_res),
        .resource = onedram_res,
        .dev = {
            .platform_data = &onedram_data,
            },
        };

And in the board file, in arch/arm/mach-s5pv210/mach-aries.c we have:

static void __init aries_fixup(struct machine_desc *desc,
        struct tag *tags, char **cmdline,
        struct meminfo *mi)
{
    mi->bank[0].start = 0x30000000;
    mi->bank[0].size = 80 * SZ_1M;
        [...]
}

So for this RAM chip we have:

CPU physical address range Usage
0x30000000 -> 0x30000000 + 80MiB -1 System RAM
0x30000000 + 80MiB -> 0x30000000 + 80MiB + 16MiB - 1 Modem shared memory

So we can suppose that there is at least one ram chip that is shared between the modem and the main CPU. Avoiding the use of this memory bank would result in loosing at least 80Mib of memory.

Workaround attempt

It might be possible to limit the amount of damage by relying on the fact that the modem has to be booted by Replicant, and make sure that the RAM chip that is shared with the modem isn't used for other things than this memory sharing.

This would make us lose about 80Mib of RAM, and the shared memory would still be used for SoC/Modem communication but as the RAM chip would be used only for that, so the modem would not be able read and write problematic data on it.

We would also need to make sure that the booloader doesn't load the kernel in that region or that the kernel is relocated to some other region before intializing the modem.

The current diff with the Nexus S kernel is here, but it doesn't boot at all with the following changes (and mkbootimg changes):

diff --git a/arch/arm/configs/herring_defconfig b/arch/arm/configs/herring_defconfig
old mode 100755
new mode 100644
index 11abbf0..99bf3f5
--- a/arch/arm/configs/herring_defconfig
+++ b/arch/arm/configs/herring_defconfig
@@ -1,7 +1,7 @@
 #
 # Automatically generated make config: don't edit
 # Linux kernel version: 2.6.35.7
-# Fri Jun  3 07:07:08 2011
+# Sun Apr  8 14:40:16 2012
 #
 CONFIG_ARM=y
 CONFIG_HAVE_PWM=y
@@ -418,8 +418,8 @@ CONFIG_ALIGNMENT_TRAP=y
 #
 CONFIG_ZBOOT_ROM_TEXT=0
 CONFIG_ZBOOT_ROM_BSS=0
-CONFIG_CMDLINE="console=ttyFIQ0" 
-# CONFIG_CMDLINE_FORCE is not set
+CONFIG_CMDLINE="console=ttyFIQ0 no_console_suspend earlyprintk=serial,ttySAC2,115200 androidboot.serialno=3733BAB66DE200EC androidboot.bootloader=I9020XXKA3 androidboot.baseband=I9020XXKB3 androidboot.info=0x4,0x0,1 androidboot.carrier=EUR gain_code=3 s3cfb.bootloaderfb=0x34a00000 mach-herring.lcd_type=0x00000000 oem_state=unlocked" 
+CONFIG_CMDLINE_FORCE=y
 # CONFIG_XIP_KERNEL is not set
 # CONFIG_KEXEC is not set

@@ -823,8 +823,6 @@ CONFIG_UEVENT_HELPER_PATH="" 
 CONFIG_STANDALONE=y
 CONFIG_PREVENT_FIRMWARE_BUILD=y
 # CONFIG_FW_LOADER is not set
-# CONFIG_FIRMWARE_IN_KERNEL is not set
-CONFIG_EXTRA_FIRMWARE="" 
 # CONFIG_DEBUG_DRIVER is not set
 # CONFIG_DEBUG_DEVRES is not set
 # CONFIG_SYS_HYPERVISOR is not set
@@ -835,7 +833,7 @@ CONFIG_MTD=y
 CONFIG_MTD_CONCAT=y
 CONFIG_MTD_PARTITIONS=y
 # CONFIG_MTD_REDBOOT_PARTS is not set
-# CONFIG_MTD_CMDLINE_PARTS is not set
+CONFIG_MTD_CMDLINE_PARTS=y
 # CONFIG_MTD_AFS_PARTS is not set
 # CONFIG_MTD_AR7_PARTS is not set

@@ -1191,6 +1189,7 @@ CONFIG_DEVKMEM=y
 CONFIG_SERIAL_SAMSUNG=y
 CONFIG_SERIAL_SAMSUNG_UARTS_4=y
 CONFIG_SERIAL_SAMSUNG_UARTS=4
+# CONFIG_SERIAL_SAMSUNG_DEBUG is not set
 CONFIG_SERIAL_SAMSUNG_CONSOLE=y
 CONFIG_SERIAL_S5PV210=y
 # CONFIG_SERIAL_MAX3100 is not set
@@ -2046,7 +2045,9 @@ CONFIG_HAVE_ARCH_KGDB=y
 CONFIG_DEBUG_USER=y
 CONFIG_DEBUG_ERRORS=y
 # CONFIG_DEBUG_STACK_USAGE is not set
-# CONFIG_DEBUG_LL is not set
+CONFIG_DEBUG_LL=y
+CONFIG_EARLY_PRINTK=y
+# CONFIG_DEBUG_ICEDCC is not set
 CONFIG_OC_ETM=y
 CONFIG_DEBUG_S3C_UART=2

diff --git a/arch/arm/mach-s5pv210/dev-herring-phone.c b/arch/arm/mach-s5pv210/dev-herring-phone.c
index f8798b3..ecef636 100755
--- a/arch/arm/mach-s5pv210/dev-herring-phone.c
+++ b/arch/arm/mach-s5pv210/dev-herring-phone.c
@@ -48,8 +48,8 @@ static struct resource mdmctl_res[] = {
     },
     [2] = {
         .name = "onedram",
-        .start = (S5PV210_PA_SDRAM + 0x05000000),
-        .end = (S5PV210_PA_SDRAM + 0x05000000 + SZ_16M - 1),
+        .start = (0x30000000  + 0x05000000),
+        .end = (0x30000000  + 0x05000000 + SZ_16M - 1),
         .flags = IORESOURCE_MEM,
     },
 };
diff --git a/arch/arm/mach-s5pv210/mach-herring.c b/arch/arm/mach-s5pv210/mach-herring.c
index c3a0182..67fa1cf 100755
--- a/arch/arm/mach-s5pv210/mach-herring.c
+++ b/arch/arm/mach-s5pv210/mach-herring.c
@@ -5494,21 +5494,17 @@ static void __init herring_fixup(struct machine_desc *desc,
         struct tag *tags, char **cmdline,
         struct meminfo *mi)
 {
-    mi->bank[0].start = 0x30000000;
-    mi->bank[0].size = 80 * SZ_1M;
+    mi->bank[0].start = 0x40000000;
+    mi->bank[0].size = 256 * SZ_1M;
     mi->bank[0].node = 0;

-    mi->bank[1].start = 0x40000000;
-    mi->bank[1].size = 256 * SZ_1M;
-    mi->bank[1].node = 1;
-
-    mi->bank[2].start = 0x50000000;
+    mi->bank[1].start = 0x50000000;
     /* 1M for ram_console buffer */
-    mi->bank[2].size = 127 * SZ_1M;
-    mi->bank[2].node = 2;
-    mi->nr_banks = 3;
+    mi->bank[1].size = 127 * SZ_1M;
+    mi->bank[1].node = 1;
+    mi->nr_banks = 2;

-    ram_console_start = mi->bank[2].start + mi->bank[2].size;
+    ram_console_start = mi->bank[1].start + mi->bank[1].size;
     ram_console_size = SZ_1M - SZ_4K;

     pm_debug_scratchpad = ram_console_start + ram_console_size;
diff --git a/BoardConfigCommon.mk b/BoardConfigCommon.mk
index fff6d1b..c09d935 100755
--- a/BoardConfigCommon.mk
+++ b/BoardConfigCommon.mk
@@ -51,10 +51,10 @@ DEFAULT_FB_NUM := 2

 BOARD_NAND_PAGE_SIZE := 4096 -s 128

-BOARD_KERNEL_BASE := 0x30000000
+BOARD_KERNEL_BASE := 0x40000000
 BOARD_KERNEL_PAGESIZE := 4096
-BOARD_KERNEL_CMDLINE := console=ttyFIQ0 no_console_suspend
-
+BOARD_KERNEL_CMDLINE := console=ttyFIQ0 no_console_suspend earlyprintk=serial,ttySAC2,115200 bootmem_debug
+BOARD_FORCE_RAMDISK_ADDRESS := 0x41000000
 #TARGET_RECOVERY_UI_LIB := librecovery_ui_crespo
 TARGET_RELEASETOOLS_EXTENSIONS := device/samsung/crespo

F-DroidAndApplications

Background

F-Droid will be removed in Replicant 4.0 0004 because it contains many applications that are not FSDG compliant.

Fixing F-droid

As Replicant cannot guarantee to have enough time to dedicate to create an alternate repository, it was decided to do the following.

The only maintenance burden here would be to work with upstream to make sure that the packages are tagged correctly in f-droid data.

In the meantime...

Without an upstream project, each Replicant user would need do the work of reviewing each application she want to use.

As this is very time consuming and would lead to a lot of work duplication, it's best for Replicant to provide some space to share the result of the reviews.

At the same time the reviews would also be tremendously useful to help fixing f-droid data.

Criteria

Since there are free versions of the Android SDK (see the SDK wiki page for more details), we can assume that all the applications that don't require microG to run build fine under at least one of the FSDG compliant GNU/Linux distributions with one of the SDK mentioned in the SDK wiki page.

It might still be useful to mention if we managed to rebuild them with an FSDG distribution and what we used to do that.

We can then review applications in a similar way than how we review packages for FSDG compliant GNU/Linux distributions.

There is also the Criteria for Android applications that was started to clarify the FSDG requirements for Android applications in general but that also applies to third party repositories in existing FSDG GNU/Linux distributions.

Being reviewed

Application and version Download link Review comments
RepWiFi Version 0.6.2 Being reviewed:
* GPLv3
* Doesn't seem to have any (nonfree) dependency
* Doesn't seem to promote nonfree software or actively push users toward the installation of nonfree software
* TODO: Try to build, though it was probably built as part of Replicant long time ago
Silence Version 0.15.16 Being reviewed:
* GPLv3 (probably GPLv3-only)
* Build systems: Android.mk (has instructions on how to produce a standalone APK), gradle
* Has some dependencies (git submodule):
- libs/com.amulyakhare.textdrawable: MIT
- libs/gradle-witness: MIT
- libs/org.greenrobot.eventbus: Apache 2.0
- libs/org.whispersystems.jobmanager: GPLv3 (build.gradle has "name 'GPLv3'", no mention of GPLv3+ or GPLv3-only)
- libs/org.whispersystems.libpastelog: GPLv3 (build.gradle has "name 'GPLv3'", no mention of GPLv3+ or GPLv3-only)
- libs/org.whispersystems.libsignal: GPLv3 (build.gradle has "name 'GPLv3'", no mention of GPLv3+ or GPLv3-only)
* Doesn't seem to promote nonfree software or actively push users toward the installation of nonfree software
* TODO: Try to build and see if it downloads all the dependencies source code and their dependencies dependencies source code if any

Not compliant

Application upstream anti-features Issues Upstream status
F-Droid None * Its repositories that are configured in by default (and enabled by default as well) have non compliant packages like Yalp, making F-Droid itself non compliant. * There is no automatic way to deduce that it's not FSDG compliant
* Upstream probably would not like having F-droid tagged with anti-features
* No current F-droid anti-features apply to that case
Yalp * NonFreeNet Yalp is a package manager that is setup to download applications from a repository that is not FSDG compliant * There is no automatic way to deduce that it's not FSDG compliant
* NonFreeNet is only about non-Free network service and not the license of the packages in the repository
* No current F-droid anti-features apply to that case
TODO:

TODO

Collaboration with the Free Software Directory (FSD)

The Free software Directory has a list of applications that run on Replicant.

We need to see with them how to handle the collaboration between both projects in the long run:

Wikidata

The Free Software Directory (FSD) seems to have way more fields seems to be able to store explanations along with the information. For instance there is a "License note" text form that could have detailed information about the license. It could probably tell which files or which parts are under which license for instance. Wikidata can't do that (it's not meant for text explanations). The Free Software Directory (FSD) also has fields and checkboxes for a lot of information, so Wikidata is probably currently lacking ways to store all that information.

Here's an example for Guix

So it might make more sense to contribute directly to the Free Software Directory (FSD) instead of Wikidata. If you still want to use Wikidata to do query on software, you could for instance:

FDroidCompliance

Introduction

F-Droid is a community-maintained software repository for Android based operating systems. It is similar to the Google Play store.

Replicant has depended very heavily on F-Droid for a long time now. End users expect app "stores" on their smart phones.

Unfortunately, F-Droid is not currently compliant with the FSF's Free Software Distribution Guidelines, which required Replicant to remove F-Droid from its upcoming 6.0 0004 release so that Replicant can continue to be FSDG compliant.

Much discussion has already been had within Replicant and between Replicant and F-Droid about how F-Droid can be modified in order to make it FSDG compliant so that it can be included again in Replicant in future releases.

F-Droid's build server has not purely free from proprietary blobs for a while now: https://gitlab.com/fdroid/fdroidserver/-/issues/383

It is important for F-Droid to be built using free tools.

Android has a decentralized app building process. This can be a very positive thing, fostering a much more diverse and playful ecosystem than app stores that Google and Apple provide on their smartphones's OSes.

Due to the freedom issues in the F-Droid build system though, a threat exists to user privacy and security.

One of these freedom issues is the fact that far too many pre-builds exist.

Replicant wants an app distribution system that runs a free toolchain so that users can rely on a fully free ecosystem.

One way of achieving this might be to utilize beuc's rebuilds: https://android-rebuilds.beuc.net/

Replicant wants to write environment setup bash scripts to build FDroid with beuc's version of the SDK in order to be able to provide a reproducible build environment that others can test.

Another freedom issue with F-Droid is that F-Droid includes apps with anti-features that are not compatible with the GNU FSDG. These apps are available alongside apps that are compatible and they are only marked with these anti-features. See #1629 for development efforts and further information on this topic. https://redmine.replicant.us/projects/replicant/wiki/FDroid

Plan

Define what to work on:
1. Cleanup this draft
2. Fill the missing information that can easily be found

Rationale: we need a rough idea of what needs to be worked on.

In parallel for Replicant:
a1. Precise how the people want to be paid (per tasks, hours, per months, etc) and the amount
a2. Find a way to report the progress if not paid by the task (quick blog post, wiki status, very fast mail on the mailing list, etc). /!\ It can take up to 1/2 day per week, as for the crowdfunding to free and upstream the Allwinner VPU. => Find a way to do it that suits people.
a3. Find out how to do it legally (employment, contract work, grant, etc)
a4. Steering commitee vote on that
a5. Find a way to legally formalize it through the FSF if needed

In parallel for NLnet:
a1. Write a very rough proposal and send it, don't wait too much as we might get a shot sooner. Make sure to be accepted in round 1 before starting to work on it or make sure to have a backup (like Replicant money).
a2. Fill the budget by calculating hours x price per hour. Keep in mind that it's a grant so you don't have the usual taxes (you need to check how to declare grants with your state) but the usual employee stuff is not covered (social security, state welfare, hollidays, extra time where you don't do productive work in an office but get paid, time spent on responding to email, or filling or preparing the MOU for NLnet etc)
a3. Send the MOU
a4. Sign it
a6. Finish a big task group, send a request for payment + bank details the first time and get paid, and redo that until everything is finished.

For the request for payment you need to point to resources that proves that the task is done. The reporting is done this way.

Example: git.replicant.us/GNUtoo/kernel_replicant_linux.git in this branch + build howto
Example2: post on the bugtracker of F-Droid with the agreed specification for the properties

Discuss with F-Droid to find a way to implement the FSDG compliance

Task Budget Comments Deliverable
Define with F-Droid upstream which properties we can use in package definition to comply with the FSDG guidelines Hard to predict as it depends on the outcome of the discussion with F-Droid => Replicant funding Specifications that are ready to be implemented by Fil bergamo
Discuss how to implement build time whitelists and blacklists Hard to predict as it depends on the outcome of the discussion with F-Droid => Replicant funding Precise specifications that are ready to be implemented by Fil bergamo
Some light coding tasks (I don't remember which one) Nlnet? Replicant? Can time be predicted?
Precise specifications: specifications that are clear enough to be implemented without making mistakes, and clear enough to understand for people using it.
Example: non-fsdg compliant property in the package definition.

Implementation

Person: Fil Bergamo

Task Budget Comments Deliverable
Implement the parsing of the properties Hard to predict as it depends on the outcome of the discussion with F-Droid => Replicant funding
Build F-Droid from an FSDG compliant distribution Hard to predict => Replicant funding Replicant 6 can't be built with FSDG compliant distros but Replicant 4.2, 9.0 and probably 10.0 too can => We need F-Droid to be built from an FSDG compliant distributions Building F-Droid from an FSDG compliant distribution + a quick HOWTO
Implement build time whitelists / blacklists Nlnet? Rough number of hours Can build F-Droid with custom blacklist and whitelists + quick HOWTO
Replicant F-Droid fork package in F-Droid Nlnet? Rough number of hours Package can be built with F-Droid tools, ideally upstream it

NLnet application

PortReplicantToAnewerAndroidVersionInitialApplication

NLnet foundation Grant application for "Finish porting Replicant to a newer Android version"

Contact information:

Your name Fil Bergamo and Kurtis Hanna
Email address contact address at the replicant.us domain
Phone numbers The phone number of Fil Bergamo which is in European union
Organisation Replicant
Country Italy(Fil Bergamo), USA (Kurtis Hanna)

General project information

Project name Make F-Droid FSDG compliant
Website / wiki https://redmine.replicant.us/projects/replicant/wiki/MakeFdroidFSDGCompliant
Abstract: Can you explain the whole project and its expected outcome(s).in 1200 characters
Replicant is a fully free software Android distribution that has to be
compliant with the FSF distribution guidelines (FSDG)
( https://www.gnu.org/distros/free-system-distribution-guidelines.html )
F-Droid has non-compliant applications like Yalp.
To fix it we need discuss with upstream to add define new anti-feature tags
in FDroid metadata, that can describe if a package is FSDG compliant,
in the most generic way possible as requested by upstream.
Once that is done we will discuss with upstream to define package and/or
anti-feature whitelist/blacklist to be implemented in the F-Droid client
in the most generic way possible.
The new tags and the whitelist/blacklist will be implemented in the F-Droid
client. The whitelist/blacklist will need to be configurable at build time,
to enable building a different FSDG F-Droid from the same source code.
F-Droid has already build time branding options.
We will then add that FSDG compliant F-Droid to the Fdroid metadata
repository.
This way we have near 0 maintenance and users of other distributions
could also use this FDroid.
We will also need to work with other projects to build FDroid on FSDG
distributions without any nonfree dependencies.
Have you been involved with projects or organizations relevant to this project before?
And if so, can you tell us a bit about your contributions?
Fil Bergamo and Kurtis Hanna are involved in Replicant since a very long time. <add a rough date>
Fil Bergamo
* Developed RepWiFi.
* Is part of the Replicant steering committee.
Kurtis Hanna:
* Is heavily involved in Replicant public relations, especially with other people working to upstream support for smartphones in Linux or u-boot for other Android or GNU/Linux distributions.
* Is involved a lot in the Replicant documentation in the wiki.

Requested support

Requested Amount (Between 5000 and 50000 Euros) Something rough works too, I've added 50000 by mistake and it was re-defined later
Does the project have other funding sources, both past and present? The Replicant project has about 200000 dollars at disposition:
* The Replicant project has a donation page https://crm.fsf.org/civicrm/contribute/transact?reset=1&id=19. Part of the donations were used for buying devices and reimburse conference attendances. We have about 20000 dollars remaining from the donation.
* The Replicant project recently received 200000 dollars from Handshake: https://www.fsf.org/news/free-software-foundation-receives-1-million-from-handshake As the FSF takes 10% that leaves us 180000 dollars
* Denis Carikli is being funded by NLnet to port Replicant to Android 9
* David "dllud" Ludovino and Ricardo "Grim" Cabrita are being funded by NLnet to work on the Replicant 9 graphic stack

Explain what the requested budget will be used for?

The budget will only be used to fund Fil Bergamo and Kurtis Hanna to work on this task.
TODO: Do you need a budget for other stuff? Like hardware or conference if Covid
confinment ends, or whatever is necessary to work on that?

Replicant will also complete the funding as we don't know how much time talking
with F-Droid can take, so it's hard to budget for it.

TODO: We think it will take something between <3> and <6> months of work
for one full time developer. <- Very rough estimation, more precise one can be done in stage2

However it is always difficult to evaluate precisely the amount of time
that this kind of project would take as it depends on how much time the discussions 
with upstream will take and what exact implementation is chosen.

<Maybe E/month * months >

The 2 people here are long time contributors to Replicant and
have a direct interest in making the project succeed.

Over time we will document the progress and add more information here:
https://redmine.replicant.us/projects/replicant/wiki/FDroidFSDGCompliance

Compare your own project with existing or historical efforts.

The first attempt was done by Wolfgang Weidermeier, and patches were merged, then reverted.
The patches also addressed the problem very partially so, even if they were merged they
wound't have been sufficent to fix the issue.

In the next attempt, people from Replicant (including Fil Bergamo, Kurtis Hanna and 
Denis Carikli) tried to discuss with upstream to avoid incomplete fixes, but that
failed because the people involved on Replicant side could only find the time to
discuss it for short period of times. So after several attempts like that we stopped
trying and planned to fund the task instead as it would give people involved enough
time to really fix it for good.

TODO: Point point to the bugreport in Replicant, in F-Droid + the old bugreport
and reverted patch.

What are significant technical challenges you expect to solve during the project, if any?

The most complicated challenges are not technical 
but human: we need to discuss with upstream to find the right solution.

Describe the ecosystem of the project, and how you will engage with relevant actors and promote the outcomes?

Explain the first step with F-Droid data and that we will open a bugreport there,
after having carefully read the FSDG compliance specification and checked with the
FSF lawyers if something is unclear.

Other Replicant developers will most probably help a bit as there is a big interest
in getting that issue fixed and that we already spent a big ammount of time discussing
plans on how to fix it at various conferences like FOSDEM <2018?>
Attachments None

How may we handle your information

What should we do in the other case,
e.g. when your project is not immediately selected?
Feel free to choose whatever you want here
Send me a copy of this application. check-box checked
PGP pubkey None (if we use Replicant contact address, we can't encrypt to it)

Fastboot Installation

Warning: flashing another operating system like Replicant may void your warranty and will erase the data stored on the device.

This guide assumes your phone is supported by fastboot.

First, you need to have fastboot already installed. If not you can follow the ToolsInstallation page to install it.

Key combinations for fastboot mode

Device Keys (held together)
HTC Dream/HTC Magic BACK, POWER
Nexus One Trackball, POWER
Nexus S VOL+, POWER
Galaxy Nexus VOL-, VOL+, POWER

Prepare the phone

  1. Turn the phone off, disconnect any USB cable
  2. Hold the key combination for fastboot mode (release only when in fastboot mode)
  3. You should be in fastboot mode. If not, remove the battery and retry the steps above
  4. Once the fastboot screen is waiting, plug the USB cable

Unlocking the bootloader

If this is the first time you reflash your phone, you will need to unlock the bootloader. This is done using fastboot:

./fastboot oem unlock

Warning: This will erase all the data stored on the phone, including the data stored on the internal memory!

Flash the images

  1. Flash the images using fastboot:
    ./fastboot flash boot boot.img
    ./fastboot flash recovery recovery.img
    ./fastboot flash system system.img
    ./fastboot flash userdata userdata.img
    
  2. Clear cache:
    ./fastboot erase cache
    
  3. Reboot:
    ./fastboot reboot
    

Your device should now be running Replicant!


F-Droid

Replicant includes F-Droid, the market application that provides free software.

The F-Droid Privileged Extension is shipped as well and makes background updates possible. Automatic background updates can be enabled in the settings of the F-Droid app.

F-Droid and the GNU Free System Distribution Guidelines (GNU FSDG)

Replicant is supported, recommended by the FSF and listed as a fully free software distribution that respects the GNU Free System Distribution Guidelines. However, F-Droid includes apps with anti-features that are not compatible with the GNU FSDG. These apps are available alongside apps that are compatible and they are only marked with these anti-features. See #1629 for development efforts and further information on this topic.

Not all F-Droid anti-features violate the GNU FSDG. The ones that do are explained below. We do not recommend the installation and usage of apps that have these anti-features.

Anti-features that are incompatible with GNU FSDG

NonFreeDep
Definition: the application depends on a non-free application (e.g. Google Maps) - i.e. it requires it to be installed on the device, but does not include it.

NonFreeAdd
Definition: the application promotes non-free add-ons, such that the app is effectively an advert for other non-free software.

NonFreeAssets
Definition: the application contains and makes use of non-free assets. The most common case is apps using artwork - images, sounds, music, etc - under a non-commercial license.

Tracking
Definition: the application tracks and reports your activity to somewhere without your consent. It’s commonly used for when developers obtain crash logs without the user’s consent, or when an app is useless without some kind of authentication


FindDevicesWithUnsignedBootloaedrs

Given the huge number of devices out there, buying each device and checking it doesn't scale. Especially as there are multiple variants and even multiple versions of the variants.

For instance for the Galaxy SII we have the GT-I9100 that has an Exynos4 and GT-I9100G that has an OMAP4. And for the GT-I9100G, there are multiple versions.

Making it easy for people to check the devices they have

The first step would be to document what tools already exist to do that and the ones that are lacking.

Some tools enable to check that.

We could make it easy to use such tools to do that by making sure that they are packaged and writing tutorials on how to do the check and report the result as well.

See BootloadersFreedom#Tools for more details.

Notes:

Checking images at large scale

The idea would be to find a way to get a very large number of stock images for Android devices make tests on the images and automatically check if the bootloaders are signed.

If the bootloaders are under a free software license and are unsigned, once we get and identify the corresponding source code we could publish them.

For the signed bootloaders under a free software license we'd better check with the FSF what is best to do as we need not to redistribute any software that is practically nonfree.

Constraints:

FindDevicesWithUnsignedBootloaedrs

Several smartphones and tablets that have an OMAP System On a Chip (SOC) are configured by hardware to try to load the bootloader from USB before loading it from the internal storage.

So far this includes at least the following deviecs:

As it might apply to other devices too, we could try to use that to find out if some devices we don't know about yet have the ability to run unsigned bootloaders.

How to check with command line utilities

To get the bootrom to try to boot on USB, you need to do the following:

If we do that, we get the following in the kernel log of your laptop:

usb 1-1: new high-speed USB device number 24 using ehci-pci
usb 1-1: unable to get BOS descriptor or descriptor too short
usb 1-1: New USB device found, idVendor=0451, idProduct=d00f, bcdDevice= 0.00
usb 1-1: New USB device strings: Mfr=33, Product=37, SerialNumber=0
usb 1-1: Product: OMAP4430
usb 1-1: Manufacturer: Texas Instruments

Note that your kernel might need to be compiled with CONFIG_USB_ANNOUNCE_NEW_DEVICES=y
to print that. In Parabola CONFIG_USB_ANNOUNCE_NEW_DEVICES=y is enabled.

We can also try to get a bit more infos with omap-usb-boot:

$ sudo omap-usb-boot -v -w boot invalidbootmedia
Finding and opening USB device
Found and opened omap4 USB device: OMAP4430
ASIC device id: 4430, HS device
Booting from device invalidbootmedia...
Booting device invalidbootmedia not found
Booting from device failed

Here we know the device is signed because it's a "HS device".
If it was not signed it would print "GP device" instead.


FixCorruptedUserDataPartition

Warnings

This tutorial is a work in progress. Remove this warning when it will be tested (and somehow indicate on which devices it was tested on).

Tutorial

Compatible devices

Only the following devices that are supported by Replicant are supported by this tutorial:

Setup ADB

Follow the instructions for setting up ADB on your computer so that you can access a root shell on your device.

NOTE: when prompted on your Replicant device, make sure that you check the box that says Always allow from this computer when you grant your computer USB debugging permissions. Otherwise, you will be unable to obtain root shell ac