[WDrijver]

Document intake (CONTRIBUTING.md section 11) of the SAGA register documentation.

What this PR does

• Original: sources/official/saga-registers/, the 93 HTML pages copied verbatim from ApolloClaude docs/hardware/sagadoc.
• Converter: tools/intake/sagaregs.py, standard library only. CI runs it with --check, like the PRM converter.
• Output: 12 generated files in core/saga-registers/. All are origin: official, status: draft, owner WDrijver, applies_to.core: "Core 12000+".

File	Content
index.md	Scope, access codes, files, register map, corrections, open questions
chunky-plane.md	GFXMODE (21 resolutions, pixel formats), chunky pointer and modulo
colour-ports.md	Planar, sprite, chunky and PIP colour ports
pip.md	PIP 1 (original) and PIP 2 (ApolloLib), the two modes
pointer.md	Pointer position, the 32x32 sprite (ApolloLib), 12-bit colours
display-control.md	SAGA CONTROL, SCREEN SHIFT, SCREENMODE ADJUST
sprite-collision.md	clxdat0–7
arne-channels.md	16 channels at $DFF400 + n × $10, CTRL/LEN/VOL/PER
arne-dma-and-interrupts.md	DMACON2, INTENA2, INTREQ2
maggie-3d.md	Official names of the 3D registers
input.md	USB joypads, mouse wheel, DB9, POTGO fire buttons
system.md	Board ID, core revision, chip ID, SPI

Scope (agreed 2026-11-04)

• index.htm is the current table; saga.htm is not used. The Atari section is skipped.
• Only SAGA-specific registers, option (b):
  • every row of the original is marked SAGA;
  • the converter takes the 183 rows where OCS, ECS and AGA are empty;
  • it adds 4 SAGA addresses that the original also marks as classic ($DFF1D0/$DFF1D2 pointer position, $DFF20A/$DFF20C DB9).
• Classic registers: "the HRM applies; on SAGA, pointers are 32-bit and reach all RAM".

Corrections applied by the converter (the original should be fixed the same way)

• Address typos:
  • $DFFAA0 → $DFF4A0;
  • $DFF4C4C → $DFF4CC;
  • $DFF21c → $DFF21C.
• Description typos:
  • AUD3L is called "channel 1";
  • BPLHPTH/BPLHPTL say 15 bits; it should be 16;
  • "Vaniall".
• Access: $DFF3EC is W, not R (WDrijver).
• Page selection: the converter uses the right pages for the Arne rows instead of the wrong links. It leaves out the copied example on the screen adjust page, and notes the wrong title of the screen shift page.
• Layout check: the converter checks all 80 Arne rows against $DFF400 + n × $10 and fails if one doesn't fit.

Added from other sources, tagged (SRC) or WDrijver

• PIP 2: $DFF3B0–$DFF3C2, colour port $DFF37C. ApolloLib is leading, as agreed.
• PIP register meanings: the format bit 8 transparency, colour key, DMA row length (0 = off), and overlay and chroma-key modes. Sources: ApolloLib and the SAGAPiP example.
• Pointer:
  • read-back at $DFE1D0/$DFE1D2;
  • the 32x32 sprite: image at $DFD000, palette at $DFF3A8/$DFF3AA.
  • Sources: ApolloLib and the ApolloPointer example.
• Arne:
  • volume $00–$FF per side, and the LEN unit for 16-bit stereo (ApolloLib);
  • channels 0–3 = Paula channels 0–3 (WDrijver).
• Board IDs: $03/$04/$05/$07/$08, Salamander and Phoenix (WDrijver); legacy V2 IDs from the ApolloOS source.

ApolloLib version: the converter uses ApolloLib from ApolloCrossDev Projects/ApolloLib (commit 2dfaa5c). The copy in ApolloClaude docs/toolchain/_ApolloLib is older and describes a 16x16 planar pointer at $DFF800 instead; that is listed as an open question.

Answers added during review (2026-11-04)

• $DFF3EC: write-only, SAGA Control 1 (OCS mode, PAL zoom, zoom mode, scanlines). Source: WDrijver.
• $DFF3EE: read and write, SAGA Control 2 (zoom shift X and Y in pixels, positive integers). Source: WDrijver.
• Pointer: from Core 12500 the 32x32x8-bit sprite replaces the 16x16 pointer. It has only 50 % semi-transparency, no real alpha. Source: WDrijver.
• PIP formats:
  • supported: $01, $02, $03, YUV888 $06, YUV444 $0E; not $04/$05;
  • transparent colour: index $FF in 8-bit, purple (red and blue at maximum) in 15- and 16-bit;
  • ApolloLib wrongly marks YUV as unsupported.
  • Source: WDrijver.
• Sprites: SAGA has the 8 classic sprites. Source: WDrijver.
• Read-back:
  • write-only registers at $DFF0xx/$DFF1xx read back at $DFE0xx/$DFE1xx;
  • nothing from $DFF200 up has a read-back shadow.
  • Source: WDrijver.
• Copper:
  • 32-bit MOVE with bit 15 of the first word set;
  • without FMODE bit 4 (SAGA), the Copper is gated to $DFF0xx/$DFF1xx;
  • with it, the Copper can write every SAGA register up to $DFF4FF, with 16- and 32-bit moves.
  • Source: Gunnar (G).
• Best practice: prefer library calls (ApolloLib for Arne and Isabelle, maggie.library for Maggie) to direct register access. New file core/best-practices/prefer-library-calls-for-saga-chips.md. Source: WDrijver.

Still open

1. "IRQ $48/$50": vector offset or vector number, and at which level (in index.md).
2. Arne maximum rate: see the conflict below. Asked Gunnar for the clock of AUDxPER, the minimum period and the maximum rate.

Conflicts with existing knowledge base files (not resolved here)

• core/saga-audio-arne/registers.md (TuKo1982, measured) says the high-quality rate caps at about 66 kHz. The original says 56 kHz, and period 65 gives 54.6 kHz.

Other changes

• AGENTS.md task table and CONTRIBUTING.md: point to core/saga-registers/.
• The chip folders (saga-video-isabelle, saga-audio-arne, saga-3d-maggie) link to the generated files.
• core/saga-audio-arne/registers.md: the channel base addresses are now documented.
• .github/CODEOWNERS: regenerated.

Structural choice to review

The generated files are in one new folder, core/saga-registers/, instead of the chip folders, because:

• generated files can't share a folder with hand-written registers.md files;
• input and system registers belong to no single chip.

Knowledge base files relied on

• core/saga-audio-arne/registers.md
• core/saga-3d-maggie/registers.md
• os/libraries/maggie-library.md
• hardware/index.md

🤖 Generated with Claude Code