Project

General

Profile

DevicePortingGuide » History » Version 17

Wolfgang Wiedmeyer, 08/28/2017 04:19 PM
update git.replicant.us links

1 2 Wolfgang Wiedmeyer
h1. Replicant 6.0 Porting Guide
2 1 Wolfgang Wiedmeyer
3
{{>toc}}
4
5 2 Wolfgang Wiedmeyer
This guide is a step-by-step explanation of the process of porting a new device to Replicant 6.0.
6 1 Wolfgang Wiedmeyer
7
h2. Overview
8
9
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:
10 2 Wolfgang Wiedmeyer
* Checking that your devices meets [[Replicant60PortingGuide#Prerequisites|the required prerequisites]]
11 1 Wolfgang Wiedmeyer
* Discovering the phone's hardware and the amount of non-free blobs involved
12
* Getting Replicant sources, reading all the relevant material about developing on Replicant
13
* Adding the device-specific repositories and files
14
* Setting up the build environment for the new device
15
* Building a recovery image
16
17 2 Wolfgang Wiedmeyer
*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_".*
18 1 Wolfgang Wiedmeyer
19
h2. Prerequisites
20
21
Before porting your device to Replicant, you must make sure it complies with the following requirements:
22 2 Wolfgang Wiedmeyer
* The phone is already supported by LineageOS (LOS) 13.0 (or, worst-case scenario, by a non-official LineageOS 13.0 or CyanogenMod 13.0 port)
23 1 Wolfgang Wiedmeyer
* The phone has a GSM modem: Replicant doesn't support CDMA phones (but you can add support for it if you're skilled)
24 2 Wolfgang Wiedmeyer
* There is a way of installing another operating system, either through the bootloader or via recovery (this is likely if there is a LOS port)
25 1 Wolfgang Wiedmeyer
* The kernel is not signed: this means that the bootloader doesn't check the kernel's signature to match with the vendor's key to allow it to run
26
27 2 Wolfgang Wiedmeyer
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.
28 11 Wolfgang Wiedmeyer
29
You can search the "XDA forum":https://forum.xda-developers.com/ 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.
30
31 12 Wolfgang Wiedmeyer
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.
32 11 Wolfgang Wiedmeyer
33
If you don't know whether your device complies or not, you will probably learn it along the way.
34 1 Wolfgang Wiedmeyer
35
h2. Discovering the phone's hardware and associated blobs
36
37
h3. Finding the device's codenames
38
39 3 Wolfgang Wiedmeyer
First of all, you'll have to find out the device's codename that was given by its manufacturer. "Wikipedia":https://www.wikipedia.org/ 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.
40 1 Wolfgang Wiedmeyer
41 3 Wolfgang Wiedmeyer
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":http://wiki.lineageos.org/devices.html or on the "LineageOS download page":https://download.lineageos.org/. For instance, the "Galaxy Nexus":http://wiki.lineageos.org/maguro_info.html codename is: @maguro@.
42 1 Wolfgang Wiedmeyer
43
h3. Investigating the hardware
44
45 3 Wolfgang Wiedmeyer
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.
46 1 Wolfgang Wiedmeyer
47 3 Wolfgang Wiedmeyer
To learn more details, you can consider looking for a teardown of the device (for instance on "iFixit":https://www.ifixit.com/), that will reveal what chips are used on the device. Looking at the kernel defconfig for the device will also help a lot, you can also try to find the service manual for the device.
48 1 Wolfgang Wiedmeyer
49
You can then compare that to the devices that are already supported in Replicant to get an idea of what will possibly work.
50
51
h3. Finding out if the device checks the kernel's signature
52
53
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.
54
55 4 Wolfgang Wiedmeyer
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.
56 1 Wolfgang Wiedmeyer
57
h3. Discovering the way of flashing the device
58
59 4 Wolfgang Wiedmeyer
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":http://wiki.lineageos.org/index.html 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.
60 1 Wolfgang Wiedmeyer
61
There are basically two ways of flashing a new operating system:
62
# 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.
63
# 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.
64
65
h3. The non-free blobs
66
67 4 Wolfgang Wiedmeyer
The key information to get before starting the port is the list of the non-free components that are required by LineageOS.
68
The easiest way to do this is to spot the device repository in "LineageOS repos":https://github.com/LineageOS/ and look for the @proprietary-files.txt@ or @extract-files.sh@ file on the @cm-13.0@ branch.
69
There is usually a link to the device repository from the device's build page in the "LineageOS Wiki":http://wiki.lineageos.org/index.html. 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.
70
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.
71 1 Wolfgang Wiedmeyer
72 4 Wolfgang Wiedmeyer
For instance, the list of non-free components for the "Galaxy Nexus":https://github.com/LineageOS/android_device_samsung_maguro/tree/cm-13.0 is "device-proprietary-files.txt":https://github.com/LineageOS/android_device_samsung_maguro/blob/cm-13.0/device-proprietary-files.txt
73
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.
74 1 Wolfgang Wiedmeyer
75
h2. Getting started with Replicant development
76
77
In order to prepare everything for the Replicant port:
78 5 Wolfgang Wiedmeyer
* Install LineageOS on the phone
79 1 Wolfgang Wiedmeyer
* Install the [[BuildDependenciesInstallation|build dependencies]]
80
* [[ReplicantSourceCode|Replicant source code]]
81 5 Wolfgang Wiedmeyer
* Read the Android Source code guide: https://source.android.com/source/index.html
82
* Read the Android Device porting guide: https://source.android.com/devices/index.html
83
* If there is no LineageOS support for your device: Read how to port CyanogenMod to your own device: https://web.archive.org/web/20161121154456/http://wiki.cyanogenmod.org/w/Doc:_porting_intro
84
  (a similar guide for LineageOS doesn't exist yet)
85 1 Wolfgang Wiedmeyer
* Read the Replicant [[DeveloperGuide|developer guide]]
86 15 Wolfgang Wiedmeyer
* Learn how to debug: [[GettingLogs|getting logs]], [[GDBDebugging|GDB debugging]]
87 1 Wolfgang Wiedmeyer
88
h2. Cloning the device files
89
90
Once your Replicant tree is ready, you can start adding the necessary repos for your device.
91
That means cloning the necessary repos in the right place. These repos are:
92 5 Wolfgang Wiedmeyer
* A *device-specific repo*. On LineageOS, it is usually called: @android_device_vendor_device@.
93 1 Wolfgang Wiedmeyer
* Sometimes one or more *common repo(s)*, usually called: @android_device_vendor_devices-common@.
94 5 Wolfgang Wiedmeyer
  Some devices don't need any common repo, but some do.
95
* A *kernel repo*. On LineageOS, it is usually called: @android_kernel_vendor_devices@.
96 1 Wolfgang Wiedmeyer
The kernel repo can be shared across a family of devices (for instance, on kernel repo for Samsung Exynos, one for Samsung OMAP, etc).
97
98 5 Wolfgang Wiedmeyer
You can find the device-specific repo from the device's page on the "LineageOS Wiki":http://wiki.lineageos.org. 
99
Make sure you check out the branches that match the LOS 13.0 version (cm-13.0).
100 1 Wolfgang Wiedmeyer
101 5 Wolfgang Wiedmeyer
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.
102
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@).
103 1 Wolfgang Wiedmeyer
104 5 Wolfgang Wiedmeyer
*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 [[Replicant60PortingGuide#Setting-up-the-build-environment| setting up the build environment]].*
105 1 Wolfgang Wiedmeyer
106
h3. In case of a missing kernel repository
107
108 6 Wolfgang Wiedmeyer
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.
109 1 Wolfgang Wiedmeyer
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.
110
That means the kernel sources will be available online. Here are some websites where such releases are done:
111
* "Samsung Open Source Release Center":http://opensource.samsung.com/
112
For Samsung kernels. Search the device codename (e.g. I9000) and download the package called "Opensource Update" (e.g. GT-I9000_Opensource_GB_Update2.zip).
113
This will hold a kernel archive with all the sources and instructions on how to build it and which defconfig to use.
114 6 Wolfgang Wiedmeyer
* "CodeAurora":https://wiki.codeaurora.org/xwiki/bin/QAEP/
115 1 Wolfgang Wiedmeyer
For MSM/QSD devices, and particularly HTC ones.
116
* "HTCdev":http://www.htcdev.com/devcenter/downloads
117
* "Motorola Sourceforge":http://sourceforge.net/motorola/
118 6 Wolfgang Wiedmeyer
* "Sony Mobile Developer":https://developer.sonymobile.com/downloads/opensource/
119
* "LG OpenSource":http://opensource.lge.com/index
120 1 Wolfgang Wiedmeyer
121
Once you have the kernel sources, read the instructions to find out which defconfig to use.
122
123
Since manufacturers usually don't release the git history along with the files, you'll need to recreate a git repo:
124
* Clone the mainline kernel in the same version as the Makefile from the sources you just obtained
125
* Remove the cloned files *except the .git directory*
126
* Move the manufacturer kernel tree at the place of the files you just removed
127
* Add all the files in git (@git add -A@) and commit (@git commit@) with a message explaining what you just imported (e.g. "GT-I9000 GB Opensource Update 2")
128
129
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@).
130
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@.
131
132
h3. In case of a prebuilt kernel
133
134 6 Wolfgang Wiedmeyer
Some devices may still use a prebuilt kernel.
135
136 1 Wolfgang Wiedmeyer
For such devices, you will need to remove the prebuilt binaries and the instructions to copy the prebuilt kernel and its modules.
137
138
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).
139
Remove the instructions to copy these prebuilts on the makefiles. Remove instructions such as:
140
<pre>
141
PRODUCT_COPY_FILES += \
142
    $(LOCAL_KERNEL):kernel
143
144
LOCAL_KERNEL := $(LOCAL_PATH)/kernel
145
</pre>
146
and anything regarding @TARGET_PREBUILT_KERNEL@ as well as the instructions to copy the prebuilt modules.
147
148
The @BoardConfig.mk@ (or @BoardConfigCommon.mk@ in the common directory for your device) will most likely hold a line like:
149
<pre>
150
TARGET_PREBUILT_KERNEL := device/samsung/p5/kernel
151
</pre>
152
you must remove this line.
153
154
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:
155
<pre>
156
TARGET_KERNEL_SOURCE := kernel/samsung/p3
157
TARGET_KERNEL_CONFIG := samsung_p5_defconfig
158
</pre>
159
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).
160
161
h3. Building the correct kernel image format
162
163
There are different types of kernel images:
164
* Android image: that is a zImage, without a separate initramfs
165
* zImage: that is a zImage, with a built-in initramfs
166
* uImage: that is an image for the u-boot bootloader, with a built-in initramfs
167
168
You need to find out which type of kernel image your device uses. Asking people who know about that is the best idea.
169
170
h4. Android image
171
172
This is the easiest case to handle: just make sure the @CONFIG_INITRAMFS_SOURCE@ option in the kernel defonfig is left blank or undefined:
173
<pre>
174
CONFIG_INITRAMFS_SOURCE=""
175
</pre>
176
177
h4. zImage with built-in initramfs
178
179
Building a zImage with a built-in initramfs requires the following steps:
180
In the kernel defconfig, define the @CONFIG_INITRAMFS_SOURCE@ option this way:
181
<pre>
182
CONFIG_INITRAMFS_SOURCE="../../root"
183
</pre>
184
185
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:
186
<pre>
187
CONFIG_INITRAMFS_SOURCE="../../recovery/root"
188
</pre>
189
190
Back to the device repository, edit the @BoardConfig.mk@ file and add the following line:
191
<pre>
192
TARGET_KERNEL_RECOVERY_CONFIG := samsung_p5_recovery_defconfig
193
</pre>
194
and make sure to replace the defconfig by the appropriate defconfig you just cloned (the one with the @_recovery_defconfig@ ending).
195
196
Still in the device repository, create a @bootimg.mk@ file containing the following:
197
<pre>
198
LOCAL_PATH := $(call my-dir)
199
200
$(INSTALLED_BOOTIMAGE_TARGET): $(INSTALLED_KERNEL_TARGET)
201
	$(ACP) $(INSTALLED_KERNEL_TARGET) $@
202
203
$(INSTALLED_RECOVERYIMAGE_TARGET): $(INSTALLED_RECOVERY_KERNEL_TARGET)
204
	$(ACP) $(INSTALLED_RECOVERY_KERNEL_TARGET) $@
205
</pre>
206
207
Edit the @BoardConfig.mk@ file and add the following line:
208
<pre>
209
BOARD_CUSTOM_BOOTIMG_MK := device/vendor/device/bootimg.mk
210
</pre>
211 6 Wolfgang Wiedmeyer
and make sure to replace @device/vendor/device/@ with the correct path to your device's repository.
212 1 Wolfgang Wiedmeyer
213
h4. uImage with built-in initramfs
214
215
Follow the previous instructions (*zImage with built-in initramfs*) and set the @BOARD_USES_UBOOT@ variable in the @BoardConfig.mk@ file:
216
<pre>
217
BOARD_USES_UBOOT := true
218
</pre>
219
220
221
h2. Setting up the build environment
222
223
Now that the repos are cloned, you need to modify some makefiles to cope with Replicant paths.
224 7 Wolfgang Wiedmeyer
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).
225 1 Wolfgang Wiedmeyer
226 7 Wolfgang Wiedmeyer
Now that your device files are ready, you can declare a new build target: these are held in @vendor/replicant/targets@.
227
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@).
228 1 Wolfgang Wiedmeyer
229 15 Wolfgang Wiedmeyer
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.
230
231
First, the toolchain needs to be built:
232
<pre>
233
./vendor/replicant/build-toolchain
234
</pre>
235
236
*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.*
237
238
To check for errors or missed occurrences in your device config, start a terminal in the Replicant tree root and lunch:
239 1 Wolfgang Wiedmeyer
<pre>
240 7 Wolfgang Wiedmeyer
. build/envsetup.sh
241
lunch replicant_device-userdebug
242 1 Wolfgang Wiedmeyer
</pre>
243
244 7 Wolfgang Wiedmeyer
Adapt replicant_device-userdebug from what you added to the @targets@ (e.g. @replicant_maguro-userdebug@).
245 1 Wolfgang Wiedmeyer
If an error occurs, it will explicitly report it and you'll need to fix it before doing anything.
246
If everything works correctly, you should see something like:
247
<pre>
248
============================================
249
PLATFORM_VERSION_CODENAME=REL
250 7 Wolfgang Wiedmeyer
PLATFORM_VERSION=6.0.1
251
REPLICANT_VERSION="replicant-6.0"
252
TARGET_PRODUCT=replicant_n7100
253
TARGET_BUILD_VARIANT=userdebug
254 1 Wolfgang Wiedmeyer
TARGET_BUILD_TYPE=release
255
TARGET_BUILD_APPS=
256
TARGET_ARCH=arm
257 7 Wolfgang Wiedmeyer
TARGET_ARCH_VARIANT=armv7-a-neon
258
TARGET_CPU_VARIANT=cortex-a9
259
TARGET_2ND_ARCH=
260
TARGET_2ND_ARCH_VARIANT=
261
TARGET_2ND_CPU_VARIANT=
262
HOST_ARCH=x86_64
263 1 Wolfgang Wiedmeyer
HOST_OS=linux
264 7 Wolfgang Wiedmeyer
HOST_OS_EXTRA=Linux-4.9.0-2-grsec-amd64-x86_64-with-debian-9.0
265 1 Wolfgang Wiedmeyer
HOST_BUILD_TYPE=release
266 7 Wolfgang Wiedmeyer
BUILD_ID=MOB31K
267
OUT_DIR=/home/wolfi/replicant/6.0-romsrc-official/out
268
WITH_SU=true
269 1 Wolfgang Wiedmeyer
============================================
270
</pre>
271
272 7 Wolfgang Wiedmeyer
This is the output for the Galaxy Note 2 (n7100).
273
274 1 Wolfgang Wiedmeyer
*You must repeat these steps everytime before building anything on a freshly-opened terminal.*
275
Remember:
276
<pre>
277 7 Wolfgang Wiedmeyer
. build/envsetup.sh
278
lunch replicant_device-userdebug
279 1 Wolfgang Wiedmeyer
</pre>
280 7 Wolfgang Wiedmeyer
281
(Make sure to replace device by your device's product name)
282 1 Wolfgang Wiedmeyer
283
h2. Building a recovery image
284
285
Now that everything is set-up, you can build the first image to test on your device: the recovery image.
286
287
The build target is *recoveryimage*, so all you have to do is:
288
<pre>
289 8 Wolfgang Wiedmeyer
mka -j9 recoveryimage
290 1 Wolfgang Wiedmeyer
</pre>
291
292
This should trigger the kernel build and the recovery initramfs build and in the end, produce the @out/target/product/device/recovery.img@ file.
293 8 Wolfgang Wiedmeyer
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.
294 1 Wolfgang Wiedmeyer
295
There is usually also a key combination to hold to boot directly to recovery: hopefully, your recovery image will start.
296
297
h2. Building the system
298
299 8 Wolfgang Wiedmeyer
It is time to build a complete set of Replicant images. This includes the system and kernel images.
300 1 Wolfgang Wiedmeyer
301
h3. Building the kernel
302
303
Let's start by building the boot image, that is both the kernel and the Android initramfs. The build target is *bootimage*:
304
<pre>
305 8 Wolfgang Wiedmeyer
mka -j9 bootimage
306 1 Wolfgang Wiedmeyer
</pre>
307
308
In the end, the @out/target/product/device/boot.img@ file will be produced.
309
310
h3. Building the system image
311
312
Building the system is the longest task. The build target is *systemimage*:
313
<pre>
314 8 Wolfgang Wiedmeyer
mka -j9 systemimage
315 1 Wolfgang Wiedmeyer
</pre>
316
317
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.
318
For instance, the following error:
319
<pre>
320
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.
321
</pre>
322
Was solved by turning @BOARD_USE_SECTVOUT@ to false:
323
<pre>
324
BOARD_USE_SECTVOUT := false
325
</pre>
326
327 14 Wolfgang Wiedmeyer
h3. Installation
328 1 Wolfgang Wiedmeyer
329 14 Wolfgang Wiedmeyer
When all the images are built, you're ready to install your Replicant build to the device. Create a flashable zip:
330
<pre>
331
make -j9 bacon
332
</pre>
333
334
The final zip is located at @out/target/product/device/replicant-6.0.zip@
335
336
There are several ways to install the zip in the recovery:
337
* Copying the zip to a microSD card and installing from the microSD card
338
* Copying the zip to the internal storage and installing from the internal storage
339
* Using @adb sideload@ to sideload the zip from your PC (most convenient way for development)
340
341
Make sure to do a factory reset before rebooting.
342
343
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.
344 1 Wolfgang Wiedmeyer
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.
345 14 Wolfgang Wiedmeyer
346
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.
347
348
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.
349 1 Wolfgang Wiedmeyer
350
h2. Android development tips
351
352
Keep in mind that all the make (and such) commands must be run in a terminal where *lunch* has been executed before.
353
354
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):
355
<pre>
356
make module
357
</pre>
358
359 9 Wolfgang Wiedmeyer
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).
360 1 Wolfgang Wiedmeyer
361
Moreover, instead of rebooting, you can kill the Android applications (@zygote@, @surfaceflinger@, @rild@) depending on what you are working on.
362
For instance for audio:
363
<pre>
364
adb shell killall zygote
365
</pre>
366
For graphics:
367
<pre>
368
adb shell killall surfaceflinger
369
</pre>
370
For the RIL:
371
<pre>
372
adb shell killall rild
373
</pre>
374
375
Be sure to always look what's going on in logs.
376
For the main buffer:
377
<pre>
378
adb logcat
379
</pre>
380 9 Wolfgang Wiedmeyer
381 1 Wolfgang Wiedmeyer
For the radio (RIL) buffer:
382
<pre>
383
adb logcat -b radio
384
</pre>
385
386 16 Wolfgang Wiedmeyer
See [[BuildTips]] for more tips.
387
388 1 Wolfgang Wiedmeyer
h2. Graphics
389
390 9 Wolfgang Wiedmeyer
Once Replicant booted on the phone, it's time to get graphics working. Several components are involved with graphics on Android:
391 1 Wolfgang Wiedmeyer
* *gralloc*: the graphical memory allocator, also handles the framebuffer
392
* *hwcomposer*: handles things like overlays and 2D blits to offload OpenGL
393
* *libEGL*: the OpenGL implementation (that's what uses the GPU to accelerate graphics)
394
395 9 Wolfgang Wiedmeyer
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.
396 1 Wolfgang Wiedmeyer
397 9 Wolfgang Wiedmeyer
To have a fluid-enough experience, you need to disable most hardware-accelerated features of Android and enable Software GL.
398
In @BoardConfig.mk@ (or @BoardConfigCommon.mk@ in the common directory for your device), you may find the following lines:
399 1 Wolfgang Wiedmeyer
<pre>
400 9 Wolfgang Wiedmeyer
USE_OPENGL_RENDERER := true
401
BOARD_EGL_NEEDS_HANDLE_VALUE := true
402
TARGET_REQUIRES_SYNCHRONOUS_SETSURFACE := true
403 1 Wolfgang Wiedmeyer
</pre>
404
405 9 Wolfgang Wiedmeyer
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.
406
407
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):
408 1 Wolfgang Wiedmeyer
<pre>
409 9 Wolfgang Wiedmeyer
BOARD_GPU_DRIVERS := swrast
410 1 Wolfgang Wiedmeyer
</pre>
411
412
h2. Audio
413
414 9 Wolfgang Wiedmeyer
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:
415 1 Wolfgang Wiedmeyer
* Audio is standard ALSA
416
* Audio is ALSA with a non-standard interface aside
417
* Audio is not ALSA but something else that is not standard
418
419
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.
420
421 9 Wolfgang Wiedmeyer
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.
422 1 Wolfgang Wiedmeyer
423 9 Wolfgang Wiedmeyer
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.
424 1 Wolfgang Wiedmeyer
425
Remember to add the working audio module to the build targets (on the makefiles in the device repo).
426
427
h2. Modem
428
429
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.
430
431
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:
432 9 Wolfgang Wiedmeyer
* The protocol is AT, which is the only standard protocol, but it is very old: it is mostly plain ASCII and newer modems usually use a binary protocol
433 1 Wolfgang Wiedmeyer
* The protocol is not standard (vendor-specific) but has been implemented in free software already
434
* The protocol is not standard and has no known free software implementation
435
436 9 Wolfgang Wiedmeyer
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).
437
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.
438 1 Wolfgang Wiedmeyer
439 9 Wolfgang Wiedmeyer
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.
440 1 Wolfgang Wiedmeyer
441 9 Wolfgang Wiedmeyer
If the protocol is not AT, it might still be supported: the "FreeSmartphone.Org":http://www.freesmartphone.org/ (FSO) project implements some undocumented protocols. You can also look at "oFono":https://01.org/ofono.
442 1 Wolfgang Wiedmeyer
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.
443
444 9 Wolfgang Wiedmeyer
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.
445 1 Wolfgang Wiedmeyer
446
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).
447
448
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.
449
450
h2. Sensors
451
452
When adding support for sensors, look at exactly what you will need to replace. There are several possible scenarios:
453 9 Wolfgang Wiedmeyer
* A *complete* free sensors module is already available for your device on the tree from LineageOS
454 1 Wolfgang Wiedmeyer
* An incomplete free sensors module is there and it requires a non-free library to fully work
455
* The sensors module is non-free
456
457
Note that sensors may require daemons aside, such as @orientationd@, @geomagneticd@, etc. You will most likely need to replace these as well.
458
459 10 Wolfgang Wiedmeyer
If the implementation is incomplete, you will have to write a replacement for the non-free library that is used.
460 1 Wolfgang Wiedmeyer
461
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.
462 17 Wolfgang Wiedmeyer
For instance, here is a reference commit of the "SMDK4x12 Sensors module":https://git.replicant.us/replicant/device_samsung_i9300/commit/?id=da6fcf71764f46b965ede87795cfbe818a03103f that you may reuse.
463 1 Wolfgang Wiedmeyer
464
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.
465
466
h3. Figuring out the magic in sensors
467
468
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.
469
470
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.
471
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.
472
473
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):
474
<pre>
475
f(x)=0,0095768072 * x 
476
</pre>
477
478
Once you have this, you may want to find out where that value comes from. In that case, we can see that:
479
<pre>
480
0,0095768072 = 9.80665 / 1024
481
</pre>
482
With @9.80665@ being the standard gravity on Earth. Hence, we have:
483
<pre>
484
f(x)=x * GRAVITY_EARTH / 1024
485
</pre>
486
We can guess that 1024 is the resolution of the ADC that provides the sensor value.
487
488
Once you have this equation figured out, you're ready to implement this in your free sensors module!
489
490
h2. Camera
491
492 10 Wolfgang Wiedmeyer
When adding support for the camera, you need to look at what is already there in LineageOS:
493 1 Wolfgang Wiedmeyer
* A camera library with full support is there
494
* A camera wrapper is there but needs a non-free library
495
* A non-free library is used directly
496
497 17 Wolfgang Wiedmeyer
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":https://git.replicant.us/replicant/device_samsung_crespo/commit/?id=63f28807de5f73597605fc80a0fcddae23eca833
498 10 Wolfgang Wiedmeyer
We cannot use YUV formats directly because the Android software EGL implementation used in Replicant does not support it.
499 1 Wolfgang Wiedmeyer
500 10 Wolfgang Wiedmeyer
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:
501 1 Wolfgang Wiedmeyer
* The camera is accessed through V4L2, with custom controls and procedure
502
* The camera is accessed through a non-standard interface
503
504 10 Wolfgang Wiedmeyer
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.
505 1 Wolfgang Wiedmeyer
506 17 Wolfgang Wiedmeyer
Here is a reference commit of the "SMDK4x12 Camera module":https://git.replicant.us/replicant/device_samsung_smdk4412-common/commit/?id=69c02aeec2adcecb87123745527d984586f4e0d0 that uses the Samsung FIMC engine. While it uses V4L2, it needs a custom procedure and custom controls to work properly.
507 1 Wolfgang Wiedmeyer
508
*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.
509
510
h2. Dealing with loaded firmwares
511
512 10 Wolfgang Wiedmeyer
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.
513 1 Wolfgang Wiedmeyer
514
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.
515
516
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).
517
518 10 Wolfgang Wiedmeyer
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 [[DeveloperGuide#New-device-documentation|Developer guide]].
519 1 Wolfgang Wiedmeyer
520
h3. Dealing with the kernel firmwares
521
522
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.
523 17 Wolfgang Wiedmeyer
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 ":https://git.replicant.us/replicant/kernel_samsung_crespo/commit/?id=cba337496d289d4eae494315737d1ce63d1ff30a
524 1 Wolfgang Wiedmeyer
525
h2. Software media decoding
526
527 10 Wolfgang Wiedmeyer
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).
528 1 Wolfgang Wiedmeyer
529 17 Wolfgang Wiedmeyer
For reference, here is the commit that removes hardware media decoding on Nexus S (crespo): "Disable hardware video encoding/decoding ":https://git.replicant.us/replicant/device_samsung_crespo/commit/?id=d622b9005abd60c3af906948b9e4fb77adf104dd
530 1 Wolfgang Wiedmeyer
531
h2. Bottomline
532
533
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!
534
535
h2. Pushing your work to Replicant repositories
536
537
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. 
538
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.
539
540
The [[DeveloperGuide#Repositories|Developer guide]] hold all the rules for naming repositories: make sure to act accordingly with these requirements!
541
542
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.
543
544
h2. Adding documentation about your device
545
546
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!
547
548 10 Wolfgang Wiedmeyer
The process is described in the [[DeveloperGuide#New-device-documentation|Developer guide]].