Skip to content

Commit

Permalink
content: more wording and punctuation improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
@Bettehem
Bettehem committed Dec 30, 2023
1 parent 17c43bb commit 6cdca60
Show file tree
Hide file tree
Showing 4 changed files with 65 additions and 67 deletions.
2 changes: 1 addition & 1 deletion content/faq/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ draft: false

<div class="white-text">
<h3>What is Droidian?</h3>
<p>Droidian is a Debian-based distribution for mobile devices. The goal of Droidian is to be able to run Debian on Android phones.This is accomplished by using well-known technologies such as libhybris and <a href="https://halium.org/">Halium</a>.</p>
<p>Droidian is a Debian-based distribution for mobile devices. The goal of Droidian is to be able to run Debian on Android phones. This is accomplished by using well-known technologies such as libhybris and <a href="https://halium.org/">Halium</a>.</p>
</div>
<br><br>

Expand Down
2 changes: 1 addition & 1 deletion content/info/ssh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,4 @@ You can also connect over WiFi:

ssh droidian@192.168.1.28

Replace 192.168.1.28 with phones ip address
Replace 192.168.1.28 with phone's ip address.
94 changes: 46 additions & 48 deletions content/porting-guide/kernel-compilation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Summary

The stock Android kernel is unfortunately not enough to be able to run Droidian.

The good news is that, on GSI-capable devices, often only kernel changes are necessary.
The good news is, that on GSI-capable devices, often only kernel changes are necessary.

Table of contents
-----------------
Expand All @@ -26,22 +26,22 @@ Table of contents
Summary
-------

