Replicant

== 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 [http://source.android.com/porting/build_system.html Android Build System documentation] which is part of

[http://source.android.com/porting/ Android Platform Developer's Guide]. You should find an answer there if you have any questions about the Makefiles referenced in this document.

== 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:

[wiki: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 [wiki: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]: [2]

[ro.ril.gprsclass]: [10]

[rild.libpath]: [/system/lib/libreference-ril.so]

[rild.libargs]: [-d/dev/smd0]

[init.svc.ril-daemon]: [running]

[ro.ril.def.agps.mode]: [2]

[gsm.version.ril-impl]: [android reference-ril 1.0]

}}}

 * /dev/smd0 is the (emulated) serial port

 * /system/lib/libreference-ril.so is where to look for the RIL hardware specific library 

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 [wiki: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 ===

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.

=== 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 [http://gitorious.org/replicant/android_hardware_msm7k/commit/e0b55a19b2fc004915503ebdfd7c4c02c4264611 the routing fix].

Note several things on [http://gitorious.org/replicant/android_hardware_msm7k/commit/e0b55a19b2fc004915503ebdfd7c4c02c4264611 the commit]:

 * the routing was disabled, I had to re-enable it

 * I had to replace some non-existant functions, for that I used public playwav2.c source code that the author released to us under the apache 2.0 license.

 * I had nearly no knowledge of C++

 * it was easy

On the nexus one the proprietary libacoustic libraries are only used for bluetooth(all the rest works if you pushed the firmwares).

=== GPS ===

Two GPS libraries exist:

 * libgps

 * libloc_api

Both provide the same functionalities at the application level.

Choose the one that is supported by your device or that has support for a device close to your device.

==== libgps ====

For adding support to libgps you need to enable it like in [http://gitorious.org/replicant/android_device_htc_dream_sapphire/commit/153ab7e8fcf6bfc294b200d60a6f01feb5bb571a 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 buf[32];

-	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_IDs[2]);

 }

 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 ====

==== 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)

== 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 ===

 * vilvord ril

 * openmoko (android on freerunner) 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