Deviceinfo reference

From postmarketOS

Most of the variables in deviceinfo have self-explanatory names and are used both when you are building postmarketOS (edit at .local/var/pmbootstrap/cache_git/pmaports/device/your_device_name/deviceinfo before flashing, and during runtime it is available at /etc/deviceinfo). if edited before flashing, be sure to rebuild the file with pmbootstrap install

All variables start with deviceinfo_ in the file - this is omitted here to save space.

Case sensitivity

The values of the deviceinfo variables are case sensitive. Most values are lowercase, but there are exceptions such as flash_heimdall_partition_kernel. See the "possible values" column for the right casing. For example, if it says true then using True or TRUE or tRuE is not valid.

device

Variable Description Possibles values
format_version Used to distinguish between different versions of this file. 0
name Device model e.g. Nokia N900
manufacturer Device manufacturer e.g. Nokia
codename Device codename e.g. nokia-n900
uboot_boardname Files for each u-boot board are placed under (/usr/share/u-boot/$uboot_boardname in alpine) directory, if u-boot port for device exists. Maybe obtained from board_configs var after : delimiter. A defconfig file exists for each board in u-boot repository in configs/${uboot_boardname}_defconfig file e.g. pine64-lts


year Release year of the device e.g. 2012
chassis The computer case of your device (!1933) e.g. handset for phones, watch (all values)
keyboard The device has a hardware keyboard. true, false
dtb Name of the device tree blob file (only used on mainline kernels or devices with a header version of 2). See the option append_dtb on how this is used. e.g. allwinner/sun50i-a64-pine64-lts or qcom-msm8974-lge-nexus5-hammerhead
append_dtb Set to true if the dtb should be appended to the Linux kernel image, if set to false the dtb will be copied to the /boot partition instead. (pmaports!387) true, false
external_storage Does the device have an sdcard or other external storage medium? true, false
flash_method Method used to flash the device (more info)
arch Device architecture, must be supported by Alpine Linux armhf, armv7, aarch64, x86, x86_64
dev_internal_storage Path to the internal storage (eMMC) (currently only used by the on-device installer). Only set this if you will use it. (pmaports!1820) e.g. /dev/vdb
dev_internal_storage_repartition Allow the internal storage to be repartitioned by postmarketOS in the on-device installer. This makes it possible to install from SD card to eMMC (pmaports!1820).

This is dangerous and should not be enabled for Android devices! For Android devices, we never change the partition table, because the bootloader expects the boot.img to be at a specific partition and changing the partition scheme would likely result in the original OS not being usable anymore.

true, false
dev_touchscreen Path to the touchscreen device (only necessary if not automatically detected, more info) e.g. /dev/input/event3
dev_touchscreen_calibration Touchscreen calibration values (only necessary for devices with resistive touchscreen, more info) e.g. 1.094563 -0.020949 -34.586121 0.009427 -1.148506 503.816956
keymaps Lists keymap options that are available for this device, this will be shown as options in the pmbootstrap init command, this will be passed to Alpine's setup-keymap command us/rx51_us ch/rx51_ch it/rx51_it
swap_size_recommended Set recommended swap file size for device. If unset, no swap file will be created for the device. Integer, in MB.
zram_swap_pct The size of the ZRAM swap is based on a percentage of the device's RAM, this allows overriding the default percentage to use in the calculation. If set to 0, ZRAM swap is disabled for the device. Integer, between 0 and 100. See /etc/conf.d/zram-init from postmarketos-base for default values.
tmp_as_tmpfs_size The size at which /tmp will be mounted from memory as tmpfs. If set to 0, no mounting will happen. This value is passed directly to the tmpfs size= param, e.g., 50% and 2g. See man tmpfs for more information.
disable_dhcpd Do not set the static ip to the network interface and do not run the DHCP daemon on it. This makes sense for devices with an ethernet port, like the Raspberry Pi (!1580). true, false
no_framebuffer Do not wait up to 10 seconds until a framebuffer device shows up and do not try to configure it (pmaports!44). true, false
initfs_compression Format and compression level to use when compressing the initramfs. The format for this is: FORMAT:LEVEL, for example zstd:fast. Supported formats are zstd, lzma, gzip, none. Supported compression levels are: default, fast, best. This option does not impact the initramfs-extra archive, it is generated without any compression. (see postmarketos-mkinitfs!25). If this option is not specified, or cannot be parsed, gzip with the default compression settings are used. postmarketos-mkinitfs 2.0 is the first version with support for this option, previous versions of mkinitfs either did not use this option or expected different values for it. default: gzip:default
getty Configure a getty on boot. Creates an entry in /etc/inittab <port>;<baudrate>
e.g. ttyS0;115200
default: not set
gpu_accelerated Defines if the device has GPU acceleration support. This property is used by pmbootstrap init to hide UIs which require GPU acceleration if the device lacks such support. default: false
super_partitions For Androids with dynamic partitions, set the super partition(s) here. See Android dynamic partitions for details. e.g. /dev/mmcblk0p68 /dev/mmcblk0p69

