synth_core/

dwarf_line.rs

//! VCR-DBG-001 step 3 — compose the source-line table (the join half).
//!
//! The DWARF Tier-1 bridge maps an ARM text offset back to a source `file:line`
//! through three established facts:
//!   1. each ARM instruction carries `source_line` = the wasm OP INDEX
//!      (`ArmInstruction.source_line`);
//!   2. step 1 (`FunctionOps.op_offsets`) maps op-index → the wasm code BYTE
//!      OFFSET (module-relative);
//!   3. step 2 parses the input wasm's `.debug_line` → (code-section-relative
//!      address → `file:line`) rows.
//!
//! This module is the join for the wasm half — **op-index → source line** —
//! which step 4 (emit) composes with the ARM layout (ARM-text-offset → op-index
//! is just `source_line`). It is pure plain-data (no gimli, no backend): the
//! caller parses the rows and supplies them, so the module is Bazel-clean and
//! unwired (frozen-safe) until the emitter consumes it.
//!
//! The crux it encodes (validated on `scripts/repro/dwarf_coherent.wasm`,
//! VCR-DBG-001 step-3 fixture): `op_offsets` are MODULE-relative while DWARF
//! addresses are CODE-section-relative, and they differ by a single constant —
//! the code section's payload start. So normalization is one subtraction:
//! `dwarf_addr = op_offset - code_base`.

/// One `.debug_line` row: a code-section-relative address and its source line.
/// `file` is an opaque caller-supplied id (e.g. an index into the line
/// program's file table) so this stays gimli-free.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LineRow {
    /// Code-section-relative address (the DWARF-for-wasm address space).
    pub addr: u32,
    pub line: u32,
    pub file: u32,
}

/// A resolved source location for a wasm op.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SourceLoc {
    pub line: u32,
    pub file: u32,
}

/// Map each wasm op (by its module-relative `op_offsets` byte offset) to a
/// source location, by normalizing into the code-section-relative DWARF address
/// space (`op_offset - code_base`) and taking the covering line-table row (the
/// last row whose address is ≤ the op's address — standard line-table lookup).
///
/// Returns one entry per `op_offsets` element (parallel to a function's ops).
/// `None` where the op precedes `code_base` (shouldn't happen for real code) or
/// no row covers it (an op before the first line-table address).
pub fn op_offsets_to_source(
    op_offsets: &[u32],
    code_base: u32,
    rows: &[LineRow],
) -> Vec<Option<SourceLoc>> {
    let mut sorted: Vec<LineRow> = rows.to_vec();
    sorted.sort_by_key(|r| r.addr);
    op_offsets
        .iter()
        .map(|&off| {
            let a = off.checked_sub(code_base)?;
            // Largest row addr ≤ a (the line in effect at address a).
            sorted
                .iter()
                .rev()
                .find(|r| r.addr <= a)
                .map(|r| SourceLoc {
                    line: r.line,
                    file: r.file,
                })
        })
        .collect()
}

// ---------------------------------------------------------------------------
// VCR-DBG-001 step 4 — PRODUCTION read + emit (the `--debug-line` feature).
//
// `read_input_dwarf_line` ports the read-side spike
// (`tests/dwarf_line_read_spike.rs` + `dwarf_compose_step3.rs::code_base`):
// pull the `.debug_*` custom sections out of the input wasm, parse `.debug_line`
// with gimli, and also report the code-section payload start (`code_base`) the
// compose normalizes against. `emit_debug_sections` ports the emit-side spike
// (`tests/dwarf_emit_roundtrip_step4.rs::emit_dwarf`): take an address-ordered
// (arm_addr → source line) table and produce a FULL debugger-readable DWARF unit
// (`.debug_info`/`.debug_abbrev`/`.debug_str`/`.debug_line`) via gimli::write,
// the CU's DW_AT_stmt_list pointing at the line table. Both are gated behind
// `--debug-line`; when the input carries no DWARF, `read_input_dwarf_line`
// returns empty rows (graceful no-op) and the emit is skipped, so the default
// object stays bit-identical.

use std::collections::HashMap;

use gimli::{Dwarf, EndianSlice, LittleEndian, SectionId};
use wasmparser::{Parser, Payload};

/// Result of reading the input wasm's DWARF line table: the parsed rows plus the
/// code-section payload start (`code_base`) the op-offset compose subtracts.
#[derive(Debug, Default, Clone)]
pub struct InputDwarfLine {
    /// Code-section-relative `.debug_line` rows (`addr` is a wasm code byte
    /// offset; for the synth bridge that equals the DWARF address space).
    pub rows: Vec<LineRow>,
    /// Module-relative byte offset of the code section payload start. Empty wasm
    /// or a wasm with no code section reports 0.
    pub code_base: u32,
    /// GLOBAL source-file table `(directory, file name)`. `LineRow.file` indexes
    /// into this — NOT the input's per-unit DWARF file index. The input wasm has
    /// several compilation units each with their own file table (colliding
    /// per-unit indices), so the reader resolves every row's file to a real
    /// `(dir, name)` string and interns it here, giving one flat table the emit
    /// reproduces 1:1. Empty when no row resolves to a file (emit then falls back
    /// to its single-file default).
    pub files: Vec<(String, String)>,
}

/// Read the input wasm's `.debug_line` into code-section-relative
/// `(addr → line)` rows and report `code_base`. Returns an empty table (rows
/// empty, the feature a no-op) when the input carries no `.debug_*` sections or
/// no parseable line program — never an error for a DWARF-free module.
pub fn read_input_dwarf_line(wasm: &[u8]) -> InputDwarfLine {
    // (a) extract every `.debug_*` custom section + find the code payload start.
    let mut sections: HashMap<String, Vec<u8>> = HashMap::new();
    let mut code_base = 0u32;
    for payload in Parser::new(0).parse_all(wasm) {
        match payload {
            Ok(Payload::CustomSection(c)) if c.name().starts_with(".debug_") => {
                sections.insert(c.name().to_string(), c.data().to_vec());
            }
            Ok(Payload::CodeSectionStart { range, .. }) => {
                code_base = range.start as u32;
            }
            _ => {}
        }
    }
    if !sections.contains_key(".debug_line") {
        return InputDwarfLine {
            rows: Vec::new(),
            code_base,
            files: Vec::new(),
        };
    }

    // (b) parse `.debug_line` with gimli. A malformed line program degrades to
    // an empty table (the feature no-ops) rather than failing the compile.
    let (rows, files) = parse_debug_line_rows(&sections).unwrap_or_default();
    InputDwarfLine {
        rows,
        code_base,
        files,
    }
}

/// gimli read of `.debug_line` → `(rows, global file table)`. The input carries
/// several compilation units, each with its own file table, so a row's per-unit
/// `file_index` is ambiguous once rows are flattened. To keep `LineRow.file`
/// meaningful across units, each row's file index is resolved (via that unit's
/// own header + `dwarf.attr_string`) to a real `(directory, name)` string and
/// interned into one flat GLOBAL table; `LineRow.file` becomes that global index.
/// `header.file(idx)` / `header.directory(idx)` handle the DWARF version's
/// indexing (v4 is 1-based; v5 is 0-based) so both are read correctly.
type LineTable = (Vec<LineRow>, Vec<(String, String)>);

fn parse_debug_line_rows(sections: &HashMap<String, Vec<u8>>) -> Result<LineTable, gimli::Error> {
    let empty: &[u8] = &[];
    let load = |id: SectionId| -> Result<EndianSlice<'_, LittleEndian>, gimli::Error> {
        let data = sections.get(id.name()).map_or(empty, |v| v.as_slice());
        Ok(EndianSlice::new(data, LittleEndian))
    };
    let dwarf = Dwarf::load(load)?;

    let mut rows = Vec::new();
    let mut files: Vec<(String, String)> = Vec::new();
    let mut units = dwarf.units();
    while let Some(header) = units.next()? {
        let unit = dwarf.unit(header)?;
        let Some(program) = unit.line_program.clone() else {
            continue;
        };
        // The header borrows the program; clone it so we can consume `program`
        // in `rows()` while still resolving file indices afterwards.
        let line_header = program.header().clone();
        let mut state = program.rows();
        while let Some((_, row)) = state.next_row()? {
            if row.end_sequence() {
                continue;
            }
            // Resolve this row's per-unit file index to a real (dir, name) and
            // intern it into the flat global table (dedup); store the global idx.
            let file = resolve_file(&dwarf, &unit, &line_header, row.file_index())
                .map(|entry| intern_file(&mut files, entry))
                .unwrap_or(0);
            rows.push(LineRow {
                addr: row.address() as u32,
                line: row.line().map(|l| l.get() as u32).unwrap_or(0),
                file,
            });
        }
    }
    Ok((rows, files))
}

