FORUMS
Remove All Ads from XDA

[DEV][TEMPLATE] AnyKernel3 - Easily Mod ROM Ramdisk + Pack Image.gz [Flashable Zip]

13,801 posts
Thanks Meter: 30,581
 
By osm0sis, Recognized Developer / Recognized Contributor on 5th March 2014, 03:32 AM
Post Reply Email Thread
AnyKernel3 -- Flashable Zip Template for Kernel Releases with Ramdisk Modifications

"AnyKernel is a template for an update.zip that can apply any kernel to any ROM, regardless of ramdisk." - Koush

The concept of AnyKernel has been around for awhile, (originally by Koushik Dutta/ClockworkMod,) which allowed a device-specific kernel zImage to be flashed over device-specific ROM and use the ramdisk that came with the ROM to reduce the chance of any issues arising from the custom kernel pairing.

The drawback to this was that some kernels require modifications to the ramdisk to enable/set up kernel features, and in the old AnyKernel format there was no way to do this. Enter AnyKernel2.

AnyKernel2 pushed the format even further by allowing kernel developers to modify the underlying ramdisk for kernel feature support easily using a number of included command methods along with properties and variables to customize the installation experience to their kernel. AnyKernel3 adds the power of topjohnwu's magiskboot for wider format support by default.

A script based on Galaxy Nexus (tuna) is included for reference. An example of ramdisk-only changes can be seen in my GN Synapse Injector repo. For an example that also modifies ROM and properly injects init.d support using busybox run-parts and sepolicy-inject see CosmicDan's CosmicTweaks project. For a multi-partition example see my N5X/6P BLOD Workaround Injector. Other working AK2/3 examples for more recent devices may be found on the Franco Kernel download repo in the >6.0 subfolders.

Please see the linked posts here for instructions on enabling full AVBv1 (Pixel), AVBv1, A/B slot and/or system-as-root (SAR) or 2-stage init (2SI) device support, and further guidelines for system-as-root/2-stage init (/system/system in recovery) modifications and root retention in general.


My development work on my many projects comes out of my free time, so if you enjoy this project or anything else I've done on xda, please consider sponsoring my ongoing work using my GitHub Sponsors profile. For a one-time donation you can hit the donate link from my profile. Thank you for your support!


Source: https://github.com/osm0sis/AnyKernel3/
Download: https://github.com/osm0sis/AnyKernel...ive/master.zip


Instructions

1) Place final kernel build product, e.g. Image.gz-dtb or zImage to name a couple, in the zip root (any separate dt, dtb, recovery_dtbo and/or dtbo should also go here for devices that require custom ones, each will fallback to the original if not included)
2) Place any required ramdisk files in /ramdisk and modules in /modules (with the full path like /modules/system/lib/modules)
3) Place any required patch files (generally partial files which go with AK3 file editing commands) in /patch
4) Modify the anykernel.sh to add your kernel's name, boot partition location, permissions for any added ramdisk files, and use methods for any required ramdisk modifications (optionally, also place banner and/or version files in the root to have these displayed during flash)
5) `zip -r9 UPDATE-AnyKernel3.zip * -x .git README.md *placeholder`

The LICENSE file must remain in the final zip to comply with licenses for binary redistribution and the license of the AK3 scripts.


If supporting a recovery that forces zip signature verification (like Cyanogen Recovery) then you will need to also sign your zip using the method I describe here:
[DEV][TEMPLATE] Complete Shell Script Flashable Zip Replacement + Signing [SCRIPT]

Not required, but any tweaks you can't hardcode into the source (best practice) should be added with an additional init.tweaks.rc or bootscript.sh to minimize the necessary ramdisk changes.

It is also extremely important to note that for the broadest AK3 compatibility it is always better to modify a ramdisk file rather than replace it.

If running into trouble when flashing an AK3 zip, the suffix -debugging may be added to the zip's filename to enable creation of a debug .tgz of /tmp for later examination while booted or on desktop.


Staying Up-To-Date

