SAGA register intake: SAGA-specific registers

.github/CODEOWNERS

@@ -26,6 +26,7 @@
 /core/best-practices/interleave-dependency-chains.md @TuKo1982
 /core/best-practices/memory-access-patterns.md @TuKo1982
 /core/best-practices/predicated-bcc-over-one-instruction.md @TuKo1982
+/core/best-practices/prefer-library-calls-for-saga-chips.md @WDrijver
 /core/best-practices/use-fusable-pairs.md @TuKo1982
 /core/cpu-68080/bank-prefix.md @TuKo1982
 /core/cpu-68080/branches-and-prediction.md @TuKo1982
@@ -155,6 +156,18 @@
 /core/saga-audio-arne/index.md @WDrijver
 /core/saga-audio-arne/registers.md @TuKo1982
 /core/saga-dma-anni/index.md @WDrijver
+/core/saga-registers/arne-channels.md @WDrijver
+/core/saga-registers/arne-dma-and-interrupts.md @WDrijver
+/core/saga-registers/chunky-plane.md @WDrijver
+/core/saga-registers/colour-ports.md @WDrijver
+/core/saga-registers/display-control.md @WDrijver
+/core/saga-registers/index.md @WDrijver
+/core/saga-registers/input.md @WDrijver
+/core/saga-registers/maggie-3d.md @WDrijver
+/core/saga-registers/pip.md @WDrijver
+/core/saga-registers/pointer.md @WDrijver
+/core/saga-registers/sprite-collision.md @WDrijver
+/core/saga-registers/system.md @WDrijver
 /core/saga-video-isabelle/index.md @WDrijver
 /hardware/index.md @WDrijver
 /os/apolloos-and-amigaos-on-v4.md @WDrijver

AGENTS.md

@@ -85,10 +85,11 @@ you read.
 | Execution mode is `os-takeover` (games, demos) | `os/os-takeover.md`, `core/` |
 | Writing code at all | `conventions/`, `toolchain/` |
 | CPU-heavy or assembly code | `core/cpu-68080/`, `core/best-practices/`, `core/pitfalls/` |
-| Graphics, screens, video modes | `core/saga-video-isabelle/` |
-| Sound | `core/saga-audio-arne/` |
+| Graphics, screens, video modes | `core/saga-video-isabelle/`, `core/saga-registers/` |
+| Sound | `core/saga-audio-arne/`, `core/saga-registers/` |
 | Memory transfers, DMA | `core/saga-dma-anni/` |
-| 3D | `core/saga-3d-maggie/` |
+| SAGA input, board ID, other SAGA registers | `core/saga-registers/` |
+| 3D | `core/saga-3d-maggie/`, `core/saga-registers/` |
 | 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/` or `hardware/` folder of the hardware involved |

CONTRIBUTING.md

@@ -78,6 +78,9 @@ Not content: `templates/` (file, repo and seed templates), `sources/`
 skills, step 2), `evals/` (AI benchmarks, step 5), `tools/` (CI scripts).
 
 Each chip folder keeps its register map in `registers.md` inside that folder.
+The official SAGA register documentation is generated into
+`core/saga-registers/` (document intake, section 11); the chip folders link
+to it.
 
 `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

core/best-practices/prefer-library-calls-for-saga-chips.md

