Porting Clockwork Recovery to New Devices

Update/Preface:

It is difficult for me to port recovery for a device I don’t have. So, people can attempt to port it using this guide. However, if you want it done properly, and probably quicker, you can loan the device to me personally at:

Koushik Dutta 2721 1st Ave 507 Seattle, WA 98121

The package must include:

  • The rooted phone.
  • A return packing slip to your address.
  • A signed statement saying: “I, <your name here>, am lending this device, <name of device>, to Koushik Dutta so that he can try to port Clockwork Recovery to the device. I understand that rooting a phone voids the warranty and tampering with the software may render the device nonfunctional. I realize and accept that the phone may not be functional when it is returned. Koushik Dutta is not liable for any damages to the device.”
  • BEFORE SENDING ME THE PACKAGE, CONFIRM WITH ME THAT I AM AVAILABLE TO PORT THE RECOVERY.

It will take around a week, and there are no gaurantees whether I will actually be able to do it (due to proprietary software, locked bootloaders, my schedule, etc). After a week (generally quicker), I will send it back. I’m a trustworthy guy and am well known in the Android community. And I’ve already done this for several loaner devices. Smile So you don’t need to worry about the safety of your precious hardware.

Otherwise, continue on the to the guide!

  • This guide will assume you have some familiarity with doing an Android Build.
  • This guide will work for phones that use a standard Android boot image format. This guide will not work for Samsung phones which use an initramfs.

First, let's check out the CyanogenMod tree. The CyanogenMod repository contains Clockwork Recovery, which is part of a full Android build.

repo init -u git://github.com/CyanogenMod/android.git -b gingerbread

repo sync

make -j4 otatools

Now, use dump_image or dd to dump your recovery or boot image from a running phone and copy it to your computer somewhere.

dump_image boot boot.img

To build Android from source for a new device, you need to set up a board config and its makefiles. This is generally a long and tedious process. Luckily, if you are only building recovery, it is a lot easier. From the root of your Android source directory (assuming you've run envsetup.sh), run the following (substituting names appropriately):

build/tools/device/mkvendor.sh device_manufacturer_name device_name /your/path/to/the/boot.img

You will receive the confirmation "Done!" if everything worked. The mkvendor.sh script will also have created the following directory in your Android source tree:

manufacturer_name/device_name

Now, type the following:

lunch full_device_name-eng

This will set the build system up to build for your new device. Open up the directory in a file explorer or IDE. You should have the following files: AndroidBoard.mk, AndroidProducts.mk, BoardConfig.mk, device_.mk, kernel, system.prop, recovery.fstab, and vendorsetup.sh.

The two files you are interested in are recovery.fstab and kernel. The kernel in that directory is the stock one that was extracted from the boot.img that was provided earlier. For the most part, recovery.fstab will work on most devices that have mtd, emmc, or otherwise named partitions. But if not, recovery.fstab will need to be tweaked to support mounts and their mount points. For example, if your /sdcard mount is /dev/block/mmcblk1p1, you would need the following lines in your BoardConfig.mk:

/sdcard vfat /dev/block/mmcblk1p1

Once the recovery.fstab has been properly setup, you can build the recovery using:

make -j4 recoveryimage

Your recovery can then be found at $OUT/recovery.img. If you are in need of building a fakeflash recovery, you will need to run the following to create the update.zip that hot replaces the recovery:

make -j4 recoveryzip

Once this is done, build, and tested, notify me, "koush", on Github and I can build official releases and add ROM Manager support!

Tip: Run "make clobber" between builds if you change the BoardConfig.mk, or the change will not get picked up.

New ROM Manager Feature - Web Connect

Some people really prefer to browse a forum and learn about a ROM before downloading it. And some developers don't want to go through the trouble of maintaining a ROM Manifest.

What if you could click a link on a forum, in your computer's browser, and it started downloading the ROM... on your phone? Introducing ROM Manager's latest and greatest Premium feature: Web Connect.

Enough talking about it. Let's try it! You must have Froyo!

  1. Get the newest ROM Manager (at least 2.0.2.9).
  2. Click the Menu button and click Web Connect to do your one-time setup.
  3. Choose the Google account you are normally logged in with on your computer.
  4. Done!

Now, click this link on your computer to download Superuser... onto your phone:
Superuser 2.3.6.1.

Cool huh? You a developer and want to add support? Use the following to get a bit.ly link set up to your ROM using Web Connect!

Droid X Recovery (and Droid 2 too!)



Well, this was a bitch.

Caveats:
This is not a *real* recovery. The way this recovery works is by hijacking portions of your boot process during system initialization and starting into recovery instead. So, if you hose your system *COMPLETELY* you will need to SBF. Specifically, if your logwrapper, logwrapper.bin, or hijack binary are missing from /system/bin, you will be screwed.

Do I have to be rooted to run this?
Yes.

So can we now install custom ROMs?
Yes, but you can't replace the kernel or boot image. But really, once you have access to /system, anything is possible. It will just take a little hackery.

How does this work?
When your device boots up, there is a init.rc script in your boot image that runs various components found in /system. The Droid X recovery bootstrap mimics the "logwrapper" binary. The hijacker then looks for "/data/.recovery_mode", and if it finds it, it unmounts /system to prevent android from starting. It then starts up recovery instead.

How do I boot into recovery?
You can manually create the /data/.recovery_mode via a terminal file and simply reboot, and you will be in recovery. Or you can use the handy Droid X Recovery Bootstrap application to reboot into recovery.

What if my phone won't boot? How do I get into recovery without the app?
When the hijacker runs, it will automatically create the "/data/.recovery_mode" file after it finishes. This tells the system that the next time it boots, it should boot into recovery. But, when the system starts, the Droid X Recovery Bootstrap will then delete that file when Android is fully started, to prevent you from booting into recovery. So what does this mean? If you fail to boot, simply pull your battery, and your next boot will be into recovery (unless your /system is *really* hosed, in which case you need to SBF).

How do I fix my phone if I really mess it up?
Use an SBF. Google it. http://twitter.com/b16a2smith/status/21544626803

Why does the Droid X Recovery Bootstrap start on boot?
As mentioned above, it needs to log that your phone booted successfully and recovery mode is not necessary. It also replaces your "adb daemon" with one that has root permissions, allowing for easier usage of the adb command.

Will this work with ROM Manager?
Yep! But you must run the Bootstrap app and leave it installed.

Is this open source?
Yep.
Recovery: http://github.com/koush/android_bootable_recovery
Droid X Bootstrap: http://github.com/koush/DroidXBootstrap
Droid X Hijack: http://github.com/koush/android_vendor_motorola_droidx

OK STOP TALKING, WHERE DO I GET IT?
You can donate and grab it for $2 off the Android Market (search for Droid X Recovery Bootstrap or Droid 2 Recovery Bootstrap), or you can download it for free here:
Droid X Recovery Bootstrap
Droid 2 Recovery Bootstrap

What good are ROMs and Themes without a Recovery?

Vote Koush.