Droidian runs on [halium](https://halium.org).
If your device is launched with Android 9 or above it is possible to port Droidian to it.
If it already has a halium-compliant kernel of halium-9.0 and above chances are that Droidian will work without much modification.
Droidian runs on [Halium](https://halium.org).
If your device was launched with Android 9 or above, it is possible to port Droidian to it.
If it already has a halium-compliant kernel (halium-9.0 and above), chances are, that Droidian will work without much modification.

If your device has shipped with Android 8.1 or 9, it probably is GSI (Generic System Image) capable, and such it's possible to use an already available, generic Android System Image with Halium patches applied.
This will reduce the amount of work the porter has to do significantly.
If your device has shipped with Android 8.1 or 9, it probably is GSI (Generic System Image) capable, and as such it's possible to use an already available, generic Android System Image with Halium patches applied.
This will reduce the amount of work the porter has to do by a significant amount.

If your device doesn't support GSI, you'll also need to compile a patched system image.
If your device doesn't support GSIs, you'll also need to compile a patched system image.
The documentation for image creation can be found in [this guide](./image-creation.md)

On Halium, the Android kernel is built via the standard Android toolchain.
While this makes sense, on GSI-capable devices this can be a waste of time since often only kernel changes are required.
While this makes sense, on GSI-capable devices, this can be a waste of time, since often only kernel changes are required.

Thus, Droidian uses a different approach to compile kernels - the upside is that you get packaging for free so that kernels can be upgraded over-the-air via APT, if you wish so.

Note that this guide assumes that you're going to cross-compile an arm64
Note: This guide assumes that you're going to cross-compile an arm64
Android kernel on an x86_64 (amd64) machine using the Android-supplied
precompiled toolchain that's available in the Droidian repositories.
It's trivial to disable cross-compiling and compiling using the standard
Expand All @@ -58,7 +58,7 @@ Prerequisites
* A Halium-compliant kernel defconfig
* Docker

If you do not have a Halium-compliant kernel yet you should modify your kernel's configuration as suggested in [Kernel adaptation](#kernel-adaptation) later in the guide.
If you do not have a Halium-compliant kernel yet, you should modify your kernel's configuration as suggested in [Kernel adaptation](#kernel-adaptation), which can be found later in this guide.

Package bring-up
----------------
Expand All @@ -68,7 +68,7 @@ you should create a new branch to house the Debian packaging.

We're also assuming that you want the resulting packages in `~/droidian/packages`.

Droidian tooling expects the kernel source to have a working git directory structure (be a kernel cloned from a git repository).
Droidian tooling expects the kernel source to have a working git directory structure (has to be a kernel cloned from a git repository).

(host)$ KERNEL_DIR="$HOME/droidian/kernel/vendor/device"
(host)$ PACKAGES_DIR="$HOME/droidian/packages"
Expand All @@ -80,7 +80,7 @@ Now it's time to fire up the Docker container.

(host)$ docker run --rm -v $PACKAGES_DIR:/buildd -v $KERNEL_DIR:/buildd/sources -it quay.io/droidian/build-essential:trixie-amd64 bash

Inside the Docker container, install the `linux-packaging-snippets`, that
Inside the Docker container, install the `linux-packaging-snippets`, which
provides the example `kernel-info.mk` file.

(docker)# apt-get install linux-packaging-snippets
Expand Down Expand Up @@ -108,24 +108,24 @@ Most of the defaults are enough for building Android kernels with the Pie
toolchain, so you'll probably need to change device-specific settings (such
as vendor, name, cmdline, defconfig and the various offsets).

by unpacking an already built `boot.img` using unpackbootimg all the offsets can be found.
By unpacking an already built `boot.img` using unpackbootimg, all the offsets can be found.

Kernel info options
-------------------

unpackbootimg syntax goes as follows
unpackbootimg syntax goes as follows:

(docker)# unpackbootimg --boot_img boot.img

or for the AOSP version of unpackbootimg
or for the AOSP version of unpackbootimg:

(docker)# unpackbootimg -i boot.img

### kernel-info.mk entries

* `KERNEL_BASE_VERSION` is the kernel version which can be viewed in Makefile at the root of your kernel source.
* `KERNEL_BASE_VERSION` is the kernel version which can be viewed in the Makefile at the root of your kernel source tree.

As an example
As an example:

```
VERSION = 4
Expand All @@ -137,19 +137,19 @@ will be 4.14.221

* `KERNEL_DEFCONFIG` is the defconfig filename found at arch/YOURARCH/configs

* `KERNEL_IMAGE_WITH_DTB` determines whether or not to include a dtb file in the kernel. if this option is set `KERNEL_IMAGE_DTB` also needs to be set. if not an attempt to find it will occur.
* `KERNEL_IMAGE_WITH_DTB` determines whether or not to include a dtb file in the kernel. If this option is set, `KERNEL_IMAGE_DTB` also needs to be set. If it is not set, an attempt to find it will occur.

* `KERNEL_IMAGE_DTB` is the path to the dtb file which can be found in arch/YOURARCH/boot/dts/SOC/
* `KERNEL_IMAGE_DTB` is the path to the dtb file, which can be found in arch/YOURARCH/boot/dts/SOC/

* `KERNEL_IMAGE_WITH_DTB_OVERLAY` determines whether or not to build a dtbo file. if this option is set `KERNEL_IMAGE_DTB_OVERLAY` also needs to be set. if not an attempt to find it will occur.
* `KERNEL_IMAGE_WITH_DTB_OVERLAY` determines whether or not to build a dtbo file. If this option is set, `KERNEL_IMAGE_DTB_OVERLAY` also needs to be set. If it is not set, an attempt to find it will occur.

* `KERNEL_IMAGE_DTB_OVERLAY` is the path to the dtbo file which can be found in arch/YOURARCH/boot/dts/SOC/
* `KERNEL_IMAGE_DTB_OVERLAY` is the path to the dtbo file, which can be found in arch/YOURARCH/boot/dts/SOC/

* `KERNEL_PREBUILT_DT` is available for devices with a prebuilt DT image (such as samsungs) and takes a path in the kernel tree.
* `KERNEL_PREBUILT_DT` is available for devices with a prebuilt DT image (such as Samsungs) and takes a path in the kernel tree.

All these values can be viewed by extracting a boot image with unpackbootimg
All the following KERNEL_BOOTIMAGE values can be found by extracting an existing boot image (boot.img) with unpackbootimg.

* `KERNEL_BOOTIMAGE_CMDLINE` corresponds to "command line args" or "BOARD_KERNEL_CMDLINE" `console=tty0` and `droidian.lvm.prefer` should be appended to the cmdline. Make sure to remove any `systempart` entry from cmdline.
* `KERNEL_BOOTIMAGE_CMDLINE` corresponds to "command line args" or "BOARD_KERNEL_CMDLINE". The options `console=tty0` and `droidian.lvm.prefer` should be appended to the cmdline. Make sure to remove any `systempart` entry from cmdline.

* `KERNEL_BOOTIMAGE_PAGE_SIZE` corresponds to "page size" or "BOARD_PAGE_SIZE"

Expand All @@ -165,13 +165,13 @@ All these values can be viewed by extracting a boot image with unpackbootimg

* `KERNEL_BOOTIMAGE_DTB_OFFSET` corresponds to "dtb address" or "BOARD_DTB_OFFSET"

Although this option is only required for kernel header version 2. it can be commented otherwise.
This option is only required for kernel header version 2. It can be commented otherwise.

* `KERNEL_BOOTIMAGE_VERSION` correlates to the kernel header version. Devices launched with Android 8 and lower are 0, Android 9 is 1, Android 10 is 2 and Android 11 is 2 and GKI devices are 3.

* For Samsung devices `DEVICE_VBMETA_IS_SAMSUNG` must be set to 1.
* For Samsung devices, `DEVICE_VBMETA_IS_SAMSUNG` must be set to 1.

* `BUILD_CC` for most devices launched with Android 9 and above is clang but if your kernel fails to build with `clang` you might try changing the value to `aarch64-linux-android-gcc-4.9` to build with gcc.
* `BUILD_CC` for most devices launched with Android 9 and above is `clang`, but if your kernel fails to build with `clang` you might try changing the value to `aarch64-linux-android-gcc-4.9` to build with gcc.

* If your device requires a toolchain which is not included in the buildsystem, you can manually download the toolchain and add the path to `BUILD_PATH`.

Expand Down Expand Up @@ -251,7 +251,7 @@ In case you're on an older device and your kernel does not compile with any of t

To use GCC change `BUILD_CC` to from `clang` to `aarch64-linux-android-gcc-4.9`

Keep in mind that any kernel newer than 4.4 should should compile fine with clang, there are always exceptions.
Keep in mind that any kernel newer than 4.4 should should compile fine with clang, though there are always exceptions.

### Build target

Expand All @@ -269,36 +269,34 @@ You can find which build target is required for your device by looking at the de

In case of any issues with initramfs (as an example unl0kr showing a black screen while encryption is enabled), scripts can be added to the packaging which will be included in the ramdisk.

[This packaging](https://github.com/droidian-devices/linux-android-fxtec-pro1x/blob/droidian/debian/initramfs-overlay/scripts/halium-hooks) can be taken as a reference.
[This packaging](https://github.com/droidian-devices/linux-android-fxtec-pro1x/blob/droidian/debian/initramfs-overlay/scripts/halium-hooks) can be used as a reference.

The following adds a function which will run in the initramfs on boot.
The mentioned example adds a function which will run in the initramfs on boot.

Any command that will aid the system in booting can be added to the script.

### build rules

On builds failing after the kernel compilation stage (during packaging), errors can be ignored.

build sequence can be altered with `override_dh_sequence` (make sure to replace sequence with your own sequence)
Build sequence can be altered with `override_dh_sequence` (make sure to replace sequence with your own sequence)

As as example
For example, this can be added to the end of `debian/rules`:

```
override_dh_dwz:
override_dh_strip:
override_dh_makeshlibs:
```

can be added to the end of `debian/rules`.

It is recommended to come back and fix the build errors later on instead of ignoring them as they might cause various issues in the future.
It is recommended to come back and fix the build errors later on instead of ignoring them, as they might cause various issues in the future.

Kernel adaptation
-----------------

As a bare minimum these options need to be enabled in your defconfig
As a bare minimum, the following options need to be enabled in your defconfig

Some of these options might not be available to you depending on your kernel version, they can be safely ignored.
Some of these options might not be available to you depending on your kernel version. Unavailable options can be safely ignored.

```
CONFIG_DEVTMPFS=y
Expand All @@ -314,7 +312,7 @@ CONFIG_ANDROID_PARANOID_NETWORK=n
CONFIG_ANDROID_BINDERFS=n
```

Usually `CONFIG_NAMESPACES` enables all the namespace options but if it did not, all these options should be added
Usually `CONFIG_NAMESPACES` enables all the namespace options, but if it did not, all these options should be added:

```
CONFIG_SYSVIPC=y
Expand All @@ -325,7 +323,7 @@ CONFIG_UTS_NS=y

Later on for other components, various options should be enabled after the initial boot is done successfully.

For Bluetooth these options are required
For Bluetooth these options are required:

```
CONFIG_BT=y
Expand All @@ -338,7 +336,7 @@ CONFIG_BT_BNEP_PROTO_FILTER=y
CONFIG_BT_HCIVHCI=y
```

For Waydroid
For Waydroid:

```
CONFIG_SW_SYNC_USER=y
Expand All @@ -349,7 +347,7 @@ CONFIG_NETFILTER_XT_TARGET_CHECKSUM=y
CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder,anbox-binder,anbox-hwbinder,anbox-vndbinder"
```

For Plymouth (boot animation)
For Plymouth (boot animation):

```
# CONFIG_FB_SYS_FILLRECT is not set
Expand All @@ -359,7 +357,7 @@ For Plymouth (boot animation)
# CONFIG_FB_VIRTUAL is not set
```

To ease debugging, pstore can be enabled to get logs on each boot
To ease debugging, pstore can be enabled to get logs on each boot:

```
CONFIG_PSTORE=y
Expand All @@ -370,23 +368,23 @@ CONFIG_PSTORE_RAM_ANNOTATION_APPEND=y

If you have pstore enabled, you might find clues in `/sys/fs/pstore` from your recovery.

You can use menuconfig to make sure all the options are enabled with all their dependencies.
You can use menuconfig to make sure all the options are enabled with all their dependencies:

(docker)# mkdir -p out/KERNEL_OBJ && make ARCH=arm64 O=out/KERNEL_OBJ/ your_defconfig && make ARCH=arm64 O=out/KERNEL_OBJ/ menuconfig

After modifying your defconfig, copy `out/KERNEL_OBJ/.config` to `arch/YOURARCH/configs/your_defconfig`.

As an alternative, `KERNEL_CONFIG_USE_FRAGMENTS = 1` can be set in `kernel-info.mk` to include defconfig fragments inside your defconfig on build time.

defconfig fragments should be placed in the root of the kernel source in a directory called droidian. [this source](https://github.com/droidian-devices/linux-android-fxtec-pro1x/tree/droidian/droidian) can be taken as a reference.
The defconfig fragments should be placed in the root of the kernel source in a directory called droidian. [This source](https://github.com/droidian-devices/linux-android-fxtec-pro1x/tree/droidian/droidian) can be used as a reference.

`KERNEL_CONFIG_USE_DIFFCONFIG` can be enabled to use the python script `diffconfig` to compare fragments and the main defconfig.
`KERNEL_CONFIG_USE_DIFFCONFIG` can be enabled in `kernel-info.mk` to use the python script `diffconfig` to compare fragments and the main defconfig.

to use diffconfig a diff file should be provided like so
To use diffconfig, a diff file should be provided like this:

`KERNEL_PRODUCT_DIFFCONFIG = diff_file`

If LXC fails to start you can use `lxc-checkconfig` after device first booted to check for other options that might be needed.
If LXC fails to start you can use the `lxc-checkconfig` command after your device first booted to check for other options that might be needed.

Compiling
---------
Expand All @@ -412,7 +410,7 @@ DTB/DTBO compilation failure

In case of DTB/DTBO compilation failure it is a good idea to try using an external dtc compiler instead of the one presend in the kernel tree.

To do so after building the control file, add `device-tree-compiler` to Build-Depends then and in `debian/rules` after the include line add
To do so after building the control file, add `device-tree-compiler` to Build-Depends then and in `debian/rules` after the include line add this:

`BUILD_COMMAND := $(BUILD_COMMAND) DTC_EXT=/usr/bin/dtc`

Expand Down
Loading

0 comments on commit 6cdca60

Please sign in to comment.