Introduction to F2FS on Android

The Flash-Friendly File System (F2FS) is a filesystem developed by Samsung for NAND flash memory, which is commonly used in Android devices. Its design specifically addresses the characteristics of NAND flash, such as write amplification and wear leveling, to improve performance and prolong the lifespan of the storage. For custom ROM enthusiasts, migrating from older filesystems like ext4 to F2FS, particularly for the /data and /cache partitions, can result in noticeably faster boot times, smoother UI interactions, and improved overall responsiveness.

Why F2FS Matters for Custom ROMs

While many official Android builds and popular custom ROMs like LineageOS have integrated F2FS support for certain devices, unofficial builds or ROMs for less common devices often lack this crucial optimization. This typically stems from a reliance on the default kernel and filesystem configurations, which might not include the necessary F2FS drivers or the recovery’s ability to format partitions with F2FS. Enabling F2FS manually requires carefully modifying the ROM’s installation script and ensuring the kernel supports it. This guide delves into the process of reverse engineering existing F2FS conversion mechanisms to adapt them for unsupported devices.

Understanding F2FS Conversion Scripts

F2FS conversion on Android devices primarily involves two critical steps: formatting the target partitions (typically /data and /cache) to F2FS, and then ensuring the device’s kernel and fstab configuration recognize and mount these partitions correctly. This process is usually orchestrated via an updater-script within the custom ROM’s ZIP package, or through a custom recovery like TWRP.

Locating and Analyzing Reference Scripts

The first step in reverse engineering is to find a working example. This could be:

1. Official LineageOS Builds: Download a LineageOS ZIP for a device known to support F2FS (e.g., some OnePlus models) and extract its updater-script.
2. TWRP Source Code: Examine the TWRP device tree for a device that supports F2FS conversion. TWRP often includes specific functions or scripts for this.
3. Other Unofficial F2FS Conversion Zips: Look for standalone F2FS converter ZIPs for similar devices.

Once you have a reference updater-script (found in META-INF/com/google/android/updater-script inside a ROM ZIP), open it with a text editor. You’ll often see commands like format("f2fs", "EMMC", "/dev/block/platform/soc/1d84000.ufshc/by-name/userdata", "0", "/data"); or shell commands executed via run_program that directly call mkfs.f2fs.

# Example snippet from an updater-script
ui_print("Mounting /data partition...");
run_program("/sbin/mount", "/data");

ui_print("Converting /data to F2FS...");
# This command is often what we need to replicate or adapt.
# The partition path and flags are crucial.
# Older scripts might use specific TWRP functions like set_fs_type.
# Newer ones might directly call mkfs.f2fs if bundled.
ifelse(
  is_mounted("/data"), unmount("/data"), true
);
run_program("/sbin/make_ext4fs", "-L", "/data", "/dev/block/platform/soc/1d84000.ufshc/by-name/userdata");
# This is an example for ext4. For F2FS, it would be mkfs.f2fs.
# More advanced scripts will copy mkfs.f2fs to /tmp and execute it.

ui_print("Setting up F2FS fstab entries...");
# This part is implicit or handled by the kernel/ROM's fstab generator.

Step-by-Step Reverse Engineering and Adaptation

1. Identify Target Partitions

First, you need to know the exact block device paths for your /data and /cache partitions. This varies significantly between devices. Connect your device in recovery mode (TWRP is ideal) and use ADB:

adb shell
ls -l /dev/block/platform/*/by-name/

Look for userdata (for /data) and cache. Note down their full paths (e.g., /dev/block/platform/soc/1d84000.ufshc/by-name/userdata).

2. Extract or Build mkfs.f2fs Binary

The updater-script needs access to the mkfs.f2fs utility to format the partitions. This binary is often:

• Bundled in the ROM ZIP: Check /tmp/install/bin or similar paths in reference ZIPs.
• Present in TWRP: TWRP often includes it.
• AOSP Source: Compile it from AOSP source for your architecture.

If you extract it from a reference ZIP, ensure it’s compatible with your device’s architecture (ARM, ARM64). You’ll place this binary in a temporary location within your custom conversion ZIP, usually /tmp during the flashing process, then execute it.

3. Modify fstab for F2FS Support

The device’s kernel needs to know to mount /data and /cache as F2FS. This is defined in the fstab file, typically located at /vendor/etc/fstab.qcom or similar paths. You’ll need to modify the fs_mgr_flags for /data and /cache entries.

Original (ext4) example:

/dev/block/platform/soc/1d84000.ufshc/by-name/userdata  /data     ext4    noatime,nosuid,nodev,barrier=1,noauto_da_alloc,discard wait,check,formattable,voldmanaged=sdcard:0,encryptable=footer,length=-1

Modified (F2FS) example:

/dev/block/platform/soc/1d84000.ufshc/by-name/userdata  /data     f2fs    noatime,nosuid,nodev,discard,inline_xattr,inline_data,active_logs=6 wait,check,formattable,voldmanaged=sdcard:0,encryptable=footer,length=-1

Note the change from ext4 to f2fs and the F2FS-specific mount options. You can use sed commands within your updater-script to patch this file on the fly, or include a pre-patched fstab if you are building the ROM.

4. Crafting the Updater Script

Now, combine these steps into your own updater-script:

1. Unmount Partitions: Ensure /data and /cache are unmounted.
2. Transfer mkfs.f2fs: Copy your mkfs.f2fs binary from the ZIP to /tmp/mkfs.f2fs and set executable permissions.
3. Format Partitions: Execute /tmp/mkfs.f2fs for /data and /cache using the correct block device paths. Adding the -O encrypt flag is crucial for encrypted /data.
4. Patch fstab: Use sed or other tools to modify the fstab file on the target device.
5. Reboot: A reboot is necessary for the new filesystem to be recognized.

# Example updater-script snippet for F2FS conversion
ui_print("Unmounting /data and /cache...");
run_program("/sbin/umount", "/data");
run_program("/sbin/umount", "/cache");

ui_print("Copying mkfs.f2fs binary...");
unzip_recursive("BIN/mkfs.f2fs", "/tmp/mkfs.f2fs");
set_perm(0, 0, 0755, "/tmp/mkfs.f2fs");

ui_print("Formatting /data to F2FS...");
run_program("/tmp/mkfs.f2fs", "-O", "encrypt", "/dev/block/platform/soc/1d84000.ufshc/by-name/userdata");

ui_print("Formatting /cache to F2FS...");
run_program("/tmp/mkfs.f2fs", "/dev/block/platform/soc/1d84000.ufshc/by-name/cache");

ui_print("Patching fstab for F2FS support...");
# This assumes your fstab is at /vendor/etc/fstab.qcom
# Adjust path and sed commands as necessary for your device.
# Example for /data
run_program("/sbin/sed", "-i", "s|/datasext4|/datasf2fs|g", "/vendor/etc/fstab.qcom");
run_program("/sbin/sed", "-i", "s|ext4snoatime|f2fssnoatime,discard,inline_xattr,inline_data,active_logs=6|g", "/vendor/etc/fstab.qcom");

# Example for /cache
run_program("/sbin/sed", "-i", "s|/cachesext4|/cachesf2fs|g", "/vendor/etc/fstab.qcom");
run_program("/sbin/sed", "-i", "s|ext4,discard|f2fs,discard,inline_xattr|g", "/vendor/etc/fstab.qcom");

ui_print("F2FS conversion complete. Rebooting...");
set_progress(1.0);

5. Testing and Troubleshooting

After creating your custom conversion ZIP, flash it via TWRP. Monitor the TWRP logs for errors. If the device fails to boot after conversion, it’s likely an issue with the fstab modification or an incompatible kernel. You might need to flash back to a working ROM or format partitions manually via TWRP to recover.

• Kernel Support: Ensure your custom kernel explicitly supports F2FS. Without it, the device won’t boot or mount the partitions correctly.
• Correct Block Paths: Double-check the /dev/block/ paths. A typo here will lead to failure.
• mkfs.f2fs Compatibility: Verify the binary matches your device’s architecture and Android version.

Conclusion

Reverse engineering F2FS conversion scripts requires a solid understanding of Android’s filesystem structure, recovery operations, and basic shell scripting. By meticulously analyzing existing implementations, identifying your device’s specific partition layouts, and carefully crafting an updater-script, you can bring the performance benefits of F2FS to unofficial custom ROMs. This process not only optimizes your device but also deepens your understanding of Android’s underlying systems, empowering you to contribute to the wider custom ROM community.