flash

These are used for flashing and booting the device, and most of them are fastboot specific. Here is a guide on how to get these values for a specific Android device (by extracting the boot.img)

Variable Description Possible values
flash_offset_base Used for flashing default: 0x10000000
flash_offset_dtb Used for flashing on header_version 2, see boot-deploy!15
flash_offset_kernel Kernel offset used for flashing
flash_offset_ramdisk Ramdisk offset used for flashing
flash_offset_second Used for flashing
flash_offset_tags Used for flashing
flash_pagesize Page size usually 2048
flash_sparse Set this to true if your device expects a sparse system image flashed
flash_sparse_samsung_format Generate a sparse image according to Samsung's own format. Currently the only allowed value is "1". See solutions for postmarketOS for more informations. In order to work flash_sparse must be set to true in conjuction to this option
flash_kernel_on_update Android devices need the kernel and initramfs to be flashed to a dedicated partition. Set this variable to true to automatically do this with the postmarketos-update-kernel script. Your device package also needs to depend on postmarketos-update-kernel.

This is dangerous and should only be enabled after reading the script and verifying that it works for a given device! Double-check that it will not flash to a wrong partition, otherwise you might render a device unbootable.

Related: pmaports!2215

kernel_cmdline Kernel command line (When modifying /etc/deviceinfo: Use kernel_cmdline_append instead. Unless you really want to override the whole kernel command-line, which is usually a bad idea.)
kernel_cmdline_append Additional kernel command line. Anything in this variable gets automatically added after kernel_cmdline. This is aimed to customize kernel_cmdline by users without having to modify the package shipped by the device package.
bootimg_blobpack Create a flashable blob for the ASUS Transformers from boot.img using BlobTools true, sign, false
bootimg_qcdt Append dtb file to boot.img (more info) true, false
bootimg_qcdt_type Define the format of dt.img exynos, sprd, qcom
bootimg_mtk_label_kernel Prepend a MediaTek boot header to the kernel before adding it to boot.img; needed on a select few MediaTek devices. The LABEL portion of the kernel header, usually KERNEL.
bootimg_mtk_label_ramdisk Prepend a MediaTek boot header to the initramfs before adding it to boot.img; needed on a select few MediaTek devices. The LABEL portion of the ramdisk header, usually ROOTFS.
bootimg_override_payload File name in mkinitfs working dir to be used

instead of linux kernel file in android boot image

filename, i.e.u-boot.bin
bootimg_override_initramfs File name in mkinitfs working dir to be used

instead of initramfs file in android boot image. See also boot-deploy!10

filename, i.e.boot_image.itb
bootimg_override_payload_compression Compression method, used to compress override_payload file.

Stock bootloader usually expect gzip payload, and fail, if it's not.

Compression method, i.e. gzip
bootimg_override_payload_append_dtb File name in mkinitfs working dir to be appended to the payload.

Stock bootloader usually expect dtb appended to the payload, and fail, if it's not.
Usually you should create a dtb with memory and chosen nodes, and install it in a place, where mkinifs script will pick it up, for example board's u-boot directory.

filename, i.e. dumb.dtb
bootimg_dtb_second Place the dtb in the "second" area of the Android boot image. See pmaports!700 for details. true, false
bootimg_append_seandroidenforce Append SEANDROIDENFORCE file to boot.img See pmaports!1000 for details. true, false
bootimg_pxa Set this to true if the device is based on the Marvell PXA1088/1908 chipset, which has header layout differences. Makes mkinitfs generate the boot image with a different mkbootimg. pxa-mkbootimg should be added as a dependency to your device package. true, false
bootimg_custom_args Additional custom arguments to pass to mkbootimg. Caution: adding contents to this variable removes the --header-version and --dtb arguments, which need to be added manually in that case e.g. --vendor_cmdline ...
header_version Header version of boot image as defined by Android documentation Number in range 0..4
generate_bootimg Set this to true for fastboot device, so the mkinitfs command will generate a boot.img file after creating the initfs. Add mkbootimg as dependency to your device's APKBUILD! true, false
generate_extlinux_config Set this to true for U-Boot device, so the mkinitfs command will generate a /boot/extlinux/extlinux.conf file after creating the initfs. true, false
generate_grub_config Set this to true for EFI device, so the mkinitfs command will generate a /boot/grub/grub.cfg file after creating the initfs. true, false
generate_systemd_boot Generate the configuration for systemd-boot or gummiboot, and install it on the system. true, false
generate_uboot_fit_images Set "true" to generate U-boot FIT images,

