Sync the manual with the current compiler and model stack - #25
Conversation
Remove revision-shaped reader provenance and generated route hashes, regenerate source-backed benchmark pages with stable names, and replace stale packaged-toolchain guidance with the pinned LLVM, QEMU, and LinxCoreModel workflow. Compile-check the public examples through a documentation-owned tile adapter and verify the intrinsic catalog against canonical v0.57 state. Constraint: v0.57 exposes exactly 111 PTO operations plus two execution identity helpers Constraint: one-level manifests remain source inventory until their retired compiler option and missing include root are migrated Rejected: promote repository-only TMATMUL_FIXP spellings into the intrinsic reference | they are absent from the canonical ISA state and pinned compiler Confidence: high Scope-risk: moderate Directive: rebuild the pinned compiler after submodule updates and preserve QEMU-before-gfsim promotion Tested: strict MkDocs build and link verification; 113-entry manual verifier; 85 manifest variants and 50 implementations; v0.57 catalog and encoding parity; DeepSeek verification; all documentation examples with pinned LLVM 23; TAdd/TLoad/TStore compiler smoke; canonical QEMU-to-LinxCoreModel smoke; ruff, shellcheck, compileall, compile.all syntax Not-tested: full one-level compilation because current main retains -mlxbc and lacks its expected include tree
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 67f0fd120e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
|
|
||
| def check_markdown_provenance(root: Path, errors: list[str]) -> None: | ||
| for path in root.rglob("*.md"): |
There was a problem hiding this comment.
Scanning root.rglob("*.md") makes docs/build.sh depend on unrelated, untracked files in the checkout. For example, a Markdown file installed under the documented repo-local .venv, or a developer's local notes containing a 40-character hash, now fails the publication gate even though it cannot be published; limit this check to the tracked reader-facing documentation set.
Useful? React with 👍 / 👎.
| inline void TMATMUL_ACC(Dst &dst, Previous &, Lhs &lhs, Rhs &rhs) { | ||
| ::MATMACC(dst, lhs, rhs); |
There was a problem hiding this comment.
When the four-operand form is called with distinct output and input accumulators, this wrapper ignores Previous and invokes MATMACC, which accumulates into the existing contents of dst. Thus the documented TMATMUL_ACC(c1, c0, a, b) form computes from an uninitialized or stale c1 instead of c0; copy the previous tile into the destination before accumulating, or otherwise preserve the source-accumulator semantics.
Useful? React with 👍 / 👎.
| python3 docs/scripts/generate_benchmark_manual.py | ||
| git diff --exit-code -- docs/content/benchmarks docs/mkdocs.yml README.md |
There was a problem hiding this comment.
In a clean checkout, running these two commands does not leave the advertised zero diff: the generator removes the three ignored hashtable_lookup_simd .data entries and the two ignored topk .data entries that are committed in the generated pages, so the following git diff --exit-code fails. Generate the checked-in pages without local ignored artifacts, or filter the inventory to tracked files, so this newly documented freshness check is reproducible.
Useful? React with 👍 / 👎.
| ) -> str: | ||
| source_hash = hashlib.sha1(rel(source, root).encode()).hexdigest()[:8] | ||
| page_name = f"{slug(source.stem)}-{source_hash}.md" | ||
| page_name = f"{slug(source.stem)}.md" |
There was a problem hiding this comment.
Switching to the unhashed filename deletes all previously published hash-suffixed URLs, so existing bookmarks and inbound links such as .../matmul/matmul-a008ac76/ now return 404. I checked the MkDocs configuration, requirements, and documentation generators and found no redirect map or retained alias pages; generate redirects from the former names while using the new stable paths for navigation.
Useful? React with 👍 / 👎.
| ## License | ||
|
|
||
| See LICENSE. | ||
| See [LICENSE](LICENSE). |
There was a problem hiding this comment.
This converts the license notice into a link to LICENSE, but no LICENSE or other license file exists anywhere in the repository, so the new GitHub-facing link is broken. Add the referenced license file or remove/change the link to an existing licensing source.
Useful? React with 👍 / 👎.
Limit publication checks and generated data inventories to tracked inputs, preserve legacy benchmark URLs with static redirects, and seed accumulated matrix products from the supplied previous tile. Remove the unsupported license link and add focused regression coverage for each executable behavior.\n\nConstraint: No new documentation dependency; redirects are emitted as static index pages.\nRejected: Markdown meta-refresh aliases | MkDocs places their canonical metadata in the document body.\nConfidence: high\nScope-risk: moderate\nDirective: Keep legacy route hashes derived from the historical source-path SHA-1 rule.\nTested: focused unittest suite, strict MkDocs build, manual verifier, Ruff, Python compileall, clean regeneration diff\nNot-tested: deployed GitHub Pages HTTP response before merge
Bring the newly landed flashMLA sources and manifest fix into the reviewed documentation branch, then regenerate the stable catalog and legacy redirects from the combined repository state.\n\nConstraint: PR #25 must merge against the current main branch.\nRejected: Preserve the incoming hash-suffixed generated catalog | it would restore unstable navigation and conflict with the reviewed stable-route generator.\nConfidence: high\nScope-risk: moderate\nDirective: Regenerate the benchmark catalog after future manifest changes.\nTested: focused unittest suite, Ruff, Python compileall, strict MkDocs build, 87-entry manual verifier, clean regeneration diff\nNot-tested: deployed GitHub Pages HTTP response before merge
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ab81d5aad9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| template <typename Dst, typename Previous, typename Lhs, typename Rhs> | ||
| inline void TMATMUL_ACC(Dst &dst, Previous &previous, Lhs &lhs, Rhs &rhs) { |
There was a problem hiding this comment.
When a reader uses the documented in-place form TMATMUL_ACC(accum, lhs, rhs)—shown in docs/content/programming/cpp-programming-guide.md and declared in docs/content/intrinsics/tmatmul_acc.md—the new public adapter exposes only this four-argument template. Compiling that call against docs/content/examples/include fails with “candidate expects 4 arguments,” so add a three-operand overload that forwards directly to MATMACC while retaining this distinct-output form.
Useful? React with 👍 / 👎.
1 participant
Summary
Verification
docs/build.sh(strict MkDocs build and internal links)TAdd,TLoad, andTStorecompiler smoke casescompile.allshell syntaxCurrent boundary
The one-level catalog is source inventory, not LLVM 23 compile proof: current main still carries the retired
-mlxbcoption and lacks the include root expected by that make lane. Repository-onlyTMATMUL_FIXPspellings remain documented as helpers because they are absent from canonical v0.57 and the pinned compiler.