Investigating memory usage with memtrace
tools.memtrace
doclevel v6.1
this chapter documents memtrace to e32toolp release 223 level.
Overview
The memtrace tool can be used to investigate the memory usage of an EPOC system. By default memtrace produces a summary listing showing the high-watermark memory usage of each EPOC process over the course of the run. memtrace can also produce a detailed listing showing how memory usage changes over time which can be used to identify transient spikes in the memory usage of an individual process and of the entire EPOC system.
Invocation syntax
memtrace [-d] tracefile
options :
	-d
where
Logfile	Memory usage trace file	
-d	Indicates that the tool should produce a detailed listing	

memtrace produces output in Comma Separated Variable format on standard output. In normal use one would redirect its output to a .csv file.
Obtaining a trace file
memtrace operates on a file containing memory usage trace information. This file is obtained by capturing kernel trace output from a running EPOC system, starting from system boot. The EPOC kernel will only output memory usage trace information if:
•	A debug build of the kernel is used.
•	Bit 26 of the kernel trace bitmask is set at boot-time – in practice this means that the statement kerneltrace 0x04000000 0 0 0 0 0 0 0 should appear in the rombuild configuration file.
Only a debug kernel will produce memory usage trace information. However in order to obtain representative results all other executables should be release versions.
The kernel trace information appears on a device-specific trace channel. The output of this channel should be logged to a file, starting from system boot. Depending on the device in use this channel may be a serial port, an ARM Embedded Trace Macrocell port or a custom device-specific port. Use of a slow trace channel will impact system performance. In the case where the trace channel is shared with comms protocols then those comms protocols will be unavailable and should be disabled. The kernel trace channel on Symbian reference platforms is the first serial port running at 115200,n,8,1.
The EPOC Emulator kernel can also produce memory usage trace information. However information obtained from the Emulator is likely to be less useful since EPOC processes may behave differently between the Emulator and target devices and since memtrace is less able to correctly assign memory usage to processes using trace information obtained on the Emulator. The Emulator kernel will only output memory usage trace information if:
•	A debug build of the kernel is used.
•	Bit 26 of the kernel trace bitmask is set at boot-time – in practice this means that the statement DebugMask 524288 should appear in the Emulator configuration file (which by default is \epoc32\data\epoc.ini).
•	It is recommended that an appropriate value be supplied in the Emulator configuration file for the MegabytesOfFreeMemory parameter for the device being emulated.
The Emulator kernel produces its trace information using the win32 OutputDebugString API. This output can be captured by starting the emulator from Microsoft Visual C++ and copying and pasting the contents of the “Output” window, or by using a dedicated program such as DebugView from www.sysinternals.com.
Understanding the results
The output from memtrace is a Comma Separated Variable format on standard output. In normal use one would redirect the output to a .csv file which can be read by many spreadsheet programs. The output can be charted using the “Chart Wizard” in Microsoft Excel. When charting a detailed listing use these exceptions from the default values:
•	Choose a ‘Chart type’ of type ‘Area’ (and sub-type ‘Stacked Area’).
•	After applying the wizard change the X-axis format ‘Number Category’ to ‘Number’ with 1 decimal place.
The detailed listing shows how the memory usage of processes and global chunks change over the course of the run. The summary listing shows the high-watermark memory usage of processes and global chunks over the course of the run.
The kernel memory usage trace information is output at the granularity of a system page (i.e. 4K on ARM devices and on the Emulator) and memtrace is unable to show memory allocation at a finer granularity than this. memtrace also groups together the memory allocated by the loader on behalf of a process with memory allocated by different threads within a process. However it lists memory allocated to global chunks (e.g. the font bitmap server shared chunks) separately from the process that created them.
The results produced for kernel memory usage should not be relied on because the kernel is a debug version and because memory used by the kernel for managing memory is not recorded.