Android/SharkBait/Porter Guide

This article is intended for porters who want to add SharkBait support for a device that's not currently supported. In this article, you will be given the general idea on how to adapt parts that are crucial for SharkBait system to work on a device. The following components will be covered:


 * Preinit. repository home
 * SharkBait-setup. repository home
 * Kernel sources. example
 * Kernel headers. example

Preinit
Preinit performs early initialization of the device to load the Gentoo init (OpenRC as of current). The following directory structure is required for a supported device ( as an example here) is as follows:

angler ├── bootimg.cfg ├── initramfs │   ├── init │   └── (other contents in initramfs) └── Makefile
 * defines offsets for kernel and initramfs, as well as kernel commandline options. Porters should adapt what they get when dissecting  for their device and make the following modifications:
 * remove  option so that abootimg does not complain about a boot.img bigger than the original one (though this is unlikely to be the case).
 * add  to the boot commandline to set SELinux to permissive.
 * holds the minimal initramfs that correctly mounts filesystems and  to load Gentoo init.
 * is required. The  init is a shell script that does the necessary jobs, but any executable file should work.
 * Mind the permissions: kernel won't be able to execute an  that's not executable, which would result in a boot failure.
 * enables processing the  programmatically before   packs it up.
 * This will be useful for things like  installation, runtime-specific things, etc.
 * will call  in the device directory (  in the directory hierarchy). Read the example   so that you handle the paths correctly.

SharkBait-setup
SharkBait-setup handles the setup of the Android container. The following directory structure is required for a supported device ( as an example here) is as follows:

angler ├── disable_encryption.sh ├── fstab.android ├── patches │   ├── fstab.angler.patch │   └── (other patches to apply to Android rootfs) └── serial-consoles (if any)
 * is ran on the helper workstation and disables encryption for the partition where the Gentoo root will reside in.
 * For devices that does not support encryption or have the Gentoo root in a partition that's not encrypted, this script should just print a notice and return 0.
 * Warn users about data wipe and wait for 10 seconds for a Ctrl-C!
 * is appended to the Gentoo fstab and contain mountpoints that are necessary for Android.
 * Android's  should not handle any internal mounts any more (external mounts such as OTG or SD card may still be managed by  ); make sure all required mounts are present.
 * It is strongly recommended to mount to  and then bind into the LXC rootfs for ease when accessing the Android partitions and extra security. Refer to the example   file for   to get a better understanding of this.
 * holds patches that will be applied to the real Android rootfs via, extracted from the current boot.img present on the device.
 * Disable all partition mounts in  or equivalent file.
 * Put more patches that are required here, such as patches on  to properly handle cgroups issues introduced by containerization. Refer to   for   for more information on this topic.
 * defines serial consoles that are available on the device, if there is any. This file will be appended to.

Kernel sources
The kernel source package of a device packages the source tree from the vendor. A ebuild for  is required; read the ebuild for for reference. Only the package name, version, and the git repo URL would require adapting; the other parts of the ebuild do not need modification.

The following modifications on the source tree are required for a working kernel:


 * Apply this patch on the tree to enable  function.
 * Supply a valid  with LXC features enabled. See the example for angler and LXC on Gentoo Wiki for reference.
 * Make sure that the kernel compiles and boots correctly with (relatively) new compilers from Gentoo.
 * Regularly merge upstream changes.

Kernel headers
Kernel headers that match the device kernel source ease the process of compiling cross-compile toolchains for Android targets. The ebuild for should be a clear example, with only the need to modify the version number and the git repo URL.

Test the port
Make sure the port boots correctly. You may need a serial console to debug boot failures. Also, check that all the hardware functions work properly (camera, bluetooth, etc.); if that's not the case point it out when submitting a merge request so that we can look into the issue. Happy hacking!