Skip to content

Latest commit

 

History

History
141 lines (120 loc) · 8 KB

SPEC.md

File metadata and controls

141 lines (120 loc) · 8 KB

Specification: LD_DEBUG Dynamic Linker Log Visualizer (ld_debug_viewer)

1. Overview and Objective

ld_debug_viewer is a client-side web application designed to parse, analyze, and visualize dynamic linker logs generated by the Linux GNU C Library dynamic linker (ld.so / ld-linux.so).

Logs are collected by running target executables with the environment variables:

LD_DEBUG=all,unused,statistics LD_DEBUG_OUTPUT=$MY_LOG_PATH ./my_application

The tool is hosted entirely on GitHub Pages, operates 100% within the browser (no backend server), vendors all required assets locally in the repository to guarantee offline and zero-breakage execution, and features a clean, minimalist user interface.


2. Technical Constraints and Requirements

  1. Host Environment: Static GitHub Pages (HTML5, CSS3, ES6+ JavaScript).
  2. Execution Context: 100% client-side (FileReader API, Web APIs, SVG/Canvas). No server-side runtime, no external API calls, works offline or via file://.
  3. No External CDNs: All scripts, styles, and assets reside locally in the repository to prevent broken external dependencies.
  4. Log Compatibility:
    • Parses LD_DEBUG=all,unused,statistics output (including PID prefixes, multi-PID logs).
    • Relocations, symbol lookups, symbol bindings, DSO dependencies (DT_NEEDED), link map addresses, version checks, unused DSOs, runtime linker statistics, and init/fini order.
  5. Filtering:
    • Distinct, independent input fields for Filename Filter and Symbol Filter.
    • Real-time instant filtering with case-sensitivity toggle and regex support.
  6. Visualization:
    • High-level KPIs and Relocation Statistics metrics.
    • Interactive Dependency Graph (DSO load hierarchy and symbol binding flows).
    • Link map memory layout (base address, size, entry point).
    • Tabular view of symbol bindings with lookup resolution history.
    • Unused DSO detection alerts.
  7. GUI Aesthetic: Minimalist, high information-density, clutter-free, responsive dark/light theme.

3. Log Grammar and Parsing Rules

The log format generated by ld.so consists of lines starting with an optional process ID and tab: ^\s*(\d+):\t?(.*)$

3.1 Key Record Formats

