Introduction: The World of Android Dynamic Partitions

Modern Android devices, particularly those launched with Android 10 and newer, leverage a sophisticated partitioning scheme known as Dynamic Partitions. This revolutionary approach, implemented via the super.img container, replaces traditional fixed-size partitions with a flexible, logical volume management system. Dynamic partitions enable seamless A/B updates, efficient storage allocation, and greater flexibility for OEMs and custom ROM developers. However, this flexibility also introduces complexity when attempting to modify the underlying storage layout.

This expert-level guide will take you on a deep dive into the super.img structure, providing a step-by-step methodology to unpack its contents, inspect individual partition images, modify their sizes or even their file system contents, and then repack them into a custom super.img. Our goal is to empower you to create bespoke dynamic partition layouts tailored for specific needs, such as optimizing storage for custom ROMs like LineageOS, accommodating large GSI images, or facilitating development workflows.

Prerequisites and Essential Tools

Before embarking on this reverse engineering journey, ensure you have the following:

• A Linux-based operating system (Ubuntu, Debian, Arch, WSL2).
• adb and fastboot installed and configured.
• The lpunpack and lpmake tools, typically found in Android’s AOSP source tree (platform/system/core/liblp) or available via precompiled binaries from various sources (e.g., LineageOS build tools, custom ROM toolchains).
• Standard Linux filesystem utilities: simg2img, e2fsck, resize2fs, mount, unzip, mkfs.ext4.
• Sufficient disk space for extraction and modification (often tens of gigabytes).

Understanding the `super.img` Architecture

At its core, super.img isn’t a traditional filesystem image. Instead, it’s a container that holds a metadata header describing a logical partition table, along with the sparse images for various dynamic partitions. These typically include system, vendor, product, system_ext, and sometimes odm. The actual storage for these logical partitions is managed by Android’s Logical Partition Manager (LPPM), which maps them onto physical “slots” within the super partition.

When you flash a new ROM or update, the system might resize these partitions on the fly. By understanding and manipulating the metadata within super.img, we can pre-define these sizes and even the presence of certain partitions.

Step 1: Extracting `super.img` Contents

First, you need to acquire the super.img file. It can typically be found in several places:

1. From a stock firmware package: Often included directly or embedded within a payload.bin (which requires a payload-dumper tool to extract).
2. From a custom ROM ZIP: Sometimes, custom ROMs provide a full super.img, or you might need to extract it from the payload.bin of the ROM’s updater.
3. Directly from a rooted device: Using adb pull /dev/block/by-name/super super.img (though this pulls the raw partition, which might be in use and thus inconsistent, and often requires specific knowledge of your device’s block device naming).

Once you have your super.img, use lpunpack to extract its constituent sparse images:

mkdir super_extractedlpunpack --sparse --output=super_extracted super.img

This command will create individual sparse image files (e.g., system.img, vendor.img) in the super_extracted directory, along with a super_layout.json or similar metadata file, depending on the lpunpack version.

Step 2: Inspecting and Modifying Partition Images

The extracted images are sparse, meaning they only store non-zero data blocks. To work with them as standard filesystem images, convert them to raw images:

simg2img super_extracted/system.img super_extracted/system_raw.img

Now, you can perform filesystem checks, resize operations, and mount them for content modification. For example, to resize system_raw.img:

# Check for errors (crucial before resizing)e2fsck -f super_extracted/system_raw.img# Resize the filesystem to its minimum possible sizeresize2fs -M super_extracted/system_raw.img# Alternatively, resize to a specific size (e.g., 5GB)# resize2fs super_extracted/system_raw.img 5G

To modify content:

mkdir system_mountsudo mount -o loop super_extracted/system_raw.img system_mount# Modify files, add apps, etc.# sudo cp my_custom_app.apk system_mount/system/app/sudo umount system_mount

After modification, you must convert the raw image back to a sparse image to prepare it for repacking into super.img:

img2simg super_extracted/system_raw.img super_extracted/system_new_sparse.img

Repeat this process for all partitions you wish to modify (e.g., vendor.img, product.img).

Step 3: Crafting a Custom `super.img` Layout

This is where we define the new partition layout. The lpmake tool requires a configuration file, often in JSON format, describing the partition groups, partitions, and their sizes. If lpunpack produced a super_layout.json, you can use that as a starting point. Otherwise, you’ll need to create one manually.

A typical lpmake manifest defines “groups” and “partitions” within those groups. Each partition needs a name, attributes, and a maximum size. Here’s an example layout.json:

{  "dynamic_partition_groups": [    {      "name": "qti_dynamic_partitions",      "size": "10000000000",      "partitions": [        {          "name": "system",          "size": "4000000000",          "image": "super_extracted/system_new_sparse.img"        },        {          "name": "vendor",          "size": "2000000000",          "image": "super_extracted/vendor_new_sparse.img"        },        {          "name": "product",          "size": "1500000000",          "image": "super_extracted/product_new_sparse.img"        },        {          "name": "system_ext",          "size": "1000000000",          "image": "super_extracted/system_ext_new_sparse.img"        }      ]    }  ],  "lpmake_args": [    "--metadata-size", "65536",    "--super-name", "super",    "--block-size", "4096",    "--virtual-ab"  ]}

Key considerations:

• dynamic_partition_groups: Defines logical groups. Most devices have a single group, often named qti_dynamic_partitions or similar.
• group.size: The total available space for partitions within that group. This should generally match the physical size of your device’s super partition (or a bit less for metadata). You can get this from fastboot getvar all or by inspecting the original super.img.
• partition.name: Matches the standard Android partition names.
• partition.size: The maximum size this partition can grow to. This is crucial for resizing. Ensure the combined sizes of all partitions in a group do not exceed the group’s size.
• partition.image: Path to your modified sparse image.
• lpmake_args: Important arguments for lpmake. --metadata-size (usually 65536 or 262144), --block-size (typically 4096), and --virtual-ab (if your device supports A/B updates and is configured for virtual A/B).

Carefully adjust the partition.size values to meet your requirements. For example, if you need more space on system for a larger GSI, increase its size, ensuring you free up space from other partitions or within the group’s total allocated size.

Step 4: Repacking `super.img`

With your custom layout.json and modified sparse images, you can now rebuild the super.img using lpmake:

lpmake --config layout.json --output super_new.img

This command will generate super_new.img, incorporating all your specified changes. Double-check the output for any errors or warnings from lpmake. The size of super_new.img should be comparable to the original, but the internal layout will reflect your modifications.

Step 5: Flashing and Verifying Your Custom `super.img`

Flashing a modified super.img is a critical step and should be done with caution. Always back up your device’s partitions if possible.

1. Reboot your device into Fastboot mode.
2. Flash the new super.img:

   fastboot flash super super_new.img

3. Reboot the device:

   fastboot reboot

Once the device boots up, you can verify your changes using adb shell:

adb shell df -h /system /vendor /productadb shell ls -l /dev/block/mapper/

The df -h command will show the mounted sizes of your partitions, reflecting your new maximum allocations. ls -l /dev/block/mapper/ will list the dynamic partitions created by the logical partition manager. If your device fails to boot (bootloop), you may have made an error in the layout or corrupted a partition image. In such cases, you might need to reflash a working stock super.img or full stock firmware.

Conclusion

Manipulating super.img and Android’s dynamic partition system opens up a world of possibilities for advanced users and developers. From optimizing storage for specialized custom ROMs to preparing devices for specific A/B update scenarios or even custom GSI integrations, the ability to control logical partition layouts is a powerful tool. While the process demands careful attention to detail and a solid understanding of Linux filesystem tools, the rewards of a perfectly tailored Android storage architecture are well worth the effort. Always proceed with backups and a thorough understanding of each step.