Port Guide

This guide describes roughly how to bring-up a new device for AXP.OS.

Requirements

New devices must match with the Device Requirements

Device

AXP.OS manifest

add all device, common, firmware etc in: https://github.com/AXP-OS/manifest

Prepare your device trees

include AXP.OS

add the following into any the device’s <device>.mk:

# enable AXP.OS vendor
$(call inherit-product, vendor/axp/config/common.mk)

fix your proprietary-files.txt

ensure you have a proper defined proprietary-files.txt in all your device trees as these are used by the Divest patcher.

if you never had updated that file (as this is nothing you actually need for other custom OS’) and you are sure that your vendor/<vendor-name>/<device>/<device>-vendor.mk is set up correctly you can generate this file like this.

remove extendrom inclusions

Check that you have no extendrom inclusions anywhere. E.g. search for it like:

grep -r "extendrom" device/

AXP.OS includes extendrom by default so this would conflict with any manual inclusions.

extract and push vendor/firmware

1. extract the latest vendor OTA (e.g. by ROME) for ZIPs or SALT for KDZ’s. Example sources where you can find those are:
   • NOTE1: ensure you select a trusted source, I cannot guarantee that the following are trusted though!
   • NOTE2: ensure you choose the latest “global” one (i.e. never provider specific ones) for the supported Android version (which is reflected by the device tree branch name)
   • OnePlus: e.g. on XDA
   • Google Pixel: here
   • LG: e.g. here or here
   • Samsung: e.g. here or here
   • use www.google.com to find more/better ones!
2. ensure you have access to the vendor_firmware repo. it is not public but you will be able to access it once you have registered and logged in!
3. add all required (which highly depends on the device) firmware files (bootloader + firmware / modem) to LFS:
   • cd vendor/firmware/<model>
   • git lfs install (this is a one-time thing per user)
   • git lfs track "*.img"
   • git add .gitattributes
   • git add *.img
4. copy Android.mk, AndroidBoardVendor.mk and 0SOURCE from any of the existing ones (e.g. hotdog)
5. adjust all files according to the device and img files you extracted and add the exact OTA identifier to 0SOURCE

create an engineering build

1. set axp_build_eng = true , e.g. in your semaphore environment
2. build as usual and fix all issues ;)

keep in mind that official devices must be enforcing, so you need to solve all needed denials correctly (i.e. not opening too much or the wrong way, see here for a rough guide).

find permission denials

To find missing permissions when bringing up a new device, enable transitional log mode:

ro.control_privapp_permissions=log

source and details: here

Set/Upgrade device encryption

See Device Encryption

Kernel patching

Devices which are not supported by DivestOS must follow some extra steps to get the kernel patched as well:

generate & test kernel patches

1. get latest CVE patcher:
   wget "http-URL-to-cve_patcher.jar" -O cve_patcher.jar
2. find your kernel version in ../../Scripts/Common/Fix_CVE_Patchers.sh and add kernel_<vendor>_<device>.sh to the #Loose versioning hacks section
3. create a kernel specific CVE patcher script (& applying the result):
   startPatcher kernel_<vendor>_<device>
4. mka bootimage
5. if it does not compile find the corresponding apply line in ../../Scripts/LineageOS-<VERSION>/CVE_Patchers/android_kernel_<vendor>_<device>.sh.
   as this is not straight forward you can make use of this little helper:
   ../../Scripts/cve_find_patch.sh '<SEARCHSTRING>'
   outcomment the resulting line(s) in ../../Scripts/LineageOS-<VERSION>/CVE_Patchers/android_kernel_<vendor>_<device>.sh and write it down (you will need it later)
6. reset your kernel dir:
   repo forall -j6 kernel/<vendor>/<device> -c "git am --abort; git rebase --abort; git reset --hard"
7. apply the patches again:
   bash ../../Scripts/LineageOS-<VERSION>/CVE_Patchers/android_kernel_<vendor>_<device>.sh
8. repeat step 4-7 until it compiles and comment the problematic one out. you need those later!
9. test if it boots
   
   if not:
   
10. edit ../../Scripts/LineageOS-<VERSION>/CVE_Patchers/android_kernel_<vendor>_<device>.sh
11. do a 50%-revert, i.e. out-comment the last 50% of the not (yet) outcommented apply lines in this file
12. reset your kernel dir:
    repo forall -j6 kernel/<vendor>/<device> -c "git am --abort; git rebase --abort; git reset --hard"
13. apply the 50%-reverted patches:
    bash ../../Scripts/LineageOS-<VERSION>/CVE_Patchers/android_kernel_<vendor>_<device>.sh
14. repeat beginning at step 4
15. if it boots though: repeat but in step 8 revert the last 50%-reverted block (i.e. let them apply again. the goal is to identify the patches preventing from boot)

once you have identified ALL problematic apply rule(s):

1. add them to the out-commenter (../../Scripts/Common/Fix_CVE_Patchers.sh):
   commentPatches android_kernel_<vendor>_<device>.sh "XXX" "YYY"
   
2. test if the out-commenter works:
   ~~ CROOT=$PWD cd ../../Scripts/LineageOS-/CVE_Patchers bash /home/androidsource/do-not-touch/axp/Scripts/Common/Fix_CVE_Patchers.sh cd $CROOT ~~ check: ../axp/Scripts/LineageOS-<VERSION>/CVE_Patchers/android_kernel_<vendor>_<device>.sh

troubleshooting kernel patching

• if kernel defconfig can’t be found: add it manually to getDefconfig
• if it does not compile: follow generate & test kernel patches and add exceptions to Fix_CVE_Patchers.sh
• if it does not boot: overwrite the device default CONFIG (e.g. like this)

Build-Process automation

axp / device

1. create a new folder named like the codename of your device in https://github.com/sfX-android/automation_scripts/tree/ansible/roles/axp.
2. copy the content from any of the existing ones into that folder so you have all required variables and stuff there.

Adjust the main device variables file: roles/axp/<device-codename>/vars/main.yml. For sure you want to change these:

• target_model_full
• target_kernel_dir (must match the manifest)
• dtree_cl (must match the manifest)
• cdtree_cl (must match the manifest)
• kernel_cl (must match the manifest)

OPTIONAL: axp / common

the following is needed only when you want to overwrite the global common variables and can be skipped otherwise.

1. create a new template in https://github.com/sfX-android/automation_scripts/tree/ansible/roles/axp/common/templates
2. name it divested.vars.<device-codename>.j2 (e.g. divested.vars.hotdog.j2)
3. copy the content from another device, e.g. from hotdog. Note: it is fully ok if it contains just the comments block as it acts as an override for the defaults only.