From 09e5346082ea5f274ef5fe2f1fe6dfca0580de94 Mon Sep 17 00:00:00 2001 From: Willem Drijver Date: Tue, 3 Nov 2026 14:29:23 +0300 Subject: [PATCH] Hardware pillar, source ranking, core notation and lesson flow - hardware/ pillar: v4-generic and one folder per V4 model, with optional applies_to.board and the common model abbreviations. - Source ranking: inline tags (G), (M), (official), (SRC), an optional basis field, and a new conflict rule in AGENTS.md (core developer, then measured, then official documentation). - Core notation "Core 12841", "Core 12830-12840", "Core 12841+" or "any", checked in CI. - Evidence section in the pitfall and lesson templates. - Lesson flow: agents offer a lesson at the end of a project or after a wrong assumption, and submit it with approval as a PR from the knowledge base submodule, or through the new issue form. - PRM converter: basis [official]; status is kept while the body is unchanged. Co-Authored-By: Claude Opus 5.5 --- .github/CODEOWNERS | 1 + .github/ISSUE_TEMPLATE/lesson.yml | 52 +++++++++++ AGENTS.md | 62 ++++++++++--- CONTRIBUTING.md | 94 +++++++++++++++++--- README.md | 10 ++- core/cpu-68080/prm/ammx-unit.md | 1 + core/cpu-68080/prm/ammx/ammx-format.md | 1 + core/cpu-68080/prm/ammx/bfly.md | 1 + core/cpu-68080/prm/ammx/bsel.md | 1 + core/cpu-68080/prm/ammx/c2p.md | 1 + core/cpu-68080/prm/ammx/load.md | 1 + core/cpu-68080/prm/ammx/loadi.md | 1 + core/cpu-68080/prm/ammx/lsdq.md | 1 + core/cpu-68080/prm/ammx/minterm.md | 1 + core/cpu-68080/prm/ammx/pack3216.md | 1 + core/cpu-68080/prm/ammx/packuswb.md | 1 + core/cpu-68080/prm/ammx/padd.md | 1 + core/cpu-68080/prm/ammx/pand.md | 1 + core/cpu-68080/prm/ammx/pandn.md | 1 + core/cpu-68080/prm/ammx/pavgb.md | 1 + core/cpu-68080/prm/ammx/pcmpccb.md | 1 + core/cpu-68080/prm/ammx/pcmpccw.md | 1 + core/cpu-68080/prm/ammx/peor.md | 1 + core/cpu-68080/prm/ammx/pmaxb.md | 1 + core/cpu-68080/prm/ammx/pmaxw.md | 1 + core/cpu-68080/prm/ammx/pminb.md | 1 + core/cpu-68080/prm/ammx/pminw.md | 1 + core/cpu-68080/prm/ammx/pmul.md | 1 + core/cpu-68080/prm/ammx/pmula.md | 1 + core/cpu-68080/prm/ammx/por.md | 1 + core/cpu-68080/prm/ammx/psub.md | 1 + core/cpu-68080/prm/ammx/rex.md | 1 + core/cpu-68080/prm/ammx/store.md | 1 + core/cpu-68080/prm/ammx/storec.md | 1 + core/cpu-68080/prm/ammx/storei.md | 1 + core/cpu-68080/prm/ammx/storeilm.md | 1 + core/cpu-68080/prm/ammx/storem.md | 1 + core/cpu-68080/prm/ammx/storem3.md | 1 + core/cpu-68080/prm/ammx/tex.md | 1 + core/cpu-68080/prm/ammx/trans.md | 1 + core/cpu-68080/prm/ammx/unpack1632.md | 1 + core/cpu-68080/prm/ammx/vperm.md | 1 + core/cpu-68080/prm/apollo-bit.md | 1 + core/cpu-68080/prm/b-registers.md | 1 + core/cpu-68080/prm/fpu-unit.md | 1 + core/cpu-68080/prm/fpu/fadd-3op.md | 1 + core/cpu-68080/prm/fpu/fdbcc-l.md | 1 + core/cpu-68080/prm/fpu/fdiv-3op.md | 1 + core/cpu-68080/prm/fpu/fmove-dn.md | 1 + core/cpu-68080/prm/fpu/fmovem.md | 1 + core/cpu-68080/prm/fpu/fmoverz.md | 1 + core/cpu-68080/prm/fpu/fmul-3op.md | 1 + core/cpu-68080/prm/fpu/fpu-format.md | 1 + core/cpu-68080/prm/fpu/fsqrt-3op.md | 1 + core/cpu-68080/prm/fpu/fsub-3op.md | 1 + core/cpu-68080/prm/index.md | 1 + core/cpu-68080/prm/instruction-efficiency.md | 1 + core/cpu-68080/prm/instruction-fusing.md | 1 + core/cpu-68080/prm/instruction-timing.md | 1 + core/cpu-68080/prm/integer-unit.md | 1 + core/cpu-68080/prm/integer/addiw.md | 1 + core/cpu-68080/prm/integer/addq-bn.md | 1 + core/cpu-68080/prm/integer/bank.md | 1 + core/cpu-68080/prm/integer/bcc-s-plus.md | 1 + core/cpu-68080/prm/integer/bra-s-plus.md | 1 + core/cpu-68080/prm/integer/bsr-s-plus.md | 1 + core/cpu-68080/prm/integer/clr-q.md | 1 + core/cpu-68080/prm/integer/cmp-bn.md | 1 + core/cpu-68080/prm/integer/cmpiw.md | 1 + core/cpu-68080/prm/integer/dbcc-l.md | 1 + core/cpu-68080/prm/integer/extub-extuw.md | 1 + core/cpu-68080/prm/integer/lea-bn.md | 1 + core/cpu-68080/prm/integer/mov3q.md | 1 + core/cpu-68080/prm/integer/move-bn.md | 1 + core/cpu-68080/prm/integer/move-sr.md | 1 + core/cpu-68080/prm/integer/move16.md | 1 + core/cpu-68080/prm/integer/move2.md | 1 + core/cpu-68080/prm/integer/movea-bn.md | 1 + core/cpu-68080/prm/integer/movec.md | 1 + core/cpu-68080/prm/integer/moveh.md | 1 + core/cpu-68080/prm/integer/movex.md | 1 + core/cpu-68080/prm/integer/moviw.md | 1 + core/cpu-68080/prm/integer/movs.md | 1 + core/cpu-68080/prm/integer/movz.md | 1 + core/cpu-68080/prm/integer/movz2.md | 1 + core/cpu-68080/prm/integer/perm.md | 1 + core/cpu-68080/prm/integer/subq-bn.md | 1 + core/cpu-68080/prm/integer/touch.md | 1 + core/cpu-68080/prm/optimizing.md | 1 + core/cpu-68080/prm/pipeline.md | 1 + core/cpu-68080/prm/programming-model.md | 1 + core/cpu-68080/prm/specs.md | 1 + core/cpu-68080/prm/superscalar.md | 1 + core/cpu-68080/prm/trace.md | 1 + hardware/best-practices/.gitkeep | 0 hardware/index.md | 57 ++++++++++++ hardware/pitfalls/.gitkeep | 0 hardware/v4-firebird/.gitkeep | 0 hardware/v4-generic/.gitkeep | 0 hardware/v4-icedrake/.gitkeep | 0 hardware/v4-manticore/.gitkeep | 0 hardware/v4-standalone/.gitkeep | 0 hardware/v4-unicorn/.gitkeep | 0 templates/files/best-practice.md | 8 +- templates/files/convention.md | 6 +- templates/files/example.md | 6 +- templates/files/guide.md | 6 +- templates/files/lesson.md | 11 ++- templates/files/pitfall.md | 11 ++- templates/files/reference.md | 6 +- templates/repo/AGENTS.md | 9 +- tools/check_frontmatter.py | 28 +++++- tools/intake/prm68080.py | 29 ++++-- tools/kblib.py | 4 +- 114 files changed, 436 insertions(+), 53 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/lesson.yml create mode 100644 hardware/best-practices/.gitkeep create mode 100644 hardware/index.md create mode 100644 hardware/pitfalls/.gitkeep create mode 100644 hardware/v4-firebird/.gitkeep create mode 100644 hardware/v4-generic/.gitkeep create mode 100644 hardware/v4-icedrake/.gitkeep create mode 100644 hardware/v4-manticore/.gitkeep create mode 100644 hardware/v4-standalone/.gitkeep create mode 100644 hardware/v4-unicorn/.gitkeep diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index dd665fc..07f5379 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -109,6 +109,7 @@ /core/saga-audio-arne/index.md @WDrijver /core/saga-dma-anni/index.md @WDrijver /core/saga-video-isabelle/index.md @WDrijver +/hardware/index.md @WDrijver /os/apolloos-and-amigaos-on-v4.md @WDrijver /os/apolloos-specific-on-v4.md @WDrijver /os/os-takeover.md @WDrijver diff --git a/.github/ISSUE_TEMPLATE/lesson.yml b/.github/ISSUE_TEMPLATE/lesson.yml new file mode 100644 index 0000000..712abef --- /dev/null +++ b/.github/ISSUE_TEMPLATE/lesson.yml @@ -0,0 +1,52 @@ +name: Submit a lesson +description: Share what a project learned about Apollo V4 development. A maintainer turns it into a file in lessons/. +title: "Lesson: " +body: + - type: markdown + attributes: + value: | + Prefer a pull request with a file from `templates/files/lesson.md` when you can (see CONTRIBUTING.md section 7). This form is the alternative. An AI agent can fill in these fields for you. + - type: input + id: project + attributes: + label: Project + description: Name, repository and dates. + validations: + required: true + - type: input + id: github + attributes: + label: Your GitHub handle + description: Becomes the owner of the lesson file. + validations: + required: true + - type: input + id: target + attributes: + label: Target + description: Core (for example "Core 12841"), target OS, execution mode and V4 model. + validations: + required: true + - type: textarea + id: went-well + attributes: + label: What went well + - type: textarea + id: went-wrong + attributes: + label: What went wrong + - type: textarea + id: ai-wrong + attributes: + label: What the AI got wrong + description: Concrete mistakes and wrong assumptions, with examples. + - type: textarea + id: evidence + attributes: + label: Evidence + description: For each measured or reported fact, the source ((G) core developer with date, (M) measured, (official) document, (SRC) source code), the core and the method. + - type: textarea + id: candidates + attributes: + label: Candidates for distillation + description: Proposed new or updated files in best-practices/, pitfalls/ or guides/. diff --git a/AGENTS.md b/AGENTS.md index 9d16bc2..fc0bff4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,10 @@ relative to the knowledge base root. of the Motorola 68000 family, with the **AMMX** SIMD extension. - **SAGA chipset**: `saga-video-isabelle` (video), `saga-audio-arne` (audio), `saga-dma-anni` (DMA), `saga-3d-maggie` (3D). +- **V4 models**: V4 Standalone (SA), V4 UniCorn (UNI, A6000), V4 IceDrake + (ICE), V4 Manticore (MC) and V4 Firebird (FB). They share the FPGA core + (68080 and SAGA) but differ as boards. The project's own AGENTS.md states + the target model(s), if it depends on one. - **Target OS**: Apollo V4 software runs on one or more of **ApolloOS R10** (fork of AROS, optimized for Apollo V4), **AmigaOS 3.9** and **AmigaOS 3.2**. The project's own AGENTS.md states which. Hardware @@ -54,6 +58,8 @@ compiler knowledge is where you will make confident mistakes. - DON'T call OS functions beyond the basic set in an `os-takeover` project, and DON'T leave the machine without restoring multitasking and the Workbench screen. Check `os/os-takeover.md`. +- DON'T assume a connector, header or memory layout is the same on every V4 + model. Check `hardware/v4-generic/` and the model's folder in `hardware/`. - DON'T invent register addresses, bit meanings, function signatures or compiler flags. If it is not in the knowledge base or in source code you have read, say that you don't know. @@ -62,8 +68,9 @@ compiler knowledge is where you will make confident mistakes. ## 3. What to read for your task -The knowledge base has three pillars: `core/` (68080 and SAGA), `os/` -(ApolloOS and AmigaOS on V4) and `toolchain/` (ApolloCrossDev). Each has its +The knowledge base has four pillars: `core/` (68080 and SAGA), `hardware/` +(the V4 boards), `os/` (ApolloOS and AmigaOS on V4) and `toolchain/` +(ApolloCrossDev). Each has its own `best-practices/` and `pitfalls/` subfolders. Read only what your task needs, and always check the `best-practices/` and `pitfalls/` of every pillar you read. @@ -79,8 +86,9 @@ you read. | Sound | `core/saga-audio-arne/` | | Memory transfers, DMA | `core/saga-dma-anni/` | | 3D | `core/saga-3d-maggie/` | +| Board connectors, headers, memory, model differences | `hardware/v4-generic/`, the model's folder in `hardware/` | | Using or changing an ApolloOS library | `os/libraries/` | -| Device drivers | `os/devs/`, plus the `core/` folder of the hardware involved | +| Device drivers | `os/devs/`, plus the `core/` or `hardware/` folder of the hardware involved | | Filesystems | `os/filesys/` | | Shell commands | `os/commands/` | | Datatypes | `os/datatypes/` | @@ -107,10 +115,14 @@ Every file starts with YAML frontmatter (full spec in `CONTRIBUTING.md`). - `draft`: unreviewed. Use with caution and tell the user when your answer depends on a draft. - `deprecated`: do not use. Follow `superseded_by`. -- **applies_to**: check that the core revision matches the user's target, - that `os` is `any` or covers every target OS of the project, and that - `mode` (if present) includes the project's execution mode. If not, or the - target is unknown, say so. +- **applies_to**: check that `core` covers the user's core (`any`, + `Core 12841`, a range `Core 12830-12840` or `Core 12841+`), that `os` is + `any` or covers every target OS of the project, and that `mode` and + `board` (if present) include the project's execution mode and V4 model. If + not, or the target is unknown, say so. +- **basis** and the tags after facts tell where a fact comes from: **(G)** + the core developer, **(M)** measured on V4 hardware, **(official)** official + Apollo documentation such as the 68080 PRM, **(SRC)** source code. - **origin** - `official`: converted from official Apollo documentation. Authoritative, but conversion errors are possible while the status is `draft`. @@ -120,8 +132,16 @@ Every file starts with YAML frontmatter (full spec in `CONTRIBUTING.md`). `sources/official/`. Never edit it. Propose the change to the maintainers as a change to the original document. -When two files contradict each other, prefer the higher status, then the more -recent `last_verified`, and tell the user about the conflict. +When two facts contradict each other, decide in this order, and always tell +the user about the conflict: + +1. The source rank: (G) core developer, then (M) measured, then (official) + documentation, then (SRC) source code, then anything else. +2. The newer core. +3. The higher status, then the more recent `last_verified`. + +So a measured fact in a pitfall beats the 68080 PRM, even when the PRM file +has a higher status. --- @@ -166,9 +186,23 @@ workaround in the knowledge base. --- -## 8. After finishing a project +## 8. Lessons: give back what the project learned + +Offer the developer a lesson when: + +- they say a project, a release or a milestone is done, or ask for a summary; +- you find that an assumption from section 2 was wrong (offer it right away, + while the details are fresh). + +Then: -Offer to draft a lesson in `lessons/` using the lesson template. Be specific -and honest about what you got wrong, especially wrong assumptions from -section 2. Those are the most valuable input for improving this knowledge -base. +1. Draft `lessons/YYYY-MM-project-name.md` from + `templates/files/lesson.md`. Be specific and honest about what you got + wrong, especially wrong assumptions from section 2. Give the evidence + (source tag, core, method) for every measured claim. +2. Show the draft to the developer. Submit nothing without their approval. +3. Submit it as described in `CONTRIBUTING.md` section 7: preferably as a + pull request from the knowledge base clone (the `ApolloKnowledgeBase/` + submodule), on a branch `lesson/YYYY-MM-project-name`; otherwise give the + developer the text for the "Submit a lesson" issue form. +4. Return the submodule to the commit the project uses afterwards. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29229de..12130c7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,8 +24,9 @@ AI agents creating or editing files in this repository MUST follow it. ## 2. Where things go -The knowledge base has three pillars: **core** (the hardware), **os** (the -operating systems) and **toolchain** (ApolloCrossDev). Each pillar holds +The knowledge base has four pillars: **core** (the FPGA core: 68080 CPU and +SAGA chipset), **hardware** (the V4 boards), **os** (the operating systems) +and **toolchain** (ApolloCrossDev). Each pillar holds reference files plus its own `best-practices/` and `pitfalls/`. Knowledge that spans pillars goes in the cross-cutting folders. @@ -38,6 +39,15 @@ core/ 68080 CPU and SAGA chipset ├── saga-3d-maggie/ 3D chip ├── best-practices/ └── pitfalls/ +hardware/ the V4 boards +├── v4-generic/ shared by all V4 models: memory map, common connectors +├── v4-standalone/ V4 Standalone (SA) +├── v4-unicorn/ V4 UniCorn (UNI, A6000) +├── v4-icedrake/ V4 IceDrake (ICE) +├── v4-manticore/ V4 Manticore (MC) +├── v4-firebird/ V4 Firebird (FB) +├── best-practices/ +└── pitfalls/ os/ ApolloOS R10, AmigaOS 3.9 and 3.2 on Apollo V4 ├── *.md running on V4, OS takeover, ApolloOS specifics ├── libraries/ devs/ filesys/ commands/ datatypes/ ApolloOS components @@ -55,7 +65,7 @@ lessons/ project retrospectives | Folder | `type` | |---|---| -| `core/`, `os/`, `toolchain/` and their subfolders | reference | +| `core/`, `hardware/`, `os/`, `toolchain/` and their subfolders | reference | | `/best-practices/` | best-practice | | `/pitfalls/` | pitfall | | `guides/` | guide | @@ -69,6 +79,12 @@ skills, step 2), `evals/` (AI benchmarks, step 5), `tools/` (CI scripts). Each chip folder keeps its register map in `registers.md` inside that folder. +`core/` is the FPGA core, the same on every V4 model. `hardware/` is the +board: connectors, headers, memory and what differs per model. Knowledge that +holds for all models goes in `hardware/v4-generic/`; a model folder holds +only what is specific to that model. Common abbreviations: SA (Standalone), +UNI or A6000 (UniCorn), ICE (IceDrake), MC (Manticore), FB (Firebird). + A best practice or pitfall goes in the pillar it is about. One that spans pillars goes in the pillar where a developer would look first, with `related:` links to the others. @@ -137,11 +153,13 @@ type: best-practice # required, see allowed values owner: github-handle # required, one GitHub handle status: draft # required, see allowed values origin: human # required, see allowed values +basis: [measured, core-developer] # optional, kinds of source used components: [cpu-68080, saga-video-isabelle] # required, see allowed values applies_to: # required - core: "" # use the team's revision notation + core: "Core 12841+" # required, see allowed values os: [any] # see allowed values mode: [os-takeover] # optional, see allowed values + board: [v4-standalone] # optional, see allowed values last_verified: 2026-10-31 # required once status is verified tags: [ammx, graphics, blitting] # optional, free keywords for search related: # optional, paths to related files @@ -168,9 +186,17 @@ generated_from: # only for document intake, section 11 after a human review - `official`: from official Apollo documentation through document intake (section 11); maintainers only, CI checks that the owner is a maintainer +- **basis:** optional list of the kinds of source the file relies on, from + the highest rank to the lowest (see "Sources and their rank" below): + `core-developer`, `measured`, `official`, `source-code`, `other` - **components:** `cpu-68080`, `saga-video-isabelle`, `saga-audio-arne`, `saga-dma-anni`, `saga-3d-maggie`, `libraries`, `devs`, `filesys`, - `commands`, `datatypes`, `toolchain`, `general` + `commands`, `datatypes`, `toolchain`, `hardware`, `general` +- **applies_to.core:** the core revisions the file is valid for: + - `any`: valid on every core + - `Core 12841`: one core + - `Core 12830-12840`: a range, both ends included + - `Core 12841+`: this core and later - **applies_to.os:** a list of target operating systems the file is valid for: - `any`: valid whatever the OS (all hardware facts); not combined with others - `apolloos-r10`: ApolloOS R10, the current 10.x versions from ApolloTeam-dev @@ -184,6 +210,28 @@ generated_from: # only for document intake, section 11 - `any`: valid in both modes; not combined with others - `os-friendly`: only for programs that keep the OS running - `os-takeover`: only for programs that take over the machine +- **applies_to.board:** optional list of V4 models the file is valid for. + Leaving it out means `any`. + - `any`: all models; not combined with others + - `v4-standalone`, `v4-unicorn`, `v4-icedrake`, `v4-manticore`, + `v4-firebird` + +### Sources and their rank + +Mark where each fact comes from with a tag right after it, and list the kinds +in `basis`. When sources disagree, the higher rank wins: + +| Rank | Tag | `basis` | Source | +|---|---|---|---| +| 1 | **(G)** | `core-developer` | Gunnar, the core developer. Name the date: "(G, 2026-10-29)" | +| 2 | **(M)** | `measured` | Measured on real V4 hardware. State the core and the method (counters, test program) | +| 3 | **(official)** | `official` | The 68080 PRM and other official Apollo documents | +| 4 | **(SRC)** | `source-code` | Read from source code (ApolloOS, a library, ApolloCrossDev) | +| 5 | | `other` | Anything else, such as forum posts or apollo-core.com | + +Within the same rank, the newer core wins. Facts tied to a core say so in the +text ("on Core 12841") and in `applies_to.core`. A later core can change +them: measure again on yours. --- @@ -227,12 +275,33 @@ don't use. ## 7. Lessons lifecycle -1. After a project, write `lessons/YYYY-MM-project-name.md` (AI may draft). -2. Lessons stay `draft` and are not read by AI agents by default. -3. Periodically, the team distills recurring points into the pillars' - `best-practices/` or `pitfalls/`, or into `guides/`, and links the lesson - in their `sources`. -4. Distilled lessons stay in place as history. +Lessons carry what a project learned back into the knowledge base. + +1. **Offer.** AI agents offer a lesson when the developer says a project, a + release or a milestone is done, or asks for a summary, and right away when + they find that an assumption from AGENTS.md section 2 was wrong. +2. **Draft.** The agent writes `lessons/YYYY-MM-project-name.md` from + `templates/files/lesson.md`, with the evidence (source, core, method) for + every measured claim, and shows it to the developer. Nothing is submitted + without the developer's approval. +3. **Submit.** Either way works: + - **Pull request (preferred):** in the knowledge base clone (the + `ApolloKnowledgeBase/` submodule of the project), on a new branch + `lesson/YYYY-MM-project-name`, commit the lesson and open a PR with + `gh pr create`. Without write access, `gh` offers to use a fork. Then + return the submodule to the commit the project uses + (`git submodule update ApolloKnowledgeBase` in the project). + - **Issue form:** open an issue with the "Submit a lesson" form on + github.com/ApolloTeam-dev/ApolloKnowledgeBase and paste the lesson. A + maintainer turns it into a file. +4. **Review.** CI checks the file; a maintainer merges it. Lessons stay + `draft` and are not read by AI agents by default: one project's experience + is not yet a rule. +5. **Distill.** The team turns the lesson's "Candidates for distillation" + into files in the pillars' `best-practices/` or `pitfalls/`, or into + `guides/`, and links the lesson in their `sources`. From then on every + agent finds it. +6. Distilled lessons stay in place as history. --- @@ -262,7 +331,8 @@ Do not delete outdated files. Set `status: deprecated`, fill in Every pull request runs (scripts in `tools/`): -- `check_frontmatter.py`: required fields, allowed values, file naming, +- `check_frontmatter.py`: required fields, allowed values (including the + `applies_to.core` notation and `basis`), file naming, type matches folder, no leftover `` text, `related`, `superseded_by` and `generated_from` paths exist, `official` files are owned by a maintainer diff --git a/README.md b/README.md index 7f37b4c..1411b4a 100644 --- a/README.md +++ b/README.md @@ -13,12 +13,13 @@ the platform correctly and to its full potential. ## What's inside -Three pillars of knowledge, each with reference files, best practices and +Four pillars of knowledge, each with reference files, best practices and pitfalls: | Pillar | Contents | |---|---| | `core/` | 68080 CPU and the SAGA chips: Isabelle (video), Arne (audio), Anni (DMA), Maggie (3D) | +| `hardware/` | The V4 boards: shared knowledge in `v4-generic/`, and per model: Standalone (SA), UniCorn (UNI, A6000), IceDrake (ICE), Manticore (MC), Firebird (FB) | | `os/` | Running on V4 under ApolloOS R10, AmigaOS 3.9 and 3.2; OS takeover; ApolloOS internals (libraries, devs, filesys, commands, datatypes) | | `toolchain/` | ApolloCrossDev setup, options and syntax | @@ -39,8 +40,9 @@ repositories and seed content), `sources/` (original official documents), `tools/` (CI scripts), and later `skills/` and `evals/`. Each file shows its owner, its status (`draft`, `reviewed`, `verified`, -`deprecated`) and which core revision, target OS and execution mode -(`os-friendly` or `os-takeover`) it applies to. +`deprecated`), where its facts come from (the core developer, measurements, +official documentation or source code) and which core revision, target OS, +execution mode (`os-friendly` or `os-takeover`) and V4 model it applies to. --- @@ -75,5 +77,7 @@ the file format and review process. The most valuable contributions are: AI models) expect - Measured optimization techniques, for the pillars' `best-practices/` - Bugs you hit and how you fixed them, for the pillars' `pitfalls/` +- Lessons from your projects: AI agents offer to draft one at the end of a + project and submit it as a pull request (see `CONTRIBUTING.md` section 7) AI agents: start with `AGENTS.md`. diff --git a/core/cpu-68080/prm/ammx-unit.md b/core/cpu-68080/prm/ammx-unit.md index 0a68399..b992192 100644 --- a/core/cpu-68080/prm/ammx-unit.md +++ b/core/cpu-68080/prm/ammx-unit.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/ammx-format.md b/core/cpu-68080/prm/ammx/ammx-format.md index 094ae16..7eb8ba3 100644 --- a/core/cpu-68080/prm/ammx/ammx-format.md +++ b/core/cpu-68080/prm/ammx/ammx-format.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/bfly.md b/core/cpu-68080/prm/ammx/bfly.md index 4385103..1be8a0e 100644 --- a/core/cpu-68080/prm/ammx/bfly.md +++ b/core/cpu-68080/prm/ammx/bfly.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/bsel.md b/core/cpu-68080/prm/ammx/bsel.md index 3245522..d09b6bc 100644 --- a/core/cpu-68080/prm/ammx/bsel.md +++ b/core/cpu-68080/prm/ammx/bsel.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/c2p.md b/core/cpu-68080/prm/ammx/c2p.md index dd790af..5bcc9e3 100644 --- a/core/cpu-68080/prm/ammx/c2p.md +++ b/core/cpu-68080/prm/ammx/c2p.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/load.md b/core/cpu-68080/prm/ammx/load.md index aefc726..0bc697d 100644 --- a/core/cpu-68080/prm/ammx/load.md +++ b/core/cpu-68080/prm/ammx/load.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/loadi.md b/core/cpu-68080/prm/ammx/loadi.md index 2ac616c..aaee86c 100644 --- a/core/cpu-68080/prm/ammx/loadi.md +++ b/core/cpu-68080/prm/ammx/loadi.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/lsdq.md b/core/cpu-68080/prm/ammx/lsdq.md index e6f3719..34455c2 100644 --- a/core/cpu-68080/prm/ammx/lsdq.md +++ b/core/cpu-68080/prm/ammx/lsdq.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/minterm.md b/core/cpu-68080/prm/ammx/minterm.md index f1b53d2..f07f106 100644 --- a/core/cpu-68080/prm/ammx/minterm.md +++ b/core/cpu-68080/prm/ammx/minterm.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pack3216.md b/core/cpu-68080/prm/ammx/pack3216.md index d3244de..0acfd51 100644 --- a/core/cpu-68080/prm/ammx/pack3216.md +++ b/core/cpu-68080/prm/ammx/pack3216.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/packuswb.md b/core/cpu-68080/prm/ammx/packuswb.md index 3195c7d..549a275 100644 --- a/core/cpu-68080/prm/ammx/packuswb.md +++ b/core/cpu-68080/prm/ammx/packuswb.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/padd.md b/core/cpu-68080/prm/ammx/padd.md index 460fc62..a6098a5 100644 --- a/core/cpu-68080/prm/ammx/padd.md +++ b/core/cpu-68080/prm/ammx/padd.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pand.md b/core/cpu-68080/prm/ammx/pand.md index c956bc3..da4b2fc 100644 --- a/core/cpu-68080/prm/ammx/pand.md +++ b/core/cpu-68080/prm/ammx/pand.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pandn.md b/core/cpu-68080/prm/ammx/pandn.md index 15b2547..3ca73da 100644 --- a/core/cpu-68080/prm/ammx/pandn.md +++ b/core/cpu-68080/prm/ammx/pandn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pavgb.md b/core/cpu-68080/prm/ammx/pavgb.md index 0be78fc..a65afce 100644 --- a/core/cpu-68080/prm/ammx/pavgb.md +++ b/core/cpu-68080/prm/ammx/pavgb.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pcmpccb.md b/core/cpu-68080/prm/ammx/pcmpccb.md index 3ebbcc6..b027ccb 100644 --- a/core/cpu-68080/prm/ammx/pcmpccb.md +++ b/core/cpu-68080/prm/ammx/pcmpccb.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pcmpccw.md b/core/cpu-68080/prm/ammx/pcmpccw.md index 8c7e6ca..8e25f95 100644 --- a/core/cpu-68080/prm/ammx/pcmpccw.md +++ b/core/cpu-68080/prm/ammx/pcmpccw.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/peor.md b/core/cpu-68080/prm/ammx/peor.md index 9ffe3a0..fd64899 100644 --- a/core/cpu-68080/prm/ammx/peor.md +++ b/core/cpu-68080/prm/ammx/peor.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pmaxb.md b/core/cpu-68080/prm/ammx/pmaxb.md index 354ec8e..c6a1fb5 100644 --- a/core/cpu-68080/prm/ammx/pmaxb.md +++ b/core/cpu-68080/prm/ammx/pmaxb.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pmaxw.md b/core/cpu-68080/prm/ammx/pmaxw.md index c6232bb..18a0226 100644 --- a/core/cpu-68080/prm/ammx/pmaxw.md +++ b/core/cpu-68080/prm/ammx/pmaxw.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pminb.md b/core/cpu-68080/prm/ammx/pminb.md index 688b27b..93ea7b6 100644 --- a/core/cpu-68080/prm/ammx/pminb.md +++ b/core/cpu-68080/prm/ammx/pminb.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pminw.md b/core/cpu-68080/prm/ammx/pminw.md index 2993ead..d1d7d18 100644 --- a/core/cpu-68080/prm/ammx/pminw.md +++ b/core/cpu-68080/prm/ammx/pminw.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pmul.md b/core/cpu-68080/prm/ammx/pmul.md index 5f61f2c..03a06d1 100644 --- a/core/cpu-68080/prm/ammx/pmul.md +++ b/core/cpu-68080/prm/ammx/pmul.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/pmula.md b/core/cpu-68080/prm/ammx/pmula.md index c37986d..acbec25 100644 --- a/core/cpu-68080/prm/ammx/pmula.md +++ b/core/cpu-68080/prm/ammx/pmula.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/por.md b/core/cpu-68080/prm/ammx/por.md index 1a48c6e..a8d31d0 100644 --- a/core/cpu-68080/prm/ammx/por.md +++ b/core/cpu-68080/prm/ammx/por.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/psub.md b/core/cpu-68080/prm/ammx/psub.md index 6bee1e2..0c57b42 100644 --- a/core/cpu-68080/prm/ammx/psub.md +++ b/core/cpu-68080/prm/ammx/psub.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/rex.md b/core/cpu-68080/prm/ammx/rex.md index d86cbdd..96e2d10 100644 --- a/core/cpu-68080/prm/ammx/rex.md +++ b/core/cpu-68080/prm/ammx/rex.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/store.md b/core/cpu-68080/prm/ammx/store.md index 89be2d3..689be36 100644 --- a/core/cpu-68080/prm/ammx/store.md +++ b/core/cpu-68080/prm/ammx/store.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/storec.md b/core/cpu-68080/prm/ammx/storec.md index 66a5242..419498a 100644 --- a/core/cpu-68080/prm/ammx/storec.md +++ b/core/cpu-68080/prm/ammx/storec.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/storei.md b/core/cpu-68080/prm/ammx/storei.md index cb59bf5..bcad6e1 100644 --- a/core/cpu-68080/prm/ammx/storei.md +++ b/core/cpu-68080/prm/ammx/storei.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/storeilm.md b/core/cpu-68080/prm/ammx/storeilm.md index 1e5f077..516b346 100644 --- a/core/cpu-68080/prm/ammx/storeilm.md +++ b/core/cpu-68080/prm/ammx/storeilm.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/storem.md b/core/cpu-68080/prm/ammx/storem.md index e353467..d3ef251 100644 --- a/core/cpu-68080/prm/ammx/storem.md +++ b/core/cpu-68080/prm/ammx/storem.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/storem3.md b/core/cpu-68080/prm/ammx/storem3.md index 0945edf..bd72c3e 100644 --- a/core/cpu-68080/prm/ammx/storem3.md +++ b/core/cpu-68080/prm/ammx/storem3.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/tex.md b/core/cpu-68080/prm/ammx/tex.md index 0f8b789..9051bfe 100644 --- a/core/cpu-68080/prm/ammx/tex.md +++ b/core/cpu-68080/prm/ammx/tex.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/trans.md b/core/cpu-68080/prm/ammx/trans.md index 2e9df58..cc77c30 100644 --- a/core/cpu-68080/prm/ammx/trans.md +++ b/core/cpu-68080/prm/ammx/trans.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/unpack1632.md b/core/cpu-68080/prm/ammx/unpack1632.md index 486aa9f..bd9d2b8 100644 --- a/core/cpu-68080/prm/ammx/unpack1632.md +++ b/core/cpu-68080/prm/ammx/unpack1632.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/ammx/vperm.md b/core/cpu-68080/prm/ammx/vperm.md index 650b107..547b6e1 100644 --- a/core/cpu-68080/prm/ammx/vperm.md +++ b/core/cpu-68080/prm/ammx/vperm.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/apollo-bit.md b/core/cpu-68080/prm/apollo-bit.md index 934fb53..61ae2b5 100644 --- a/core/cpu-68080/prm/apollo-bit.md +++ b/core/cpu-68080/prm/apollo-bit.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/b-registers.md b/core/cpu-68080/prm/b-registers.md index 5cacf55..d530f1e 100644 --- a/core/cpu-68080/prm/b-registers.md +++ b/core/cpu-68080/prm/b-registers.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu-unit.md b/core/cpu-68080/prm/fpu-unit.md index 659899e..d5dc893 100644 --- a/core/cpu-68080/prm/fpu-unit.md +++ b/core/cpu-68080/prm/fpu-unit.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fadd-3op.md b/core/cpu-68080/prm/fpu/fadd-3op.md index 98dc695..06845ce 100644 --- a/core/cpu-68080/prm/fpu/fadd-3op.md +++ b/core/cpu-68080/prm/fpu/fadd-3op.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fdbcc-l.md b/core/cpu-68080/prm/fpu/fdbcc-l.md index 5263b87..90ac936 100644 --- a/core/cpu-68080/prm/fpu/fdbcc-l.md +++ b/core/cpu-68080/prm/fpu/fdbcc-l.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fdiv-3op.md b/core/cpu-68080/prm/fpu/fdiv-3op.md index 355d25e..876039c 100644 --- a/core/cpu-68080/prm/fpu/fdiv-3op.md +++ b/core/cpu-68080/prm/fpu/fdiv-3op.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fmove-dn.md b/core/cpu-68080/prm/fpu/fmove-dn.md index 3ae16fb..e49c32b 100644 --- a/core/cpu-68080/prm/fpu/fmove-dn.md +++ b/core/cpu-68080/prm/fpu/fmove-dn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fmovem.md b/core/cpu-68080/prm/fpu/fmovem.md index 6635502..3df4b6d 100644 --- a/core/cpu-68080/prm/fpu/fmovem.md +++ b/core/cpu-68080/prm/fpu/fmovem.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fmoverz.md b/core/cpu-68080/prm/fpu/fmoverz.md index 0933ce5..1e9536b 100644 --- a/core/cpu-68080/prm/fpu/fmoverz.md +++ b/core/cpu-68080/prm/fpu/fmoverz.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fmul-3op.md b/core/cpu-68080/prm/fpu/fmul-3op.md index 088d396..bcfa366 100644 --- a/core/cpu-68080/prm/fpu/fmul-3op.md +++ b/core/cpu-68080/prm/fpu/fmul-3op.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fpu-format.md b/core/cpu-68080/prm/fpu/fpu-format.md index 0071770..af2c89d 100644 --- a/core/cpu-68080/prm/fpu/fpu-format.md +++ b/core/cpu-68080/prm/fpu/fpu-format.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fsqrt-3op.md b/core/cpu-68080/prm/fpu/fsqrt-3op.md index 09f8cb3..8bf63a5 100644 --- a/core/cpu-68080/prm/fpu/fsqrt-3op.md +++ b/core/cpu-68080/prm/fpu/fsqrt-3op.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/fpu/fsub-3op.md b/core/cpu-68080/prm/fpu/fsub-3op.md index 6832628..173bba6 100644 --- a/core/cpu-68080/prm/fpu/fsub-3op.md +++ b/core/cpu-68080/prm/fpu/fsub-3op.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/index.md b/core/cpu-68080/prm/index.md index 365e8e3..7edd911 100644 --- a/core/cpu-68080/prm/index.md +++ b/core/cpu-68080/prm/index.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/instruction-efficiency.md b/core/cpu-68080/prm/instruction-efficiency.md index 5a9fd88..1d8d791 100644 --- a/core/cpu-68080/prm/instruction-efficiency.md +++ b/core/cpu-68080/prm/instruction-efficiency.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/instruction-fusing.md b/core/cpu-68080/prm/instruction-fusing.md index 7f5cbdb..1db7e7d 100644 --- a/core/cpu-68080/prm/instruction-fusing.md +++ b/core/cpu-68080/prm/instruction-fusing.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/instruction-timing.md b/core/cpu-68080/prm/instruction-timing.md index 464fd10..34543b3 100644 --- a/core/cpu-68080/prm/instruction-timing.md +++ b/core/cpu-68080/prm/instruction-timing.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer-unit.md b/core/cpu-68080/prm/integer-unit.md index 108d913..81419e4 100644 --- a/core/cpu-68080/prm/integer-unit.md +++ b/core/cpu-68080/prm/integer-unit.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/addiw.md b/core/cpu-68080/prm/integer/addiw.md index 8f968b4..ae81fa9 100644 --- a/core/cpu-68080/prm/integer/addiw.md +++ b/core/cpu-68080/prm/integer/addiw.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/addq-bn.md b/core/cpu-68080/prm/integer/addq-bn.md index 533b9fa..3b72515 100644 --- a/core/cpu-68080/prm/integer/addq-bn.md +++ b/core/cpu-68080/prm/integer/addq-bn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/bank.md b/core/cpu-68080/prm/integer/bank.md index be89be8..e9d131b 100644 --- a/core/cpu-68080/prm/integer/bank.md +++ b/core/cpu-68080/prm/integer/bank.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/bcc-s-plus.md b/core/cpu-68080/prm/integer/bcc-s-plus.md index 2d18116..35f984d 100644 --- a/core/cpu-68080/prm/integer/bcc-s-plus.md +++ b/core/cpu-68080/prm/integer/bcc-s-plus.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/bra-s-plus.md b/core/cpu-68080/prm/integer/bra-s-plus.md index d8e65ac..b809312 100644 --- a/core/cpu-68080/prm/integer/bra-s-plus.md +++ b/core/cpu-68080/prm/integer/bra-s-plus.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/bsr-s-plus.md b/core/cpu-68080/prm/integer/bsr-s-plus.md index d709152..45b1a4d 100644 --- a/core/cpu-68080/prm/integer/bsr-s-plus.md +++ b/core/cpu-68080/prm/integer/bsr-s-plus.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/clr-q.md b/core/cpu-68080/prm/integer/clr-q.md index 19c592e..d5625f6 100644 --- a/core/cpu-68080/prm/integer/clr-q.md +++ b/core/cpu-68080/prm/integer/clr-q.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/cmp-bn.md b/core/cpu-68080/prm/integer/cmp-bn.md index db0f11e..885365b 100644 --- a/core/cpu-68080/prm/integer/cmp-bn.md +++ b/core/cpu-68080/prm/integer/cmp-bn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/cmpiw.md b/core/cpu-68080/prm/integer/cmpiw.md index 7de53a9..f246233 100644 --- a/core/cpu-68080/prm/integer/cmpiw.md +++ b/core/cpu-68080/prm/integer/cmpiw.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/dbcc-l.md b/core/cpu-68080/prm/integer/dbcc-l.md index 035fd76..9ebc777 100644 --- a/core/cpu-68080/prm/integer/dbcc-l.md +++ b/core/cpu-68080/prm/integer/dbcc-l.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/extub-extuw.md b/core/cpu-68080/prm/integer/extub-extuw.md index 33086eb..4737f07 100644 --- a/core/cpu-68080/prm/integer/extub-extuw.md +++ b/core/cpu-68080/prm/integer/extub-extuw.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/lea-bn.md b/core/cpu-68080/prm/integer/lea-bn.md index 552aff6..44cfd02 100644 --- a/core/cpu-68080/prm/integer/lea-bn.md +++ b/core/cpu-68080/prm/integer/lea-bn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/mov3q.md b/core/cpu-68080/prm/integer/mov3q.md index 61426e0..145a8d2 100644 --- a/core/cpu-68080/prm/integer/mov3q.md +++ b/core/cpu-68080/prm/integer/mov3q.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/move-bn.md b/core/cpu-68080/prm/integer/move-bn.md index 9960871..ff2877d 100644 --- a/core/cpu-68080/prm/integer/move-bn.md +++ b/core/cpu-68080/prm/integer/move-bn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/move-sr.md b/core/cpu-68080/prm/integer/move-sr.md index fc6eb12..edaff31 100644 --- a/core/cpu-68080/prm/integer/move-sr.md +++ b/core/cpu-68080/prm/integer/move-sr.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/move16.md b/core/cpu-68080/prm/integer/move16.md index 9b71adb..8d729d2 100644 --- a/core/cpu-68080/prm/integer/move16.md +++ b/core/cpu-68080/prm/integer/move16.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/move2.md b/core/cpu-68080/prm/integer/move2.md index 04bcdf6..8976c31 100644 --- a/core/cpu-68080/prm/integer/move2.md +++ b/core/cpu-68080/prm/integer/move2.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/movea-bn.md b/core/cpu-68080/prm/integer/movea-bn.md index 299a44f..f983313 100644 --- a/core/cpu-68080/prm/integer/movea-bn.md +++ b/core/cpu-68080/prm/integer/movea-bn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/movec.md b/core/cpu-68080/prm/integer/movec.md index 2c3560e..1f552be 100644 --- a/core/cpu-68080/prm/integer/movec.md +++ b/core/cpu-68080/prm/integer/movec.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/moveh.md b/core/cpu-68080/prm/integer/moveh.md index 1d08eb8..9e3f971 100644 --- a/core/cpu-68080/prm/integer/moveh.md +++ b/core/cpu-68080/prm/integer/moveh.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/movex.md b/core/cpu-68080/prm/integer/movex.md index dbe1e48..7185f18 100644 --- a/core/cpu-68080/prm/integer/movex.md +++ b/core/cpu-68080/prm/integer/movex.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/moviw.md b/core/cpu-68080/prm/integer/moviw.md index 800e515..fe3bea8 100644 --- a/core/cpu-68080/prm/integer/moviw.md +++ b/core/cpu-68080/prm/integer/moviw.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/movs.md b/core/cpu-68080/prm/integer/movs.md index a6bfe01..0792273 100644 --- a/core/cpu-68080/prm/integer/movs.md +++ b/core/cpu-68080/prm/integer/movs.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/movz.md b/core/cpu-68080/prm/integer/movz.md index c3756a6..ad1d6a2 100644 --- a/core/cpu-68080/prm/integer/movz.md +++ b/core/cpu-68080/prm/integer/movz.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/movz2.md b/core/cpu-68080/prm/integer/movz2.md index 27e63b8..7911a60 100644 --- a/core/cpu-68080/prm/integer/movz2.md +++ b/core/cpu-68080/prm/integer/movz2.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/perm.md b/core/cpu-68080/prm/integer/perm.md index d9dc303..88f7af2 100644 --- a/core/cpu-68080/prm/integer/perm.md +++ b/core/cpu-68080/prm/integer/perm.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/subq-bn.md b/core/cpu-68080/prm/integer/subq-bn.md index f468862..2a72e95 100644 --- a/core/cpu-68080/prm/integer/subq-bn.md +++ b/core/cpu-68080/prm/integer/subq-bn.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/integer/touch.md b/core/cpu-68080/prm/integer/touch.md index 08f7e5a..79bc651 100644 --- a/core/cpu-68080/prm/integer/touch.md +++ b/core/cpu-68080/prm/integer/touch.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/optimizing.md b/core/cpu-68080/prm/optimizing.md index 9227f4e..4776c4b 100644 --- a/core/cpu-68080/prm/optimizing.md +++ b/core/cpu-68080/prm/optimizing.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/pipeline.md b/core/cpu-68080/prm/pipeline.md index 3f96c55..9f948b5 100644 --- a/core/cpu-68080/prm/pipeline.md +++ b/core/cpu-68080/prm/pipeline.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/programming-model.md b/core/cpu-68080/prm/programming-model.md index 42fc0a5..3845c01 100644 --- a/core/cpu-68080/prm/programming-model.md +++ b/core/cpu-68080/prm/programming-model.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/specs.md b/core/cpu-68080/prm/specs.md index 00f9cb2..a740ffc 100644 --- a/core/cpu-68080/prm/specs.md +++ b/core/cpu-68080/prm/specs.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/superscalar.md b/core/cpu-68080/prm/superscalar.md index e0973dd..010fcb3 100644 --- a/core/cpu-68080/prm/superscalar.md +++ b/core/cpu-68080/prm/superscalar.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/core/cpu-68080/prm/trace.md b/core/cpu-68080/prm/trace.md index e09ebf7..5780fe3 100644 --- a/core/cpu-68080/prm/trace.md +++ b/core/cpu-68080/prm/trace.md @@ -4,6 +4,7 @@ type: reference owner: WDrijver status: reviewed origin: official +basis: [official] components: [cpu-68080] applies_to: core: "any" diff --git a/hardware/best-practices/.gitkeep b/hardware/best-practices/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hardware/index.md b/hardware/index.md new file mode 100644 index 0000000..a113b23 --- /dev/null +++ b/hardware/index.md @@ -0,0 +1,57 @@ +--- +title: Apollo V4 hardware overview +type: reference +owner: WDrijver +status: draft +origin: ai-assisted +components: [hardware] +applies_to: + core: "any" + os: [any] +tags: [v4, boards, models, standalone, unicorn, icedrake, manticore, firebird] +sources: + - "WDrijver (maintainer), V4 models and abbreviations, 2026-11-03" +--- + +## Summary + +The V4 models share the same FPGA core (68080 CPU and SAGA chipset, see +`core/`) but differ as boards. This pillar holds the board knowledge: +connectors, headers, memory and model differences. + +## Details + +### Models + +| Model | Abbreviations | Folder | `applies_to.board` | +|---|---|---|---| +| V4 Standalone | SA | `hardware/v4-standalone/` | `v4-standalone` | +| V4 UniCorn | UNI, A6000 | `hardware/v4-unicorn/` | `v4-unicorn` | +| V4 IceDrake | ICE | `hardware/v4-icedrake/` | `v4-icedrake` | +| V4 Manticore | MC | `hardware/v4-manticore/` | `v4-manticore` | +| V4 Firebird | FB | `hardware/v4-firebird/` | `v4-firebird` | + +The V4 Standalone and the V4 UniCorn are different models. + +### Where things go + +- `hardware/v4-generic/`: knowledge that holds for every V4 model. +- `hardware/v4-/`: only what is specific to that model. A fact that + holds for several, but not all, models goes in `v4-generic/` with + `applies_to.board` listing those models. +- `hardware/best-practices/` and `hardware/pitfalls/`: as in the other + pillars. + +**No content yet.** If your task depends on board details, tell the user +that the knowledge base does not cover them yet. + +## Differences from AmigaOS / AROS / 68060 + +Classic Amiga hardware knowledge (Zorro, Gayle, the A1200 trapdoor) does not +tell you what a V4 model has. Check the model's folder. + +## Do / Don't + +- DO check `applies_to.board` before using a board fact for your target + model. +- DON'T assume a connector or header exists on every V4 model. diff --git a/hardware/pitfalls/.gitkeep b/hardware/pitfalls/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hardware/v4-firebird/.gitkeep b/hardware/v4-firebird/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hardware/v4-generic/.gitkeep b/hardware/v4-generic/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hardware/v4-icedrake/.gitkeep b/hardware/v4-icedrake/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hardware/v4-manticore/.gitkeep b/hardware/v4-manticore/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hardware/v4-standalone/.gitkeep b/hardware/v4-standalone/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hardware/v4-unicorn/.gitkeep b/hardware/v4-unicorn/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/templates/files/best-practice.md b/templates/files/best-practice.md index dec24fe..1ab9a53 100644 --- a/templates/files/best-practice.md +++ b/templates/files/best-practice.md @@ -4,11 +4,13 @@ type: best-practice owner: status: draft origin: -components: [] +basis: [] +components: [] applies_to: - core: "" + core: "" os: [] mode: [] + board: [] last_verified: tags: [] related: [] @@ -27,7 +29,7 @@ sources: [] ``` ## Evidence -| Variant | Measurement | Core revision | Test setup | +| Variant | Measurement | Core | Test setup | |---|---|---|---| | Baseline (generic 68k) | <...> | <...> | <...> | | Optimized | <...> | <...> | <...> | diff --git a/templates/files/convention.md b/templates/files/convention.md index dc6fb63..c89b09c 100644 --- a/templates/files/convention.md +++ b/templates/files/convention.md @@ -4,11 +4,13 @@ type: convention owner: status: draft origin: -components: [] +basis: [] +components: [] applies_to: - core: "" + core: "" os: [] mode: [] + board: [] last_verified: tags: [] related: [] diff --git a/templates/files/example.md b/templates/files/example.md index 1d845c9..2ba0d92 100644 --- a/templates/files/example.md +++ b/templates/files/example.md @@ -4,11 +4,13 @@ type: example owner: status: draft origin: -components: [] +basis: [] +components: [] applies_to: - core: "" + core: "" os: [] mode: [] + board: [] last_verified: tags: [] related: [] diff --git a/templates/files/guide.md b/templates/files/guide.md index 08193b0..317567c 100644 --- a/templates/files/guide.md +++ b/templates/files/guide.md @@ -4,11 +4,13 @@ type: guide owner: status: draft origin: -components: [] +basis: [] +components: [] applies_to: - core: "" + core: "" os: [] mode: [] + board: [] last_verified: tags: [] related: [] diff --git a/templates/files/lesson.md b/templates/files/lesson.md index b0acc8a..3bcc81a 100644 --- a/templates/files/lesson.md +++ b/templates/files/lesson.md @@ -4,11 +4,13 @@ type: lesson owner: status: draft origin: -components: [] +basis: [] +components: [] applies_to: - core: "" + core: "" os: [] mode: [] + board: [] last_verified: tags: [] related: [] @@ -27,5 +29,10 @@ sources: [] ## What the AI got wrong +## Evidence +| Claim | Source | Core | Method | +|---|---|---|---| +| | <(G) date / (M) / (official) document / (SRC) file> | | | + ## Candidates for distillation - diff --git a/templates/files/pitfall.md b/templates/files/pitfall.md index 253c3ae..e4dd625 100644 --- a/templates/files/pitfall.md +++ b/templates/files/pitfall.md @@ -4,11 +4,13 @@ type: pitfall owner: status: draft origin: -components: [] +basis: [] +components: [] applies_to: - core: "" + core: "" os: [] mode: [] + board: [] last_verified: tags: [] related: [] @@ -33,3 +35,8 @@ sources: [] ## Detection + +## Evidence +| Claim | Source | Core | Method | +|---|---|---|---| +| | <(G) date / (M) / (official) document / (SRC) file> | | | diff --git a/templates/files/reference.md b/templates/files/reference.md index d2ff30d..abe07bd 100644 --- a/templates/files/reference.md +++ b/templates/files/reference.md @@ -4,11 +4,13 @@ type: reference owner: status: draft origin: -components: [] +basis: [] +components: [] applies_to: - core: "" + core: "" os: [] mode: [] + board: [] last_verified: tags: [] related: [] diff --git a/templates/repo/AGENTS.md b/templates/repo/AGENTS.md index 6ab9990..28daeac 100644 --- a/templates/repo/AGENTS.md +++ b/templates/repo/AGENTS.md @@ -19,7 +19,8 @@ without it. - **What it is:** - **Kind:** -- **Target:** core revision <...> +- **Target core:** +- **Target model:** - **Target OS:** - **Execution mode:** - **Languages:** @@ -53,3 +54,9 @@ Build and fix all errors and warnings before presenting code. When you find something missing or wrong in ApolloKnowledgeBase while working here, tell the user and offer to draft a change following `ApolloKnowledgeBase/CONTRIBUTING.md`. + +Offer a lesson when the user says the project, a release or a milestone is +done, and right away when an assumption turns out wrong. Follow +`ApolloKnowledgeBase/AGENTS.md` section 8: draft it from the lesson template, +show it to the user, and only submit it (as a pull request from the +`ApolloKnowledgeBase/` submodule) with their approval. diff --git a/tools/check_frontmatter.py b/tools/check_frontmatter.py index 5216b6d..3d0fe1d 100644 --- a/tools/check_frontmatter.py +++ b/tools/check_frontmatter.py @@ -16,9 +16,17 @@ ORIGINS = {"human", "ai-assisted", "official"} COMPONENTS = {"cpu-68080", "saga-video-isabelle", "saga-audio-arne", "saga-dma-anni", "saga-3d-maggie", "libraries", "devs", - "filesys", "commands", "datatypes", "toolchain", "general"} + "filesys", "commands", "datatypes", "toolchain", "hardware", + "general"} OSES = {"any", "apolloos-r10", "amigaos-3.9", "amigaos-3.2"} MODES = {"any", "os-friendly", "os-takeover"} +BOARDS = {"any", "v4-standalone", "v4-unicorn", "v4-icedrake", "v4-manticore", + "v4-firebird"} +# Kinds of source, highest rank first (CONTRIBUTING.md section 4). +BASES = ["core-developer", "measured", "official", "source-code", "other"] +# "any", one core ("Core 12841"), a range ("Core 12830-12840") or a minimum +# ("Core 12841+"). +CORE_RE = re.compile(r"^(any|Core \d+(\+|-\d+)?)$") REQUIRED = ["title", "type", "owner", "status", "origin", "components", "applies_to"] NEEDS_SOURCES = {"reference", "best-practice"} @@ -133,6 +141,24 @@ def check(path): errs += check_values(at, "os", OSES) if "mode" in at: errs += check_values(at, "mode", MODES) + if "board" in at: + errs += check_values(at, "board", BOARDS) + core = at.get("core") + if not (isinstance(core, str) and CORE_RE.match(core)): + errs.append(f"invalid core '{core}': use \"any\", " + "\"Core 12841\", \"Core 12830-12840\" or " + "\"Core 12841+\"") + else: + m = re.match(r"^Core (\d+)-(\d+)$", core) + if m and int(m.group(1)) >= int(m.group(2)): + errs.append(f"core range '{core}' must go from low to high") + + basis = fm.get("basis") + if basis is not None: + if not isinstance(basis, list) or not basis: + errs.append("basis must be a non-empty list") + else: + errs += [f"invalid basis '{b}'" for b in basis if b not in BASES] lv = fm.get("last_verified") if status == "verified" and not lv: diff --git a/tools/intake/prm68080.py b/tools/intake/prm68080.py index d0ec797..8d43037 100644 --- a/tools/intake/prm68080.py +++ b/tools/intake/prm68080.py @@ -1052,7 +1052,8 @@ def storem3_frame(f, blocks, i): def frontmatter(title, tags, related, extra_sources=()): quoted = '"' + title.replace('\\', '\\\\').replace('"', '\\"') + '"' lines = ["---", f"title: {quoted}", "type: reference", f"owner: {OWNER}", - "status: draft", "origin: official", "components: [cpu-68080]", + "status: draft", "origin: official", "basis: [official]", + "components: [cpu-68080]", "applies_to:", ' core: "any"', " os: [any]", f"tags: [{', '.join(tags)}]"] if related: @@ -1729,9 +1730,28 @@ def build(): return files +STATUS_RE = re.compile(r"^(status|last_verified):.*\n", re.M) + + def without_status(text): """The text without the status fields a maintainer may set.""" - return re.sub(r"^(status|last_verified):.*\n", "", text, flags=re.M) + return STATUS_RE.sub("", text) + + +def body(text): + """The text after the frontmatter.""" + return text.split("\n---\n", 1)[-1] + + +def keep_status(old, new): + """New text with the status fields of the old text, when the body is + unchanged. A file keeps the status a maintainer gave it until its body + changes; then it is generated as draft again.""" + if old is None or body(old) != body(new): + return new + fields = "".join(m.group(0) for m in STATUS_RE.finditer(old)) + return STATUS_RE.sub("", new, count=1).replace( + "origin: ", fields + "origin: ", 1) if fields else new def main(): @@ -1745,9 +1765,8 @@ def main(): for rel, text in files.items(): p = os.path.join(out, rel) old = open(p, encoding="utf-8").read() if os.path.isfile(p) else None - # A file keeps the status a maintainer gave it until its content - # changes; then it is generated as draft again. - if old is None or without_status(old) != without_status(text): + files[rel] = text = keep_status(old, text) + if old != text: stale.append(rel) extra = sorted(existing - set(files)) if "--check" in sys.argv: diff --git a/tools/kblib.py b/tools/kblib.py index c9f0e45..f268620 100644 --- a/tools/kblib.py +++ b/tools/kblib.py @@ -12,9 +12,9 @@ SKIP_DIRS = {"templates", "seed", "sources", "tools", "skills", "evals", ".github", ".git"} -# The three knowledge pillars. Files in a pillar are references, except in +# The four knowledge pillars. Files in a pillar are references, except in # its best-practices/ and pitfalls/ subfolders. -PILLARS = {"core", "os", "toolchain"} +PILLARS = {"core", "hardware", "os", "toolchain"} PILLAR_SUBFOLDER_TYPES = {"best-practices": "best-practice", "pitfalls": "pitfall"}