simdref 0.0.0__py3-none-any.whl

simdref/pdfparse/types.py

@@ -0,0 +1,77 @@
+"""Vendor-neutral PDF enrichment types."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class PdfDescriptionPayload:
+    sections: dict[str, str]
+    source_url: str
+    page_start: int | None = None
+    page_end: int | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "sections": self.sections,
+            "source_url": self.source_url,
+            "page_start": self.page_start,
+            "page_end": self.page_end,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PdfEnrichmentResult:
+    descriptions: dict[str, PdfDescriptionPayload]
+    fallback_page_count: int = 0
+    stats: dict[str, int] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "descriptions": {key: value.to_dict() for key, value in self.descriptions.items()},
+            "fallback_page_count": self.fallback_page_count,
+            "stats": dict(self.stats),
+        }
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, object]) -> "PdfEnrichmentResult":
+        descriptions: dict[str, PdfDescriptionPayload] = {}
+        raw_descriptions = payload.get("descriptions") or {}
+        if isinstance(raw_descriptions, dict):
+            for key, value in raw_descriptions.items():
+                if not isinstance(value, dict):
+                    continue
+                descriptions[str(key)] = PdfDescriptionPayload(
+                    sections=dict(value.get("sections") or {}),
+                    source_url=str(value.get("source_url") or ""),
+                    page_start=value.get("page_start") if isinstance(value.get("page_start"), int) else None,
+                    page_end=value.get("page_end") if isinstance(value.get("page_end"), int) else None,
+                )
+        raw_stats = payload.get("stats") or {}
+        stats = {
+            str(key): int(value)
+            for key, value in raw_stats.items()
+            if isinstance(value, int)
+        } if isinstance(raw_stats, dict) else {}
+        fallback_page_count = payload.get("fallback_page_count")
+        return cls(
+            descriptions=descriptions,
+            fallback_page_count=fallback_page_count if isinstance(fallback_page_count, int) else 0,
+            stats=stats,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PdfSourceSpec:
+    source_id: str
+    display_name: str
+    source_url: str
+    local_candidates: Sequence[Path]
+    cache_path: Path
+    cache_version: int
+    signature_paths: Sequence[Path]
+    parser: Callable[..., PdfEnrichmentResult]
+    find_source: Callable[..., Path | None]

simdref/pdfrefs.py

@@ -0,0 +1,95 @@
+"""Shared normalized PDF reference helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+PdfRef = dict[str, str]
+
+_LEGACY_INTEL_SOURCE_ID = "intel-sdm"
+_LEGACY_INTEL_LABEL = "Intel SDM"
+
+
+def normalize_pdf_refs(
+    pdf_refs: list[dict[str, Any]] | None,
+    metadata: dict[str, str] | None = None,
+) -> list[PdfRef]:
+    """Return normalized PDF references, preserving legacy Intel metadata."""
+    normalized: list[PdfRef] = []
+    seen: set[tuple[str, str, str, str, str]] = set()
+
+    for ref in pdf_refs or []:
+        candidate = {
+            "source_id": str(ref.get("source_id") or "").strip(),
+            "label": str(ref.get("label") or "").strip(),
+            "url": str(ref.get("url") or "").strip(),
+            "page_start": str(ref.get("page_start") or "").strip(),
+            "page_end": str(ref.get("page_end") or "").strip(),
+        }
+        if not candidate["source_id"] or not candidate["label"] or not candidate["url"]:
+            continue
+        key = (
+            candidate["source_id"],
+            candidate["label"],
+            candidate["url"],
+            candidate["page_start"],
+            candidate["page_end"],
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        normalized.append(candidate)
+
+    legacy = legacy_intel_pdf_ref(metadata)
+    if legacy is not None:
+        key = (
+            legacy["source_id"],
+            legacy["label"],
+            legacy["url"],
+            legacy["page_start"],
+            legacy["page_end"],
+        )
+        if key not in seen:
+            normalized.append(legacy)
+    return normalized
+
+
+def legacy_intel_pdf_ref(metadata: dict[str, str] | None) -> PdfRef | None:
+    """Build a normalized ref from legacy Intel-specific metadata keys."""
+    if not metadata:
+        return None
+    url = (metadata.get("intel-sdm-url") or "").strip()
+    if not url:
+        return None
+    return {
+        "source_id": _LEGACY_INTEL_SOURCE_ID,
+        "label": _LEGACY_INTEL_LABEL,
+        "url": url,
+        "page_start": (metadata.get("intel-sdm-page-start") or "").strip(),
+        "page_end": (metadata.get("intel-sdm-page-end") or "").strip(),
+    }
+
+
+def apply_legacy_pdf_metadata(metadata: dict[str, str], pdf_refs: list[PdfRef]) -> dict[str, str]:
+    """Populate legacy Intel keys for backward-compatible payloads."""
+    legacy = next((ref for ref in pdf_refs if ref.get("source_id") == _LEGACY_INTEL_SOURCE_ID), None)
+    if legacy is None:
+        return metadata
+    if legacy.get("url"):
+        metadata.setdefault("intel-sdm-url", legacy["url"])
+    if legacy.get("page_start"):
+        metadata.setdefault("intel-sdm-page-start", legacy["page_start"])
+    if legacy.get("page_end"):
+        metadata.setdefault("intel-sdm-page-end", legacy["page_end"])
+    return metadata
+
+
+def pdf_ref_label(ref: PdfRef) -> str:
+    label = ref.get("label") or ref.get("source_id") or "PDF"
+    page_start = ref.get("page_start") or ""
+    page_end = ref.get("page_end") or ""
+    if page_start and page_end and page_end != page_start:
+        return f"{label} (pages {page_start}-{page_end})"
+    if page_start:
+        return f"{label} (page {page_start})"
+    return label

simdref/perf.py

@@ -0,0 +1,220 @@
+"""Shared performance-metric extraction helpers.
+
+Functions in this module extract latency, throughput (cycles-per-instruction),
+and other microarchitecture-level performance data from the nested
+``arch_details`` dictionaries stored on :class:`~simdref.models.InstructionRecord`.
+
+They are consumed by the CLI, LSP, web-export, and man-page modules so
+that the extraction logic lives in exactly one place.
+
+Each ``arch_details[core]`` entry may carry provenance keys added by the
+ingesters (``source``, ``source_kind``, ``source_version``, ``applies_to``,
+``citation_url``). ``source_kind`` is either ``"measured"`` or
+``"modeled"``; when absent it defaults to ``"measured"`` for compatibility
+with the original uops.info rows which are measured.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NamedTuple
+
+
+class PerfValue(NamedTuple):
+    """A labeled performance value.
+
+    ``value`` is the cycle-count string (``"-"`` when missing).
+    ``source_kind`` is ``"measured"`` or ``"modeled"``.
+    ``core`` is the microarchitecture id the value came from (empty when none).
+    """
+
+    value: str
+    source_kind: str
+    core: str
+
+    def __str__(self) -> str:
+        return self.value
+
+
+MISSING_PERF = PerfValue("-", "", "")
+
+
+def _is_numeric(value: str) -> bool:
+    """Check if a string is a non-negative number (integer or decimal)."""
+    if not value:
+        return False
+    parts = value.split(".", 1)
+    return all(p.isdigit() for p in parts) and parts[0] != ""
+
+
+def _source_kind(details: dict[str, Any]) -> str:
+    """Return the provenance kind for an ``arch_details`` entry.
+
+    Defaults to ``"measured"`` when unset so legacy uops.info rows carry
+    the correct label without migration.
+    """
+    kind = details.get("source_kind")
+    if kind in ("measured", "modeled"):
+        return kind
+    return "measured"
+
+
+def latency_cycle_values(latencies: list[dict[str, Any]]) -> list[str]:
+    """Collect unique cycle-count strings from a list of latency dicts.
+
+    Each *latency* dict may contain keys like ``cycles``, ``cycles_mem``,
+    ``cycles_addr``, or ``cycles_addr_index``.  Values are collected in
+    order, skipping duplicates.
+
+    Returns:
+        De-duplicated list of cycle-count strings (may be empty).
+    """
+    values: list[str] = []
+    for latency in latencies:
+        for key in ("cycles", "cycles_mem", "cycles_addr", "cycles_addr_index"):
+            value = latency.get(key)
+            if value and value not in values:
+                values.append(value)
+    return values
+
+
+def best_numeric(values: list[str]) -> str:
+    """Return the smallest numeric string from *values*, or ``"-"`` if empty.
+
+    Non-numeric entries (e.g. ``"variable"``) are ignored when a numeric
+    alternative exists.  If every entry is non-numeric the first value is
+    returned as-is.
+    """
+    if not values:
+        return "-"
+    numeric = [v for v in values if _is_numeric(str(v))]
+    if numeric:
+        return min(numeric, key=lambda v: float(v))
+    return values[0]
+
+
+def _cpi_values(details: dict[str, Any]) -> list[str]:
+    measurement = details.get("measurement") or {}
+    out: list[str] = []
+    for key in ("TP_unrolled", "TP_loop", "TP_ports", "TP"):
+        value = measurement.get(key)
+        if value and value not in out:
+            out.append(value)
+    return out
+
+
+def _best_labeled(
+    arch_details: dict[str, dict[str, Any]],
+    value_fn,
+    kind_filter: str | None = None,
+) -> PerfValue:
+    """Return the lowest numeric value across arch entries, with provenance.
+
+    *value_fn* is called on each ``details`` dict and must return a list of
+    candidate cycle-count strings. When *kind_filter* is ``"measured"`` or
+    ``"modeled"`` only entries with that ``source_kind`` are considered.
+    """
+    best: tuple[float, str, str, str] | None = None
+    first_non_numeric: PerfValue | None = None
+    for core, details in arch_details.items():
+        kind = _source_kind(details)
+        if kind_filter is not None and kind != kind_filter:
+            continue
+        for value in value_fn(details):
+            value_str = str(value)
+            if _is_numeric(value_str):
+                numeric = float(value_str)
+                if best is None or numeric < best[0]:
+                    best = (numeric, value_str, kind, core)
+            elif first_non_numeric is None:
+                first_non_numeric = PerfValue(value_str, kind, core)
+    if best is not None:
+        return PerfValue(best[1], best[2], best[3])
+    if first_non_numeric is not None:
+        return first_non_numeric
+    return MISSING_PERF
+
+
+def best_latency_labeled(
+    arch_details: dict[str, dict[str, Any]],
+    kind_filter: str | None = None,
+) -> PerfValue:
+    """Lowest latency across arch entries, as a :class:`PerfValue`.
+
+    Prefers measured rows: if any measured row exposes a numeric latency
+    it is picked over all modeled rows. Pass ``kind_filter="modeled"`` to
+    select only modeled data.
+    """
+    def lat_values(details: dict[str, Any]) -> list[str]:
+        return latency_cycle_values(details.get("latencies") or [])
+
+    if kind_filter is None:
+        measured = _best_labeled(arch_details, lat_values, kind_filter="measured")
+        if measured.value != "-":
+            return measured
+        return _best_labeled(arch_details, lat_values, kind_filter="modeled")
+    return _best_labeled(arch_details, lat_values, kind_filter=kind_filter)
+
+
+def best_cpi_labeled(
+    arch_details: dict[str, dict[str, Any]],
+    kind_filter: str | None = None,
+) -> PerfValue:
+    """Lowest cycles-per-instruction across arch entries, as a :class:`PerfValue`."""
+    if kind_filter is None:
+        measured = _best_labeled(arch_details, _cpi_values, kind_filter="measured")
+        if measured.value != "-":
+            return measured
+        return _best_labeled(arch_details, _cpi_values, kind_filter="modeled")
+    return _best_labeled(arch_details, _cpi_values, kind_filter=kind_filter)
+
+
+def best_latency(arch_details: dict[str, dict[str, Any]]) -> str:
+    """Return the best (lowest) latency across all microarchitectures.
+
+    Prefers measured rows over modeled rows (see :func:`best_latency_labeled`).
+    """
+    return best_latency_labeled(arch_details).value
+
+
+def best_cpi(arch_details: dict[str, dict[str, Any]]) -> str:
+    """Return the best (lowest) cycles-per-instruction across all microarchitectures.
+
+    Prefers measured rows over modeled rows (see :func:`best_cpi_labeled`).
+    """
+    return best_cpi_labeled(arch_details).value
+
+
+def best_latency_measured(arch_details: dict[str, dict[str, Any]]) -> PerfValue:
+    """Lowest latency drawn exclusively from ``source_kind="measured"`` rows."""
+    return best_latency_labeled(arch_details, kind_filter="measured")
+
+
+def best_latency_modeled(arch_details: dict[str, dict[str, Any]]) -> PerfValue:
+    """Lowest latency drawn exclusively from ``source_kind="modeled"`` rows."""
+    return best_latency_labeled(arch_details, kind_filter="modeled")
+
+
+def best_cpi_measured(arch_details: dict[str, dict[str, Any]]) -> PerfValue:
+    """Lowest CPI drawn exclusively from ``source_kind="measured"`` rows."""
+    return best_cpi_labeled(arch_details, kind_filter="measured")
+
+
+def best_cpi_modeled(arch_details: dict[str, dict[str, Any]]) -> PerfValue:
+    """Lowest CPI drawn exclusively from ``source_kind="modeled"`` rows."""
+    return best_cpi_labeled(arch_details, kind_filter="modeled")
+
+
+def variant_perf_summary(arch_details: dict[str, dict[str, Any]]) -> tuple[str, str]:
+    """Return ``(best_latency, best_cpi)`` strings for a single variant."""
+    return best_latency(arch_details), best_cpi(arch_details)
+
+
+def variant_perf_summary_labeled(
+    arch_details: dict[str, dict[str, Any]],
+) -> tuple[PerfValue, PerfValue]:
+    """Return labeled ``(latency, cpi)`` for a single variant.
+
+    Each element carries its ``source_kind`` and originating ``core`` so
+    renderers can show "(measured, SKL)" / "(modeled, neoverse-n1)" suffixes.
+    """
+    return best_latency_labeled(arch_details), best_cpi_labeled(arch_details)

simdref/perf_sources/__init__.py

@@ -0,0 +1,51 @@
+"""Ingesters for measured and modeled microarchitectural perf data.
+
+Public surface:
+
+- :func:`ingest_llvm_mca` — drives the llvm-exegesis → llvm-mc →
+  llvm-mca pipeline per canonical core and returns modeled
+  :class:`PerfRow` s.
+- :func:`collect_core_schedule` — lower-level single-core entry point.
+- :func:`merge_perf_rows` — attaches produced rows to an existing catalog.
+- :data:`CANONICAL_CORES` — name-map from upstream core ids → stable ids.
+
+Per-instruction measured data for RISC-V RVV is not currently available
+from any public upstream: ``rvv-bench-results`` publishes kernel-level
+benchmarks (memcpy, chacha20, etc.), not instruction tables. RISC-V
+per-core rows therefore come from llvm-mca scheduling models only.
+"""
+
+from simdref.perf_sources.cores import (
+    CANONICAL_CORES,
+    canonical_core_id,
+    core_architecture,
+)
+from simdref.perf_sources.llvm_mca import (
+    LLVM_MCA_MIN_VERSION,
+    LLVMMcaError,
+    LLVMMcaUnavailable,
+    detect_llvm_mca_version,
+    ingest_llvm_mca,
+    parse_llvm_mca_json,
+)
+from simdref.perf_sources.llvm_scheduling import (
+    LLVMSchedulingError,
+    collect_core_schedule,
+)
+from simdref.perf_sources.merge import PerfRow, merge_perf_rows
+
+__all__ = [
+    "CANONICAL_CORES",
+    "canonical_core_id",
+    "core_architecture",
+    "PerfRow",
+    "merge_perf_rows",
+    "LLVM_MCA_MIN_VERSION",
+    "LLVMMcaError",
+    "LLVMMcaUnavailable",
+    "LLVMSchedulingError",
+    "detect_llvm_mca_version",
+    "ingest_llvm_mca",
+    "parse_llvm_mca_json",
+    "collect_core_schedule",
+]

simdref/perf_sources/cores.py

@@ -0,0 +1,101 @@
+"""Canonical core-id table.
+
+Upstream sources disagree about core naming: LLVM uses ``neoverse-n1``,
+rvv-bench labels its rows ``c908``/``c910``. This module
+maps every upstream alias to a single canonical id used inside
+``InstructionRecord.arch_details`` so lookups and filters are deterministic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CoreSpec:
+    """A canonical microarchitecture entry."""
+
+    canonical_id: str
+    architecture: str  # "x86", "aarch64", "riscv"
+    llvm_triple: str
+    llvm_cpu: str
+    aliases: frozenset[str]
+
+
+# AArch64 cores covered by LLVM scheduling models. Aliases include the
+# exact strings emitted by the upstream sources.
+AARCH64_CORES: tuple[CoreSpec, ...] = (
+    CoreSpec("cortex-a72", "aarch64", "aarch64-unknown-linux-gnu", "cortex-a72",
+             frozenset({"cortex-a72", "A72"})),
+    CoreSpec("cortex-a76", "aarch64", "aarch64-unknown-linux-gnu", "cortex-a76",
+             frozenset({"cortex-a76", "A76"})),
+    CoreSpec("cortex-a78", "aarch64", "aarch64-unknown-linux-gnu", "cortex-a78",
+             frozenset({"cortex-a78", "A78"})),
+    CoreSpec("cortex-x1", "aarch64", "aarch64-unknown-linux-gnu", "cortex-x1",
+             frozenset({"cortex-x1", "X1"})),
+    CoreSpec("cortex-x2", "aarch64", "aarch64-unknown-linux-gnu", "cortex-x2",
+             frozenset({"cortex-x2", "X2"})),
+    CoreSpec("neoverse-n1", "aarch64", "aarch64-unknown-linux-gnu", "neoverse-n1",
+             frozenset({"neoverse-n1", "N1", "Neoverse-N1"})),
+    CoreSpec("neoverse-n2", "aarch64", "aarch64-unknown-linux-gnu", "neoverse-n2",
+             frozenset({"neoverse-n2", "N2", "Neoverse-N2"})),
+    CoreSpec("neoverse-v1", "aarch64", "aarch64-unknown-linux-gnu", "neoverse-v1",
+             frozenset({"neoverse-v1", "V1", "Neoverse-V1"})),
+    CoreSpec("neoverse-v2", "aarch64", "aarch64-unknown-linux-gnu", "neoverse-v2",
+             frozenset({"neoverse-v2", "V2", "Neoverse-V2"})),
+    CoreSpec("a64fx", "aarch64", "aarch64-unknown-linux-gnu", "a64fx",
+             frozenset({"a64fx", "A64FX"})),
+    # Apple cores reuse the Linux AArch64 triple so llvm-exegesis can
+    # assemble on a non-Darwin host. The scheduling data we consume is
+    # keyed off --mcpu, not --mtriple, so the numbers are identical.
+    CoreSpec("apple-m1", "aarch64", "aarch64-unknown-linux-gnu", "apple-m1",
+             frozenset({"apple-m1", "M1"})),
+    CoreSpec("apple-m2", "aarch64", "aarch64-unknown-linux-gnu", "apple-m2",
+             frozenset({"apple-m2", "M2"})),
+    CoreSpec("thunderx2t99", "aarch64", "aarch64-unknown-linux-gnu", "thunderx2t99",
+             frozenset({"thunderx2t99", "ThunderX2"})),
+)
+
+# RISC-V cores with measured (rvv-bench) and modeled (LLVM) coverage.
+RISCV_CORES: tuple[CoreSpec, ...] = (
+    CoreSpec("sifive-u74", "riscv", "riscv64-unknown-linux-gnu", "sifive-u74",
+             frozenset({"sifive-u74", "U74"})),
+    CoreSpec("sifive-x280", "riscv", "riscv64-unknown-linux-gnu", "sifive-x280",
+             frozenset({"sifive-x280", "X280"})),
+    # LLVM 22 exposes the sifive-p400 and sifive-p600 *families* under the
+    # specific part names p450 and p670 (the default LLVM CPU names for
+    # those families). The canonical id is kept generic so catalog
+    # consumers can filter by family rather than part.
+    CoreSpec("sifive-p400", "riscv", "riscv64-unknown-linux-gnu", "sifive-p450",
+             frozenset({"sifive-p400", "sifive-p450", "P400", "P450"})),
+    CoreSpec("sifive-p600", "riscv", "riscv64-unknown-linux-gnu", "sifive-p670",
+             frozenset({"sifive-p600", "sifive-p670", "P600", "P670"})),
+    CoreSpec("c908", "riscv", "riscv64-unknown-linux-gnu", "xiangshan-nanhu",
+             frozenset({"c908", "C908"})),
+    CoreSpec("c910", "riscv", "riscv64-unknown-linux-gnu", "xiangshan-nanhu",
+             frozenset({"c910", "C910"})),
+    CoreSpec("x60", "riscv", "riscv64-unknown-linux-gnu", "sifive-x280",
+             frozenset({"x60", "X60", "Spacemit-X60"})),
+)
+
+CANONICAL_CORES: tuple[CoreSpec, ...] = AARCH64_CORES + RISCV_CORES
+
+_ALIAS_INDEX: dict[str, CoreSpec] = {}
+for _core in CANONICAL_CORES:
+    for _alias in _core.aliases:
+        _ALIAS_INDEX[_alias.casefold()] = _core
+    _ALIAS_INDEX[_core.canonical_id.casefold()] = _core
+
+
+def canonical_core_id(name: str) -> str | None:
+    """Return the canonical id for *name* or ``None`` if unknown."""
+    if not name:
+        return None
+    core = _ALIAS_INDEX.get(name.casefold())
+    return core.canonical_id if core is not None else None
+
+
+def core_architecture(canonical_id: str) -> str | None:
+    """Return the architecture family (x86/aarch64/riscv) for a canonical id."""
+    core = _ALIAS_INDEX.get(canonical_id.casefold())
+    return core.architecture if core is not None else None