Now that you've got a ready zip for your device, you might be wondering how to keep it up-to-date with the latest AnyKernel commits. AnyKernel2 and AnyKernel3 have been painstakingly developed to allow you to just drop in the latest update-binary and tools directory and have everything "just work" for beginners not overly git or script savvy, but the best practice way is as follows:

1) Fork my AnyKernel3 repo on GitHub
2) `git clone https://github.com/<yourname>/AnyKernel3`
3) `git remote add upstream https://github.com/osm0sis/AnyKernel3`
4) `git checkout -b <devicename>`
5) Set it up like your <devicename> zip (i.e. remove any folders you don't use like ramdisk or patch, delete README.md, and add your anykernel.sh and optionally your Image.*-dtb if you want it up there) then commit all those changes
6) `git push --set-upstream origin <devicename>`
7) `git checkout master` then repeat steps 4-6 for any other devices you support

Then you should be able to `git pull upstream master` from your master branch and either merge or cherry-pick the new AK3 commits into your device branches as needed.


Enjoy!
Questions, comments and feedback welcome.



Credits & Thanks: All authors of the included binaries and the tools I used to port them over for their amazing work. koush for the original AnyKernel concept.

Disclaimer: Naturally, you take all the responsibility for what happens to your device when you start messing around with things.


XDA:DevDB Information
AnyKernel3, Tool/Utility for the Android General

Contributors
osm0sis

Version Information
Status: Stable
Stable Release Date: 2019-11-03

Created 2014-03-04
Last Updated 2019-11-12
The Following 300 Users Say Thank You to osm0sis For This Useful Post: [ View ]
5th March 2014, 03:33 AM |#2  
osm0sis's Avatar
OP Recognized Developer / Recognized Contributor
Flag Halifax
Thanks Meter: 30,581
 
Donate to Me
More
Script Commands Reference
Everything to edit is self-contained in anykernel.sh. A quick-reference for the commands and properties included are as follows.

Properties / Variables

These are some properties the update-binary will read during the install process, allowing you to customize your installation, e.g. block= is a shell variable to specify the kernel/boot block partition that the dump_boot command method will copy and unpack.

Code:
kernel.string=KernelName by YourName @ xda-developers
do.devicecheck=1
do.modules=1
do.cleanup=1
do.cleanuponabort=0
device.name1=maguro
device.name2=toro
device.name3=toroplus
device.name4=tuna
supported.versions=6.0 - 7.1.2
supported.patchlevels=2019-07 -

block=/dev/block/platform/omap/omap_hsmmc.0/by-name/boot;
is_slot_device=0;
ramdisk_compression=auto;
do.devicecheck=1 specified requires at least device.name1 to be present. This should match ro.product.device or ro.build.product from build.prop for your device. There is support for as many device.name# properties as needed. You may remove any empty ones that aren't being used.

do.modules=1 will push the contents of the module directory to the same location relative to root (/) and apply 644 permissions.

do.cleanup=0 will keep the zip from removing it's working directory in /tmp/anykernel (by default) - this can be useful if trying to debug in adb shell whether the patches worked correctly.

do.cleanuponabort=0 will keep the zip from removing it's working directory in /tmp/anykernel (by default) in case of installation abort.

supported.versions= will match against ro.build.version.release from the current ROM's build.prop. It can be set to a list or range. As a list of one or more entries, e.g. 7.1.2 or 8.1.0, 9 it will look for exact matches, as a range, e.g. 7.1.2 - 9 it will check to make sure the current version falls within those limits. Whitespace optional, and supplied version values should be in the same number format they are in the build.prop value for that Android version.

supported.patchlevels= will match against ro.build.version.security_patch from the current ROM's build.prop. It can be set as a closed or open-ended range of dates in the format YYYY-MM, whitespace optional, e.g. 2019-04 - 2019-06, 2019-04 - or - 2019-06 where the last two examples show setting a minimum and maximum, respectively.