one image per *.its file in board's u-boot directory

true, false
generate_legacy_uboot_initfs For the Nokia N900, we use a legacy version of the uboot bootloader right now. When setting this variable to true, the initramfs will generate an uboot legacy compatible initramfs file. Modern versions of uboot can load regular initramfs files. true, false
legacy_uboot_load_address Set a custom load address for the legacy uboot initfs (see pmaports!578, only makes sense in combination with generate_legacy_uboot_initfs). default: 80008000
legacy_uboot_image_name Set a custom uboot image name, required by some device bootloaders that expect a specific image name. (boot-deploy!11) default: postmarketos
flash_fastboot_partition_kernel Only relevant for fastboot flash methods, the partition where the kernel or boot.img will be stored (!1741). default: "boot"
flash_fastboot_partition_system Only relevant for fastboot flash methods, the partition where the system image will be stored (see also: partition-layout). default: "system"
flash_fastboot_partition_vbmeta For AVB devices: set vbmeta partition to be flashed with a custom vbmeta.img which has verity flag disabled (!1885). partition name, e.g. vbmeta
flash_fastboot_partition_dtbo For devices that require dtbo populated: set dtbo partition to be flashed with a custom dtbo.img that's generated by the linux package (!2099). partition name, e.g. dtbo
flash_fastboot_max_size Set this if the fastboot required by your device has an upper limit to the size of system images it will flash. Size, in MB
flash_heimdall_partition_kernel Only relevant for heimdall flash methods, the partition where the kernel or boot.img will be stored. default: "KERNEL"
flash_heimdall_partition_initfs Only relevant for the heimdall-isorec flash method, the partition where the initramfs will be stored. default: "RECOVERY"
flash_heimdall_partition_system Only relevant for heimdall flash methods, the partition where the system image will be stored (see also: partition-layout). default: "SYSTEM"
flash_heimdall_partition_vbmeta For AVB devices: set vbmeta partition to be flashed with a custom vbmeta.img which has verity flag disabled (!1936, !1885). partition name, e.g. VBMETA
flash_rk_partition_kernel Only relevant for rk flash method, the partition where the kernel will be stored. !2165 e.g. cache
flash_rk_partition_system Only relevant for rk flash method, the partition where the system image will be stored (see also: partition-layout). !2165 e.g. userdata
flash_mtkclient_partition_kernel Only relevant for MTKClient flash methods, the partition where the kernel or boot.img will be stored. default: "boot"
flash_mtkclient_partition_rootfs Only relevant for MTKClient flash methods, the partition where the system image will be stored (see also: partition-layout). default: "system"
flash_mtkclient_partition_vbmeta For AVB devices: set vbmeta partition to be flashed with a custom vbmeta.img which has verity flag disabled. partition name, e.g. vbmeta
flash_mtkclient_partition_dtbo For devices that require dtbo populated: set dtbo partition to be flashed with a custom dtbo.img that's generated by the linux package. partition name, e.g. dtbo
boot_filesystem Sets the filesystem used for the /boot partition containing initramfs-extra default: "ext4", "fat16", "fat32"
root_filesystem Sets the filesystem used for the / partition (!2011) default: "ext4"
rootfs_image_sector_size Some devices made after 2016 with UFS storage use 4096 byte sectors and therefore need this option to boot. Read !1725 for details. default: 512
sd_embed_firmware A comma-separated list of binary:offset (where binary is under /usr/share) (!1739) e.g. firmware/librem5dev/u-boot.bin:33,firmware/librem5dev/m4.bin:2
sd_embed_firmware_step_size The number of bytes for each increment of the offset specified in the sd_embed_firmware default: 1024
partition_blacklist A comma-separated list of partitions that should not be flashed, because they brick the device. There are only very few devices where it is necessary (e.g. Ouya). !1759 e.g. boot,recovery
boot_part_start Number of sectors from the start of the drive to place the boot partition. Some devices may need this increased, if their bootloader takes up more space (like the Librem 5). (!1856) default: 2048
partition_type Type of partition table to be generated (!2160) default: msdos
mkinitfs_postprocess A script that runs after generating the initramfs. It gets the path to the generated initramfs file as parameter. An example use case is applying a signature verification hack to a boot.img file for amazon-soho (pmaports!2056). e.g. /usr/share/postmarketos-mkinitfs/amazon-omap-boot-hack.sh

multiboot involving Android

See U-Boot porting for more information.

