Customization Guide

Updated 9/30/2013:This guide is a menu of options to customize your experience after you have installed CM9 on the Samsung Epic 4G.

Battery Optimization Guide

Updated June 2nd, 2012
This guide gives recommendations on Epic 4G batteries, explains the many options you can customize to improve battery life and how to diagnose battery drain problems on CM9 for the Samsung Epic 4G.  Some of this advice is based upon our current understanding of bugs in CM9 and how to best workaround causes of battery drain until the developers are able to fix their causes.  We will update this guide as we learn more.  If you have suggestions for further improve this guide, please reply in the comments below.

Shipping Epic 4G to Spain

Today we bought an Epic 4G from Craigslist for $60.  It works fine but the glass is cracked.  Tomorrow we are shipping it to Spain!  Makes total sense, right?

Sometimes I wish I had a real camera...

The CM9 crespo maintainer KalimochoAz will help us with our kernel-3.0.x port.  We will merge the Epic and Nexus S kernel into the same kernel tree, currently based on kernel-3.0.23.  Epic uses many of the same hardware drivers as crespo.  By merging our kernel source, we can more easily benefit from the combined efforts of our two sizable development and testing teams.  In the medium term we can explore the possibility of merging in other Samsung Galaxy S phones.  In the long-term, we hope to rebase the kernel to upstream kernel-3.4+ after Android mainlining is complete.  Perhaps we will one day be able to push our device drivers to the linux-next staging tree.  That is the vision.

Meanwhile, bbelos will have our team's Nexus S 4G.  He will work with KalimochoAz on the kernel-3.0.x port.  That way both developers will be able to verify that changes made to one phone does not break the other phone.

Should we begin calling it the Nexus Slide? =)

Update 4/25/2012:
This March 6th attempt to ship an Epic 4G to Spain seems to have disappeared in the mail.  We have now shipped another Epic, this time USPS Express Mail International with tracking and insurance.

Update 5/3/2012:
KalimAz finally received an Epic 4G in Spain!

Details on the Disappearing SD Media Issue

As recently noted, we're currently testing a set of fixes for the disappearing SD media/ringtone issue that has been plaguing CM users for quite some time.  First of all, we'd like to thank all the users who submitted details, logs, and dumpstates concerning this problem (and others) and being patient while we investigated the cause.  In particular, if you sent any logs/dumpstates to us, we have read them, and although we haven't been able to personally respond to every report, we still want to say "thanks!" for your instrumental role in helping us figure it out.  So, thanks!

Second, this bug was a real challenge to fix.  Given the strange, "perfect storm"-like conditions needed for it to manifest, and the fact that it affects every CM device with removable storage, we feel it's worth a solid write-up.  So, here we go.

Symptoms

Users have been reporting at least since our CM9 alpha1 release that ringtones, notifications, and other media installed to the SD card occasionally "disappear".  In each instance, the actual SD card files remain intact, but they're lost from the media database that's used by Android for selecting ringtones, notifications, Gallery media, etc.  Usually the problem would be resolved in the short term by rebooting or manually forcing a media scan via Dev Tools.  However, the problem would inevitably come back for most users in a couple of days.  Meanwhile, other users (including myself) experienced lost SD media not even once.

Background

An Android provider application, MediaProvider, is responsible for maintaining databases that provide details on all media stored on the device.  There are separate databases for media on "internal" and "external" (e.g., SD card) storage volumes.