block=auto instead of a direct block filepath enables detection of the device boot partition for use with broad, device non-specific zips. Also accepts specifically boot or recovery.

is_slot_device=1 enables detection of the suffix for the active boot partition on slot-based devices and will add this to the end of the supplied block= path. Also accepts auto for use with broad, device non-specific zips.

ramdisk_compression=auto allows automatically repacking the ramdisk with the format detected during unpack. Changing auto to gz, lzo, lzma, xz, bz2, lz4, or lz4-l (for lz4 legacy) instead forces the repack as that format, and using cpio or none will (attempt to) force the repack as uncompressed.

customdd="<arguments>" may be added to allow specifying additional dd parameters for devices that need to hack their kernel directly into a large partition like mmcblk0, or force use of dd for flashing.

slot_select=active|inactive may be added to allow specifying the target slot. If omitted the default remains active.

Note: Currently pushing modules is to the active slot only.

Command Methods

Code:
ui_print "<text>" [...]
abort ["<text>" [...]]
contains <string> <substring>
file_getprop <file> <property>

set_perm <owner> <group> <mode> <file> [<file2> ...]
set_perm_recursive <owner> <group> <dir_mode> <file_mode> <dir> [<dir2> ...]

dump_boot
split_boot
unpack_ramdisk

backup_file <file>
restore_file <file>
replace_string <file> <if search string> <original string> <replacement string> <scope>
replace_section <file> <begin search string> <end search string> <replacement string>
remove_section <file> <begin search string> <end search string>
insert_line <file> <if search string> before|after <line match string> <inserted line>
replace_line <file> <line replace string> <replacement line>
remove_line <file> <line match string>
prepend_file <file> <if search string> <patch file>
insert_file <file> <if search string> before|after <line match string> <patch file>
append_file <file> <if search string> <patch file>
replace_file <file> <permissions> <patch file>
patch_fstab <fstab file> <mount match name> <fs match type> block|mount|fstype|options|flags <original string> <replacement string>
patch_cmdline <cmdline entry name> <replacement string>
patch_prop <prop file> <prop name> <new prop value>
patch_ueventd <ueventd file> <device node> <permissions> <chown> <chgrp>

repack_ramdisk
flash_boot
flash_dtbo
write_boot

reset_ak [keep]
setup_ak
"if search string" is the string it looks for to decide whether it needs to add the tweak or not, so generally something to indicate the tweak already exists. "cmdline entry name" behaves somewhat like this as a match check for the name of the cmdline entry to be changed/added by the patch_cmdline function, followed by the full entry to replace it. "prop name" also serves as a match check in patch_prop for a property in the given prop file, but is only the prop name as the prop value is specified separately.

Similarly, "line match string" and "line replace string" are the search strings that locate where the modification needs to be made for those commands, "begin search string" and "end search string" are both required to select the first and last lines of the script block to be replaced for replace_section, and "mount match name" and "fs match type" are both required to narrow the patch_fstab command down to the correct entry.

"scope" may be specified as "global" to force all instances of the string targeted by replace_string to be replaced. Omitted or set to anything else and it will perform the default first-match replacement.

"before|after" requires you simply specify "before" or "after" for the placement of the inserted line, in relation to "line match string".

"block|mount|fstype|options|flags" requires you specify which part (listed in order) of the fstab entry you want to check and alter.

dump_boot and write_boot are the default method of unpacking/repacking, but for more granular control, or omitting ramdisk changes entirely ("OG AK" mode), these can be separated into split_boot; unpack_ramdisk and repack_ramdisk; flash_boot respectively. flash_dtbo can be used to flash a dtbo image. It is automatically included in write_boot but can be called separately if using "OG AK" mode or creating a dtbo only zip.

Multi-partition zips can be created by removing the ramdisk and patch folders from the zip and including instead "-files" folders named for the partition (without slot suffix), e.g. boot-files + recovery-files, or kernel-files + ramdisk-files (on some Treble devices). These then contain zImage, and ramdisk, patch, etc. subfolders for each partition. To setup for the next partition, simply set block= (without slot suffix) and ramdisk_compression= for the new target partition and use the reset_ak command.

