rslr/amiga-bootcamp
1
0
Fork 0
mirror of https://github.com/alfishe/amiga-bootcamp.git synced 2026-06-13 00:26:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add memory types article, expand blitter cookbook, update cross-references

Browse source 
New articles:
- 01_hardware/common/memory_types.md: comprehensive Chip/Fast/Slow RAM reference
  with DMA accessibility matrix, per-model configurations (A500-A4000),
  accelerator memory expansion (classic + modern), adaptive software behavior,
  pitfalls with impact analysis, FPGA/emulation notes
- AGENTS.md: documentation standards and methodology guidelines

Blitter programming (08_graphics/blitter_programming.md):
- Rewrote minterm truth table with narrative explanation and worked  example
- Added 7 advanced use cases with assembly/C code: shifted BOB, hardware scroll,
  area fill polygon, interleaved bitplane BOBs, double-buffered game loop,
  GUI window drag, tile map renderer
- Added Good/Bad Patterns section with 5 named antipatterns
- Added Practical Limitations table (10 constraints with workarounds)
- Expanded Common Minterms table with Description and Real-World Use Case columns

Cross-reference updates:
- Root README: added memory types to coverage, quick start, section index
- 01_hardware/README: updated common/ folder description
- address_space.md: linked to memory_types.md and chip_ram_expansion.md
- memory_management.md (exec): linked to hardware memory types reference
- bitmap.md, sprites.md, animation.md, audio.md: linked to memory_types.md
  explaining DMA Chip RAM requirement for each subsystem
- chip_ram_expansion.md: linked to comprehensive memory types article
This commit is contained in:
Ilia Sharin 2026-04-25 14:12:46 -04:00
parent 26dfed8b44
commit c4522ef2ed
12 changed files with 1609 additions and 87 deletions
Download patch file Download diff file Expand all files Collapse all files

374
AGENTS.md Normal file
View file

@ -0,0 +1,374 @@
# AGENTS.md — Technical Article Quality Standards
> **Audience**: AI coding assistants and human contributors.
> Read this before writing or expanding any `.md` file in this repository.
---
## Language & Spelling
- **American English only** — `color`, `behavior`, `initialize`, never `colour`, `behaviour`, `initialise`
- Use clear, direct technical prose — no filler, no hedging, no marketing language
- Prefer active voice: "The Blitter copies data" not "Data is copied by the Blitter"
- **Hexadecimal**: Use Motorola syntax (`$DFF180`) for hardware registers and memory addresses, not C-style (`0xDFF180`), unless explicitly within a C code block.
---
## Pre-Flight: Knowledge Base Scan (MANDATORY)
Before writing or expanding any article, you **must**:
1. **Read the root [README.md](README.md)** — it contains the full Documentation Map with every article in the repository. Understand what already exists to avoid duplicating content and to identify cross-linking opportunities.
2. **Scan the section's `README.md`** — know what sibling articles exist in the same folder. Your article should complement, not repeat, adjacent content.
3. **Search for related content** — use grep or file listing to find existing mentions of your topic across the repository. If another article already covers a subtopic in depth, link to it rather than rewriting it.
4. **Check for established patterns** — look at 2–3 exemplary articles in the repository (see "What Makes an Exemplary Article" below) to match style, depth, and structure.
> [!IMPORTANT]
> Every article must exist within the knowledge graph. Orphaned articles are unacceptable. Update the root README's Documentation Map when adding new articles.
---
## Article Structure
Every article must follow this skeleton. Omit sections that genuinely don't apply, but the **Overview** and **Navigation** are mandatory.
### 1. Navigation Breadcrumb (line 1)
```markdown
[← Home](../README.md) · [Section Name](README.md)
```
### 2. Title
Use a single `#` heading. Include the subject and a subtitle with key subtopics:
```markdown
# Memory Management — AllocMem, FreeMem, MemHeader
# Copper Programming — Deep Dive
# Animation — GEL System: BOBs, VSprites, AnimObs
```
### 3. Overview
The first section after the title. Must answer in **one dense paragraph**:
- **What** is this subsystem/API/feature?
- **Where** does it live in the system? (which library, which chip, which layer)
- **Why** does it exist? What problem does it solve?
- **Key constraints** the reader must internalize immediately
Good example:
> The Blitter (Block Image Transfer) is a DMA engine that performs raster operations on rectangular blocks of memory. It operates on up to 4 channels (A, B, C → D) using programmable minterm logic and can work independently of the CPU.
Bad example:
> This document describes the Blitter. The Blitter is used for graphics.
### 4. Architecture / How It Works
- Use **Mermaid diagrams** for system relationships, data flows, and state machines
- Show where the component sits in the overall system (chip, library, OS layer)
- Explain the **hardware backing** — which DMA engines, which custom chip registers, what bus interactions
### 5. Data Structures & Register Tables
- Show the **actual C struct** from NDK headers with inline comments
- Follow with a **field description table** for non-obvious fields
- Include the NDK source path: `/* exec/memory.h — NDK39 */`
- Annotate critical constraints inline: `/* Chip RAM only! */`
- **Hardware Registers**: Documentation must use the following table format, including the R/W (Read/Write/Strobe) capability:
```markdown
| Address | Name | R/W | Description |
|-----------|---------|-----|-------------|
| `$DFF054` | BLTCON0 | W | Blitter control register 0 (minterms, channels) |
```
### 6. API Reference
- Show function prototypes with LVO offsets: `/* LVO -198 */`
- Include practical usage snippets immediately after each prototype
- Group related functions together
### 7. Decision Guides & Comparison Tables
When multiple approaches exist, provide a **decision matrix**:
```markdown
| Criterion | Option A | Option B |
|---|---|---|
| When to use | ... | ... |
| Limitation | ... | ... |
```
### 8. Historical Context & Modern Analogies (MANDATORY for architectural topics)
This is **not optional** for any article covering a fundamental or architectural concept.
**Historical perspective:**
- Include a **competitive landscape** table comparing to contemporary platforms (Atari ST, C64, NES, Mac, PC, arcade hardware)
- Explain what made the Amiga's approach innovative (or not) relative to its era
- Provide **pros/cons analysis** in the context of 1985–1994 hardware constraints
**Modern analogies:**
- Add a **comparison table** mapping Amiga concepts to modern equivalents (macOS Core Animation, Vulkan/Metal, Unity/Unreal, etc.)
- Explain **why** the analogy holds and where it breaks down
- Help modern developers build intuition by connecting unfamiliar retro concepts to things they already know
### 9. Practical Examples
- Every article must include at least one **complete, working code example**
- Examples must compile — no pseudocode unless explicitly marked
- Show the full lifecycle: init → use → cleanup
- Annotate non-obvious lines with inline comments
### 10. When to Use / When NOT to Use
Every API or subsystem article must include explicit guidance on:
- **When to use** — the ideal scenarios, applicability ranges, sweet spots
- **When NOT to use** — situations where a different approach is better, with explanation of why
- **Applicability ranges** — quantify limits (e.g., "works well up to ~20 BOBs; beyond that, custom blitter routines outperform")
### 11. Best Practices & Antipatterns
- **Best practices**: Numbered list of actionable recommendations. Each item should be one line.
- **Antipatterns**: Common bad habits that compile but produce subtle bugs, poor performance, or system instability. Show the antipattern and the correct alternative side by side.
### 12. Pitfalls & Common Mistakes
- Use a dedicated **Pitfalls** section near the end
- Each pitfall gets a numbered subsection with:
- A **bad code example** showing the bug
- An explanation of **why** it fails
- The **correct** version
### 13. Use Cases
Provide real-world use cases that demonstrate practical application:
- What kind of software uses this feature?
- Which well-known Amiga titles or applications relied on it?
- What are the common integration patterns?
### 14. FAQ (when topic resonates)
For topics that commonly generate questions (memory management, blitter programming, display modes), include a short FAQ section addressing the most frequent developer questions.
### 15. References
- NDK header paths
- ADCD 2.1 section references
- Cross-links to related articles in this repository
- External links where authoritative (Apple docs, Commodore manuals)
---
## Formatting Standards
### Memory Maps
- When illustrating memory layouts, stack frames, or hunk structures, use **monospace ASCII box-drawing** (`┌─┐`) rather than Mermaid flowcharts. Mermaid is for logic/state; ASCII boxes are for byte-precise memory layouts.
### Reverse Engineering & Patching
When documenting reverse engineering efforts (e.g., bypassing limitations, understanding undocumented behavior):
- **Disassembly**: Use standard 68k/x86 disassembly blocks with file offsets and original hex bytes included.
- **Unified Patch Tables**: Use the exact table structure below to show offset, byte delta, instruction, and rationale:
```markdown
| File Offset | Original | Patched | Assembly | Rationale |
|-------------|-----------|-----------|------------------|-----------|
| `$0001A4` | `66 0A` | `4E 71` | `NOP` | Defeats the check |
```
- **Call Graphs**: Use Mermaid diagrams for call graphs and tables for obfuscation routines/gate mechanisms.
### Tables
- Use tables for structured comparisons, flag lists, register maps, field descriptions
- Always include a header row and separator
- Keep cells concise — one concept per cell
### Code Blocks
- Use fenced code blocks with language tags: ` ```c `, ` ```asm `, ` ```markdown `
- Include NDK source attribution in struct definitions
- Use `/* comment */` for inline annotations in C code
### Mermaid Diagrams
- Use for architecture diagrams, data flow, state machines, and system relationships
- Apply consistent styling: `fill:#e8f4fd,stroke:#2196f3` for DMA/hardware, `fill:#fff9c4,stroke:#f9a825` for coprocessors
- Keep diagrams readable — no more than ~15 nodes per diagram
### Alerts
Use GitHub-style alerts sparingly for critical information:
```markdown
> [!NOTE]
> Background context that aids understanding
> [!WARNING]
> Common mistake that causes data corruption or system crash
```
- **The Chip RAM Alert**: Any API, struct, or hardware register that requires DMA-accessible memory must be highlighted with a `> [!WARNING]` block explicitly stating **Requires Chip RAM**.
### Horizontal Rules
Use `---` to separate major sections. Don't use between subsections.
---
## Depth Expectations
### Shallow (unacceptable)
A struct dump with no context, no explanation of relationships, no examples, no pitfalls. This is a header file, not documentation.
### Adequate
Overview + struct descriptions + one example + references. Functional but not a learning resource.
### Deep (target quality)
Everything above, plus:
- Architectural diagrams showing hardware relationships
- Historical context and competitive landscape
- Modern analogies for accessibility
- Decision guides for choosing between approaches
- Multiple examples covering common and edge cases
- Comprehensive pitfalls with bad/good code pairs
- Performance analysis with quantified costs
- Cross-references to related articles
**Every article in this repository should target "Deep" quality.**
---
## What Makes an Exemplary Article — Key Differentiators
Analysis of the best articles in this repository ([exe_crunchers.md](03_loader_and_exec_format/exe_crunchers.md), [idcmp.md](09_intuition/idcmp.md), [animation.md](08_graphics/animation.md)) reveals consistent patterns that separate deep technical writing from shallow reference stubs:
### 1. The "Why It Exists" Opening
Every great article opens by answering *why* someone should care — not just what the thing is. Compare:
- ✗ *"IDCMP is a messaging system in Intuition."*
- ✓ *"Rather than polling for input, an Amiga application **sleeps** — consuming zero CPU — until Intuition sends a message. This is fundamental to why AmigaOS could multitask smoothly on a 7 MHz 68000 with 512 KB of RAM."*
### 2. Multi-Phase Architecture Diagrams
Great articles don't just describe a process — they break it into **numbered phases** with Mermaid diagrams at each stage. Example: `exe_crunchers.md` walks through 7 discrete steps of the decrunch stub, each with its own code block and explanation. This transforms opaque behavior into a debuggable mental model.
### 3. Named Antipatterns with Bad/Good Pairs
The best articles give antipatterns memorable names:
- "The Kitchen Sink" (requesting all IDCMP flags)
- "The Phantom Gadget" (dereferencing IAddress after ReplyMsg)
- "The Signal Swallower" (checking only one signal source)
Each antipattern shows the **broken code**, explains **why it breaks**, and provides the **corrected version**. This pattern is far more effective than generic warnings.
### 4. Decision Flowcharts
When multiple approaches exist, the best articles include a Mermaid decision flowchart that guides the reader to the correct choice. See IDCMP's "Use IDCMP or Exec MsgPort?" flowchart — it encodes the decision logic visually.
### 5. Use-Case Cookbooks
Beyond toy examples, exemplary articles include a **cookbook** of real-world patterns:
- Double-click detection
- Rubber-band selection
- Multi-signal event loops (IDCMP + Timer + ARexx)
- Menu multi-select chains
These are copy-paste-ready patterns that solve actual developer problems.
### 6. Quantified Performance Tables
Great articles don't just say "this is slow" — they provide concrete numbers:
- "Mouse movement at fast drag: ~500+ messages/sec — can starve other tasks"
- "3 blitter ops per BOB per frame — expensive at scale"
- "Decompression: ~2–5 seconds on a 7 MHz 68000"
### 7. Cross-Platform Comparison Tables
The best articles include a comparison table that maps Amiga concepts to their equivalents on other platforms (both contemporary and modern). This serves two purposes:
- **Historical context** — shows what was unique about the Amiga
- **Modern accessibility** — helps developers coming from Windows/macOS/Linux build intuition
See IDCMP's comparison with Win32/X11/Cocoa/Qt and animation's comparison with Atari ST/C64/NES.
### 8. Memory Safety Checklists
For any API that involves allocation, messaging, or shared resources, exemplary articles include a **risk/cause/prevention** table that acts as a pre-flight checklist.
### 9. The "Impact on FPGA/Emulation" Section
Since this repository targets MiSTer FPGA developers, the best articles note implementation concerns for hardware reproduction: timing-sensitive code, self-modifying code, custom chip register access patterns, cache coherency requirements.
### What Mediocre Articles Are Missing
Compare the above with shallow articles that typically lack:
- No "why" — just "what"
- No architecture diagrams
- No decision guides — reader doesn't know when to use the feature
- No pitfalls — reader will hit every bug the hard way
- No antipatterns — reader will write bad code that compiles
- No performance data — reader has no budget intuition
- No cross-platform context — reader can't connect to existing knowledge
- No use-case cookbook — reader can describe the API but can't solve problems with it
---
## Research Methodology
Before writing or expanding an article:
1. **Web research** — Search for real-world usage, developer forum discussions, and existing technical analyses. Ground the article in how practitioners actually used the technology, not just what the API reference says.
2. **Cross-reference NDK headers** — Verify struct layouts, flag values, and LVO offsets against the actual NDK 3.9 headers.
3. **Study real software** — Reference well-known Amiga titles, demos, and applications that use the feature. Cite specific examples when possible.
4. **Verify with hardware documentation** — Cross-check against the Amiga Hardware Reference Manual and custom chip datasheets.
5. **Check modern parallels** — Research whether the concept has modern equivalents; this improves accessibility and reveals design insights.
6. **Scan this repository first** — Follow the Pre-Flight Knowledge Base Scan procedure above before creating any new content.
---
## Content Principles
1. **Hardware grounding** — Always explain which chip, which DMA channel, which register. The Amiga is a hardware platform; software docs without hardware context are incomplete.
2. **No placeholders** — Every code example must be complete enough to compile. Every struct must show real fields from NDK headers. Every register must show the real address.
3. **API Versioning** — Always specify the minimum OS version required for an API (e.g., 'Requires OS 2.0+'). If a struct changed between versions, document the NDK 3.9 version as the modern baseline, and use the `/* V39 */` inline comments exactly as they appear in the headers.
4. **Big-Endian Warning** — Any article dealing with file formats (HUNK, IFF, ADF) or memory structures must explicitly state that the 68000 is **Big-Endian**. Modern developers will almost always read `0x1234` backwards if not reminded.
5. **Honest trade-offs** — When the OS provides an API that most professional software bypassed, say so. When a feature has scaling problems, quantify them. Don't oversell.
6. **Cross-linking** — Every article should link to at least 2–3 related articles. The documentation is a graph, not a list.
7. **Source attribution** — Cite NDK versions, ADCD sections, and ROM Kernel Reference Manual chapters. This is a technical reference, not folklore.
8. **De-abbreviation** — When introducing abbreviations (GEL, BOB, DMA, OCS), always provide the full name on first use and include a full-name column in summary tables.
9. **Real-world grounding** — Every feature must be contextualized with real use cases, applicability ranges, and honest guidance on when to use alternatives. Avoid documenting APIs in a vacuum.
---
## README Index Maintenance
When creating or significantly expanding an article:
- Update the section's `README.md` index table
- Update the root `README.md` Documentation Map if the article is new
- Index entries should be descriptive, not just the topic name:
- ✗ `AnimOb, BOB, VSprite, GEL system`
- ✓ `GEL system deep dive: BOBs, VSprites, AnimObs, hardware foundation, collision detection, double buffering, performance tuning`
---
## Commit Messages
!!!DO NOT make any commits without user asking!!!
Use conventional commit format:
```
docs(amiga): <concise description of what changed>
```
!!!DO NOT include co-authored-by trailers!!!