When a device is first booted, the MediaScannerService runs to create (if it doesn't already exist) and populate the "internal" media database by scanning every file in /system/media/.  The MediaScannerService also runs every time an SD card is mounted on the device where it creates and populates the "external" media database by scanning every file in /mnt/sdcard/ (except for directories containing a .nomedia file).

There's three other important features to note about MediaProvider:

1. While a "card-wide" scan is performed on boot and insertion of SD media, individual applications can register new media files in the media database, at any time, by calling the MediaScannerConnection::scanFile method.
2. MediaProvider is designed to support multiple "external" media databases on devices that feature removable storage.  Specifically, it's designed to maintain the three most recent external databases, one for each of the three most-recently inserted SD cards, so that one could cycle through a few different SD cards on their device without having to rebuild the database each time.
3. MediaProvider runs in its own process, "android.process.media", which like any non-critical process, is subject to being killed by ActivityManager so that its resources may be reclaimed.

Bug #1: Google+'s Repeated Registration of "hangout_ringtone.m4a"

It turns out that the trigger for SD media disappearance, in every case we've observed, is actually due to the "odd behavior" of a proprietary third-party application, Google+.  In particular, Google+ installs a media file, "hangout_ringtone.m4a", to /mnt/sdcard/Notifications/ on every (or at least, most) device boot-ups.  Its procedure is to first copy "hangout_ringtone.m4a" from its internal resources to /mnt/sdcard/Notifications/, then call the MediaScannerConnection::scanFile method on the new file to register it in the media database.

We're not exactly certain why Google+ does this on each boot-up, but we do know that often when the copy routine is run, Vold is still performing a file-system consistency check on the SD card.  So the SD card has yet to mount, and thus, the "hangout_ringtone.m4a" appears to not be already installed.

It's probably a bug that Google+ doesn't check Environment::getExternalStorageState to see if external media is mounted yet before performing the file copy.  However, it's definitely a bug that on receipt on a FileNotFoundException during the copy, that Google+ calls MediaScannerConnection::scanFile on the (non-existent) file anyways.

Now, this kind of bug would normally be harmless in the absence of additional bugs within Android itself.  Certainly the operating system should be able to tolerate applications doing "odd", but otherwise harmless activities like attempting to media scan a non-existent file.  However, this bug is still notable in understanding the underlying problem as it serves as a trigger condition for underlying OS bugs that we would otherwise not observe in the absence of this program.  In particular, CM users with Google+ installed appear to have experience disappearing SD media rather frequently, whereas users without Google+ experienced it never.  Even among us developers and testers, it was roughly a 50/50 split of who experienced the problem and who didn't, leaving us a bit baffled.

Bug #2: Media Scanning of (Non-Existent) Files, When the SD Card isn't Mounted, Has the Side Effect of Creating a Second External Media Database

A private method, MediaProvider::attachVolume is called anytime a media scan is performed, in order to "attach" to either the internal, or an external media database, creating it if necessary, prior to performing the scan.  When attachVolume is called on behalf of an application invoking the MediaScannerConnection::scanFile routine, there's no explicit check if external media is mounted before attaching to the external media database.  For the most part, this isn't problematic itself as the database is eventually created and written to storage once the media is mounted.

However, on devices featuring removable storage, the attachVolume method selects a unique database name, "external-XXXXXXXX.db" where "XXXXXXXX" is the hexadecimal representation of the SD card's FAT volume ID, e.g., "external-6997f084.db".  The method responsible for looking up the volume ID, FileUtils::getFatVolumeId, returns the ID as an integer quality, and may return "-1" in the event of an error.  Unfortunately, attachVolume doesn't check for this error condition, and thus, if the method is called when an SD card is not (yet) mounted, it will attach to (and later create if necessary) the database "external-ffffffff.db", where "ffffffff" is the 32-bit hexadecimal representation of "-1".

(An aside: It's not clear me that 0xffffffff isn't a valid FAT volume ID that could be present on an SD card, particularly one that's not formatted by Android.  However, Android implicitly treats it as an invalid ID by reserving that value for the condition of FileUtils.getFatVolumeId's returning error.)

Now, if the above problem were the only media database-related bug in Android, it wouldn't be a particularly big issue.  The "wrong" database is only created when an SD card isn't mounted, and the media scanner scans the entire contents of the SD card on media mount events.  Furthermore, MediaProvider is designed to maintain the three most-recently used databases, so even if the "right" database were to be attached on a subsequent reboot (or other) event, it would only be slightly stale and the mount-time SD card media scan would bring it up to date.

Bug #3: The Media Database Garbage Collector is, Well, Broken

Despite the fact that MediaProvider is supposed to preserve the three most-recently used external media databases, and the fact that Bug #2 erroneously creates only two such databases with a single SD card, we observed that these external databases were being created fresh on attach events, implying that the older of the two databases was constantly being deleted.

The method responsible for deleting old databases, MediaProvider.DatabaseHelper::onCreate, implements an LRU (least-recently-used) garbage collection policy.  The first thing it does is call android.app.Context::databaseList to find the list of MediaProvider's databases.  The databaseList method, as implemented by android.app.ContextImpl::databaseList, literally returns the list of files in /data/data/com.android.providers.media/databases/.  Next, the garbage collector checks the list for databases last modified over two months ago and deletes them.  Finally, it checks the remaining external databases, preserves the three most-recently used (including the one being attached) and deletes the rest.

Unfortunately, the directory /data/data/com.android.providers.media/databases/ contains SQLite temporary files (e.g., ".db-shm" and ".db-wal" files) in addition to the SQLite databases themselves.  These files are returned by the ContextImpl::databaseList method, and are considered as distinct "databases" subject to the garbage collector's deletion policies.

It turns out this breaks the garbage collector in at least two ways.  The first is that the garbage collector may delete one or more of these temporary files, including those associated with the actively-in-use "internal" database.  The other is that these extra files inflate the total number of databases, and so external databases end up being deleted well before the three-database limit is reached.  In short, the garbage collector code works only, and coincidentally, in the single circumstance where exactly one external database exists alongside the internal database.  In the presence of two or more external databases, which we have due to bug #2, the older of the two is inevitably deleted.

(Aside #2: Although we consider bug #3 to exist within MediaProvider's garbage collector, the "actual" bug may lie in the ContextImpl::databaseList and ContextImpl::deleteDatabase methods, depending on one's perspective.  It's quite reasonable to assume that these methods should return only actual databases, hiding their associated temporary files and handling their deletion internally.  If these methods, which are part of Android's public API and used by third-party applications, were to be modified in this fashion, then the MediaProvider database garbage collector would be correct as is.)

The "Perfect Storm" Condition

Even with the above two OS bugs, if MediaProvider were to only attach once to an external database for the duration that SD media is mounted, these problems wouldn't be observed by users.  That's because, regardless of which database is attached to, and whether it's up-to-date, stale, or brand new, the mount-time SD card media scan would still bring it up to date.

For SD media to disappear, MediaProvider has to attach to external databases at least twice during the same mount period, which as it turns out, does happen.  The exact sequence of events that results in the disappearing of SD media is as follows:

• Shortly after boot, a third-party application (e.g., Google+) issues a MediaScannerConnection::scanFile on a (non-existent) SD card media file, prior to the SD card being mounted (bug #1).
• When the scanFile call is issued, MediaProvider attaches to the wrong external database, "external-ffffffff.db", due to the missing error check on the FileUtils.getFatVolumeId call (bug #2).
• Once the SD card is mounted, MediaProvider creates the "external-ffffffff.db" database and populates it by scanning every file in /mnt/sdcard/.
• When creating the new, wrong, "external-ffffffff.db" database, the garbage collector deletes the old, right, "external-XXXXXXXX.db" database (bug #3).
• Some time later, the MediaProvider process is killed by ActivityManager so that its resources may be reclaimed ("perfect storm" condition).
• Later yet, a new MediaProvider process is spawned to handle a media database query for an incoming call, notification, etc., at which point SD media disappears.

Now, in the last event, since the SD card is already mounted, the new MediaProvider instance attaches to the right, previously-deleted external database "external-XXXXXXXX.db" and creates it.  Since this happens outside a media mount event, the media scanner does not run and the database remains empty.  And the database will continue to remain empty while processing subsequent ringtone, notification, and other media events until reboot or a forced media scan.

So that's the story on disappearing SD media, in a nutshell. =)

Aftermath

We've created two issues in CM gerrit that patch bugs #2 and #3.  We're currently testing these patches and expect them to be included in the Epic CM9 alpha6 release.  Once they're committed from gerrit, they should make it into following round of CM9 nightlies for other devices.  We're also looking into backporting these patches to CM7 as well.  Hopefully, that'll be the end of it.

If you appreciate our work, please support the Epic CM team.  Follow us on Google+, Twitter or Facebook.

The Road to CM9 beta0 for Epic 4G

UPDATE: CM9 beta0 has been released! 

Flashable Bootanimations for the Epic 4G

Customize your Epic 4G boot animation with our CWM5 flashable .zip's below.  These should work on any Epic 4G ROM, BML or MTD, stock Samsung-based, CM7 or CM9 as long as your CWM5 has a proper /etc/fstab.  These are installed as /data/local/bootanimation.zip, which means it persists through future upgrades of CM9 until you remove it.  Below we also provide a convenient add-on boot animation remover.

• CM9 version 2, 24fps (as included in CM9 beta1 through beta4 for Epic 4G)
  md5 7006a66c8c24b31be4df2fc1880b8b2b
• Flash this if you want the old Andy boot animation.  Use the Remover below to revert to the boot animation included in your ROM.
• CM9 version 1, 40fps (TOO BIG AND SLOW)
  md5 9500153830ca6bd31144f8d2cd0a9330
• Full CM9 animation, optimized by Rodderik for smaller file sizes. This matches the boot animation in the original Youtube video.  The frames per second and file sizes are so large that it substantially slows booting your phone.
• This is why we didn't include this in CM9 alpha5.  The version included in CM9 alpha5 is only the last half, and with half frames removed, and at almost 25% the frame rate in order to allow the phone to boot faster.
• ICS stock animation
  md5 8625a2a234d3aadd4b982d849ff7a1a9
• Nexus ICS stock animation (below).

• Add-on Boot Animation Remover
  md5 664c409202708b68163cdd338d8d3e78
• Flash this in CWM5 to remove the add-on boot animation.

Discuss this on the Tips & Customization thread on XDA.

CM9 alpha5 for Epic 4G released

The Epic CM team is proud to announce the release of CM9 alpha5 for Sprint's Samsung Epic 4G. Please follow us on Google+, Twitter or Facebook!

Release Notes - IMPORTANT

• New gapps-ics-20120224-signed.zip is recommended for alpha5 if you choose to use gapps.
• Do not restore backups of core system app data, like for Phone, Contacts, Messaging or Calendar.  Doing so will likely break MMS or Calendar sync.
• Alternate Kernels, Themes or Mods you download from other sites replace arbitrary chunks of the operating system.  If you change the operating system, you are no longer running Epic CM9 alpha5.  If you run into trouble, you need to seek support from the author of that mod. If you reinstall CM9 stock OS + kernel and are still able to reproduce the bug, then you may seek support here. 

Changelog

• Fix to allow Chrome Beta to work on CM9.
• Fix that prevents the modem from crashing in certain conditions.
• Fixed ability to turn off blinking LED during low battery.  Blinking LED causes the battery to drain faster.  Settings > Display > Pulse low battery light.
• Slick new CM9 Bootanimation by Cameron Bezadpour, optimized for Epic by Rodderik.

Links

See the CM9 Status page for more details. Then proceed to the CM9 Install Guide.  Please check if your bugs are already filed in the Epic CM Issue Tracker.

If you appreciate this work, please consider supporting the Epic CM team. Thank you!

Coming soon in CM9 alpha5 for Epic 4G

Update: CM9 alpha5 has been released!

CM9 alpha4 for Epic 4G released

The Epic CM team is proud to announce the release of CM9 alpha4 for Sprint's Samsung Epic 4G. Please follow us on Google+, Twitter or Facebook.

Release Notes - IMPORTANT

• You must install the new gapps-ics-20120215-signed.zip after you install alpha4 or some components will be missing.
• Do not restore backups of core system app data, like for Phone, Contacts, Messaging or Calendar.  Doing so will likely break MMS or Calendar sync.
• Alternate Kernels, Themes or Mods you download from other sites replace arbitrary chunks of the operating system.  If you change the operating system, you are no longer running Epic CM9 alpha4.  If you run into trouble, you need to seek support from the author of that mod. If you reinstall CM9 stock OS + kernel and are still able to reproduce the bug, then you may seek support here. 

Changelog

• Fixed the much hated Ringing of Death bug.  This was the short chirp before the ringtone, or constant ringtone that would play during or after an incoming call.
• Fixed ICS multitouch protocol in qt602240 driver.  This should make it possible to play certain multitouch games like Dead Space™.  It also fixes the touchscreen driver with CWM 5.8+ (not released by koush yet).
• LED notifications have been changed to enable significant power savings.  LED notification has been changed to blink every 15 seconds, roughly matching the delay in Samsung's EL30.  This alone eliminates ~71% wakelocks, while previously the CPU was unable to sleep at all while the notification LED is blinking.
• LED notifications may be turned off entirely for additional power savings.  Settings > Display > Pulse notification light.  This allows you to continue to hear the notification chime and vibration without the added battery drain of LED blinking.
• Adjusted heap settings to match crespo.  This is very similar to a popular tweak in the forums.  It prevents some Out of Memory crashes (i.e. NPR News).  You can use these three lines in /system/build.prop to benefit from this tweak prior to alpha4.
• dalvik.vm.heapstartsize=5m
• dalvik.vm.heapgrowthlimit=48m
• dalvik.vm.heapsize=128m
• Dialer will no longer lockup in rare occasions.
• Numeric battery % indicator now works!

Links

See the CM9 Status page for more details. Then proceed to the CM9 Install Guide.  Please check if your bugs are already filed in the Epic CM Issue Tracker.

If you appreciate this work, please consider supporting the Epic CM team. Thank you!

EL30 Factory Firmware Image

We have a surprise for you - an untouched, factory EL30 TAR!

Get links and installation information after the break!

Coming soon in CM9 alpha4 for Samsung Epic 4G

UPDATE 2/19/2012: CM9 alpha4 has been released.

CM9 alpha3 for Epic 4G released

The Epic CM team is proud to announce the release of CM9 alpha3 for Sprint's Samsung Epic 4G. Please follow us on Google+.  Read what is coming soon in alpha4.

Release Notes - IMPORTANT

• Help Needed! We have identified a serious but rare issue called the Ringing of Death that a few CM9 users have reported.  We were unable to fix it for alpha3, but we suspect it has something to do with audio routing from the radio.  It would help tremendously if we can figure out a reproducible method to trigger this bug.  Please follow the directions and report here if you have any experiences with this issue and have time to help.
• If you are upgrading from alpha2...
• Go into Mobile Network's settings page and select Auto:Domestic Roaming.  This will make sure that if you unintentionally disabled Roaming in a previous alpha release it will work.  Data wipe does not fix this issue it is stored in the radio NVRAM.
• If you use Sprint VM and are not clearing data go into the Phone app and open Settings>Voice Mail Settings and change the VM number from *86 to your phone number.
• The Install Guide has a new version of gapps-ics.  You really do not need to upgrade unless you want working Picasa sync integrated with Gallery.  It also fixes automatic reinstall of your previous apps from Market.

Changelog

• Battery Related
• Fix automatic brightness setting.  In alpha2 you could save power by turning off automatic brightness and manually reducing brightness. This is fixed by updating the array values for brightness levels to match CM7 and stock.  This reduces wasted power and hot screens reported by some users.
• Capacitive buttons backlights (Menu, Home, Back, Search) now mimic TW behavior by turning off the backlight after a 6 second timeout.  This both saves battery and improves the user experience in darkness.
• Fix the power profile.  Previously battery usage blame percentages were less accurate.
• LED charging indicator no longer turns off after you dismiss a notification.
• Switched to crespo kernel audio driver.  The kernel audio driver (wm8994) now matches the userspace driver (libaudio) we added in alpha2.  Should hopefully resolve speakerphone mic issues.
• Voicemail default number is set to your phone number and not *86 by default on new installs.
• MMS now shows profile faces.
• Fix roaming bug.  Prior to alpha 3 opening Mobile Networks settings unintentionally disabled roaming.  Folks upgrading from alpha2 should open System settings and ensure Auto: Domestic Roaming is selected to enable roaming support.
• Added roaming options.  Alpha3 includes domestic, international, both, and no roaming options as found in gingerbread TW ROMs.
• Fixed the annoying "Data usage warning" that was previously impossible to dismiss from the notification window.
• Removed Chinese and Japanese IME.  Install the better IME's from Android Market if you need Asian language input.

Links

See the CM9 Status page for more details. Then proceed to the CM9 Install Guide.  Please check if your bugs are already filed in the Epic CM Issue Tracker.

If you appreciate this work, please consider supporting the Epic CM team. Thank you!

Epic CM Issue Tracker

We now have the Epic CM Issue Tracker to help us organize and prioritize our development.  Please do not report if your issues have anything to do with:

• Non-standard CM9 kernels.
• Voicemail - already known solutions for that problem. 
• Already listed on the CM9 Status page.

Nexus S 4G KANG to Epic 4G

Today I had an opportunity to purchase a Nexus S 4G with clean ESN from Craigslist at a bargain price of $140.  We wouldn't be able to buy dev phones like this if it were not for Epic community donations.  There is much we can learn from this very similar phone to improve Epic's ICS experience.  Their similarity helps us to be able to compare Epic's behavior, code and bugs to Google's leaked Android 4.0.4 and CM9 Android 4.0.3.

Below are a few thoughts after examining AOSP 4.0.4 and CM9 4.0.3 on how we can improve Epic CM9:

• Sprint PRL and Profile update (and Activation?)
• Auto-brightness more responsive than Epic.  It also seems to be more dim than Epic, saving extra battery.
• Strength of haptic feedback is much weaker than Epic.  Onscreen keyboard seems to be 10% of Epic, just barely enough to feel it.  This points toward yet more opportunities to tune Epic for battery savings.
• CM9 has built-in tuning options for the CPU governor.
• CM9 has built-in tuning for Voodoo color.  It does however seem to suffer from the same ugly color gradients that happen on Epic when we tried a Voodoo color port.  The Epic CM team will need to determine if we can fix the Voodoo defaults to not be ugly, and decide if we want to later include Voodoo color in the default kernel.
• CM9 Nexus S 4G includes overclocking.  The Epic CM team has not yet decided if we will include overclocking in the default kernel, because stability is our top priority.
• CM9 Nexus S 4G uses the 3.0.17 kernel with Kernel samepage merging (KSM), with a convenient menu option to enable it in Settings > Performance > Memory management.  KSM frees up ~2-15MB of RAM but at a heavy cost, constantly scanning memory for pages to unify, eating battery and preventing the processor from sleeping.  Epic's kernel already appears to give ~11MB more RAM to userspace than Nexus S 4G.  We will probably have KSM as an option after Epic ports to a 3.x-based kernel, but we will not likely recommend its use.  There are other approaches like the CMA allocator or hardware accel blacklist that would save us a lot more memory without such heavy cost of CPU.
• We need to port Epic's current 2.6.35-based kernel to 3.x.  It now appears that merging with KalimochoAz's crespo kernel would be a good idea.  jnadke is working on this general issue.

If you appreciate our work, please consider supporting the Epic CM team.