Similarly, multi-slot zips can be created with the normal zip layout for the active (current) slot, then resetting for the inactive slot by setting block= to the partition (without slot suffix) again, slot_select=inactive and ramdisk_compression= to the desired options for the target slot and using the reset_ak keep command, which will retain the patch and any added ramdisk files for the next slot.

backup_file may be used for testing to ensure ramdisk changes are made correctly, transparency for the end-user, or in a ramdisk-only "mod" zip. In the latter case restore_file could also be used to create a "restore" zip to undo the changes, but should be used with caution since the underlying patched files could be changed with ROM/kernel updates.

You may also use ui_print "<text>" to write messages back to the recovery during the modification process, abort "<text>" to abort with optional message, and file_getprop "<file>" "<property>" and contains "<string>" "<substring>" to simplify string testing logic you might want in your script.

Binary Inclusion

The AK3 repo includes current ARM builds of magiskboot, magiskpolicy and busybox by default to keep the basic package small. Builds for other architectures and optional binaries (see below) are available from the latest Magisk zip, or my latest AIK-mobile and Flashlt packages, respectively, here:

https://forum.xda-developers.com/sho....php?t=2073775 (Android Image Kitchen thread)
https://forum.xda-developers.com/sho....php?t=2239421 (Odds and Ends thread)

Optional supported binaries which may be placed in /tools to enable built-in expanded functionality are as follows:

mkbootfs - for broken recoveries, or, booted flash support for a script/app via bind mount to /tmp (deprecated/use with caution)
flash_erase, nanddump, nandwrite - MTD block device support for devices where the dd command is not sufficient
dumpimage, mkimage - DENX U-Boot uImage format support
mboot - Intel OSIP Android image format support
unpackelf, mkbootimg - Sony ELF kernel.elf format support, repacking as AOSP standard boot.img for unlocked bootloaders
elftool (with unpackelf) - Sony ELF kernel.elf format support, repacking as ELF for older Sony devices
mkmtkhdr (with unpackelf) - MTK device boot image section headers support for Sony devices
futility + chromeos test keys directory - Google ChromeOS signature support
BootSignature_Android.jar + avb keys directory - Google Android Verified Boot 1.0 (AVBv1) signature support
rkcrc - Rockchip KRNL ramdisk image support

Optionally moving ARM builds to tools/arm and putting x86 builds in tools/x86 will enable architecture detection for use with broad, device non-specific zips.
The Following 118 Users Say Thank You to osm0sis For This Useful Post: [ View ]
5th March 2014, 05:25 AM |#3  
bsmitty83's Avatar
Senior Member
Flag Detroit
Thanks Meter: 10,391
 
More
Boom . dibs on first
You get 2 thank button presses fro me lol
Awesome work man as always
The Following 6 Users Say Thank You to bsmitty83 For This Useful Post: [ View ] Gift bsmitty83 Ad-Free
5th March 2014, 05:32 AM |#4  
Hetalk's Avatar
Senior Member
Flag Ahmedabad
Thanks Meter: 3,159
 
More
Good thing that this amazing work has it's own thread. Congrats buddy.

Sent from my Galaxy Nexus using XDA Premium 4 mobile app
The Following 2 Users Say Thank You to Hetalk For This Useful Post: [ View ] Gift Hetalk Ad-Free
5th March 2014, 05:52 AM |#5  
osm0sis's Avatar
OP Recognized Developer / Recognized Contributor
Flag Halifax
Thanks Meter: 30,581
 
Donate to Me
More
Thanks guys!

I figured it would be nice to get it out there and also have it as a "Help Desk" thread for kernel devs who have questions about implementation, etc. too. Some devices might require switching it from dd to MTD-Utils, so I can help with that. So on and so forth.