Event Type Regular Expression / Pattern Extracted Data Fields
Needed DSO file=(?<target>[^ ;\[]+)(?:\s*\[\d+\])?;\s+needed by (?<source>[^ \[\n\r]+) source (caller), target (library)
Search Path find library=(?<lib>[^ ;\[]+).*?; searching\s+search cache=(?<cache>[^\n]+)\s+trying file=(?<path>[^\n]+) lib, path
Link Map file=(?<file>[^ ;\[]+).*?; generating link map\s+dynamic:\s+(?<dyn>0x[0-9a-fA-F]+)\s+base:\s+(?<base>0x[0-9a-fA-F]+)\s+size:\s+(?<size>0x[0-9a-fA-F]+)\s+entry:\s+(?<entry>0x[0-9a-fA-F]+)\s+phdr:\s+(?<phdr>0x[0-9a-fA-F]+)\s+phnum:\s+(?<phnum>\d+) file, dynamic, base, size, entry, phdr, phnum
Version Check checking for version ['](?[^] in file (?[^ ]+)(?:\s*[\d+])? required by file (?[^ [\n]+)` version, file, required_by
Relocation Target relocation processing:\s*(?<file>[^\s]+) Sets current relocation context current_reloc_file
Symbol Lookup symbol=(?<sym>[^ ;]+);\s+lookup in file=(?<file>[^ ;\[]+) symbol, lookup_file sequence
Symbol Binding binding file (?<from>[^ \[\n]+).*? to (?<to>[^ :\[\n]+).*?:\s*(?<type>[a-zA-Z0-9_ ]+)\s+symbol\s*['](?^']+)['?` from, to, type, symbol, version, lookup_chain
Unused DSO file=(?<file>[^ ;\[]+)(?:\s*\[\d+\])?;\s+unused:\s*(?<reason>.+) or Unused direct dependencies:\s*(?<file>[^\n]+) file, reason
Statistics `runtime linker statistics:(?<stats_block>.*?)(?:calling init $
Init / Fini calling init:\s*(?<file>.+) / calling fini:\s*(?<file>.+) Execution sequence of initializers/finalizers

4. Architecture and File Structure

d:/ld_debug_viewer/
├── index.html              # Main HTML entry point (semantic, responsive, minimalist layout)
├── css/
│   └── style.css           # Minimalist CSS styling with CSS variables (Dark/Light themes)
├── js/
│   ├── parser.js           # Robust ld.so log parser and data extraction engine
│   ├── graph.js            # Standalone, interactive SVG-based DAG & network visualizer (0 dependencies)
│   ├── table.js            # Virtualized/paginated searchable table component
│   └── app.js              # Application state coordinator, event handlers, file drop, sample loading
├── vendor/                 # Local directory for any vendored helper assets (guarantees offline safety)
├── ldlog.2967              # Bundled sample log file for testing & immediate 1-click exploration
├── SPEC.md                 # System specification and documentation
└── README.md               # User guide, GitHub Pages setup instructions, and command reference

5. UI and Visualization Design

5.1 Minimalist Header & Control Bar

  • App Title: LD_DEBUG Visualizer
  • File Controls:
    • Select Log File input (File API)
    • Drag-and-drop overlay on viewport
    • Load Sample (ldlog.2967) button for instant zero-setup demonstration
    • Export Filtered CSV / Export JSON
    • Theme Toggle (Dark Mode / Light Mode)
    • Quick Info button showing the generation command: LD_DEBUG=all,unused,statistics LD_DEBUG_OUTPUT=~/my_log ./app

5.2 Metrics Bar

High-contrast, compact metric cards:

  • Total Relocations: Total count processed.
  • Bound Symbols: Unique symbols and total bindings.
  • Loaded DSOs: Count of shared objects loaded.
  • Relocation Overhead: Cycle count and percentage of total startup time.
  • Loader Startup Time: Total dynamic loader cycles.
  • Unused DSOs: Green badge (0) or Red alert badge (>0) warning of dead dependencies.

5.3 Filter Controls Bar

Two distinct, dedicated inputs:

  1. Filename Filter: Filters bindings and nodes where filename/path matches (source or target).
  2. Symbol Filter: Filters symbol names (e.g. malloc, pthread, __vdso).
  • Options: Case Sensitive checkbox, Regex checkbox, Cross-library Only checkbox.

5.4 View Tabs

  1. Dependency Graph:
    • Interactive SVG canvas with zoom, pan, fit-to-view, and node drag.
    • Dual-mode switch:
      • DSO Load Tree (DT_NEEDED): Shows library dependency hierarchy.
      • Symbol Call Flow: Edges weighted by number of bound symbols.
    • Unused DSOs flagged with warning borders.
    • Clicking any node filters the table view directly to that DSO.
  2. Symbol Bindings Table:
    • Columns: Line #, Symbol Name, Requesting Object, Bound Provider, Type, Version, Lookups Count.
    • Expandable row showing step-by-step lookup search path (which files were probed before resolution).
  3. Link Map & Memory Layout:
    • Table of base addresses, virtual memory sizes, entry points, and ELF program header info.
  4. Linker Statistics & Init Order:
    • Performance cycle breakdown table with percentage bar charts.
    • Exact sequence of calling init: executions.
  5. Raw Log Viewer:
    • Searchable, line-numbered raw log with syntax color coding.

6. Verification and Test Strategy

  1. Automated Parser Unit Tests: Run against ldlog.2967 to verify 100% extraction accuracy:
    • 135 bindings verified.
    • 1 DT_NEEDED edge verified (docker -> libc.so.6).
    • 6 statistics metrics parsed.
    • 2 init calls parsed.
    • Correct handling of vDSO and dynamic linker self-bindings.
  2. Edge Cases:
    • Multi-PID logs (filter by PID or merge).
    • Unused DSOs present vs absent.
    • Empty/truncated logs.
    • Logs with ANSI color escapes or trailing newlines.
  3. Browser Compatibility:
    • Local file:// protocol execution.
    • python -m http.server local hosting.
    • GitHub Pages production deployment.