Skip to content

User Guide

github-actions[bot] edited this page Nov 18, 2026 · 2 revisions

GridLock User Guide

Looking for a hands-on walkthrough with the 7 bundled MPI showcase programs (deadlock_ring.cpp, inspection_demo.cpp, collective_mismatch.cpp, ghost_cell_drift.cpp, heap_imbalance.cpp, tag_mismatch_stall.cpp, and simd_struct_watch.cpp)? See the Hands-On Tutorial (docs/TUTORIAL.md) for step-by-step examples, MemView DIFF RANKS and EXPORT, offline man / Zeal docsets (F1), and the PACKAGE MANAGER dock.

GridLock Workspace Overview

1. Launching & Stepping an MPI Target

  1. Select a Target and Rank Count (-np):
    • Pick one of the 7 bundled MPI showcase programs (inspection_demo (MPI), deadlock_ring (MPI), collective_mismatch (MPI), ghost_cell_drift (MPI), heap_imbalance (MPI), tag_mismatch_stall (MPI), simd_struct_watch (MPI)) or choose Open ELF / Binary... in the TARGET dropdown on the main toolbar.
    • Set the number of MPI processes (1..64) in the RANKS (-np) spin box.
  2. Choose a Debugger Backend (Edit -> Preferences -> Debugger):
    • Select the local debugger backend in the Debugger Engine dropdown: GNU GDB (gdb), LLVM LLDB-DAP (lldb-dap), NVIDIA CUDA-GDB (cuda-gdb), or AMD ROCm GDB (rocgdb).
  3. Start the Session (▶ Run Target):
    • While idle, only ▶ Run Target is enabled; stepping and stop buttons remain disabled until a target is running.
    • Clicking ▶ Run Target starts the MPI ranks in the Server Rack panel, pauses Rank 0 at main, marks the active source line in SourceCodeView, and enables the stepping controls.
  4. Step Instructions (↷ Step Inst):
    • Clicking ↷ Step Inst advances the active rank's instruction pointer (rip) and updates the disassembly view, CFG, decompiler, registers, rank status cards, memory view, and source editor together.
  5. Stop or Terminate (■ Stop / ✕ Terminate Session):
    • Ends the debugging session, clears the execution marker, and returns the toolbar to its idle state.