/// Resolve a line-program `file_index` to `(directory, file name)` strings using
/// the owning unit's header. `header.file` / `header.directory` apply the correct
/// per-version indexing; `attr_string` resolves both inline (`.debug_line`) and
/// `.debug_line_str`/`.debug_str` forms. `None` when the index has no file entry
/// (e.g. DWARF v4 index 0).
fn resolve_file(
    dwarf: &Dwarf<EndianSlice<'_, LittleEndian>>,
    unit: &gimli::Unit<EndianSlice<'_, LittleEndian>>,
    header: &gimli::LineProgramHeader<EndianSlice<'_, LittleEndian>>,
    file_index: u64,
) -> Option<(String, String)> {
    let file = header.file(file_index)?;
    let name = dwarf
        .attr_string(unit, file.path_name())
        .ok()?
        .to_string_lossy()
        .into_owned();
    let dir = match header.directory(file.directory_index()) {
        Some(av) => dwarf
            .attr_string(unit, av)
            .ok()
            .map(|s| s.to_string_lossy().into_owned())
            .unwrap_or_default(),
        None => String::new(),
    };
    Some((dir, name))
}

/// Intern a `(dir, name)` into the global file table, returning its index
/// (existing if already present). Keeps the table small (the fixture interns a
/// single `panicking.rs`).
fn intern_file(files: &mut Vec<(String, String)>, entry: (String, String)) -> u32 {
    if let Some(i) = files.iter().position(|f| *f == entry) {
        return i as u32;
    }
    files.push(entry);
    (files.len() - 1) as u32
}

/// One function to describe with a `DW_TAG_subprogram` child DIE (#394, Tier-1)
/// so a debugger backtrace shows the FUNCTION NAME, not a bare address. Carries
/// the function's name and its object-relative `[low_pc, high_pc)` `.text` range
/// (byte offsets against the `.text` base). The emitter relocates `low_pc`
/// against the SAME `.text` symbol as the CU (addend = `low_pc`) and writes
/// `high_pc - low_pc` as the offset form of `DW_AT_high_pc` (no relocation).
#[derive(Debug, Clone)]
pub struct SubprogramInfo {
    /// The export/function name shown in a debugger frame.
    pub name: String,
    /// Object-relative `.text` byte offset of the function's first instruction.
    pub low_pc: u64,
    /// Object-relative `.text` byte offset one past the function's last byte.
    pub high_pc: u64,
}

