Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
52 changes: 52 additions & 0 deletions .github/ISSUE_TEMPLATE/lesson.yml
Original file line number Diff line number Diff line change
@@ -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: <project name>"
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/.
62 changes: 48 additions & 14 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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/` |
Expand All @@ -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`.
Expand All @@ -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.

---

Expand Down Expand Up @@ -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.
94 changes: 82 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -55,7 +65,7 @@ lessons/ project retrospectives

| Folder | `type` |
|---|---|
| `core/`, `os/`, `toolchain/` and their subfolders | reference |
| `core/`, `hardware/`, `os/`, `toolchain/` and their subfolders | reference |
| `<pillar>/best-practices/` | best-practice |
| `<pillar>/pitfalls/` | pitfall |
| `guides/` | guide |
Expand All @@ -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.
Expand Down Expand Up @@ -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: "<core revision or range>" # 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
Expand All @@ -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
Expand All @@ -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.

---

Expand Down Expand Up @@ -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.

---

Expand Down Expand Up @@ -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 `<placeholder>` text, `related`,
`superseded_by` and `generated_from` paths exist, `official` files are
owned by a maintainer
Expand Down
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

Expand All @@ -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.

---

Expand Down Expand Up @@ -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`.
1 change: 1 addition & 0 deletions core/cpu-68080/prm/ammx-unit.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ type: reference
owner: WDrijver
status: reviewed
origin: official
basis: [official]
components: [cpu-68080]
applies_to:
core: "any"
Expand Down
1 change: 1 addition & 0 deletions core/cpu-68080/prm/ammx/ammx-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ type: reference
owner: WDrijver
status: reviewed
origin: official
basis: [official]
components: [cpu-68080]
applies_to:
core: "any"
Expand Down
1 change: 1 addition & 0 deletions core/cpu-68080/prm/ammx/bfly.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ type: reference
owner: WDrijver
status: reviewed
origin: official
basis: [official]
components: [cpu-68080]
applies_to:
core: "any"
Expand Down
Loading
Loading