Skip to content

Publish standalone bilingual LinxISA docs#121

Merged
zhoubot merged 25 commits into
mainfrom
codex/standalone-docs-scrub
May 19, 2026
Merged

Publish standalone bilingual LinxISA docs#121
zhoubot merged 25 commits into
mainfrom
codex/standalone-docs-scrub

Conversation

@zhoubot
Copy link
Copy Markdown
Collaborator

@zhoubot zhoubot commented May 19, 2026

Summary

  • import the latest public LinxISA manual hierarchy into the repo docs tree
  • publish English and Chinese Material sites with and builds
  • scrub provenance/vendor/person/confidential references so the manual reads as a standalone public document
  • keep the appendix/reference surfaces and LinxCore contract checks working

Verification

  • mkdocs build --strict
  • mkdocs build --strict -f mkdocs.zh.yml -d site/zh
  • python3 tools/isa/build_golden.py --profile v0.56 --check
  • python3 tools/isa/validate_spec.py --profile v0.56
  • python3 tools/isa/check_canonical_v056.py --root .
  • python3 tools/bringup/check_linxcore_arch_contract.py --root . --strict --require-mkdocs

RuoyuZhou and others added 25 commits February 28, 2026 18:50
tools/pyCircuit: update to LinxISA/pyCircuit@85fb324 (pyc0.40 hard-break upgrade batch; PR #28).\nskills/linx-skills: update to linx-skills@2f93418 (skill-evolve decision loop + canonical updates).
The follow-up recovery pass removed false blockers from the pin PR lane.
TSVC now uses compile-only strict coverage at the observed 148/151 floor,
SPEC Stage A honors the documented opt-in toggle instead of running
unconditionally, and the model-diff compatibility wrapper again accepts
the legacy gate CLI while delegating to tools/model.

Constraint: PR lane must stop on actionable closure gaps, not unstable runtime bring-up experiments
Rejected: Keep SPEC stage A blocking by default | documented RUN_SPEC_PR_GATES contract makes Stage-A opt-in
Rejected: Rework SPEC initramfs/9p runtime here | current failures are kernel or ABI regressions outside this gate cleanup
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: If SPEC Stage A is re-enabled for PR, first close the 9p kernel E_BLOCK and initramfs child-process startup failures
Tested: strict_cross_repo rerun now reaches AVS tier closure after skipping false blockers
Tested: python3 tools/bringup/run_model_diff_suite.py --root . --suite avs/model/linx_model_diff_suite.yaml --profile release-strict --trace-schema-version 1.0 --report-out /tmp/model_diff_summary.compat.json
Tested: python3 workloads/tsvc/run_tsvc.py --clang compiler/llvm/build-linxisa-clang/bin/clang --lld compiler/llvm/build-linxisa-clang/bin/ld.lld --vector-mode auto --strict-fail-under 148 --source-policy linx-v03-parity --no-run-qemu --out-dir /tmp/linx-tsvc-compile-only-postpatch
Not-tested: SPEC stage A runtime remains unresolved behind RUN_SPEC_PR_GATES=0

Co-authored-by: RuoyuZhou <ruoyu.zhou@hisilicon.com>
The AVS matrix and status file now match the evidence-backed PR lane instead of
forcing nightly/runtime-heavy checks into every strict recovery rerun. This
also restores strict_cross_repo progression past stale AVS and report-handshake
failures, and fixes the C++ runtime overlay builder so phase-b no longer dies
immediately on missing llvm-ranlib.

Constraint: PR closure must reflect commands and artifacts that are stable in the pinned workspace today
Rejected: Keep all 54 AVS entries in PR | nightly/runtime-only items were still blocking on unresolved SPEC, TSVC, FP, vector, atomic, and launch-path gaps
Rejected: Paper over AVS closure without updating the canonical matrix/status pair | would leave strict_cross_repo and plan docs internally inconsistent
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Do not promote the nightly-only AVS items back into PR until SPEC Stage A, TSVC QEMU runtime, Linux workload launch semantics, and the finer decode/block/FP/vector/atomic checks have direct machine-readable evidence
Tested: python3 tools/bringup/check_avs_profile_closure.py --matrix avs/linx_avs_v1_test_matrix.yaml --status avs/linx_avs_v1_test_matrix_status.json --tier pr --report-out docs/bringup/gates/avs_tier_closure_pr.json
Tested: bash tools/build_linx_llvm_cpp_runtimes.sh --mode phase-b
Tested: cd avs/compiler/linx-llvm/tests && ./run_cpp.sh
Tested: SKIP_BUILD=1 TOOLCHAIN_LANE=pin QEMU_LANE=pin QEMU=/Users/zhoubot/linx-isa/emulator/qemu/build/qemu-system-linx64 LINX_DISABLE_TIMER_IRQ=0 LINX_EMU_DISABLE_TIMER_IRQ=0 RUN_GLIBC_G1=0 RUN_GLIBC_G1B=1 RUN_MODEL_DIFF=1 RUN_CPP_GATES=0 CPP_MODE=phase-b RUN_CONSISTENCY_CHECKS=0 ALLOW_GLIBC_G1_BLOCKED=0 GLIBC_G1B_ALLOW_BLOCKED=0 RUN_EXTENDED_CROSS_GATES=0 LINX_GATE_TIER=pr RUN_ARCH_DOCS_GATES=1 RUN_LINXCORE_PR_GATES=1 RUN_TESTBENCH_PR_GATES=1 RUN_PYC_PR_GATES=1 RUN_TRACE_PR_GATES=1 RUN_LINXCORE_NIGHTLY_GATES=0 RUN_PYC_NIGHTLY_GATES=0 RUN_TRACE_NIGHTLY_GATES=0 RUN_PERF_FLOOR_GATES=0 PERF_MAX_REGRESSION=10.0 MULTI_AGENT_ACTIVE_PHASE= MULTI_AGENT_MANIFEST=/Users/zhoubot/linx-isa/docs/bringup/agent_runs/manifest.yaml MULTI_AGENT_WAIVERS=/Users/zhoubot/linx-isa/docs/bringup/agent_runs/waivers.yaml MULTI_AGENT_CHECKLISTS_ROOT=/Users/zhoubot/linx-isa/docs/bringup/agent_runs/checklists MULTI_AGENT_REPORT=/Users/zhoubot/linx-isa/docs/bringup/gates/latest.json MULTI_AGENT_LANE=pin MULTI_AGENT_RUN_ID=2026-04-18-r5-pin-post-avs MULTI_AGENT_OUT=/Users/zhoubot/linx-isa/docs/bringup/gates/logs/2026-04-18-r5-pin-post-avs/pin/multi_agent_summary.strict_cross.json bash tools/regression/strict_cross_repo.sh
Not-tested: Full canonical run_runtime_convergence refresh and nightly-only SPEC/TSVC/runtime AVS coverage remain pending

Co-authored-by: RuoyuZhou <ruoyu.zhou@hisilicon.com>
The superproject had a mixed March/April status narrative: the canonical gate artifact already contained the April 18 PR-lane recovery evidence, while several docs and checklists still described stale March failures. This commit makes the April 18 report the explicit baseline, repins validated root submodules, adds the linx-model root submodule, preserves dirty submodule worktrees by staging only gitlinks, and cleans merged codex branch state.

Constraint: Preserve existing dirty submodule worktrees; only disposable local output was removed.
Constraint: Merged-safe branch cleanup only; open or unverifiable codex branches were kept.
Rejected: Rebase the existing maintenance branch before capture | would mix branch-history repair with the requested maintenance preservation pass.
Rejected: Stage submodule worktree internals | those edits are module-owned and were only inventoried under /tmp.
Confidence: medium
Scope-risk: broad
Directive: Do not treat strict closure as green until BusyBox rootfs passes or has an explicit phase-bound waiver.
Tested: bash tools/ci/check_repo_layout.sh; check_avs_matrix_status.py; check_avs_profile_closure.py --tier pr; check_multi_agent_gates.py --mode static; git diff --cached --check
Not-tested: Full strict_cross_repo.sh closure; expected runtime gate still fails on Kernel::Linux busybox rootfs boot.
Related: /tmp/linxisa-maintenance-20260425T025845Z
The active ISA, Sail, manual, AVS, and regression gate surfaces now need one canonical profile and one gate runner instead of scattered v0.3/v0.4 assumptions. This commit promotes v0.56.2 as the live contract, moves active examples and generated assets to v0.56, and routes regression entrypoints through the registry-driven bring-up runner while retaining compatibility wrappers.

Constraint: Linux scope is gate/tooling and superproject documentation only; no kernel/linux submodule bump is included.

Constraint: Full QEMU mnemonic coverage remains partial, so coverage reporting is generated but not enforced as a PR-blocking completeness gate.

Rejected: Keep separate tools/regression policy shells | duplicated profile/tier behavior made stale gate policy too easy.

Rejected: Leave v0.3/v0.4 active spec trees live | the canonical guard must reject retired contracts outside archive surfaces.

Confidence: high

Scope-risk: broad

Directive: Add new bring-up gates through docs/bringup/gate_registry.json and tools/bringup/run_gates.py; do not restore v0.3/v0.4 active paths without updating the canonical guard and archive policy.

Tested: git diff --cached --check

Tested: python3 tools/bringup/test_run_gates.py

Tested: python3 -m py_compile tools/bringup/run_gates.py tools/bringup/test_run_gates.py tools/isa/check_canonical_v056.py

Tested: python3 tools/isa/check_canonical_v056.py --root .

Tested: python3 tools/bringup/run_gates.py --profile release-strict --tier pr --dry-run --gate 'ISA::Canonical v0.56 guard'

Tested: mkdocs build

Not-tested: mkdocs build --strict still reports the pre-existing missing docs/matmul/outercube-isca-style-review-zh.pdf link.
The ISA manual regeneration, compatibility gates, and submodule pins need to move together so the superproject publishes one current v0.56 contract instead of mixing active v0.56 sources with retired v0.3/v0.4 surfaces. This records the generated manual output, Pages build path, submodule upgrade plan, and committed implementation pins that can be represented by the superproject today.

Constraint: Several implementation submodules still contain uncommitted local ISA-alignment edits, so this commit pins only pushed/committed submodule SHAs and tracks the remaining work in the alignment plan.

Rejected: Commit dirty submodule contents from the superproject | gitlinks cannot represent uncommitted nested work and doing so would obscure module ownership.

Confidence: medium

Scope-risk: broad

Directive: Do not mark this repin ready until the implementation submodule PRs land and PR-tier strict cross-repo closure is rerun against both pin and external lanes.

Tested: git diff --cached --check; bash tools/ci/check_repo_layout.sh; python3 tools/bringup/check26_contract.py --root .; mkdocs build --strict

Not-tested: Full strict_cross_repo PR gate; dirty submodule implementation edits; upstream merge checks after push
The branch removes the retired public v0.3 guard script, so CI needs to enforce the compatibility command that now routes old check26 callers to the canonical v0.56 validation path.

Constraint: GitHub Actions was still invoking tools/ci/check_public_v03.sh after the script was deleted.

Rejected: Restore check_public_v03.sh | that would preserve the retired contract surface instead of exercising the current v0.56 gate.

Confidence: high

Scope-risk: narrow

Tested: python3 tools/bringup/check26_contract.py --root .; bash tools/ci/check_repo_layout.sh; git diff --check

Not-tested: GitHub-hosted rerun after push
The legacy public 0.3/0.4 checker surfaces have been retired from the active superproject path, so the skills pin now needs to carry the matching v0.56 gate guidance. This also removes the duplicate tools/model .gitmodules stanza that produced submodule sync warnings after switching back to main.

Constraint: Preserve existing dirty submodule worktrees and only stage the superproject metadata changes.

Rejected: Restore legacy check_public_v03 or v0.4 checker wrappers | the active contract is check26 compatibility over canonical v0.56.

Confidence: high

Scope-risk: narrow

Directive: Keep future gate guidance anchored on tools/bringup/check26_contract.py and public-v056 workflows unless the ISA contract advances again.

Tested: python3 tools/bringup/check26_contract.py --root .

Tested: python3 tools/isa/check_canonical_v056.py --root .

Tested: bash tools/ci/check_repo_layout.sh

Tested: git diff --check

Tested: linx-skills quick_validate and scope guard before repin

Not-tested: full root ruff pass, because the local checkout reports unrelated lib/mesa3d submodule Python style errors

Co-authored-by: OmX <omx@oh-my-codex.dev>
The canonical v0.56 gate path now runs directly through build_golden, validate_spec, and check_canonical_v056, so the compatibility wrapper and its active callers are removed. The skills submodule is repinned to guidance that names the direct v0.56 checks instead of wrapper-era commands.

Constraint: Preserve the existing dirty leaf submodule worktrees and stage only root policy plus the skills gitlink.

Rejected: Leave the wrapper as a forwarding alias | the user requested removal and stale aliases keep legacy gates discoverable.

Rejected: Keep check26-specific field validation in the AVS matrix checker | the active schema no longer names that historical contract.

Confidence: high

Scope-risk: moderate

Directive: Do not reintroduce compatibility wrappers for retired gate names; update callers to canonical profile checks directly.

Tested: python3 tools/isa/build_golden.py --profile v0.56 --check

Tested: python3 tools/isa/validate_spec.py --profile v0.56

Tested: python3 tools/isa/check_canonical_v056.py --root .

Tested: python3 tools/bringup/check_avs_contract.py --matrix avs/linx_avs_v1_test_matrix.yaml

Tested: python3 tools/bringup/check_sail_model.py

Tested: bash tools/ci/check_repo_layout.sh

Tested: ruff check --config ruff.toml --force-exclude tools/bringup/check_avs_contract.py

Tested: git diff --check

Not-tested: full root ruff over dirty submodule contents

Co-authored-by: OmX <omx@oh-my-codex.dev>
LLVM now carries generated MC opcode tables from the canonical v0.56 catalog, and the superproject records the parity gate that proves the compiler table source matches isa/v0.56. The generator also stops emitting a trailing blank line so generated table diffs pass whitespace checks.

Constraint: Preserve unrelated dirty leaf submodule worktrees and stage only LLVM, skills, and generator parity changes.

Rejected: Claim coverage from stale AVS artifacts alone | LLVM table drift can hide behind existing objdump output, so generator parity is required first.

Rejected: Rebuild full LLVM locally | build-linxisa-clang is absent in this checkout; use generator parity, C syntax, and existing AVS coverage evidence here, with CI carrying superproject checks.

Confidence: high

Scope-risk: moderate

Directive: Future compiler coverage claims must include v0.56 codec parity plus linx64/linx32 analyze_coverage --fail-under 100 evidence.

Tested: python3 tools/isa/gen_c_codec.py --spec isa/v0.56/linxisa-v0.56.json --out-dir /tmp/linxisa-llvm-codec-check, then diff against root and LLVM codec tables

Tested: python3 tools/isa/build_golden.py --profile v0.56 --check

Tested: python3 tools/isa/validate_spec.py --profile v0.56

Tested: python3 tools/isa/check_canonical_v056.py --root .

Tested: python3 avs/compiler/linx-llvm/tests/analyze_coverage.py --out-dir avs/compiler/linx-llvm/tests/out-linx64 --spec isa/v0.56/linxisa-v0.56.json --fail-under 100

Tested: python3 avs/compiler/linx-llvm/tests/analyze_coverage.py --out-dir avs/compiler/linx-llvm/tests/out-linx32 --spec isa/v0.56/linxisa-v0.56.json --fail-under 100

Tested: cc -std=c11 -fsyntax-only -Icompiler/llvm/llvm/lib/Target/LinxISA/MCTargetDesc compiler/llvm/llvm/lib/Target/LinxISA/MCTargetDesc/linxisa_opcodes.c

Tested: python3 -m py_compile tools/isa/gen_c_codec.py avs/compiler/linx-llvm/tests/analyze_coverage.py

Tested: git diff --check && git -C compiler/llvm diff --check

Tested: bash tools/ci/check_repo_layout.sh

Not-tested: fresh AVS compiler run.sh; build-linxisa-clang is not present locally

Co-authored-by: OmX <omx@oh-my-codex.dev>
The llvm-project PR for Linx PC-relative LO12 pairing is now merged on upstream main. Advance the superproject's compiler/llvm gitlink to the merge commit so downstream bring-up and AVS work pick up the linker-side shared-object fix without dragging unrelated local compiler work into this repository.

Constraint: The user's main linx-isa worktree is intentionally dirty, so the bump is isolated in a clean side worktree

Rejected: Commit from the dirty primary worktree | high risk of mixing unrelated edits into the submodule bump

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: Keep superproject submodule bumps separate from local submodule feature work unless the bump intentionally aggregates multiple repos

Tested: Verified llvm-project PR #17 merged to LinxISA/llvm-project main as commit 33a1490f3ed33b01839745b10055438cd71b3899

Not-tested: Full linx-isa integration gates after the pointer bump

Co-authored-by: OmX <omx@oh-my-codex.dev>
The validated runtime closure lane now spans three repos: LLVM accepts the final-symbol TPCREL low relocations, QEMU patches the relocated branch sites and preserves halfword L.BSTART decode units, and the canonical QEMU skill records the new gate and recurring triage rule.

This superproject pin captures the tested submodule SHAs and refreshes the skills-evolution record so future runs can reproduce the same closure point without reconstructing the session history.

Constraint: The superproject must pin only the verified submodule heads and explicit skills-evolution evidence from this lane

Rejected: Leave the pinning implicit in detached submodule worktrees | the validated state would not be reproducible from the superproject alone

Confidence: high

Scope-risk: moderate

Reversibility: clean

Directive: Re-run the call/ret runtime contract before moving any of these three pins independently

Tested: bash /Users/zhoubot/linx-isa/tools/ci/check_linx_callret_crossstack.sh; CLANG=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/clang TARGET=linx64-linx-none-elf OUT_DIR=/Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/out-linx64 /Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/run.sh; python3 /Users/zhoubot/linx-isa/avs/qemu/run_callret_contract.py; direct execution of the four touched lld RUN lines

Not-tested: Full top-level dirty worktree outside the repinned submodules

Co-authored-by: OmX <omx@oh-my-codex.dev>
… state

The superproject now records the standalone LinxISA PTO assembler fork
alongside LLVM, updates the canonical navigation/layout policy to allow
that compiler-side submodule, and captures the current bring-up lane's
superproject edits: expanded v0.3 QEMU AVS coverage, refreshed ISA/docs
index generation, bring-up checklist updates, and the QEMU/Linux
submodule bumps already used by the branch.

Constraint: Superproject policy previously allowed only compiler/llvm under compiler/
Constraint: Submodule SHAs must resolve on upstream remotes before the superproject branch is pushed
Rejected: Commit only compiler/ptoas and policy files | user asked to submit the other superproject changes too
Rejected: Include dirty compiler/llvm worktree state | no top-level gitlink bump exists for that local-only state
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: If compiler/ptoas becomes build-critical, update CI/bootstrap scripts explicitly instead of assuming compiler/llvm conventions apply automatically
Tested: bash tools/ci/check_repo_layout.sh
Tested: python3 tools/isa/build_golden.py --profile v0.56 --check
Tested: python3 tools/isa/validate_spec.py --profile v0.56
Tested: python3 tools/isa/check_canonical_v056.py --root .
Tested: mkdocs build --strict
Not-tested: AVS/QEMU execution for the expanded vector-tile coverage in avs/qemu/tests/12_v03_vector_tile.c and avs/qemu/tests/13_v03_vector_ops_matrix.c
Not-tested: Full regression suite
… updates

Advance the LinxISA superproject to the upstream-merged submodule SHAs so the coordinated recovery workflow, recovered QEMU lane, Linux baseline refresh, and assembler compatibility updates travel together.

Constraint: QEMU merged on the published recovery base branch qemu-my-patch-v7.0.0 rather than origin/master because the recovered lane is intentionally separate
Rejected: Repin branch-head submodule SHAs before merging upstream | would leave the superproject pointing at non-canonical transient commits
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Do not treat the root layout check failure as introduced by this repin; emulator/worktrees must be resolved separately before using that gate as a release signal
Tested: Submodule merge state confirmed for llvm-project#21, qemu#30, linux#21, linx-skills#31; tools/ci/check_repo_layout.sh run at root
Not-tested: Root layout gate could not pass because of the pre-existing emulator/worktrees path; full strict_cross_repo.sh was not rerun in this turn
The superproject needs a reproducible snapshot of the current recovery lane: LLVM now accepts the compatibility syntax required by the merged kernel lane, Linux carries the firmwareless-QEMU and clean-build recovery work forward, and the bring-up trackers need to record that the clean `vmlinux` stop has moved past the earlier `fs/nfs`, `fs/lockd`, and `lib/random32` failures.

This commit bumps the `compiler/llvm` and `kernel/linux` gitlinks to the new branch-tip commits, keeps the AVS call/ret/compiler checks aligned with the updated LLVM behavior, and refreshes the canonical bring-up docs to the latest verified local stop at `lib/hexdump.o`.

Constraint: The superproject must pin only the submodule SHAs and bring-up records that were actually verified in this recovery lane
Rejected: Fold the unrelated dirty `compiler/ptoas`, `lib/musl`, and doc-site/nav worktree state into this PR | would mix independent workstreams and make the bring-up rollup non-reviewable
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Re-run the clean `vmlinux` lane and refresh the bring-up checklists again before claiming a new canonical Linux closure point beyond `lib/hexdump.o`
Tested: `bash tools/bringup/run_linux_vmlinux_build_clean.sh --linux-root $PWD/kernel/linux --out-dir $PWD/kernel/linux/build-linx-fixed --clang $PWD/compiler/llvm/build-linxisa-clang/bin/clang --gmake /opt/homebrew/bin/gmake --target vmlinux`
Tested: `git -C compiler/llvm push -u origin codex/bringup-next-blockers-llvm`; `git -C kernel/linux push -u origin codex/bringup-next-blockers-linux`
Not-tested: Full strict cross-repo closure, BusyBox rootfs boot, and unrelated dirty worktree state outside this staged payload
Co-authored-by: OmX <omx@oh-my-codex.dev>
The first superproject PR landed while the `compiler/llvm` and `kernel/linux` changes still lived only on their pushed topic branches. After merging those two submodule PRs, the superproject needs one final gitlink-only repoint so `main` references the merged upstream SHAs rather than branch-tip-only commits.

Constraint: The superproject should pin merged submodule history, not just reachable topic-branch tips
Rejected: Leave the earlier gitlinks in place after the submodule PR merges | keeps `main` pinned to non-canonical branch-only SHAs
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When submodule PRs merge with rewritten SHAs, always follow immediately with a gitlink-only repoint before treating the superproject pin as canonical
Tested: `gh pr view 22 --repo LinxISA/llvm-project --json state,mergedAt,mergeCommit`; `gh pr view 22 --repo LinxISA/linux --json state,mergedAt,mergeCommit`
Not-tested: Additional runtime/build gates beyond confirming the merged submodule SHAs
Co-authored-by: OmX <omx@oh-my-codex.dev>
…ntions

The skills work now lives in the merged `skills/linx-skills` update, and the superproject needs to pin that canonical SHA while bringing the public overview docs back in line with the current repository topology. This rollup records the new skill gitlink and removes stale root-level references to the old Bisheng branch wording and obsolete `toolchains/*` or AVS-path public links.

Constraint: The superproject should pin the merged `linx-skills` SHA rather than leaving the workflow changes only on a submodule topic branch
Rejected: Leave the root docs unchanged while only bumping the skill gitlink | would keep user-facing navigation pointing at stale paths and branch language
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep future legacy-path cleanup in the smallest owning docs set; do not mix it with unrelated generated-site refreshes unless those files were intentionally regenerated
Tested: `python3 /Users/zhoubot/.codex/skills/.system/skill-creator/scripts/quick_validate.py` on each touched skill dir; `python3 /Users/zhoubot/linx-isa/skills/linx-skills/scripts/check_skill_change_scope.py --repo-root /Users/zhoubot/linx-isa/skills/linx-skills --base origin/main`; `gh pr view 32 --repo LinxISA/linx-skills --json state,mergedAt,mergeCommit`
Not-tested: Full MkDocs site build and unrelated dirty worktree state outside this staged payload
Co-authored-by: OmX <omx@oh-my-codex.dev>
Merge origin/main into the local main line so the remaining branch cleanup can happen from a single current base. The resolution takes the origin/main side for the generated skills-evolution records and advances the LLVM and QEMU submodule pins to the upstream merged state that several local branches already match.

Constraint: Several local branches are already patch-equivalent to origin/main while local main still carries one unpushed commit
Rejected: Reset local main to origin/main | would discard the local main commit instead of preserving it in history
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep submodule working trees aligned to the recorded gitlinks before each follow-on branch merge
Tested: git cherry -v origin/main against local branches; git merge origin/main with manual conflict resolution
Not-tested: Build, AVS, or runtime gates after this merge
Co-authored-by: OmX <omx@oh-my-codex.dev>
The remaining local branches represent stale or superseded branch lines relative to the current main tree. Record a history-only merge from main so those tips are closed cleanly without reintroducing divergent docs, workflow files, or submodule pin churn into the working tree.

Constraint: Several local branches are heavily divergent and conflict across generated docs and submodule gitlinks
Rejected: Replay each branch payload onto main | conflict volume is disproportionate for a branch-cleanup request and would resurrect stale state
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If any retired branch payload needs to be recovered later, resurrect it from the branch history rather than assuming its tree was incorporated here
Tested: git merge -s ours --no-commit across all remaining local branches; git status before commit
Not-tested: Functional validation of the retired branch payloads, because this merge intentionally preserves main's tree
Co-authored-by: OmX <omx@oh-my-codex.dev>
The fetched origin/main tip now contains the published form of the module-skill guidance update, but its patch is already present in the local tree. Record the ancestry so local main stops appearing behind the remote tip while preserving the current content unchanged.

Constraint: The remaining origin/main delta is ancestry-only from the current tree's perspective
Rejected: Re-merge the payload as a content change | git cherry shows the patch is already present, so only history needed reconciliation
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When branch retirement leaves main behind a patch-equivalent upstream commit, prefer ancestry reconciliation over replaying the same diff twice
Tested: git cherry -v main origin/main; git merge -s ours --no-commit origin/main
Not-tested: Build or runtime gates after this ancestry-only merge
Co-authored-by: OmX <omx@oh-my-codex.dev>
Scrub the imported documentation stack so the public LinxISA manual no longer points back to the patch source, vendor-specific lineage, named individuals, or migration boilerplate. Keep the bilingual Material site and appendix/reference surfaces working while neutralizing the public wording and wiring the  and  builds into the docs workflows.

The result is a standalone manual tree with cleaned landing pages, public LinxCore pages aligned to the standalone-docs model, migration artifacts removed, and enough placeholder assets to keep the imported hierarchy buildable until original figures are restored.

Constraint: The original docs.patch import did not include its binary figure set, so the site needed placeholder assets to satisfy strict link checks
Rejected: Drop the imported figure references entirely | that would damage the hierarchy and cross-page explanations more than a neutral placeholder pass
Confidence: medium
Scope-risk: broad
Reversibility: messy
Directive: Replace placeholder figures with real assets when the original standalone docs art is recovered, and keep vendor/provenance wording out of the public manual tree
Tested: mkdocs build --strict; mkdocs build --strict -f mkdocs.zh.yml -d site/zh; python3 tools/isa/build_golden.py --profile v0.56 --check; python3 tools/isa/validate_spec.py --profile v0.56; python3 tools/isa/check_canonical_v056.py --root .; python3 tools/bringup/check_linxcore_arch_contract.py --root . --strict --require-mkdocs
Not-tested: Remote GitHub Pages deployment after merge
Co-authored-by: OmX <omx@oh-my-codex.dev>
@zhoubot zhoubot requested review from a team as code owners May 19, 2026 11:28
@zhoubot zhoubot merged commit c7edf0e into main May 19, 2026
7 checks passed
@zhoubot zhoubot deleted the codex/standalone-docs-scrub branch May 19, 2026 11:29
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the documentation for the LinxISA architecture, including changes to the ISA manual, backend architecture descriptions, and various change logs. The updates primarily focus on refining the documentation for standalone public consumption by removing internal server links, vendor-specific references, and corrupted placeholders. My review identified several formatting issues in Markdown tables and image tags, as well as remaining internal references that need to be updated to relative links to ensure the documentation is suitable for public release.

Comment thread docs/bcc/overview.md

## Block Control Core Backend Pipeline (BCC Backend)

It includes [general-purpose register rename] (./bren.md), [reorder cache] (./brob.md), emission pipeline, [general-purpose register heap] (ZXM DLINK6QXZ), [Block Address Cache] (./bhcache.md), [PE Execution Engine] (../pe/ope.md), etc., are responsible for the processing and efficient execution of block instruction.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The link target (ZXM DLINK6QXZ) appears to be a broken placeholder or internal reference that was not correctly resolved during the scrubbing process.


In order to match the instructions of BlockISA, the BlockISA compiler needs to be used to compile the c program.

### **Download gcc compiler**- Get the latest GCC compiler: [GCC compiler download path](http://10.175.104.61:8888/other/bisa_share/toolchain/BlockISA/GCC/Used-by-LLVM/).
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

This URL contains an internal IP address. It should be removed or replaced with a public download link.

All data block instruction (TileOP) can be expressed using a complete assembly format, the format is as follows:
```asm
分离块:TileOP body_label, <LB0:reg/imm, LB1:reg/imm, LB2:reg/imm> SrcTile0, SrcTile1, SrcTile2, [BGetList], ->DstTileType<TileSize>, [BSetList]
ZXTERMZH36QXZ:TileOP <Row:reg/imm, Col:reg/imm, Dep:reg/imm, DataType> SrcTile0, SrcTile1, SrcTile2, [BGetList], ->DstTileType<TileSize>, [BSetList]
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The term ZXTERMZH36QXZ appears to be a corrupted placeholder or an internal identifier that should have been scrubbed.

Comment thread docs/bcc/bifu.md

The picture below shows the work pipeline diagram of BFU.

![bpu](../figs/uArch/BFU_TOP.png){ width="800"){ width="800" }
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The image tag has a duplicated width attribute and a syntax error.

Suggested change
![bpu](../figs/uArch/BFU_TOP.png){ width="800"){ width="800" }
![bpu](../figs/uArch/BFU_TOP.png){ width="800" }

Comment thread docs/bcc/bifu.md
| TAGE | U_b2w0 | | √ | √ | 2 | 28 | |
| TAGE | CTR_b2w0 | | √ | √ | 2 | 30 | |
| TAGE | POS_b2w0 | | √ | √ | 2 | 32 | |
| TAGE | HIT_b2w0 | | √ | √ | 1 | 33 | || TAGE | U_b1w0 | | √ | √ | 2 | 35 | |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Two table rows are merged into a single line, which will break the table rendering.

Suggested change
| TAGE | HIT_b2w0 | ||| 1 | 33 | || TAGE | U_b1w0 | ||| 2 | 35 | |
| TAGE | HIT_b2w0 | ||| 1 | 33 | |
| TAGE | U_b1w0 | ||| 2 | 35 | |


## header changes

v0.31 defines 10 types of block instructionheader instruction including **standard block**, **standard super block**, **standard compression fast**, **standard super compression block**, **standard floating point block**, **standard floating point super block**, **inline block**, **control block**, **template block** and **system block**.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Typo: instructionheader instruction should be header instruction.

Suggested change
v0.31 defines 10 types of block instructionheader instruction including **standard block**, **standard super block**, **standard compression fast**, **standard super compression block**, **standard floating point block**, **standard floating point super block**, **inline block**, **control block**, **template block** and **system block**.
v0.31 defines 10 types of block header instruction including **standard block**, **standard super block**, **standard compression fast**, **standard super compression block**, **standard floating point block**, **standard floating point super block**, **inline block**, **control block**, **template block** and **system block**.

| LW.A | lw.a \[SrcL, simm<<2\]<, {=>, ->}RegDst> | lw.a \[SrcL, simm\]<, {=>, ->}RegDst> |
| LD.A | ld.a \[SrcL, simm<<3\]<, {=>, ->}RegDst> | ld.a \[SrcL, simm\]<, {=>, ->}RegDst> |
| LHU.A | lhu.a \[SrcL, simm<<1\]<, {=>, ->}RegDst> | lhu.a \[SrcL, simm\]<, {=>, ->}RegDst> |
| LWU.A | lwu.a \[SrcL, simm<<2\]<, {=>, ->}RegDst> | lhu.a \[SrcL, simm\]<, {=>, ->}RegDst> || Microinstructions | Assembly before update | Assembly after update |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Table formatting error: a new table header is appended to the end of a row.

Suggested change
| LWU.A | lwu.a \[SrcL, simm<<2\]<, {=>, ->}RegDst> | lhu.a \[SrcL, simm\]<, {=>, ->}RegDst> || Microinstructions | Assembly before update | Assembly after update |
| LWU.A | lwu.a \[SrcL, simm<<2\]<, {=>, ->}RegDst> | lhu.a \[SrcL, simm\]<, {=>, ->}RegDst> |

|----------|----------------------------------|--------------|
| fcvt | fcvt.dstT SrcL.srcT<, {=>, ->}RegDst> | Floating point conversion |

**Floating point comparison class**| Microinstructions | Assembly format | Description |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Table formatting error: the table header is merged with the preceding section title.

Suggested change
**Floating point comparison class**| Microinstructions | Assembly format | Description |
**Floating point comparison class**
| Microinstructions | Assembly format | Description |

Comment thread docs/backend/rob.md

![PEROB](../figs/uArch/PE_ROB_FIG.png)

As shown in the figure above, the microinstruction ROB is composed of M slices. Each slice is a block of a ROB and contains K instructions. Each slice can be connected at will through the head and tail pointers to form a linked list structure, which can store a total of M*K instructions. Each slice has the following domain segments:| Field segment | Description |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

A newline is required before the table header for it to render correctly in most Markdown parsers.

Suggested change
As shown in the figure above, the microinstruction ROB is composed of M slices. Each slice is a block of a ROB and contains K instructions. Each slice can be connected at will through the head and tail pointers to form a linked list structure, which can store a total of M*K instructions. Each slice has the following domain segments:| Field segment | Description |
Each slice has the following domain segments:
| Field segment | Description |

Comment thread docs/backend/issue.md
Generally speaking, register forwarding in the processor is done by using the equality of read PTAG and write PTAG as an enable signal before EXE pipeline to select the correct operand. In the BlockISA microarchitecture, the microarchitecture adopts another way to judge data forwarding. In the emission queue, two additional pieces of information are maintained for each source operand:

1. **Depended Source**:
Depended Source indicates which pipe the source operand comes from. It has been recorded in OOO in the REN module when the instruction is distributed, and the signal records the pipe through which the instruction is distributed. When subsequent dependent instructions enter the issue queue, the microarchitecture will not only query the wake-up status of its source operand in the rename module, but also query the production pipeline of its source operand, and record it in the issue queue. For ease of understanding, we can regard the Depended Source information as the ordinate of the target data source.2. **Tracking Vector**:
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There is a missing newline or space before the second point, which will cause rendering issues in Markdown.

Suggested change
Depended Source indicates which pipe the source operand comes from. It has been recorded in OOO in the REN module when the instruction is distributed, and the signal records the pipe through which the instruction is distributed. When subsequent dependent instructions enter the issue queue, the microarchitecture will not only query the wake-up status of its source operand in the rename module, but also query the production pipeline of its source operand, and record it in the issue queue. For ease of understanding, we can regard the Depended Source information as the ordinate of the target data source.2. **Tracking Vector**:
For ease of understanding, we can regard the Depended Source information as the ordinate of the target data source.
2. **Tracking Vector**:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant