Repository navigation
Memory Reverse Engineering and Profiling
This guide covers process memory inspection and cross-rank byte diffing (MemView), virtual memory and heap-caller profiling (MemoryProfilerWidget), interactive pointer and struct graph visualization (PointerGraphDialog), ELF64 disassembly, 2D Control Flow Graphs, decompilation (DisassemblyView), and CPU register telemetry (RegisterView).
Open the Memory View tab in the bottom dock (Alt+4 -> Memory View). Ensure HEX DUMP is selected in the top bar.
-
Source Status Badge: Shows
IDLE (NO BINARY),STATIC ELF (READ-ONLY)(reading virtual sections directly from disk viaElfBinaryInspector),LIVE RANK N (PID P), orREMOTE RANK N (...). -
Fast
process_vm_readvPath (NativeMemoryReader+MemoryBoundsValidator):- For local live processes, GridLock reads target memory directly via Linux
process_vm_readv, enforcingMIN_VALID_BASE_ADDRESS >= 0x1000, natural element/stride alignment, 64-bit overflow guards, and a64 MiBper-transfer cap before falling back to GDB/MI or DAP memory reads whenptrace_scoperestricts cross-process reads or when connected to a remotegdbserver/qemu-usertarget.
- For local live processes, GridLock reads target memory directly via Linux
-
Seeking to an Address or Expression:
- Enter a hex address (
0x404040), decimal literal (0d16384), symbol/pointer variable (send_buf.data()), or register ($rsp) inAddr:, setBytes:(1..4096, default256), and clickRead(or pressEnter). - Left-clicking any
0x...pointer value in theVariablesdock automatically reads 256 bytes from that address intoMemView.
- Enter a hex address (
-
Step Mutation Highlighting: Bytes that changed since the previous debugger stop are highlighted in bold red (
#f44747) across the 16-byte-per-row hex and ASCII columns. -
Standalone Pop-Out Window: Click
⤢ POP OUTin the top-right corner ofMemViewto detach the entire memory inspector (1280x820) onto a second monitor; click⤡ DOCK(or close the window) to snap it back into the bottom dock.
- Pause at least two MPI ranks at a synchronization point (for example before
MPI_AllreduceorMPI_Barrier). - Enter the buffer address or expression (such as
&packetordomain.data()) inAddr:and setBytes:. - Set
Base:(for example0) andTarget:(for example1or2), then clickDiff Ranks. -
MemViewcomparesBaseagainstTargetbyte-by-byte (usingMemoryDiffer::compareMemoryoverprocess_vm_readvwhen addresses match, or per-rank debugger evaluation when ASLR/stack addresses differ). Every differing byte is highlighted in bold red (#f44747); hover over any red byte to see a tooltip showingBaseline: 0x.. | Target: 0x...
- Read the desired buffer into
MemView(Addr:andBytes:). - Select the element type in
Type::Int32(int32_t),Float(float), orDouble(double). - Click
Exportand choose an output path:-
CSV Files (*.csv): Unpacks the buffer as a typed row-major CSV slice (std::setprecision(9)) viaMemoryExporter::exportToCsv. -
Binary Files (*.bin): Writes the exact raw byte slice verbatim viaMemoryExporter::exportToBinary.
-
Inside Memory View, click LIBRARY MEMORY MAP in the top bar to switch from the hex dump to the virtual memory profiler.

-
/proc/<pid>/smapsVMA Categorization: ParsesSize,Rss, andPrivate_Dirtyacross all mapped regions of the selected rank (Rank 0 .. Rank N-1orAll Ranks Overview) and classifies each region into five categories:-
Shared Lib: Loaded.solibraries (libmpi.so,libc.so,libstdc++.so, CUDA/ROCm runtimes). -
Heap / Call Site: Process[heap]and attributed dynamic allocations. -
Anon mmap: Anonymousrw-pmappings outside[heap]. -
MPI /dev/shm: Shared-memory transport segments (/dev/shm/*, POSIX shm, XPMEM/Vader buffers). -
Stack: Thread[stack]mappings.
-
-
LD_PRELOADHeap Caller Attribution (Track Heap Callers (LD_PRELOAD)):- Checked by default. When
gccorccis available, GridLock compiles a small interposition library (/tmp/gridlock_memtrack_v2_<uid>.so) and injects it viaLD_PRELOADinto GDB-spawned ranks. - Allocations
>= 4 KBviamalloc,calloc,realloc, andfreeunwind pastlibstdc++operator newframes using_Unwind_Backtrace,dladdr, andaddr2line, writing live call-site totals to/tmp/gridlock_mem_<pid>.tsvand deducting attributed heap bytes from the raw[heap]bucket so totals are never double-counted.
- Checked by default. When
-
Proportional Bar & 2D Treemap (
MemoryTreemapCanvas): Hover over any tile to inspectCategory,Live / RSS,Private Dirty, and symbol/range details. Single-click a tile to select its row in the breakdown table; double-click any tile or table row to jump straight back toHEX DUMPat that mapping's start address. -
Sortable Breakdown Table: 6 columns (
Library / Region,Category,Live / RSS (MB),Private Dirty (MB),% of Total,Top Symbol / Address Range) with numeric MB/% sorting and instant substring filtering (Filter libraries, symbols, or categories...). -
5 Color Schemes (synced with
Edit -> Preferences -> Appearance -> Memory Map Color Scheme):-
Distinct(category and library distinct hues, default) -
Viridis(perceptually uniform sequential green-blue-yellow) -
Plasma(perceptually uniform purple-orange-yellow) -
Ocean(cool-to-warm blue-cyan) -
High-Contrast(Okabe-Ito colorblind-safe palette)
-
Open Tools -> Pointer & Struct Graph Visualizer... from the menu bar, or right-click any struct/pointer variable in the Variables dock and select Visualize in Pointer / Struct Graph....

-
Graph a Root Expression: Type a C/C++ struct or pointer variable (such as
sim,pkt,cfg, orhead) into the top input box and clickGraph Expression(or pressEnter). -
Interactive Dereferencing (
➔ Deref):- Each card displays
expression : Type @ 0xAddressand lists its member fields (name : value (type)). - Non-null pointer and composite fields show a clickable
➔ Derefpill badge (null pointers display a mutednullptrbadge and are guarded against dereferencing). - Click
➔ Deref(or double-click a field row) to expand that child node live viaIBackendCoordinator::requestVariableChildren, or clickExpand All Pointers (1 Hop)on the toolbar to expand every visible frontier pointer by one level.
- Each card displays
-
Cycle and Shared-Alias Detection:
- Cards are deduplicated by normalized virtual address (
0x...), so multiple pointers referencing the same heap object converge onto the same card. - Forward tree edges render as solid cyan (
#38bdf8) cubic Bezier curves. Back-edges (linked-list rings, parent pointers) and multi-parent shared aliases render as dashed amber (#f59e0b) curves labeledCYCLE / SHARED ALIAS.
- Cards are deduplicated by normalized virtual address (
-
Layout and Navigation: Drag cards freely on the canvas, pan with mouse drag, click
Auto-Layout (Layered DAG)to arrange nodes left-to-right by depth, useZoom +,Zoom -,Fit,Clear Graph, and✕ CLOSE.
Press Alt+2 for the full-width REVERSE perspective, or inspect assembly alongside C/C++ code in the CODE perspective (Alt+1).

-
CFG (Space)/Linear (Space): PressSpace(or click the top-right toggle button) to switch between:-
Linear Assembly: Intel-syntax disassembly (
objdump -d -l -C -M intel) with a46pxleftBranchFlowGutterdrawing multi-lane forward/backward conditional and unconditional jump arcs, emerald▶PC chevrons, and amber◆bookmark diamonds. -
2D Control Flow Graph (
CfgGraphView): Basic-block cards connected by orthogonal true (green), false (red), and unconditional (blue) edges, annotated with live MPI rank badges ([R0],[R0-R3 (4)]),[DEADLOCK]alerts, and a120x90bottom-right minimap. Pan with middle-drag,Space+left-drag, orLeft/Rightarrow keys; pressHometo snap back to the active block.
-
Linear Assembly: Intel-syntax disassembly (
-
DECOMPILERandSPLIT (CFG+DECOMP):- Generates structured
Approx C,C++ / MPI, orPseudocode(selectable in the footerTarget:dropdown, withAutorefresh and manualRefresh). - Clicking any line in the decompiler or
SourceCodeViewjumps the linear disassembly, CFG, andMemViewto the corresponding DWARF instruction address; selecting any identifier token (2..32chars) highlights every occurrence across assembly, CFG blocks, and decompiled output. - By default, the decompiler pane hides automatically when
SourceCodeViewalready shows matching DWARF source; enableShow Pseudo-C Decompiler when Source Editor is visibleinPreferences -> Debuggerto keep all three panes open together.
- Generates structured
-
Cross-Reference Inspector (
XrefInspectorDialog): PressX(or right-click ->Inspect Cross-References (X)) to inspect incoming callers/branches (XREFS TO) and outgoingCALL,CJMP,JMP, and RIP-relativeDATAreferences (XREFS FROM) with a live filter bar and assembly preview pane. Double-click any row to jump to that address. -
Right-Click Context Menu (Linear Mode): Provides
Seek in Memory View,Inspect Cross-References (X),Lookup in Reference Manual (F1),Toggle Bookmark(auto-synced with source breakpoints), andPatch Instruction(nop). -
Instruction & ELF64 Patching: Press
Ctrl+Shift+PinDisassemblyViewto assemble/patch an instruction at the current address (splicing; [PATCHED]into the listing and updatingElfBinaryInspector's in-memory section image viawriteVirtualMemory, which can be written out as an executable ELF64 binary viaElfBinaryInspector::savePatchedBinary).
-
RegistersDock (RegisterView):- Pins
rip,rsp, andrbpat the top, color-coding instruction pointers, stack pointers, andeflags. - Changed register values highlight in bold red on each step.
- The search bar (
Filter registers by name or hex/dec value...) matches register names, hex strings (401125), and converted unsigned decimal values. Double-clicking any register seeksDisassemblyViewandMemViewto its pointer value.
- Pins
-
Bottom Status Bar Telemetry (
ElfBinaryInspector):- Displays
ARCH, focusedMPI RANK, activePC/SEEK, sessionSTATUS, per-rankSTACK(active frame deltastackTop - $rspplus mapped[stack]RSS) andHEAP([heap]RSS from/proc/<pid>/smaps), plus hostRAM(/proc/meminfo) and deltaCPU %(/proc/stat), configurable asGB,%, orBothinPreferences -> Behavior.
- Displays
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
Getting Started
User Reference
- Keyboard Shortcuts
- UI & Debugging Manual
- MPI Diagnostics & HPC
- Memory, RE & Profiling
- Configuration & Themes
Internals & Plan