Variable Description Possibles values
bootimg_vendor_dependent a list of source files for generating boot images, dependent on vendor boot image file presence on a device space separated bootloader payload source filenames
bootimg_vendor_android_boot_image Filename. Place your android boot image in a /boot directory with that name. It also may be copied by pmbootstrap during installation. See also: boot-deploy!19 filename.
bootimg_vendor_device_tree_identifiers space separated list of patterns, used to identify dtb for Android. regex patterns, i.e. "qcom,msm-id\s*=\s*<0x141\s*0x20001>; qcom,board-id\s*=\s*<0x08\s*0x0e>;"

splash

Variable Description Possibles values
screen_width The width of the display (DEPRECATED: no longer required) 800, 720, 1440... anything really
screen_height The height of the display (DEPRECATED: no longer required) 1280, 2560... other
framebuffer_landscape Rotate framebuffer output by 270° (pmaports!530, pmaports!546) true, false (default)

usb

Change how the target device shows up when connected with USB to a host PC. pmaports!706 added support for these variables in the mkinitfs script, when using the configfs network method.

Variable Description Default
usb_idVendor Vendor ID 0x18D1 ("Google Inc.")
usb_idProduct Product ID 0xD001 ("Nexus 4 (fastboot)")
usb_serialnumber Device's serial number string postmarketOS
usb_network_function Name of the network function to use, located in /config/usb_gadget/g1/functions/ ncm.usb0 with a fallback to rndis.usb0
usb_network_udc Name of the USB Device Controller (UDC) to use, typically found in /sys/class/udc whatever UDC is found in /sys/class/udc

The correct IDs can be seen in init.*.usb.rc of Android/TWRP sources for that device (or directly in rootfs, boot into twrp and see) OR plug in device running stock Android/TWRP and watch dmesg for things like

[    3.939519] usb 1-2.4: New USB device found, idVendor=2717, idProduct=ff40, bcdDevice= 4.14
[    3.939521] usb 1-2.4: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[    3.939521] usb 1-2.4: Product: MI 9
[    3.939522] usb 1-2.4: Manufacturer: Xiaomi

cgpt/depthcharge

These variables are used with ChromeOS devices (pmbootstrap!2163).

Variable Description Possible values
cgpt_kpart Path to the file to be written to kernel partition e.g. /usr/share/u-boot/google-peach-pit/u-boot-dtb.img.kpart, /boot/vmlinuz.kpart
cgpt_kpart_start Number of sectors from the start of the drive to place the kernel partition e.g. 8192
cgpt_kpart_size Size of kernel partition e.g. 32768
depthcharge_board Board codename used in depthcharge-tools, see https://github.com/alpernebbi/depthcharge-tools/blob/master/depthcharge_tools/boards.ini e.g. kevin
generate_depthcharge_image Set this to true, so the mkinitfs command will generate a vmlinuz.kpart file after creating the initramfs. Add depthcharge-tools as dependency to your device's APKBUILD! true, false

Obsolete options

weston

  • weston_pixman_type: used to be a Weston specific workaround for the "red screen bug" (#54): we patched Weston to accept a --pixman-type argument to override the framebuffer mode that the kernel driver reports. However, this patch was quickly incompatible with future changes in Weston, and it is not as good as patching the kernel to report the right framebuffer mode, so it was removed (pmaports#136).
  • Various options from weston.ini used to be duplicated, but this was removed in !739. If you need to set weston specific options from your device (such as the output backend or the keymap), please add a weston.ini file to your pmaport (example).

device

  • nonfree: Components of the device, that only run with closed source firmware. This is now legacy due to nobody uses it. (pmaports#438)
  • dev_keyboard: Originally intended to point osk-sdl to the hardware keyboard, but was never used. (It should detect hardware keyboards automatically...)
  • modules_initfs: Kernel modules to include in the initramfs, has been replaced with the modules-initfs file in the device package (pmaports!4169). See Device_specific_package#Kernel_modules for more information.
  • mesa_driver: This was used by osk-sdl, which will be dropped from pmaports in pmaports!4732

flash

  • flash_fastboot_vendor_id: fastboot used to have a -i option, but this was removed (#1830). Since we only had one device using this and nobody to verify if the option is really needed with this device, we decided to remove it. If you are interested in bringing it back, please create a new issue.
  • bootimg_mtk_mkimage: Did the same as bootimg_mtk_label_kernel and bootimg_mtk_label_ramdisk but with hard-coded LABEL values. Replaced in boot-deploy!49 when it was discovered that not all devices follow the exact same format.
  • generate_gummiboot: Generate necessary config for and install gummiboot (Dropped in boot-deploy 0.11)

usb

  • usb_rndis_function: renamed to usb_network_function in pmaports!3669.

See also