/// Emit an address-ordered `(arm_addr, line)` table as a FULL minimal DWARF unit
/// (gimli::write) and return EVERY non-empty `.debug_*` section it produces —
/// `.debug_info`, `.debug_abbrev`, `.debug_str`, `.debug_line` (and
/// `.debug_line_str`/`.debug_ranges` etc. when non-empty). The caller composes
/// the table (one address-sorted, de-duped sequence covering every function);
/// this produces the section bytes for non-ALLOC ELF `PROGBITS` sections.
/// Returns an empty `Vec` for an empty table (nothing to map ⇒ no sections ⇒
/// output stays byte-identical).
///
/// Crucially this emits a real root `DW_TAG_compile_unit` DIE with `DW_AT_name`,
/// `DW_AT_low_pc`/`DW_AT_high_pc` spanning the emitted text, and the line program
/// attached — so the CU's `DW_AT_stmt_list` points at `.debug_line`. That makes
/// the line table reachable via the NORMAL debugger walk (`.debug_info` → CU →
/// `DW_AT_stmt_list` → line program), not just a standalone `.debug_line` parse.
///
/// Ports `tests/dwarf_emit_roundtrip_step4.rs::emit_dwarf` (which emits the same
/// full unit and round-trips through `Dwarf::units()`).
pub fn emit_debug_sections(
    table: &[(u64, u32, u32)],
    text_sym: usize,
    files: &[(String, String)],
    subprograms: &[SubprogramInfo],
) -> Vec<EmittedDwarfSection> {
    use gimli::write::{Address, AttributeValue, DwarfUnit, LineProgram, LineString, Sections};

    if table.is_empty() {
        return Vec::new();
    }

    let encoding = gimli::Encoding {
        format: gimli::Format::Dwarf32,
        version: 4,
        address_size: 4,
    };
    let mut dwarf = DwarfUnit::new(encoding);

    // The span of emitted text the unit describes: low_pc=`.text`+0 (text base),
    // high_pc one past the last mapped address.
    let high_pc = table.iter().map(|&(a, _, _)| a).max().unwrap_or(0) + 1;

    // Reproduce the input's source-file table so a debugger resolves each stop to
    // the REAL file (e.g. `panicking.rs`), not the fabricated `synth.wasm`. The
    // comp-dir/file passed to `LineProgram::new` become the unit's primary file;
    // use the FIRST real interned file for it (never `synth.wasm`) so even the
    // primary is a genuine name. Then `add_file` each interned file and map its
    // global index → the returned `FileId`. When the input carried no resolvable
    // file table (`files` empty) keep the historical single-file default so a
    // DWARF-less-but-lined input still emits something rather than panicking.
    //
    // gimli 0.33's `LineProgram::new` args are
    // `(working_dir, working_dir_info, source_file, source_file_info)`.
    let (primary_dir, primary_name) = files
        .first()
        .map(|(d, n)| (d.clone().into_bytes(), n.clone().into_bytes()))
        .unwrap_or_else(|| (b"/synth".to_vec(), b"synth.wasm".to_vec()));
    let mut program = LineProgram::new(
        encoding,
        gimli::LineEncoding::default(),
        LineString::String(primary_dir),
        None,
        LineString::String(primary_name.clone()),
        None,
    );
    // Global file index → emitted `FileId`. `file_ids[0]` always exists (either
    // the first real file or the single fallback), so an out-of-range row index
    // clamps to it rather than panicking.
    let mut file_ids = Vec::with_capacity(files.len().max(1));
    if files.is_empty() {
        let dir = program.default_directory();
        file_ids.push(program.add_file(LineString::String(b"synth.wasm".to_vec()), dir, None));
    } else {
        for (dir, name) in files {
            let dir_id = program.add_directory(LineString::String(dir.clone().into_bytes()));
            file_ids.push(program.add_file(
                LineString::String(name.clone().into_bytes()),
                dir_id,
                None,
            ));
        }
    }

    // The sequence base is `.text + 0` as a RELOCATABLE address (one
    // `DW_LNE_set_address` against the `.text` symbol, addend 0); each row's
    // `address_offset` stays a text-relative DELTA, so only this single site
    // needs a relocation per section. Addend 0 ⇒ the in-place bytes are
    // byte-identical to the previous `Address::Constant(0)` form.
    let text_base = Address::Symbol {
        symbol: text_sym,
        addend: 0,
    };
    program.begin_sequence(Some(text_base));
    for &(addr, line, file) in table {
        let row = program.row();
        row.address_offset = addr;
        row.file = *file_ids.get(file as usize).unwrap_or(&file_ids[0]);
        row.line = line as u64;
        program.generate_row();
    }
    program.end_sequence(high_pc);
    dwarf.unit.line_program = program;

    // Populate the root DW_TAG_compile_unit DIE: a name, the text span, and (via
    // gimli auto-wiring the attached line_program) DW_AT_stmt_list → .debug_line.
    // Name the CU after the primary real source file (fallback `synth.wasm`).
    {
        let cu_name = files
            .first()
            .map(|(_, n)| n.clone())
            .unwrap_or_else(|| "synth.wasm".to_string());
        let name_id = dwarf.strings.add(cu_name);
        let root = dwarf.unit.root();
        let root_die = dwarf.unit.get_mut(root);
        root_die.set(gimli::DW_AT_name, AttributeValue::StringRef(name_id));
        root_die.set(gimli::DW_AT_low_pc, AttributeValue::Address(text_base));
        root_die.set(gimli::DW_AT_high_pc, AttributeValue::Udata(high_pc));
    }

    // #394 Tier-1: attach one DW_TAG_subprogram child DIE per function so a
    // debugger backtrace shows the FUNCTION NAME, not a bare address.
    //   - DW_AT_name    = the export/function name.
    //   - DW_AT_low_pc  = the function's `.text` address, relocated against the
    //     SAME `__synth_text_base` symbol as the CU low_pc but with addend =
    //     the function's object-relative offset, so it shifts correctly when a
    //     linker places `.text` (each is an extra `.rel.debug_info` record).
    //   - DW_AT_high_pc = the offset (size) form `high_pc - low_pc` — a plain
    //     constant, so it needs no relocation (matches the CU's high_pc form).
    // No parameters/locals/frame-base yet — that is Tier-2, gated on VCR-RA.
    {
        let root = dwarf.unit.root();
        for sp in subprograms {
            let name_id = dwarf.strings.add(sp.name.clone());
            let die_id = dwarf.unit.add(root, gimli::DW_TAG_subprogram);
            let die = dwarf.unit.get_mut(die_id);
            die.set(gimli::DW_AT_name, AttributeValue::StringRef(name_id));
            die.set(
                gimli::DW_AT_low_pc,
                AttributeValue::Address(Address::Symbol {
                    symbol: text_sym,
                    addend: sp.low_pc as i64,
                }),
            );
            die.set(
                gimli::DW_AT_high_pc,
                AttributeValue::Udata(sp.high_pc.saturating_sub(sp.low_pc)),
            );
        }
    }

    let seed = RelocWriter {
        inner: gimli::write::EndianVec::new(LittleEndian),
        relocs: Vec::new(),
    };
    let mut sections = Sections::new(seed);
    if dwarf.write(&mut sections).is_err() {
        return Vec::new();
    }

    let mut out: Vec<EmittedDwarfSection> = Vec::new();
    let _ = sections.for_each(|id, w: &RelocWriter| -> Result<(), ()> {
        let bytes = w.inner.slice();
        if !bytes.is_empty()
            && let Some(name) = section_name(id)
        {
            let text_relocs = w
                .relocs
                .iter()
                .map(|&(offset, _addend, size)| DwarfTextReloc {
                    offset: offset as u32,
                    size,
                })
                .collect();
            out.push(EmittedDwarfSection {
                name,
                bytes: bytes.to_vec(),
                text_relocs,
            });
        }
        Ok(())
    });
    out
}