@@ -0,0 +1,65 @@
+---
+title: Prefer library calls over direct SAGA register access
+type: best-practice
+owner: WDrijver
+status: draft
+origin: ai-assisted
+basis: [other]
+components: [saga-audio-arne, saga-video-isabelle, saga-3d-maggie]
+applies_to:
+  core: "any"
+  os: [any]
+tags: [saga, arne, isabelle, maggie, library, apollolib, maggie-library, registers]
+related:
+  - core/saga-registers/index.md
+  - os/libraries/maggie-library.md
+  - core/saga-audio-arne/index.md
+  - core/saga-video-isabelle/index.md
+  - core/saga-3d-maggie/index.md
+sources:
+  - "WDrijver (maintainer), library calls for the SAGA chips, 2026-11-04"
+  - "maggie.library, github.com/RMortenB/MaggieLibrary (the author's source, golden source)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib"
+---
+
+## Goal
+
+Code that keeps working when the SAGA hardware or its use changes. A library
+call hides register layouts, core differences and setup order, so the
+program doesn't depend on them.
+
+## Technique
+
+For the SAGA chips, prefer the library calls to direct register access
+(WDrijver, 2026-11-04):
+
+| Chip | Use | Source |
+|---|---|---|
+| Arne (SAGA audio) | ApolloLib | github.com/WDrijver/ApolloCrossDev, `Projects/ApolloLib` |
+| Isabelle (SAGA video) | ApolloLib | github.com/WDrijver/ApolloCrossDev, `Projects/ApolloLib` |
+| Maggie (SAGA 3D) | maggie.library | github.com/RMortenB/MaggieLibrary (the author's source, golden source) |
+
+- An official library for Arne and Isabelle is in development. Until it is
+  released, ApolloLib is the best choice for library calls to Arne and
+  Isabelle.
+- maggie.library is described in
+  [os/libraries/maggie-library.md](../../os/libraries/maggie-library.md).
+  When you need more than that file covers, the author's repository is the
+  golden source.
+- The registers are documented in
+  [core/saga-registers/](../saga-registers/index.md), for library work and
+  for code that must access them directly.
+
+## Evidence
+
+| Variant | Measurement | Core | Test setup |
+|---|---|---|---|
+| Library calls instead of direct register access | Preferred: a best practice, not a forced rule | any | Statement (WDrijver, 2026-11-04) |
+
+## When not to use
+
+- This is a best practice, not a rule. Direct register access stays
+  allowed, for example in `os-takeover` code (games, demos) or where a
+  library has no call for what you need.
+- When you write to SAGA registers directly, say so, as AGENTS.md section 2
+  asks.

core/saga-3d-maggie/index.md

@@ -16,8 +16,9 @@ sources:
 
 Maggie, the SAGA 3D chip.
 
-**This folder is only partly covered.** It has the span registers as
-maggie.library uses them (`registers.md`) and the pitfalls in
+**This folder is only partly covered.** It has the official register names
+([core/saga-registers/maggie-3d.md](../saga-registers/maggie-3d.md)), the
+span registers as maggie.library uses them (`registers.md`) and the pitfalls in
 `core/pitfalls/maggie-*.md`. For anything else, tell the user that the
 knowledge base does not cover it yet. Do not fill the gap with classic Amiga
 or 68060 knowledge.
@@ -27,7 +28,8 @@ or 68060 knowledge.
 ### Planned files
 
 - `registers.md`: the span unit registers as maggie.library uses them, with
-  measured behaviour (exists; no official register documentation yet)
+  measured behaviour (exists; the official names are in
+  `core/saga-registers/maggie-3d.md`)
 - One file per feature, for example texture mapping
 - Using maggie.library: [os/libraries/maggie-library.md](../../os/libraries/maggie-library.md)
 
@@ -41,5 +43,8 @@ No content yet.
 
 ## Do / Don't
 
+- DO prefer the library calls (maggie.library) to direct register access: a best
+  practice, not a forced rule (see
+  [prefer-library-calls-for-saga-chips.md](../best-practices/prefer-library-calls-for-saga-chips.md)).
 - DON'T invent register addresses, bit meanings or instruction behavior for
   the SAGA 3D (Maggie). Say that the knowledge base does not cover it.

core/saga-3d-maggie/registers.md

@@ -15,6 +15,7 @@ related:
   - core/pitfalls/maggie-depth-test-colour-write.md
   - core/pitfalls/maggie-span-tail.md
   - core/pitfalls/maggie-span-usage.md
+  - core/saga-registers/maggie-3d.md
 sources:
   - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 15.7"
   - "maggie.library source, github.com/RMortenB/MaggieLibrary, commit 64c78ef (2026-08-17)"

core/saga-audio-arne/index.md

@@ -16,17 +16,19 @@ sources:
 
 Arne, the SAGA audio chip.
 
-**This folder is only partly covered.** `registers.md` has the registers and
-values used in V4 audio driver work. For anything else, tell the user that
-the knowledge base does not cover it yet. Do not fill the gap with classic
-Amiga (Paula) or 68060 knowledge.
+**This folder is only partly covered.** The official register map is in
+[core/saga-registers/arne-channels.md](../saga-registers/arne-channels.md)
+and [arne-dma-and-interrupts.md](../saga-registers/arne-dma-and-interrupts.md).
+`registers.md` has the values measured in V4 audio driver work. For anything
+else, tell the user that the knowledge base does not cover it yet. Do not
+fill the gap with classic Amiga (Paula) or 68060 knowledge.
 
 ## Details
 
 ### Planned files
 
-- `registers.md`: partial register reference (exists; the full map is still
-  missing)
+- `registers.md`: values measured in driver work (exists); the official map
+  is in `core/saga-registers/`
 - One file per feature, for example channels or sample formats
 
 ### For contributors
@@ -39,5 +41,8 @@ No content yet.
 
 ## Do / Don't
 
+- DO prefer the library calls (ApolloLib) to direct register access: a best
+  practice, not a forced rule (see
+  [prefer-library-calls-for-saga-chips.md](../best-practices/prefer-library-calls-for-saga-chips.md)).
 - DON'T invent register addresses, bit meanings or instruction behavior for
   the SAGA audio (Arne). Say that the knowledge base does not cover it.

core/saga-audio-arne/registers.md

@@ -13,6 +13,7 @@ tags: [arne, audio, saga, registers, dma, interrupts]
 related:
   - core/saga-audio-arne/index.md
   - core/cpu-68080/core-at-a-glance.md
+  - core/saga-registers/arne-channels.md
 sources:
   - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 1 and 13"
 ---
@@ -33,7 +34,8 @@ is not documented here yet.
 | LEN | 32-bit count of **sample pairs** |
 | VOL | Left volume in bits 15–8, right volume in bits 7–0 |
 
-The base addresses of the channel registers are not given in the source.
+The channel base addresses are in the official register map:
+[core/saga-registers/arne-channels.md](../saga-registers/arne-channels.md).
 
 ### Control and interrupt registers
 
@@ -63,5 +65,5 @@ The base addresses of the channel registers are not given in the source.
 
 - DO keep the period at 65 or higher.
 - DO give LEN in sample pairs, not words.
-- DON'T guess the remaining ARNE registers: the knowledge base does not
-  cover them yet.
+- DON'T guess ARNE registers: use the official map in
+  `core/saga-registers/`.

core/saga-registers/arne-channels.md

@@ -0,0 +1,97 @@
+---
+title: "SAGA Arne audio channel registers"
+type: reference
+owner: WDrijver
+status: draft
+origin: official
+basis: [core-developer, official, source-code]
+components: [saga-audio-arne]
+applies_to:
+  core: "Core 12000+"
+  os: [any]
+tags: [saga, arne, audio, registers]
+related:
+  - core/saga-registers/index.md
+  - core/saga-audio-arne/registers.md
+  - core/saga-registers/arne-dma-and-interrupts.md
+  - core/best-practices/prefer-library-calls-for-saga-chips.md
+sources:
+  - "SAGA register documentation, sources/official/saga-registers/ (HTML)"
+  - "ApolloLib, github.com/WDrijver/ApolloCrossDev Projects/ApolloLib (ApolloCrossDev_Defines.h, ApolloCrossDev_LibC.c), commit 2dfaa5c (2026-09-02)"
+  - "WDrijver (maintainer), answers on the SAGA register documentation, 2026-11-04"
+  - "Gunnar (core developer, BigGun), Apollo chat, 2026-11-04 (relayed by WDrijver)"
+generated_from: sources/official/saga-registers/index.htm
+---
+
+<!-- GENERATED by tools/intake/sagaregs.py from sources/official/saga-registers/. Do not edit: change the original or the script's CORRECTIONS/ADDITIONS, and regenerate. -->
+
+## Summary
+
+Arne, the SAGA audio unit, has 16 channels of 8- or 16-bit mono or 16-bit stereo samples from any RAM, each with a 32-bit pointer and length at `$DFF400 + n × $10`. Channels 0–3 are the Paula channels.
+
+## Details
+
+### Channel layout
+
+16 channels, channel n at `$DFF400 + n × $10` (n = 0–15). The converter checks every row of the original against this layout.
+
+| Offset | Register | Size | Access | Meaning |
+|---|---|---|---|---|
+| +0 | AUDxL | L | W | Pointer to the sample data (32-bit, any RAM) |
+| +4 | AUDxLEN | L | W | Length in sample pairs (32-bit) |
+| +8 | AUDxVOL | W | W | Volume: bits 15–8 left, 7–0 right |
+| +A | AUDxCTRL | W | W | Control (see below) |
+| +C | AUDxPER | W | W | Period (16-bit) |
+
+- `$DFF430`: corrected: typo in the original: this is channel 3.
+- `$DFF4A0`: corrected: typo in the original: the AUD10 block is at $DFF4A0, as the channel layout requires.
+- `$DFF4CC`: corrected: typo in the original: AUD12PER is at $DFF4CC, as the channel layout requires.
+
+### Channels 0–3 and Paula
+
+Arne channels 0–3 are the four Paula channels: the same voices, with the classic registers at `$DFF0A0`–`$DFF0DF` and the Arne registers at `$DFF400`–`$DFF43F` (WDrijver, 2026-11-04). ApolloLib starts and stops channels 0–3 with DMACON bits 0–3 (`$DFF096`) and checks them in DMACONR (`$DFF002`); channels 4–15 use DMACON2 (SRC, see [arne-dma-and-interrupts.md](arne-dma-and-interrupts.md)).
+
+### AUDxCTRL
+
+| Bits | Function | Description |
+|---|---|---|
+| 2 | Stereo | 16bit/16bit interleaved mode - 64bit align |
+| 1 | OneShot | Channel will turn itself off at sample end |
+| 0 | 16bit | 0=8bit, 1=16bit samples |
+
+Sample formats (original):
+
+- 8bit signed mono. Data stored in pairs, data aligment 16bit
+- 16bit signed mono, Data stored in pairs, data alignment 32bit
+- Left/Rigth signed 16bit stereo, Data in memory in pairs, memory alignment 64bit
+
+ApolloLib writes `$0005` (16-bit stereo, looping) and `$0007` (16-bit stereo, one-shot) (SRC). The other bits are not described.
+
+### AUDxLEN
+
+The count is in pairs of samples (original). For 16-bit stereo, ApolloLib writes the size in bytes / 8: one count is two stereo frames of 2 × 16 bits (SRC).
+
+### AUDxVOL
+
+Bits 15–8 left volume, bits 7–0 right volume (original). Each side ranges from `$00` to `$FF` (ApolloLib, SRC).
+
+### AUDxPER
+
+16bit PERIOD COUNT This register contains the period (rate) of audio channel x DMA data transfer. The minimum period is 65 color clocks. This means that the smallest number that should be placed in this register is 65 decimal. This corresponds to a maximum sample frequency of 56 khz.
+
+The period coding is compatible with Paula: Arne runs at the same clock as Paula (G, 2026-11-04), the PAL colour clock of 3546895 Hz. So period = 3546895 / sample rate (44.1 kHz gives 80), and period 65 gives 3546895 / 65 = 54.6 kHz, not the 56 kHz in the original.
+
+Whether Arne accepts periods below 65 is not documented: core/saga-audio-arne/registers.md states a rate of about 66 kHz, which would need period 54 (see [index.md](index.md)).
+
+## Differences from AmigaOS / AROS / 68060
+
+- Paula has 4 channels, 8-bit samples, 6-bit volume and Chip RAM only. Arne channels 0–3 are those same channels, with the extra registers at `$DFF400`.
+- Classic AUDxLEN counts words; Arne AUDxLEN counts sample pairs and is 32 bits.
+
+## Do / Don't
+
+- DO prefer the library calls (ApolloLib) to direct access to these registers: a best practice, not a forced rule (see [prefer-library-calls-for-saga-chips.md](../best-practices/prefer-library-calls-for-saga-chips.md)).
+- DO keep the period at 65 or higher.
+- DO give AUDxLEN in sample pairs.
+- DO start channels 0–3 with DMACON and channels 4–15 with DMACON2.
+- DON'T program channel 0–3 through both register sets at the same time.