Once we get a few devs who know how to use it, it should be pretty easy to help others. I'm looking at you Smitty. No pressure.
The Following 14 Users Say Thank You to osm0sis For This Useful Post: [ View ]
5th March 2014, 06:36 AM |#6  
ak's Avatar
Senior Member
Flag Ak Land Valley
Thanks Meter: 69,895
 
Donate to Me
More
I finished my thanks ... but as always a great job.
The Following User Says Thank You to ak For This Useful Post: [ View ] Gift ak Ad-Free
5th March 2014, 07:12 AM |#7  
Quote:
Originally Posted by ak

I finished my thanks ... but as always a great job.

So wait im confused. ?.. so 1) those that mean I can flash ak kerenl 4.2 with ur any kernel to my 4.4 o.O.
2) those it have to be same kerenl for same phone manufacturer. Meaning can I be stupid enought to flash a nexus 4 kernel in my gnexus?
I understand any kernel cause I have been using smitty so thanks
The Following 2 Users Say Thank You to milojoseph For This Useful Post: [ View ] Gift milojoseph Ad-Free
5th March 2014, 07:17 AM |#8  
osm0sis's Avatar
OP Recognized Developer / Recognized Contributor
Flag Halifax
Thanks Meter: 30,581
 
Donate to Me
More
Quote:
Originally Posted by milojoseph

So wait im confused. ?.. so 1) those that mean I can flash ak kerenl 4.2 with ur any kernel to my 4.4 o.O.
2) those it have to be same kerenl for same phone manufacturer. Meaning can I be stupid enought to flash a nexus 4 kernel in my gnexus?
I understand any kernel cause I have been using smitty so thanks

Haha I wrote "device-specific" in the OP to try and avoid this very confusion.

Since I answered this same question earlier tonight in my Odds and Ends thread I'll just paste it here:
Quote:
Originally Posted by caspboy

so now devs can use kernels from other devices with their roms?

Quote:
Originally Posted by osm0sis

No. That's crazy talk.

The concept of AnyKernel has been around for awhile, (originally by Koushik Dutta/ClockworkMod,) which allows device-specific kernels to be flashed over device-specific ROMs and use the ramdisk that came with the ROM to reduce the chance of any issues arising from the custom kernel pairing.

The drawback to this is that some kernels require modifications to the ramdisk to enable/set up kernel features, but in the old AnyKernel format there was no way to do this. Until now.

AnyKernel 2.0 makes it easy for kernel devs to use a number of simple command methods to automate the process of adding tweaks into a ROM's underlying ramdisk during the flashing process.

Hopefully that helps. Basically exactly what's in the OP since that's where I edited it in from.

The only way I can explain it any further is with the very basics: that kernel boot.img files contain a zImage and a ramdisk. "AnyKernel Classic" just slaps the custom kernel zImage on top of the ROM's untouched default kernel boot.img ramdisk. AnyKernel 2.0 allows kernel devs to also modify the ramdisk to add anything required for kernel features in addition to the usual repacking it with the custom zImage and flashing it.
The Following 4 Users Say Thank You to osm0sis For This Useful Post: [ View ]
5th March 2014, 07:32 AM |#9  
wisefreakz's Avatar
Senior Member
Flag Sampa City
Thanks Meter: 646
 
More
Great thread!! Best of lucky bro!!!

Sent from my Galaxy Nexus using xda app-developers app
The Following User Says Thank You to wisefreakz For This Useful Post: [ View ] Gift wisefreakz Ad-Free
5th March 2014, 07:54 AM |#10  
aosp's Avatar
Inactive Recognized Developer
Thanks Meter: 5,028
 
Donate to Me
More
AnyKernel will work on my phone now 😱 Thanks for enhancing awesome @osm0sis but DrRamdisk to the rest of you guys 😁
The Following User Says Thank You to aosp For This Useful Post: [ View ] Gift aosp Ad-Free
Post Reply Subscribe to Thread

Tags
anykernel, flashable zip, kernel, scripting, template

Guest Quick Reply (no urls or BBcode)
Message:
Previous Thread Next Thread
Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes