Add Copper ISA Complete Reference Manual

New file: 08_graphics/copper/copper_reference.md
- Full instruction set reference with opcode encoding table
- Bit-level encoding for MOVE, WAIT, SKIP (7-bit masks)
- Beam position encoding: V counter (8-bit), H counter (7-bit)
- Copper control registers (COP1LC, COP2LC, COPJMP, COPCON, DMACON)
- Copper list structure, dual lists, SKIP-based double buffering
- DMA timing budget calculations per scanline
- Register reference for all copper-writable targets
- OCS/ECS/AGA differences (AGA 24-bit color via BPLCON3 LOCT)
- Programming models: bare metal, OS-friendly UCopList, self-modifying
- Common patterns: rainbow, split screen, status bar, sprite mux
- Debugging: 8 common pitfalls with symptoms and fixes
- Mermaid fetch-execute cycle diagram

Updated files:
- 08_graphics/README.md: add copper_reference.md to index
- 08_graphics/copper/copper.md: cross-reference link, fix MOVE/WAIT
  encoding, fix UCopList CMOVE syntax
- 08_graphics/copper/copper_programming.md: cross-reference link, fix
  horizontal resolution (2 color clocks, not 4)

08_graphics/README.md

@@ -14,6 +14,7 @@ The Amiga graphics system is built on custom DMA-driven hardware (Agnus/Alice +
 | [ham_ehb_modes.md](ham_ehb_modes.md) | HAM6/HAM8 encoding pipeline, EHB half-brite, fringing, palette programming, FPGA decoder logic |
 | [copper.md](copper/copper.md) | Copper coprocessor, instruction format, UCopList |
 | [copper_programming.md](copper/copper_programming.md) | Copper deep dive: architecture, copper list construction, gradient and raster effects |
+| [copper_reference.md](copper/copper_reference.md) | Copper ISA complete reference: full encoding, control registers, timing, register map, debugging |
 | [blitter.md](blitter/blitter.md) | Blitter DMA engine, minterms, BltBitMap |
 | [blitter_programming.md](blitter/blitter_programming.md) | Blitter deep dive: minterms, cookie-cut masking, line draw, fill mode |
 | [sprites.md](sprites.md) | Hardware sprites: DMA engine, data format, attached 15-color sprites, multiplexing, AGA enhancements, priority control |

08_graphics/copper/copper.md

@@ -6,6 +6,8 @@
 
 The **Copper** is a simple coprocessor in the Amiga custom chips that executes a list of instructions synchronized to the video beam. It can write to any custom chip register at any beam position, enabling per-scanline color changes, split screens, and hardware-level display effects without CPU intervention.
 
+For the complete ISA reference with full bit-level encoding, beam position details, control registers, timing, and debugging guidance, see **[copper_reference.md](copper_reference.md)** — the Copper ISA Complete Reference Manual.
+
 ---
 
 ## Instruction Format
@@ -15,8 +17,9 @@ The Copper has only three instructions, each 32 bits (one longword):
 ### MOVE — Write a Register
 
 ```
-[register_offset (9 bits)] [value (16 bits)]
-Bit layout: 0RRRRRRRR00000000 VVVVVVVVVVVVVVVV
+[register_offset] [value (16 bits)]
+Word 1: 0000000R RRRRRRR0 (Offset)
+Word 2: VVVVVVVV VVVVVVVV (Data)
 ```
 
 - Register offset is relative to `$DFF000` (custom chip base)
@@ -26,8 +29,11 @@ Bit layout: 0RRRRRRRR00000000 VVVVVVVVVVVVVVVV
 ### WAIT — Wait for Beam Position
 
 ```
-[vpos (8 bits)] [hpos (7 bits)] [1] [vmask (7 bits)] [hmask (7 bits)] [0]
-Bit layout: VVVVVVVVHHHHHH01 vvvvvvvvhhhhhhh0
+[vpos (8 bits)] [hpos (7 bits)] [1]
+Word 1: VVVVVVVV HHHHHHH1
+
+[BFD (1 bit)] [vmask (7 bits)] [hmask (7 bits)] [0]
+Word 2: Bvvvvvvv hhhhhhh0
 ```
 
 - Pauses until the beam reaches at least the specified (vpos, hpos)
@@ -86,13 +92,16 @@ The OS manages copper lists through `GfxBase`:
 Applications can inject copper instructions into the system list via `UCopList`:
 
 ```c
+#include <hardware/custom.h>
+extern struct Custom custom;
+
 struct UCopList *ucl = AllocMem(sizeof(struct UCopList), MEMF_PUBLIC|MEMF_CLEAR);
 
 CINIT(ucl, 100);                    /* init, max 100 instructions */
 CWAIT(ucl, 44, 0);                  /* wait for line 44 */
-CMOVE(ucl, *((UWORD *)0xDFF180), 0x0F00); /* COLOR00 = red */
+CMOVE(ucl, custom.color[0], 0x0F00); /* COLOR00 = red */
 CWAIT(ucl, 100, 0);
-CMOVE(ucl, *((UWORD *)0xDFF180), 0x000F); /* COLOR00 = blue */
+CMOVE(ucl, custom.color[0], 0x000F); /* COLOR00 = blue */
 CEND(ucl);                          /* end of list */
 
 viewport->UCopIns = ucl;

08_graphics/copper/copper_programming.md

@@ -61,7 +61,7 @@ graph LR
 | No branching/loops | Executes linearly top-to-bottom; no jumps or calls |
 | No memory read | Can only WRITE to registers — cannot read anything |
 | No CPU memory access | Writes only to custom chip registers (`$DFF000`+), not RAM or CIA |
-| No sub-pixel timing | Horizontal resolution: 4 color clocks (~8 low-res pixels) |
+| No sub-pixel timing | Horizontal resolution: 2 color clocks (~4 low-res pixels) |
 | V counter wraps at 255 | PAL lines 256–311 require a double-WAIT trick |
 | Chip RAM only | The copper list itself must reside in Chip RAM (DMA-accessible) |
 
@@ -82,7 +82,7 @@ The Copper has exactly **3 instructions**, each 32 bits (2 words):
 ### MOVE — Write to Register
 
 ```
-Word 1:  RRRRRRRR R0000000     R = register address (9 bits)
+Word 1:  0000000R RRRRRRR0     R = register offset (bits 8-1)
 Word 2:  DDDDDDDD DDDDDDDD    D = 16-bit data value
 
 Constraints:
@@ -275,8 +275,8 @@ FreeCopList(ucl);
 
 | Item | Cycles |
 |---|---|
-| Each Copper instruction | 4 color clocks (= 8 low-res pixels) |
-| WAIT resolution (horizontal) | 4 color clocks minimum |
+| Each Copper instruction | 2 color clocks (= 4 low-res pixels) |
+| WAIT resolution (horizontal) | 2 color clocks minimum |
 | Maximum instructions per line | ~112 (NTSC) / ~114 (PAL) |
 | PAL visible lines | 256 (lines 44–300) |
 | NTSC visible lines | 200 (lines 44–244) |
@@ -315,6 +315,7 @@ Reposition sprites mid-frame to display more than 8 sprites:
 ## References
 
 - HRM: *Copper* chapter — complete instruction encoding
+- **[copper_reference.md](copper_reference.md)** — Copper ISA Complete Reference Manual (full encoding, control registers, timing, register map, debugging)
 - [copper.md](../../01_hardware/ocs_a500/copper.md) — register-level reference
 - [copper.md](copper.md) — graphics.library UCopList API
 - [Video Signal & Timing](../../01_hardware/common/video_timing.md) — beam counters, scanline anatomy, clock tree