/// A relocation a `.debug_*` section needs against the `.text` symbol so a host
/// linker fixes up the embedded `.text` address when `.text` is placed. REL
/// form: the in-place bytes already hold the addend (always `0` for our
/// text-base references), so only the site (`offset`) and `size` travel here.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DwarfTextReloc {
    /// Byte offset within the section where the relocated address word sits.
    pub offset: u32,
    /// Size of the relocated value (always 4 for DWARF32 addresses).
    pub size: u8,
}

/// One emitted `.debug_*` section: its ELF name, bytes, and the `.text`-symbol
/// relocations it needs (empty for address-free sections like `.debug_str`).
#[derive(Debug, Clone)]
pub struct EmittedDwarfSection {
    /// `'static` ELF section name (e.g. `.debug_line`).
    pub name: &'static str,
    /// Section payload bytes.
    pub bytes: Vec<u8>,
    /// `.text`-symbol relocations within this section (REL, in-place addend 0).
    pub text_relocs: Vec<DwarfTextReloc>,
}

/// A gimli `write::Writer` that delegates to an inner `EndianVec` but records
/// every `Address::Symbol` write as a relocation. ONLY `write_address` is
/// overridden — `write_offset` (gimli's internal section-to-section references,
/// e.g. `.debug_info` → `.debug_str`/`.debug_abbrev` and `DW_AT_stmt_list` →
/// `.debug_line`) keeps the default, so those stay CONCRETE intra-file offsets
/// and need no section symbols. The relocations captured are the `.text`
/// references: the line program's `DW_LNE_set_address`, the CU's `DW_AT_low_pc`,
/// and one per `DW_TAG_subprogram` `DW_AT_low_pc` (#394). `Clone` so
/// `Sections::new` can seed each section writer.
#[derive(Clone)]
struct RelocWriter {
    inner: gimli::write::EndianVec<LittleEndian>,
    /// (offset within section, addend, size) for each `Address::Symbol` write.
    relocs: Vec<(usize, i64, u8)>,
}

