Introduction

smem is a memory tool for analyzing the amount of memory usage
on a Linux system. The 'ps' tool provided with Android only shows the
VSIZE and RSS memory columns. Even if you install busybox on an
android system, that tool's 'ps' will also only show you only the VSIZE
value. VSIZE is the total size of the virtual image, and RSS is the
resident set size - the amount of physical pages accounted by the kernel
to a particular process. These numbers are not very useful to indicate
the actual cost in memory of a particular application or daemon.

smem is a tool that can give numerous reports on memory usage on Linux systems.
Unlike existing tools, smem can report proportional set size (PSS), which is a
more meaningful representation of the amount of memory used by libraries and
applications in a virtual memory system.

Because large portions of physical memory are typically shared among multiple
applications, the standard measure of memory usage known as resident set size (RSS)
will significantly overestimate memory usage. PSS instead measures each
application's "fair share" of each shared area to give a realistic measure.
of the activity of a system during boot.

smem consists of a data capture tool, for use on an android target,
and an analysis tool for use on a development host machine.

Overview of Steps to Use smem

To use smem on an Android System, you need to perform
the following steps:

* install the smem tool on your host machine
* build smemcap on your host machine (or use a pre-built binary)
* install smemcap on your Android target system
* use smemcap to capture the memory information from /proc on the target
* retrieve the collected data from the system
* use the smem tool with the collected data, on the host
* view memory information and charts
* [optionally] provide additional system information

These steps will be described in detail in the following
sections. This paper was written based on Android 1.5
software and SDK.

Building 'smemcap' (or use pre-built binary)

To collect the memory information from the /proc filesystem on the target
you need to run the 'smemcap' program. smem also includes a shell script
called 'capture' which can collect the data on a standard Linux desktop.
However, the Android environment does not have the necessary shell environment
or command line tools for this program to work. So you will need to use
the compiled C program.

Compile the smemcap program as a native Android program against the
bionic C library. Details about this are outside the scope of this
document, but you can use the instructions here:
Compiling Native Apps for Android

Pre-built binary (for G1)

Note: Due to constraints on file uploads on this wiki, I had to upload it as a tar file. Download it and untar with: 'tar -xvf Android-smemcap.tar'

Installing 'android-smemcap' onto your Android target

To install the android-smemcap program on your target, you just need to copy the
program, and make sure it is executable. It is recommended to make a separate directory
for smem capture data, on the /data portion of the target file system. (However,
any writable directory can be used, such as one on an sdcard.)

Collect memory information on the target

Now, to measure the memory usage on the target, use the android-smemcap program to
collect the data from the /proc filesystem.

$ adb shell
$ cd /data/smem
$ ./android-smemcap >memdata1.tar
$ exit

You can also do this directly from the host, using the adb shell:

$ adb shell "/data/smem/android-smemcap >/data/smem/memdata1.tar"

Note the use of quotes to have the shell redirection on the target
stay on the target. Due to the binary nature of the data output
by android-smemcap, you can not redirect it directly through
the 'adb shell' command to the host filesystem.

Retrieving the collected data from the system

Now, collect the data from the target, and retrieve it to the host:

$ adb pull /data/smem/memdata1.tar .

This will pull the just-created file 'memdata1.tar' from the target
and place it in the current directory.

Review the data on the host

Now, you can use the smem tool on the host, to view the target process data:

In this example, my kernel was a test kernel that was significantly larger than a standard production
kernel.

Using the graphical viewer

The graphical viewer provides options for zooming and panning portions of the graph,
for adjusting graph display parameters, switching between views, and saving a view
to an image file.

Here is a snapshot of the smem (matplotlib) chart viewer:

Here are some tips:

Sometimes it is difficult to read the chart labels. You can view the labels more easily
if you pan and zoom the chart.

To zoom in on an area, click on the 'zoom to rectangle' button. Drag a rectangle in the viewing area.
For a bar chart, the rectangle must reside within the graph area of the chart (above the x axis and to the
right of the y axis). Once you unclick your mouse button, a zoomed image is then shown.
You can pan the zoomed image by clicking the 'pan axes' button, and dragging the image with
the left mouse button. (This "pan axes" button puts the chart in 'pan/zoom' mode. Click
the button again to revert to regular view mode.)

You can also zoom using the right mouse button in the 'pan/zoom' mode.

You can adjust the location of the chart on the page (which is also sometimes necessary to see the full labels),
by clicking on the "configure subplots" button. Experiment with changing different parameters, such as the bottom
or left parameters.

Save a view to a file using the "save the figure" button. Select the image format to save in, from the drop-down
list at the bottom of the dialog. Available formats are: bmp, eps, jpg, png, ps, svg.

Interpreting the results

See the smem web site for an explanation of USS and PSS, and how these measurements should be interpreted
to analyze a running system.