Firefox OS/Performance/Modifying boot.img

Modifying boot.img

This page is meant to illustrate the general steps necessary to make changes to the ramdisk in the boot partition of the Flame. This may be desired for a number of reasons such as making changes to the init rc scripts or the init program itself, without changing the kernel.

Ideally, the build system would build the kernel and ramdisk, and then create a boot.img which one could then flash. In this case, it's simply a matter of making whatever changes are necessary (and of course init would be automatically included as well). On the flame however, it was not quite so easy.

Obtaining a boot.img

To retrieve the boot.img from the device one can simply find the boot partition in the filesystem, and use |adb pull|.

For the flame, for example:

adb pull /dev/block/platform/msm_sdcc.1/by-name/boot .

Where the file specified above is a friendly symlink to |/dev/block/mmcblk0p7|.

Hamachi Quirks

For certain other devices (such as the hamachi) the partitions lived under |/dev/mtd/| and the mappings could be found by executing |cat /proc/mtd| on the device, which would emit something like the following, indicating the partition mappings:

dev:    size   erasesize  name
mtd0: 00600000 00020000 "boot"
mtd1: 0c800000 00020000 "system"
mtd2: 02800000 00020000 "cache"
mtd3: 00400000 00020000 "misc"
[...]
mtd20: 01b00000 00020000 "FOTA"
mtd21: 00120000 00020000 "APPSBL"
mtd22: 023c0000 00020000 "APPS"

From this we see that mtd0 is the boot partition and hence to retrieve it we would run

adb pull /dev/mtd/mtd0

Alternatively

If one already has an image from the OEM or elsewhere, pulling the boot partition from the device is not necessary.

Splitting apart the boot.img

The boot partition contains 2-3 distinct entities: The kernel, the ramdisk, and optionally based on how the kernel was configured, the device tree binary. The instructions outlined here for unpacking a boot.img are mostly sufficient, except it does not account for the device tree section (which is necessary on a Flame). For more information on the structure of this partition in general see: https://github.com/xiaolu/mkbootimg_tools/blob/master/dtbtool.txt .

To get the kernel and the ramdisk from the boot.img, one can make use of the tool unmkbootimg invoked as such:

unmkbootimg boot.img

Along with outputting the files zImage (the kernel) and initramfs.cpio.gz (the ramdisk), this program also displays the required command to rebuild the boot partition with the same configuration it was found in, e.g.:

mkbootimg --kernel zImage --ramdisk initramfs.cpio.gz --base 0 --pagesize 2048 --cmdline 'androidboot.hardware=aphone' -o new_boot.img

Keep the kernel and ramdisk files somewhere safe, as they will be required for later steps.

The device tree binary is the last section (after which is zero padding if the image was pulled from the device). A device tree is basically a data structure for describing the hardware of the device to the kernel, and It is generally compiled to a binary format more suitable for machines to read than humans. It signals its beginning in the boot partition with the 4 byte magic |QCDT|. To extract this blob I simply used dd on the partition image skipping to whatever offset the magic was found at, and then trimming the trailing zeros similarly. A command such as this can be used to find the offset:

strings -o boot.img | grep QCDT | awk '{print $1}'

And then one can use dd as such:

dd if=boot.img of=dtblob skip='$DT_OFFSET' bs=1

This is not the most elegant of procedures, however I have not as of yet found a better way. (The correct solution I suppose would be extending the unmkbootimg utility appropriately).

So now that we have all three parts we continue on to making modifications. We will keep the kernel and device tree around unchanged for rebuilding the boot.img. The ramdisk on the other hand, we will unpack into a directory, make changes to, and repackage. This is where files such as init and init.rc (and various other *.rc's) live.

Firstly, to unpack the ramdisk into a directory:

mkdir initramfs_dir
cd initramfs_dir
gunzip -c ../initramfs.cpio.gz | cpio -i

Make the desired changes, such as replacing init and modifying init.rc (both of which live in the root of the directory), and then repackage:

$SRC_TOP/out/host/$HOST_NAME/bin/mkbootfs . | gzip > ../newinitramfs.cpio.gz

One can make the mkbootfs tool by invoking |./build.sh mkbootfs| from the FirefoxOS source tree;

Now with the command we got from the unmkbootimg utility, we can reconstruct the boot.img with the newly generated ramdisk, such that it retains the same settings and kernel parameters. As well, if the original boot.img contained a device tree, make sure to add |--dt $DTBLOBNAME| to the end of the command. The utility mkbootimg can be built in the FirefoxOS source tree by invoking |./build.sh mkbootimg| and the resulting binary is found in |$SRC_TOP/out/host/$HOST_NAME/bin/|

Once the new boot partition has been constructed, simply flash with fastboot or whichever tool is necessary for your device, e.g.:

fastboot flash boot new_boot.img

Note that with fastboot one can also specify to boot once using an image, as opposed to flashing it unto the device. You might want to do this first to make sure everything went well...:

fastboot boot new_boot.img