This article is in need of a technical review.
Valgrind gives developers access to information about memory allocations, thread/processes, and other things relevant to the performance of a program. It is included in the Firefox OS tree, and can be run on certain phones that have the proper resources. This article explains how to use it.
Before running Valgrind against Firefox OS, it's recommended that developers familiarize themselves with the Debugging Mozilla with Valgrind article. Most of the information it contains is relevant to running against Firefox OS, though many of the build and command line steps are taken care of by the Firefox OS build and execution scripts.
To run Valgrind against Firefox OS on a phone, a phone with higher than normal specs is required. Valgrind is resource intensive, and will generally cause Out Of Memory errors on phones with anything less than 1GB of RAM. As of this writing (2013-12-04), Valgrind is being tested on Firefox OS running on Nexus 4 phones with 2GB of RAM, but it should run on Geeksphone Keons and similar spec phones. Look at Phone and device data for more details of the phones available.
Running Valgrind on FxOS Phones
Let's look at the process of running Valgrind.
To build Firefox OS with valgrind enabled, add the following to to the
Building debug (
B2G_DEBUG) is also recommended. Building with no optimizations (
B2G_NOOPT) makes things run almost unusably slow, and is not recommended except in cases where it is thought that optimizations may be obfuscating errors.
Note: Running Valgrind on a Firefox OS phone is done in the context of the phone, not the host operating system. This means that developers can use any platform that has adb available and will execute the
run-valgrind.sh script to run valgrind on the phone.
To run Firefox OS under valgrind, use the
run-valgrind.sh script from the B2G directory. This script does the following:
- Remounts the phone file system as r/w.
- Copies the current debug
libxul.sowith full symbols to the phone. As this file is many hundreds of MB, this step can take multiple minutes to finish. It needs to be redone every time a new build is made. To run valgrind without the
libxulcopy step, run this command:
- Reboots the phone.
- Kills the b2g process that starts up on phone startup.
- Runs its own b2g process under valgrind.
All valgrind output will be written to the
stdout of the terminal executing the
run-valgrind.sh script. This can either be read in the terminal or piped to a file.
Note: Since the
run-valgrind.sh script owns the adb process running the b2g process, killing the script will also kill b2g and valgrind on the phone. It is recommended that the phone be rebooted after running a valgrind session, as it can leave things in an odd state.
Running Valgrind on Firefox OS Desktop
Running valgrind against Firefox OS Desktop works the same way as running it against desktop Firefox. Consult the Debugging Mozilla with Valgrind page for more information. All of the relevant build flags will need to be added to
mozconfig, and all platform-specific issues in the page will apply.
Note that running Valgrind on the desktop in OOP/process-per-tab mode will require adding the following option to make sure child processes are also traced:
Maintaining and Updating Firefox OS Valgrind
While patches are upstreamed when applicable, Valgrind for Firefox OS is maintained in a forked repository to keep things as up to date as possible while also dealing with the eccentricities of the Firefox OS build tree and versions.
Updating Valgrind Repos
WARNING: EXPERIENCE WITH GIT REQUIRED. Do not attempt to upgrade the valgrind repos if you are not familiar with handling complex Git operations. Any updates to the github repo will mirror to
git.mozilla.org, which will then be pulled by developers using the HEAD of the manifests repo. While breaking Valgrind will not break builds on anything that does not have Valgrind enabled (e.g. Buildbot automation), it will very much annoy developers who are trying to use it.
The main Firefox OS valgrind and VEX repos are at
The master branch is a pristine version of the SVN trunk of each of these repos, while the Firefox OS branch contains Firefox OS-specific patches rebased on top of the trunk.
Note: ALWAYS UPDATE BOTH REPOS AT THE SAME TIME. While they are two seperate repos, VEX is usually a submodule of Valgrind, and the HEAD of valgrind usually points to the HEAD of VEX.
These are replicated onto the
git.mozilla.org domain for use in B2G manifests:
- The main repos are kept in sync with the valgrind SVN with git svn. To pull updates to the repos, clone the valgrind and vex repos from github, then run the following:
git svn init -s [subversion repo url]
- Pulling the SVN info will take hours, but when it is done, your tree should be in sync with the main Valgrind SVN.
- To pull further updates, the following set of commands is used:
git checkout master git svn fetch git svn rebase git push [github-remote-name] master git checkout fxos git rebase master
- There is a good chance that there will be patch conflicts during the Firefox OS branch rebase step. If you cannot work the issue out, email the author of the conflicting commit.
- After rebasing, run a full Firefox OS build with the
B2G_VALGRINDflag to make sure that it still builds. The most common required fixes are listed in the scripts section below.
- Once you have rebased AND TESTED the build against the Firefox OS tree, you will have to force push the Firefox OS branch due to head change.
git push -f [github-remote-name] fxos
Build, Install, and Execution Scripts
There are multiple scripts that are either part of the Valgrind Firefox OS branch or B2G repo that may need to be updated after a repo fetch.
This is the Android build system script. More often than not, this is where changes will need to be made, due to files being added/removed from the Valgrind tree. Use a
-j1 build to see which target is failing to build, and if it is missing a file or referencing a non-existent file, update that project's file list.
This contains the list of packages that need to be built and added to the FxOS system image, referenced by
gonk-misc/b2g.mk. This usually needs no update as it is rare for Valgrind to add new packages, but if they're needed, put them here.
The script for running Valgrind on the phone. If there are new command line arguments that are needed to run Valgrind on the phone, put them here. This is also where we copy the library with debug symbols to the phone, so any adjustment/change to that process should happen here.