impl gimli::write::Writer for RelocWriter {
    type Endian = LittleEndian;

    fn endian(&self) -> Self::Endian {
        self.inner.endian()
    }

    fn len(&self) -> usize {
        self.inner.len()
    }

    fn write(&mut self, bytes: &[u8]) -> gimli::write::Result<()> {
        self.inner.write(bytes)
    }

    fn write_at(&mut self, offset: usize, bytes: &[u8]) -> gimli::write::Result<()> {
        self.inner.write_at(offset, bytes)
    }

    fn write_address(
        &mut self,
        address: gimli::write::Address,
        size: u8,
    ) -> gimli::write::Result<()> {
        use gimli::write::Address;
        match address {
            Address::Constant(val) => self.inner.write_udata(val, size),
            Address::Symbol { symbol: _, addend } => {
                // REL: record the site and write the addend in place (0 ⇒ the
                // bytes match the old `Address::Constant(0)` exactly).
                let offset = self.inner.len();
                self.relocs.push((offset, addend, size));
                self.inner.write_udata(addend as u64, size)
            }
        }
    }
}

/// `'static` ELF section name for the `.debug_*` sections the emitter can
/// produce. Returns `None` for any section id we do not wire (none are expected
/// for this minimal unit, but the match keeps the names `'static`).
fn section_name(id: SectionId) -> Option<&'static str> {
    Some(match id {
        SectionId::DebugInfo => ".debug_info",
        SectionId::DebugAbbrev => ".debug_abbrev",
        SectionId::DebugStr => ".debug_str",
        SectionId::DebugLine => ".debug_line",
        SectionId::DebugLineStr => ".debug_line_str",
        SectionId::DebugRanges => ".debug_ranges",
        SectionId::DebugRngLists => ".debug_rnglists",
        SectionId::DebugStrOffsets => ".debug_str_offsets",
        SectionId::DebugAddr => ".debug_addr",
        _ => return None,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn covering_row_lookup() {
        // code_base 100; rows at code-rel 0→line10, 8→line11, 20→line12.
        let rows = [
            LineRow {
                addr: 0,
                line: 10,
                file: 1,
            },
            LineRow {
                addr: 8,
                line: 11,
                file: 1,
            },
            LineRow {
                addr: 20,
                line: 12,
                file: 1,
            },
        ];
        // ops at module 100 (→0), 104 (→4), 108 (→8), 130 (→30).
        let got = op_offsets_to_source(&[100, 104, 108, 130], 100, &rows);
        assert_eq!(got[0].map(|s| s.line), Some(10)); // addr 0  → row 0
        assert_eq!(got[1].map(|s| s.line), Some(10)); // addr 4  → still row 0
        assert_eq!(got[2].map(|s| s.line), Some(11)); // addr 8  → row 8
        assert_eq!(got[3].map(|s| s.line), Some(12)); // addr 30 → row 20 (last ≤)
    }

    #[test]
    fn op_before_first_row_is_none() {
        let rows = [LineRow {
            addr: 8,
            line: 11,
            file: 1,
        }];
        // op at module 100 → code-rel 0, before the first row (addr 8).
        let got = op_offsets_to_source(&[100], 100, &rows);
        assert_eq!(got[0], None);
    }

    #[test]
    fn op_before_code_base_is_none() {
        let rows = [LineRow {
            addr: 0,
            line: 1,
            file: 1,
        }];
        let got = op_offsets_to_source(&[50], 100, &rows);
        assert_eq!(got[0], None);
    }
}