docs(amiga): complete AmigaOS 3.1/3.2 developer reference — 172 files across 17 sections

Comprehensive technical documentation covering:
- Hardware: OCS/ECS/AGA custom chip registers, Copper & Blitter deep dives
- Boot sequence: cold boot through startup-sequence
- Binary format: HUNK executable spec, relocation, debug info
- Linking & ABI: .fd files, LVO tables, register calling conventions
- Exec kernel: tasks, interrupts, memory, signals, semaphores
- AmigaDOS: file I/O, FFS/OFS layout, CLI/Shell scripting
- Graphics: planar bitmaps, Copper programming, HAM/EHB modes
- Intuition: screens, windows, IDCMP, BOOPSI
- Devices: trackdisk, SCSI, serial, timer, audio, keyboard
- Libraries: utility, expansion, IFFParse, locale, ARexx
- Networking: bsdsocket API, SANA-II, TCP/IP stack comparison
- Toolchain: GCC, vasm/vlink, SAS/C, NDK, debugging
- Reverse engineering: IDA/Ghidra setup, compiler fingerprints, case studies
- CPU & MMU: 68040/060 emulation libs, PMMU, cache management
- Driver development: SANA-II, Picasso96/RTG, AHI audio

All files include breadcrumb navigation. No local paths or proprietary content.

01_hardware/ocs_a500/blitter.md

@@ -0,0 +1,154 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [OCS](README.md)
+
+# Blitter
+
+## Overview
+
+The **Blitter** (Block Image Transferrer) is a DMA-driven coprocessor inside Agnus. It performs block copy, fill, and line-draw operations directly on Chip RAM without CPU involvement, at DMA bus speed.
+
+## Channels
+
+The Blitter has four channels:
+
+| Channel | Role | Register Pointer |
+|---|---|---|
+| **A** | Source (with mask) | BLTAPTH/BLTAPTL |
+| **B** | Source (with shift) | BLTBPTH/BLTBPTL |
+| **C** | Source (destination content) | BLTCPTH/BLTCPTL |
+| **D** | Destination | BLTDPTH/BLTDPTL |
+
+Any channel can be disabled per operation. The result written to D is computed as a **minterm** (boolean function) of A, B, C.
+
+## BLTCON0 — Control Register 0
+
+```
+bit 15-8: USEA, USEB, USEC, USED (enable channels A/B/C/D)
+bit  7-0: LF (Logic Function / minterm) — 8-bit truth table
+           Bit = result bit for combination of A,B,C
+           Bit 7: !A!B!C
+           Bit 6:  A!B!C
+           Bit 5: !AB!C
+           Bit 4:  AB!C
+           Bit 3: !A!BC
+           Bit 2:  A!BC
+           Bit 1: !ABC
+           Bit 0:  ABC
+```
+
+### Common Minterm Values
+
+| Minterm | Hex | Operation |
+|---|---|---|
+| D = A AND B | $C0 | Mask copy |
+| D = A | $F0 | Simple copy (A only) |
+| D = A OR C | $FC | Overlay (A onto C) |
+| D = A XOR C | $3C | XOR blit |
+| D = NOT A | $0F | Invert A |
+| D = (A AND B) OR (!A AND C) | $CA | Cookie-cut (transparency) |
+
+### Cookie-Cut Example
+
+Cookie-cut (transparent sprite blit):
+```asm
+; A = mask (1=opaque, 0=transparent)
+; B = sprite data
+; C = background
+; D = result: background where mask=0, sprite where mask=1
+; Minterm: D = (A AND B) OR (!A AND C) = $CA
+
+move.w  #$09F0, BLTCON0    ; USE A,B,C,D; minterm=$CA
+move.w  #$0000, BLTCON1
+```
+
+## BLTCON1 — Control Register 1
+
+```
+bit 15:  DOFF   — disable D write (dry run for fill detection)
+bit  4:  IFE    — inclusive fill enable
+bit  3:  EFE    — exclusive fill enable
+bit  2:  FCI    — fill carry in (start state)
+bit  1:  DESC   — descending mode (blit from bottom-right)
+bit  0:  LINE   — line draw mode
+```
+
+## BLTSIZE — Start Blitter
+
+```
+BLTSIZE = (height << 6) | width_in_words
+```
+
+Writing to BLTSIZE starts the blit operation immediately. The blitter holds the bus until complete.
+
+Example — blit 16×16 pixels (1 word wide, 16 lines):
+```asm
+move.w  #((16<<6)|1), BLTSIZE
+```
+
+Example — blit 320×256 (20 words wide, 256 lines):
+```asm
+move.w  #((256<<6)|20), BLTSIZE
+```
+
+## Modulo Registers
+
+Modulo is the number of **bytes** to skip at the end of each row (to move to the start of the next row in a larger bitmap):
+
+```
+BLTxMOD = (bytes_per_row_in_bitmap) - (width_of_blit_in_bytes)
+```
+
+For a 320-pixel wide (40-byte row) bitmap, blitting a 32-pixel (4-byte) wide section:
+```
+Modulo = 40 - 4 = 36
+```
+
+## First/Last Word Masks
+
+`BLTAFWM` (first word mask) and `BLTALWM` (last word mask) mask the A channel for the first and last word of each blit row, allowing sub-word-aligned blitting.
+
+For a fully aligned blit with no partial words:
+```asm
+move.w  #$FFFF, BLTAFWM
+move.w  #$FFFF, BLTALWM
+```
+
+## Line Draw Mode (BLTCON1 bit 0)
+
+In line mode, the blitter draws a line between two points using the Bresenham algorithm:
+- A channel provides the single pixel pattern (usually $8000 for MSB)
+- D channel is the destination bitmap
+- BLTSIZE specifies the line length (height=octant length, width=2)
+- BLTCON1 encodes octant, sign flags, and texture data
+
+Line mode is used by `graphics.library` `Draw()` calls internally.
+
+## Fill Mode (BLTCON1 IFE/EFE)
+
+**Exclusive fill (EFE):** Each set bit toggles the fill state — produces XOR fill (like polygon rasterisation).
+**Inclusive fill (IFE):** Set bit turns fill on, stays on until end of row — used for solid polygon fill.
+
+Fill operates in D channel only (no source channels active). BLTCON1 `DESC` bit = 1 when filling bottom-up.
+
+## Waiting for Blitter Completion
+
+```asm
+; Busy-wait on BLTCON0 busy bit
+WaitBlit:
+    btst    #6, DMACONR+1    ; test BBUSY bit (bit 14 of DMACONR, byte=bit6)
+    bne.s   WaitBlit
+```
+
+Or via exec (preferred):
+```c
+WaitBlit();   /* graphics.library — waits and resets to safe state */
+```
+
+> [!CAUTION]
+> Never start a blit while the blitter is busy. Always call `WaitBlit()` or poll `DMACONR[BBUSY]` before setting up new blit registers.
+
+## References
+
+- ADCD 2.1 Hardware Manual — Blitter chapter
+- NDK39: `hardware/blit.h`, `graphics/blitattr.h`
+- graphics.library Autodocs: `BltBitMap`, `BltTemplate`, `BltClear`
+- http://amigadev.elowar.com/read/ADCD_2.1/Hardware_Manual_guide/node006D.html