How to Dump VEE Memory from a Running Device using IAR with MICROEJ SDK 5

[alex.colleux]

The Heap Analyzer is a set of tools to help developers understand the content of the Java heap and find problems such as memory leaks.

See Heap Dumper & Heap Analyzer documentation to learn more about Heap tools usage.

This tutorial describes how to dump the VEE Memory from a running device in order to analyze it using the Heap Analyzer.

This tutorial is compatible with MICROEJ SDK 5, MICROEJ SDK 6 Heap Dumper documentation is available here.
The below procedure allows to dump VEE memory in a Mono-Sandbox context. Refer to the following documentation to dump VEE memory in a Multi-Sandbox context: Generate VEE memory dump script.

Requirements

• IAR EmbeddedWorkbench version 8.x or 9.x.
• Debug probe attached to a running device.

1) Get the IAR Memory Dump Script

The IAR Memory Dump script is used to automate the heap dump.

Get the proper script, depending on your IAR EmbeddedWorkbench version:

• heapdump_iar8.x.zip (599 Bytes)
• heapdump_iar9.x.zip (602 Bytes)

2) Retrieve the .hex File from the Device

• Register the downloaded .mac script in the debugger project option:

  • Open the Debugger Project option window by clicking on Project > Options... > Debugger > Setup,
  • Check the option Use macro file(s) and browse to the .mac file,
  • Click on OK to confirm:
    
    

• Run your code in debug mode in IAR (or attach to the running target).

The .mac file contains a heapdump() method that allows to dump the VEE memory.
The output folder can be edited in the .mac file.
The default folder is C:\tmp, note that the tmp/ folder needs to be created before script execution, otherwise the script will fail.

3) Trigger the Heap Dump

The heapdump() method can be triggered in several ways.

Trigger the Dump from a Native Function

• In this example, the GC done hook is used to trigger the VM Dump. It is called when calling explicitly a System.gc(); in the application,

• Add the following function in your C code:

  void LLMJVM_on_Runtime_gc_done(){
  
  }
  

• Add the macro heapdump() as an action expression to a code breakpoint:

  • Open IAR Breakpoints window by clicking on View > Breakpoints,
  • Right-Click in the Breakpoints window and select New Breakpoint > Code,
    • In the Break at text field enter: LLMJVM_on_Runtime_gc_done
    • In the Expression text field enter: heapdump()
    • Click on OK.

• When System.gc() will be triggered from the application, the debugger will hit the breakpoint, the heapdump() macro function is executed and the memory is dumped into a *.hex file:
  

  

• The vm_heap.hex file is available in the tmp/ folder:
  

Trigger the Dump from the Debugger View

This method may lead to inconsistent memory dumps if the VEE is running while the dump is triggered.

• In IAR, enable the View > Quick Watch view,

• Pause the debugger,

• In the Quick Watch field, write heapdump() and press enter:
  

  

• The memory is dumped in a .hex file in the tmp/ folder.

4) Visualize the Heap Dump

• In MICROEJ SDK 5, setup the Heap Dumper MICROEJ Tool to generate a .heap file from the .hex memory dump:
  
  
  
  
  
• Click on Run to execute the heap dumper tool,
• An application.heap file is generated in the output folder specified in the launch configuration,
• Use the Heap Viewer tool to inspect the content of the heap.

Alex for MicroEJ