How to port Mobian to new devices (roughly)
This is incomplete and also work in progress, but still available as the question of how Mobian can be ported often comes up.
Overview
Mobian images are built using mobian-recipes.
To build an image, there has to be a kernel that can boot on the target device. Mobian uses a mainline kernel and carries some patches that are being upstreamed, but are not yet in the mainline kernel. Mobian does not package heavily device-specific kernels.
A good indicator that a device can currently boot a Linux kernel is the postmarketOS wiki. If the target device is listed as supported by mainline Linux and has decent support, one may proceed. If not, options are to work on the kernel, wait for support to improve (which can take years or does never happen if nobody does the work) or port to another device.
In the best case (almost never), the target device has support.
The procedure would then be as follows:
- Compile kernel for devices that will not run on an upstream mainline kernel (most)
Add the device to a locally cloned copy of Mobian-recipes https://salsa.debian.org/Mobian-team/mobian-recipes
For example, for adding a Qualcomm-based device, add the appropriate parameters to https://salsa.debian.org/Mobian-team/mobian-recipes/-/blob/master/devices/qcom/configs/wip.toml?ref_type=heads
- If values are not known, it might be helpful to look at postmarketOS, maybe they've already figured that out and the device package has the right info in the "deviceinfo" file.
example for the Pixel 3a: https://gitlab.postmarketos.org/postmarketOS/pmaports/-/blob/master/device/community/device-google-sargo/deviceinfo
- in this example the device model's codename as well as the boot parameters can be found
- add kernel .deb from first step to devices/qcom/packages/
- try to build an SSH-enabled image:
apply the changes shown in https://salsa.debian.org/tiol/mobian-recipes/-/compare/master...wip%2Ftiol%2Fssh?from_project_id=71384 to the local copy of mobian-recipes,
launch ./build.sh -t <device> -s , where <device> can be either qcom-wip or any of the already supported devices' chipset (this latter case applies if the relevant kernel is already available and distributed by Mobian, but the device is missing some feature, e.g. due to missing FW files)
- if the build succeeded, try to flash the image to the device and boot it
once the image boots, try to SSH into it via USB networking
- look at dmesg, make a list of missing firmware files
- mount vendor/firmware partitions and locate the missing firmware files
- process can be different for different generation's devices
- for A/B slot devices, e.g. op6, it can be as simple as (first command is grep-ped on vendor partition for space reasons)
mobian@mobian:~$ ls -lh /dev/disk/by-partlabel/ | grep vendor lrwxrwxrwx 1 root root 11 6 ott 1972 vendor_a -> ../../sdd16 lrwxrwxrwx 1 root root 11 6 ott 1972 vendor_b -> ../../sdd44 mobian@mobian:~$ sudo mkdir -p /media/vendor_a mobian@mobian:~$ sudo mount /dev/sdd16 /media/vendor_a mobian@mobian:~$ ls /media/vendor_a/ app bin bt_firmware build.prop default.prop dsp etc firmware firmware_mnt lib lib64 lost+found odm overlay package radio rfs ueventd.rc mobian@mobian:~$ ls /media/vendor_a/firmware a225p5_pm4.fw a300_pm4.fw a420_pm4.fw a530v1_pfp.fw a530v3_seq.fw2 a630_zap.b00 a630_zap.mdt cppf.b02 cppf.b06 ipa_fws.b01 ipa_fws.elf widevine.b00 widevine.b04 widevine.mdt a225_pfp.fw a330_pfp.fw a530_gpmu.fw2 a530v1_pm4.fw a540_gpmu.fw2 a630_zap.b01 CAMERA_ICP.elf cppf.b03 cppf.b07 ipa_fws.b02 ipa_fws.mdt widevine.b01 widevine.b05 wlan a225_pm4.fw a330_pm4.fw a530_pfp.fw a530v2_seq.fw2 a630_gmu.bin a630_zap.b02 cppf.b00 cppf.b04 cppf.mdt ipa_fws.b03 leia_pfp_470.fw widevine.b02 widevine.b06 a300_pfp.fw a420_pfp.fw a530_pm4.fw a530v3_gpmu.fw2 a630_sqe.fw a630_zap.elf cppf.b01 cppf.b05 ipa_fws.b00 ipa_fws.b04 leia_pm4_470.fw widevine.b03 widevine.b07
- for newer devices with dynamic/super partitions, a few more steps are required, e.g. fairphone-fp4
mobian@mobian:~$ ls -lh /dev/disk/by-partlabel/ | grep super lrwxrwxrwx 1 root root 11 25 lug 1970 super -> ../../sda10 mobian@mobian:~$ sudo make-dynpart-mappings /dev/sda10 [sudo] password di mobian: warn: This looks like metadata for retrofit partitions. Only the first slot is mapped. mobian@mobian:~$ ls /dev/mapper/ control odm_a product_a system_a system_a-cow system_ext_a vendor_a mobian@mobian:~$ sudo mkdir -p /media/vendor_a mobian@mobian:~$ sudo mount -o ro /dev/mapper/vendor_a /media/vendor_a/ mobian@mobian:~$ ls /media/vendor_a/ app bin bt_firmware build.prop default.prop dsp etc firmware firmware_mnt lib lib64 libnfc-nxp_RF.conf lost+found odm overlay radio rfs ueventd.rc mobian@mobian:~$ ls /media/vendor_a/firmware a615_zap.b00 a619_gmu.bin a620_zap.mdt a650_zap.b01 aw8695_osc_rtp_24K_5s.bin aw882xx_spk_reg_r.bin hx_criteria.csv ipa_fws.b04 iris6_ccf3.fw lagoon_ipa_fws.b03 st21nfc_fw.bin widevine.b04 wigig a615_zap.b01 a620_zap.b00 a630_sqe.fw a650_zap.b02 aw882xx_monitor.bin aw882xx_voice_reg_l.bin ipa_fws.b00 ipa_fws.elf iris6.fw lagoon_ipa_fws.b04 widevine.b00 widevine.b05 wlan a615_zap.b02 a620_zap.b01 a650_gmu.bin a650_zap.elf aw882xx_rcv_reg_l.bin aw882xx_voice_reg_r.bin ipa_fws.b01 ipa_fws.mdt lagoon_ipa_fws.b00 lagoon_ipa_fws.elf widevine.b01 widevine.b06 wlanmdsp.otaupdate a615_zap.elf a620_zap.b02 a650_sqe.fw a650_zap.mdt aw882xx_rcv_reg_r.bin CAMERA_ICP.elf ipa_fws.b02 iris6_ccf1.fw lagoon_ipa_fws.b01 lagoon_ipa_fws.mdt widevine.b02 widevine.b07 a615_zap.mdt a620_zap.elf a650_zap.b00 aw8695_haptic.bin aw882xx_spk_reg_l.bin Himax_firmware.bin ipa_fws.b03 iris6_ccf2.fw lagoon_ipa_fws.b02 st21nfc_fw7.bin widevine.b03 widevine.mdt
- further example with super partition structure, google-sargo
mobian@mobian:~$ ls -lh /dev/disk/by-partlabel/ | grep system
lrwxrwxrwx 1 root root 16 29 gen 1970 system_a -> ../../mmcblk0p68
lrwxrwxrwx 1 root root 16 29 gen 1970 system_b -> ../../mmcblk0p69
mobian@mobian:~$ sudo make-dynpart-mappings /dev/mmcblk0p69
device-mapper: create ioctl on system_b failed: Device or resource busy
device-mapper: create ioctl on vendor_b failed: Device or resource busy
device-mapper: create ioctl on product_b failed: Device or resource busy
device-mapper: create ioctl on system_ext_b failed: Device or resource busy
warn: This looks like metadata for retrofit partitions. Only the first slot is mapped.
mobian@mobian:~$ ls /dev/mapper/
control product_b system_b system_ext_b vendor_b
mobian@mobian:~$ sudo mkdir -p /media/vendor_b
mobian@mobian:~$ sudo mount -o ro /dev/mapper/vendor_b /media/vendor_b/
mount: (hint) your fstab has been modified, but systemd still uses
the old version; use 'systemctl daemon-reload' to reload.
mobian@mobian:~$ ls /media/vendor_b/
apex app bin build.prop dsp etc firmware firmware_mnt framework lib lib64 lost+found media odm odm_dlkm overlay radio rfs ueventd.rc usr vendor_dlkm
mobian@mobian:~$ ls /media/vendor_b/firmware
a615_zap.b00 adsp.b07 adsp.b21 adspua.jsn cdsp.b02 cmnlib64.b00 cmnlib.mbn cppf.b03 cs40l20.wmfw ipa_fws.b00 rt5514_dsp_fw4.bin widevine.b04
a615_zap.b01 adsp.b08 adsp.b22 bdwlan-bonito.bin cdsp.b03 cmnlib64.b01 cmnlib.mdt cppf.b04 Data.msc ipa_fws.b01 synaptics_0.img widevine.b05
a615_zap.b02 adsp.b09 adsp.b23 bdwlan-bonito-JPN.bin cdsp.b04 cmnlib64.b02 confirmationui.b00 cppf.b05 drv2624.bin ipa_fws.b02 TEST_MAPPING widevine.b06
a615_zap.elf adsp.b10 adsp.b24 bdwlan-bonito-ROW.bin cdsp.b05 cmnlib64.b03 confirmationui.b01 cppf.b06 easel ipa_fws.b03 venus.b00 widevine.b07
a615_zap.mdt adsp.b11 adsp.b25 bdwlan-bonito-USA.bin cdsp.b06 cmnlib64.b04 confirmationui.b02 cppf.b07 fpctzappfingerprint.b00 ipa_fws.b04 venus.b01 widevine.mbn
a630_gmu.bin adsp.b12 adsp.b26 bdwlan-bonito-VZW.bin cdsp.b07 cmnlib64.b05 confirmationui.b03 cppf.mbn fpctzappfingerprint.b01 ipa_fws.elf venus.b02 widevine.mdt
a630_sqe.fw adsp.b13 adsp.b27 bdwlan-sargo.bin cdsp.b08 cmnlib64.mbn confirmationui.b04 cppf.mdt fpctzappfingerprint.b02 ipa_fws.mdt venus.b03 wlan
adsp.b00 adsp.b14 adsp.b28 bdwlan-sargo-JPN.bin cdsp.b09 cmnlib64.mdt confirmationui.b05 crbtfw21.tlv fpctzappfingerprint.b03 manifest.xml venus.b04 wlanmdsp.mbn
adsp.b01 adsp.b15 adsp.b29 bdwlan-sargo-ROW.bin cdsp.b10 cmnlib.b00 confirmationui.b06 crnv21.bin fpctzappfingerprint.b04 modemuw.jsn venus.mbn
adsp.b02 adsp.b16 adsp.b30 bdwlan-sargo-USA.bin cdsp.b11 cmnlib.b01 confirmationui.b07 crus_sp_config_b4_rx.bin fpctzappfingerprint.b05 nanoapp_config.textproto venus.mdt
adsp.b03 adsp.b17 adsp.b31 bdwlan-sargo-VZW.bin cdsp.mbn cmnlib.b02 confirmationui.mdt crus_sp_config_b4_tx.bin fpctzappfingerprint.b06 pn557.bin widevine.b00
adsp.b04 adsp.b18 adsp.mbn CAMERA_ICP.elf cdsp.mdt cmnlib.b03 cppf.b00 crus_sp_config_s4_rx.bin fpctzappfingerprint.b07 rt5514_dsp_fw1.bin widevine.b01
adsp.b05 adsp.b19 adsp.mdt cdsp.b00 cdspr.jsn cmnlib.b04 cppf.b01 crus_sp_config_s4_tx.bin fpctzappfingerprint.mbn rt5514_dsp_fw2.bin widevine.b02
adsp.b06 adsp.b20 adspr.jsn cdsp.b01 citadel cmnlib.b05 cppf.b02 write a config for droid-juicer, which will then extract those files
- place config in /usr/share/droid-juicer/configs/
- try to run droid-juicer
- reboot
- see whether dmesg complains about less missing files
Then improve the port from there.