Skip to content

Latest commit

 

History

History
106 lines (87 loc) · 5.61 KB

STRUCTURE.md

File metadata and controls

106 lines (87 loc) · 5.61 KB

Documentation structure

This file is the map of LiveHD's documentation: where each kind of doc lives, and when to read which. It is intentionally thin — it links out rather than duplicating content. Read this first on a cold start.

The layers

Layer Lives in Format Read it when…
Current work todo/ HTML you want the open task list, a task's design, or to record/close a task
Default algorithm reference (draft) external ../docs/docs/lhd/ Markdown → mkdocs you need the current synthesis algorithm, conditional physical flow, reuse policy and research references
LiveHD & Pyrope reference external ../docs → masc-ucsc.github.io/docs Markdown → mkdocs you need the "why/what": language semantics, IR concepts, CLI usage, architecture
Agent how-to + rules AGENTS.md Markdown you are building/testing/debugging, or need the change-gated coding rules
Directory orientation <dir>/README.md Markdown you are editing a specific directory and need its layout / gotchas
This map STRUCTURE.md Markdown cold start: figuring out where something belongs

Format principle

Documents a human reads but does not edit are HTML (the todo/ hub; the ../docs site is Markdown source rendered to HTML by mkdocs). Documents that are agent-only / agent-mostly are Markdown (AGENTS.md, directory README.mds, this file).

Layer details

todo/ — current work (HTML)

  • todo/index.html is the hub: a bullet summary of every open task, grouped by topic (LiveHD, Pyrope, Verilog) and by Group N.
  • One file per task at todo/<topic>/<id>.html. A task's full design lives in its page; cross-task dependencies are visible via shared Group letters.
  • Generated results and reproduction artifacts (reports, plots, metrics, logs, snapshots and benchmark outputs) belong under ignored repros/, never under todo/ or in Git. Task pages may link to these local artifacts; the links are available only in a checkout containing the corresponding results.
  • Lifecycle: a task page is deleted the moment the whole task lands. This layer is strictly current work — it carries no history (git does).

Task page structure

Every todo/<topic>/<id>.html follows the same shape so tasks read uniformly:

  1. <h1> — the task badge + a short title, then a 1–2 sentence summary.
  2. Depends on — a bullet list of the tasks this one needs first, each with a one-sentence reason; None. if it has no prerequisites.
  3. Subtasks — pending — the work left, as labelled items A, B, C, …, each with its own bullet list. The letter is a stable id.
  4. Subtasks — landed — subtasks that were pending and have shipped, moved here keeping their original letter (not deleted), until the whole task is done and the page is removed. None yet. if empty.
  5. (optional) Design notes — reference / spec material kept at the bottom.

When a subtask ships, mark it and move it from pending to landed with the same letter; delete the whole page only once the task is fully complete. Skeleton:

<h1><strong class="item-id">1d</strong> Demand-driven emit + DCE</h1>
<p>Short summary…</p>

<h2>Depends on</h2>
<ul><li><a class="xref" href="1f.html">1f</a> — why, in one sentence.</li></ul>
<!-- or: <p>None.</p> -->

<h2>Subtasks — pending</h2>
<ul class="subtasks">
  <li><strong>D — sea-of-nodes rewrite.</strong>
    <ul><li>detail</li></ul></li>
</ul>

<h2>Subtasks — landed</h2>
<ul class="subtasks">
  <li><strong>A — D1 range→sweep.</strong> <span class="status landed">landed</span></li>
</ul>

../docs — reference and algorithm methodology (Markdown → mkdocs)

  • The draft algorithm reference (../docs/docs/lhd/) describes the implemented default flow for expert readers and agents, with a separate conditional physical-flow chapter. Its maintenance appendix maps source evidence and local-document retirement candidates. Experimental algorithms, option catalogs and evaluation histories remain in their dedicated references.
  • The LiveHD guide (../docs/docs/livehd/*) and the Pyrope language reference (../docs/docs/pyrope/*) are the canonical "why/what". The Pyrope pages are the de-facto language contract.
  • The language/IR contract stays conceptual. The algorithm reference may link to source evidence and component READMEs without duplicating their details. Change-gated: content changes need human confirmation.

AGENTS.md — agent how-to + change-gated rules

  • Build/test commands, sibling-repo paths, running Pyrope/Yosys tests, debugging tips, and the Contracts section (compiler-warning policy, contract-test immutability). Enforcement scripts live in scripts/contracts/; baselines in .contracts/.
  • There is no in-repo docs/contracts/ directory — that role split into the ../docs reference (human contract) and AGENTS.md (agent rules).

<dir>/README.md — directory orientation (on-need)

  • A short Overview → Key files → Gotchas/debug hints for a directory, in Markdown. Added or extended only when there is a demonstrated need (an agent misread the structure, a file's purpose is non-obvious, or there's a debug gotcha). Examples: graph/README.md, upass/README.md, inou/attr/README.md, simlib/README.md.

Cross-links

  • README for humans: README.md.
  • Global agent guidance: AGENTS.md (also pointed to by CLAUDE.md).