A Tour of Windows CE Memory Tools
Posted by: Sue Loh
This list of tools completes what I started with my perf tool list from
Heap Memory Tools
Each of these tools works by hooking all of the heap allocation function calls. The difference is mostly in how they're controlled and how they collect their data.
AppVerifier is Microsoft's official tool for finding the source of a heap leak. It shipped with the CE test kit (CETK) in 4.2 but in 5.0 it ships with the OS. It records a callstack for each heap allocation, discarding data about allocations that are freed. So in the end you can look to see which allocations were not freed, and get callstacks to identify them. AppVerifier can be controlled over KITL from the desktop side, and it also has a device-side UI for controlling it on a standalone device.
In CE 4.2, AppVerifier was shipped as part of the Windows CE Test Kit (CETK), which I think you get as a separate install on top of Platform Builder. In CE 5.0, AppVerifier is included with Platform Builder. I'm actually unsure of whether you get it with Visual Studio or eVC, but I think you can.
AppVerifier is actually much more than a heap tool. You can write an AppVerifier wrapper shim to catch any API call. AppVerifier comes with a set of shim DLLs to wrap heap allocations, handle opens/closes and other interesting events. But you could write your own shim to catch any API call and do something interesting with it. The intention of AppVerifier is to catch programming mistakes in general, at run-time. If you ever asked, "Who is calling API Foo()?" or wanted a log of API calls over time, AppVerifier is the tool for you. You can't ship an OS with shims in it, but you can use shims for all sorts of debugging scenarios.
I talk about CeLog a lot; it's really just a logging engine. But we've gone into the heap APIs and added CeLog logging calls to them, so you can set up CeLog to record a stream of heap calls. It will also record callstacks for the heap accesses. However we don't ship any official tools to process that stream and do things like identify leaks. There's an unofficial tool -- "memalyzer," that you can use. If you have Platform Builder you have memalyzer (it'll be in your path if you open a build command window). Memalyzer parses the CeLog log file and reports any leaks that it sees.
Also I should warn you that we might completely remove memalyzer in favor of AppVerifier. After all, why maintain something that's already replaced. I'd rather have us spend the time to make AppVerifier better.
- Since the memalyzer tool is unofficial, I don't have any public documentation I can point you at. :-( It "just works," right?!
LMEMDEBUG records all the heap operations (plus callstacks) into memory. It discards callstacks for freed allocations, so that you only track callstacks for apparent leaks. It can also give you heap statistics like total allocation counts and bucketed size histograms. It is controlled entirely from the Target Control Window, so it requires KITL. It comes with Platform Builder, and if you do a debug build it'll be built and run by default. On a retail build I think you have to build it manually (see public\common\oak\drivers\lmemdebug).
- The only documentation I know about is in the OS tree, under %_WINCEROOT%\public\common\oak\drivers\lmemdebug\lmemdebug.txt.
Again, I should warn you that we might completely remove lmemdebug in favor of AppVerifier.
Another company, Entrek, has a suite of tools that includes one which can catch heap leaks. I think it is similar to AppVerifier. It's aimed at application developers instead of people who are using Platform Builder.
Despite the fact that they LOOK like they might be useful, I don't find these tools good for investigating heap problems: Remote Performance Monitor, Remote Heap Walker, or the "hd" command in the Target Control Window.
Virtual Memory Tools
The Windows CE virtual memory model (32MB of VM per process) can lead to pain with virtual address space pressure. Unfortunately our tools are not all that great, in my opinion. :-(
The main thing these tools do underneath is call VirtualQuery on the entire range of address space. So with some work you could write one yourself.
"mi" and friends
The Target Control Window (which requires KITL) has a "mi" command to get memory information. If you run that command it'll do a dump of VM usage per process. There's also a standalone version of this tool called "memtool" (it's the same code, built into an EXE). However I am pretty sure that writes to the debug output so it requires KITL too.
- Dang it, where did our more in-depth description of the tool go? Well see the 4.0 docs at http://msdn.microsoft.com/library/en-us/wcepb40/html/_wcepb_Memory_Usage_Tool.asp. I swear we wrote up some more info for 5.0.
DevHealth (Windows Mobile 5 only)
If you have WM5, you should skip "mi" and use DevHealth. It gets all the same information that "mi" does, plus a bunch more. It adds up physical memory usage, and usage per heap. DevHealth is an EXE which you can run on a standalone device, that outputs everything to a text file. It comes with the Windows Mobile Platform Builder install, so if you're an ISV you might have to finagle a copy from somewhere.
- I'm sorry, I don't know exactly where to send you but there is some documentation for DevHealth in the Windows Mobile docs. Those aren't online so I can't give you a link to them.
Update, Feb. 15, 2006: Also see the dumpmem tool, http://support.microsoft.com/default.aspx?scid=kb;en-us;326164