2. Source Editing, Split Views & Project Tree Operations

  • Project Explorer (FILES Tab): Right-click inside the FILES tree in ProjectExplorerWidget to create a new source file (New Source File (.cpp)), create a header (New Header File (.hpp) with #pragma once), create a directory (New Folder), rename an entry (F2), or delete a file. Newly created .cpp files can be registered directly in meson.build or CMakeLists.txt.
  • Unsaved Buffer Markers & Saving: Edited tabs display a ● prefix (● main.cpp) until saved with Ctrl+S (or Ctrl+Shift+S to save all modified tabs). Closing a modified tab prompts to save or discard changes.
  • Split Editors & Header/Source Toggle (F10): Split the editor horizontally (Split Right) or vertically (Split Down) in EditorTabManager to view two files at once, and press F10 to jump between a .hpp header and its matching .cpp implementation file.
  • Scope Breadcrumb Bar & Git Diff Gutter: The bar at the top of the editor shows the current file, struct/class, and function (File > Class > Function). The right edge of the line-number gutter marks lines added, modified, or deleted relative to git diff.

3. Editor Gutter, Conditional Breakpoints & clangd LSP

Cursor-Anchored Breakpoint Popover

  • Two-Lane Gutter (SourceCodeView): The source editor gutter keeps breakpoint markers (●), conditional breakpoint badges (?), and the current execution arrow (▶) in their own column next to the line numbers so they never overlap.
  • Hover Preview: Moving the cursor over the gutter highlights the line and shows a preview dot where a click will toggle a breakpoint.
  • Conditional Breakpoint Popover (ConditionalBreakpointDialog): Right-clicking a line in the gutter opens a compact popover next to the cursor:
    • Line Preview: Shows the line number and the C/C++ statement at that line.
    • Rank Filter: Choose All MPI Ranks or Focused Rank Only to control which ranks stop at the breakpoint.
    • clangd Autocomplete: As you type a condition (such as rank == 0 or data[i].), GridLock feeds the expression to clangd at that line in the file so you get completion suggestions for local variables and struct fields.
    • Save or Remove: Press Enter (Done) to apply the condition, or click Remove Breakpoint to delete it.
  • Inline Diagnostics & AST Navigation (ClangdLspClient):
    • Diagnostics & Hover: Compiler errors and warnings are underlined directly in the editor, and hovering over a symbol shows its type signature and Doxygen summary.
    • Go to Definition (F12), Find References (Shift+F12), and Rename (Shift+F6): Jump to a symbol's declaration/definition with F12, list all references in the document with Shift+F12, or rename an identifier across the AST without touching comments or string literals with Shift+F6.

4. Bottom Tool Rail & Panel Groups

Bottom Tool-Window Rail — Debug Mode

The bottom dock uses a vertical icon rail on the left to switch between four panel groups:

  • Debug: Shows GDB Console, Memory View, and Evaluator for low-level process inspection.
  • MPI: Shows MPI Diagnostics and Package Manager. Inside MPI Diagnostics, a toolbar switches between the DEADLOCK ANALYZER and NETWORK LOG views, displays a rank summary, and exports diagnostic reports.
  • Terminal: Opens the embedded PTY Terminal (QTermWidget).
  • Docs: Opens the offline Reference Manual for browsing Zeal docsets and system man pages.

Bottom Tool-Window Rail — MPI Diagnostics Mode


5. Searching HPC & System Packages ("mpi" Walkthrough)

Package Manager — MPI Table View

The Package Manager tab (HpcConsoleWidget) checks which MPI libraries and development packages are installed on your machine or cluster node:

  1. Supported Package Managers: Checks for available backends automatically in order: Spack (spack), Pacman (pacman), DNF (dnf), APT (apt / dpkg-query), Zypper (zypper), RPM (rpm), and EasyBuild (eb).
  2. Searching for "mpi" Packages:
    • Click MPI on the bottom tool rail and select the Package Manager tab.
    • Type "mpi" into the search box or click Refresh.
    • Filter by All, Installed Only, or Available, or pick a specific package manager from the Backend dropdown.
  3. Display Modes (Table | List | Raw):
    • Table: Sortable columns (Package Name, Version, Arch, Source / Repo, Status, Summary) showing installed and available packages (such as openmpi, mpich, hypre, fftw-mpi, and scalapack).
    • List: Summary cards showing package name, version, repository, install status, and description.
    • Raw: Unformatted command-line output from the underlying package manager.

Package Manager — MPI List View


6. SLURM Batch Script Import & Project Build Runner

Preferences — 16-Directive SLURM Batch Auto-Detection

Importing #SBATCH Job Scripts (Edit -> Preferences -> HPC / Cluster)

  • Click Browse / Load Batch Script... or paste a SLURM batch script into the SLURM Batch Script Auto-Detector box in PreferencesDialog.
  • GridLock reads #SBATCH flags (--job-name, --partition, --account, --qos, --nodes, --ntasks, --ntasks-per-node, --cpus-per-task, --gres, --mem, --time, --constraint, --reservation, --chdir, --output, --error) along with module load lines and fills in the cluster launch settings automatically.

Building Projects (Build -> Build Target (F7) / Clean / Rebuild)

  • GridLock checks the project directory and runs the matching build tool:
    • Meson (meson.build): Runs ninja -C builddir (and ninja -C builddir -t clean).
    • CMake (CMakeLists.txt): Runs cmake --build build --parallel (and cmake --build build --target clean).
    • GNU Make (Makefile): Runs make -j$(nproc) (and make clean).
    • Single MPI Source File: Compiles standalone .cpp or .c files with mpicxx -g -O0 (falling back to g++ -g -O0).

7. Switching Perspectives (Alt+1 / Alt+2 / Alt+3)

  • CODE (Alt+1): Side-by-side C/C++ source editor and disassembly view for source and instruction stepping.
  • REVERSE (Alt+2): Hides the source editor and gives the full center area to the split CFG + Decompiler view.
  • MPI (Alt+3): Focuses the MPI Diagnostics panel (Deadlock Analyzer and Network Log) and expands the bottom dock.
  • Maximize Bottom Dock (Ctrl+M): Toggles the bottom dock between its normal height and an expanded view when reading long logs or documentation.

GridLock Reverse Engineering Perspective


8. Binary Navigation, Cross-References, Patching & Docs (F1)

GridLock MPI Diagnostics

  • Jump to Address or Symbol (Ctrl+G): Type a hex address (0x00401149) or symbol name (sym.main) in the toolbar seek box to jump both DisassemblyView and MemView to that location.
  • Cross-References (X): Press X on an instruction in DisassemblyView to open XrefInspectorDialog and see incoming callers/branches (XREFS TO) and outgoing calls/jumps (XREFS FROM).
  • Patching Instructions & Bytes (Ctrl+Shift+P / Ctrl+E): Replace instructions in DisassemblyView or edit raw bytes in MemView, then write out a patched ELF binary via MainWindow::exportPatchedBinary.
  • Offline Documentation (F1): Press F1 on an MPI call (MPI_Init, MPI_Send, MPI_Recv, MPI_Barrier, MPI_Allreduce) or standard C/POSIX function to look up its page in the Reference Manual tab.

9. Attach to Running Process & Remote GDB Targets (Ctrl+Alt+P)

Open File -> Attach to Process... (Ctrl+Alt+P) to attach GridLock to a running local Linux process, an active multi-rank MPI job, or a remote gdbserver / QEMU GDB stub.

Tab 1: Local Processes (/proc) & Multi-Rank MPI Grouping

Attach to Running Process — /proc MPI Job Grouping

  1. Automatic MPI Job Discovery (ProcessScanner):
    • Scans /proc/<pid>/{comm,cmdline,status,environ,exe} and inspects OpenMPI (OMPI_COMM_WORLD_RANK, OMPI_COMM_WORLD_SIZE), MPICH/Hydra (PMI_RANK, PMI_SIZE), PMIx (PMIX_RANK), and SLURM (SLURM_PROCID, SLURM_JOB_ID, SLURM_NTASKS) environment variables.
    • Groups sibling MPI ranks under an expandable MPI Job (N ranks) — <binary> tree header sorted by world rank (Rank 0/4 .. Rank 3/4).
  2. Whole-Job or Single-Rank Attach:
    • Selecting the top-level MPI Job (N ranks) header and clicking Attach to Selected attaches one GdbRankCoordinator (-target-attach <pid>) or DapCoordinator instance per rank across the job and populates the Server Rack cards.
    • Selecting an individual rank row or a standalone process attaches only to that PID.
  3. kernel.yama.ptrace_scope Check:
    • When /proc/sys/kernel/yama/ptrace_scope is >= 1, Linux blocks non-parent ptrace attaches with EPERM. GridLock displays a warning banner at the top of the dialog with a Copy sysctl Fix button that copies:
      echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Tab 2: Remote Target (gdbserver / QEMU)

Attach to Remote GDB Target — QEMU & gdbserver

Switch to the Remote Target (gdbserver / QEMU) tab to debug cross-architecture binaries under qemu-user, full-system QEMU VMs, or remote compute nodes running gdbserver:

  1. Endpoint Formats (ProcessScanner::expandRemoteEndpoints):
    • Single Target: localhost:1234 or 127.0.0.1:2222 (Rank 0).
    • Multi-Rank Port Range: localhost:1234..1237 expands automatically into 4 rank endpoints (localhost:1234 for Rank 0 through localhost:1237 for Rank 3).
    • Comma-Separated Endpoints: node0:1234, node1:1234, node2:1234, node3:1234 assigns each host:port to a sequential MPI rank.
  2. Local Symbol Binary (ELF) & GDB Binary:
    • Point Local Symbol Binary (ELF) to the unstripped ELF binary on your workstation so GridLock loads DWARF source-line mappings, symbols, and CFG blocks before issuing -target-select.
    • Pick gdb, gdb-multiarch, aarch64-linux-gnu-gdb, or riscv64-linux-gnu-gdb in the GDB Binary selector.
  3. Protocol Mode (remote vs. extended-remote):
    • remote (qemu-user -g / gdbserver): Issues -target-select remote <host:port>. Use this for qemu-aarch64 -g 1234 ./guest_binary, qemu-riscv64 -g 1234 ./guest_binary, or standard gdbserver :1234 ./target_binary.
    • extended-remote (gdbserver --multi): Issues -target-select extended-remote <host:port> for persistent gdbserver --multi sessions.

Clone this wiki locally