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
19 commits 1 branch 0 tags 2.4 MiB
Commit graph

19 commits

This branch
This branch
All branches
Author SHA1 Message Date
Ilia Sharin
c4522ef2ed Add memory types article, expand blitter cookbook, update cross-references 
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
 2026-04-25 14:12:46 -04:00
Ilia Sharin
26dfed8b44 docs(amiga): fix Quartz Composer typo and add hyperlink 2026-04-24 16:19:47 -04:00
Ilia Sharin
ea2869b8b9 docs(amiga): expand animation guide with GEL architecture, hardware foundation, and historical context 2026-04-24 16:16:21 -04:00
Ilia Sharin
f61c26b542 Expand documentation suite: 30+ articles enriched with diagrams, code examples, and hardware details 
Graphics: text_fonts (bitmap layout, styles), sprites (DMA, multiplexing), gfx_base (chipset detection), rastport (draw modes, clipping), ham_ehb (mermaid fixes), display_modes (HAM palettes)

Devices: scsi (per-model interfaces, Gayle limits, CD-ROM, native vs vendor drivers), console (ANSI sequences, CON:/RAW:), parallel (CIA registers, pinout), timer (resource exhaustion), gameport (quadrature, XOR state)

Libraries: workbench (WBStartup, AppWindow/Icon/MenuItem), rexxsyslib (ARexx port hosting, command parsing), diskfont (font directory, colour fonts), keymap (rawkey codes, dead keys), locale (catalogue system, date formatting), layers (ClipRect, refresh types), utility (TagItem chains), icon (DiskObject, ToolTypes), iffparse (IFF structure, ByteRun1), expansion (Zorro AutoConfig)

Networking: tcp_ip_stacks (major rewrite - Amiga vs Unix architecture, SANA-II pipeline, PPP/SLIP dial-up, Ethernet cards, MiSTer), bsdsocket (pure API ref), sana2 (buffer hooks, driver requirements), protocols (all code examples). Deduplicated overlap between the three files.

Toolchain: debugging (Enforcer patterns, SnoopDOS, GDB remote, kprintf checklist), sasc (pragma encoding, __saveds idioms), stormc (NEW - StormC IDE, C++, PowerPC)

References: error_codes (DOS, Exec, trackdisk, Intuition error tables)
Driver development: rtg_driver (Native driver analysis, P96 tuning)

All 22 README indexes updated. Root README synced with stormc.md entry.
 2026-04-23 21:37:26 -04:00
Ilia Sharin
0ded078134 Phase 1 continued: serial, input devices + README indexes 
10_devices:
- serial.md: expanded with DB-25 pinout, custom chip UART registers,
  baud rate calculation table, open/configure/read/write patterns,
  serial debugging (KPrintF/Sushi)
- input.md: expanded with handler chain architecture diagram,
  InputEvent struct, event classes table, qualifier bits, custom
  handler with key remapping, event consumption/blocking,
  synthetic event injection, Commodities Exchange

Updated indexes:
- 07_dos/README.md — enriched descriptions for all files
- 10_devices/README.md — enriched descriptions for all files
 2026-04-23 20:28:03 -04:00
Ilia Sharin
da9e7d3b63 Phase 1: enrich 07_dos and 10_devices (highest FPGA priority) 
07_dos:
- file_io.md: 108→240+ lines — buffered I/O (FRead/FWrite/SetVBuf),
  access mode comparison, FileHandle struct with offsets, standard
  handles, Printf %ld warning, FileInfoBlock, practical patterns
  (copy file, get size, load to RAM), error code table
- filesystem.md: 91→270+ lines — full disk geometry (ADF/HDF),
  all 8 DOS\x filesystem IDs, root block byte-level layout, file
  header layout with reverse-order pointer quirk, OFS vs FFS data
  blocks with efficiency numbers, bitmap blocks, extension blocks,
  checksum algorithm, Python ADF reader
- locks_examine.md: 113→270+ lines — lock semantics diagram, FileLock
  struct with handler discovery, ExAll bulk scan, practical patterns
  (atomic write, path resolution, volume info), 4 antipatterns
  (leaked locks, exclusive too long, unchecked IoErr, DupLock),
  pattern matching

10_devices:
- audio.md: 73→240+ lines — hardware architecture diagram, channel
  registers with offsets, period/frequency table, priority allocation,
  double-buffering, audio interrupts, AM/PM modulation, direct HW
- timer.md: 80→230+ lines — CIA timer hardware, all 5 units with
  decision flowchart, non-blocking delays, signal-based waiting,
  time arithmetic, ReadEClock, periodic game loop pattern, pitfalls
- trackdisk.md: 82→210+ lines — MFM encoding, track format, disk
  geometry, read/write/motor, change notification, track caching,
  direct hardware access, FPGA timing implications
- keyboard.md: 58→220+ lines — CIA-A serial handshake protocol with
  sequence diagram, bit rotation quirk, complete key code map,
  key matrix bitmap, reset sequence, FPGA notes
 2026-04-23 20:23:50 -04:00
Ilia Sharin
aeaea88d75 03/exe_crunchers: expand architecture with full decrunch lifecycle 
Replaced the brief 'key insight' paragraph with a comprehensive
two-phase execution model covering:
- Phase 1 (OS): what LoadSeg sees, how wrapper relocations are applied
- Phase 2 (stub): all 6 reconstruction steps with code examples:
  1. Metadata block preserving original hunk count/sizes/memflags
  2. Chip vs Fast RAM allocation (with IMPORTANT warning about
     DMA-invisible Fast RAM for bitmap/audio data)
  3. Decompression into separately allocated hunks
  4. Relocation regeneration from embedded tables
  5. BPTR segment chain construction (with C code)
  6. Wrapper cleanup and JMP to original entry
- The segment list handoff problem (double-free hazard) and the
  three solutions: pr_SegList patching, chain linking, in-place
 2026-04-23 18:50:46 -04:00
Ilia Sharin
4593ff135a 03: new article — exe_crunchers.md (executable packers deep dive) 
New comprehensive article on Amiga executable crunchers covering:
- Architecture: how crunched files remain valid HUNK executables
- Major crunchers: PowerPacker, Imploder, Shrinkler, ByteKiller,
  Titanics, CrunchMania, PackFire, XPK framework
- PP20 format: efficiency table, decrunch info, decrunch colours
- Shrinkler internals: 1536-context adaptive probability model,
  range coder, parity context flag, stack-based context table,
  actual 68000 decompressor source from GitHub
- LZ77/LZSS vs context-modelling+range-coding algorithms
- Relocation handling: 3 strategies (compressed relocs, delta
  table, merged single-hunk)
- Memory layout diagrams: before/during/after decompression
- Detection: magic signatures table, fake header warning,
  Python scanner script
- Tools: xfdmaster modular architecture, Ancient C++ library,
  debugger-based extraction (last resort)
- FPGA/emulation impact: timing, self-modifying code, cache

Based on web research: verified PP20 format spec, Shrinkler
source (askeksa/Shrinkler), Ancient library (temisu/ancient),
xfdmaster slave module architecture.

Updated indexes: 03/README.md, root README.md
 2026-04-23 18:41:07 -04:00
Ilia Sharin
7df1f11f15 03/04: deep enrichment of loader/exec format and linking/libraries 
Sections 03 and 04 augmented to bootcamp quality with targeted
enrichment based on content analysis (not just file size).

03_loader_and_exec_format:
- overlay_system.md: full rewrite — tree architecture diagram,
  HUNK_OVERLAY binary format, overlay manager runtime internals,
  worked binary example, linker support, modern alternatives
- hunk_relocation.md: full rewrite — visual before/after diagram,
  patching algorithm with code, RELOC32SHORT and DREL32 formats,
  PC-relative impact comparison table, self-referencing relocs,
  error scenarios, Python reloc scanner tool

04_linking_and_libraries:
- library_structure.md: full rewrite — ASCII memory layout diagram,
  JMP table encoding (why 6 bytes), MakeLibrary internals with both
  function array formats, complete library creation example with
  .fd file, checksum verification, lifecycle state diagram
- shared_libraries_runtime.md: full rewrite — OpenLibrary 4-step
  resolution path, ramlib disk loader internals, disk search path,
  version negotiation table (v33-v47), CloseLibrary/Expunge deep
  dive, memory-low sweep, common pitfalls table
- register_conventions.md: full rewrite — FPU register map,
  inter-library A6 save/restore pattern, small-data model with
  __saveds keyword, varargs/TagItem pattern deep dive,
  stack-based wrapper explanation, disassembly identification

Updated indexes:
- 03_loader_and_exec_format/README.md
- 04_linking_and_libraries/README.md
- Root README.md (sections 03 and 04)
 2026-04-23 18:30:45 -04:00
Ilia Sharin
99a6d53f57 boot_sequence: enrich all articles + new kickstart_rom.md 
New: kickstart_rom.md (ROM structure, module inventory, tools, custom ROMs)
Enriched: cold_boot (diagnostics, LED codes, troubleshooting),
kickstart_init (ExecBase creation, ROM scan, 4-phase init),
dos_boot (strap, boot block, Startup-Sequence), early_startup (recovery)
Updated: 02_boot_sequence/README.md, root README.md
 2026-04-23 18:12:45 -04:00
Ilia Sharin
59929047d4 exec_os: enrich all stubs to bootcamp-quality reference articles 
Complete rewrite of 14 exec_os articles from stubs to comprehensive
deep-dive technical references with architecture diagrams, pitfalls,
and best practices.

New: multitasking.md (scheduler, IPC, memory safety, real-world scenarios)
Enriched: exec_base, tasks_processes, library_system, library_vectors,
interrupts, exceptions_traps, memory_management, message_ports, signals,
semaphores, io_requests, lists_nodes, resident_modules

Updated indexes: 06_exec_os/README.md, root README.md
 2026-04-23 17:55:31 -04:00
Ilia Sharin
4d136b0672 doc: Intuition bootcamp — comprehensive enrichment of all subsystem articles 
Transformed 8 stub articles (720 lines total) into full bootcamp-grade
references (5,100+ lines) with architecture diagrams, complete code
examples, struct field references, pitfalls, and best practices.

IDCMP (idcmp.md — 1,060 lines):
- IntuiMessage field reference with types, sizes, value ranges
- Use-case cookbook: double-click, rubber-band, multi-signal, BOOPSI
- When to use IDCMP vs alternatives (decision flowchart)
- 5 named antipatterns with WRONG/RIGHT code
- Memory safety checklist and defensive event loop template
- Cross-platform comparison table (Win32, X11, Cocoa, Qt)

Input Events (input_events.md — 850 lines):
- Event class routing and QoS analysis (priority-as-QoS hierarchy)
- Intuition consumption table (what survives the handler chain)
- lowlevel.library bypass for CD32/game input
- Latency analysis with pipeline timing budget (68000 vs 68040)
- Input strategy comparison (IDCMP vs handler vs direct hardware)
- Game input patterns: direct HW polling, CIA keyboard, hybrid handler
- Signal pattern for proper handler→application communication

Windows (windows.md — 370 lines):
- Window anatomy diagram, WA_ tag reference tables
- Refresh modes comparison (Simple/Smart/SuperBitMap)
- Window types: standard, backdrop, borderless, GimmeZeroZero
- Coordinate system, border offsets, struct Window fields
- Modification API (move, resize, title, busy pointer)

Gadgets (gadgets.md — 403 lines):
- Three-generation evolution (raw/GadTools/BOOPSI)
- Complete GadTools lifecycle with setup, creation, events, cleanup
- Runtime state updates (GadTools vs raw Intuition)
- Raw struct Gadget: GFLG_*, GACT_*, GTYP_* flag tables
- Proportional and string gadget internals

BOOPSI (boopsi.md — 505 lines):
- Class hierarchy Mermaid diagram
- Method dispatch sequence diagram
- ICA interconnection architecture (icclass, modelclass, ICTARGET_IDCMP)
- Full custom gadget class tutorial (4 steps with complete code)
- Built-in class reference table
- C++/Qt analog comparison table

Menus (menus.md — 378 lines):
- Menu hierarchy diagram (Menu → Item → Sub-Item)
- GadTools NewMenu workflow with field reference
- Event handling with multi-select chain walking
- Checkmark/mutual exclusion, sub-menus, dynamic modification
- Keyboard shortcut system (single-char and NM_COMMANDSTRING)

Requesters (requesters.md — 370 lines):
- EasyRequest return value logic table
- ASL file requester with multi-select and full tag reference
- ASL font and screenmode requesters
- Non-blocking BuildEasyRequest/SysReqHandler pattern
- Requester state persistence

IntuitionBase (intuition_base.md — 267 lines):
- Library version table (OS 1.2 through 3.2.x)
- Struct field reference with safety annotations
- ViewLord architecture diagram
- LockIBase vs Forbid/Permit guidance
- Complete library function overview (5 categories)

README index updated with enriched article descriptions.
 2026-04-23 17:29:18 -04:00
Ilia Sharin
a01d9be2bd doc: Intuition Screens — comprehensive rewrite with Copper mechanics, input routing, hazards 
- Copper connection: how the coprocessor enables multi-resolution screen
  coexistence via scanline-synchronized register switching, with cross-links
  to Copper articles (08_graphics, 01_hardware)
- Display modes: OCS/ECS/AGA/RTG chipset generations, native resolution
  table (PAL/NTSC × LoRes/HiRes/SuperHires × interlaced), special modes
  (HAM, HAM-8, EHB), Display ID system, RTG with CyberGraphX/Picasso96
- Screen dragging: Copper WAIT coordinate manipulation, keyboard shortcuts,
  real-world usage patterns (Workbench+game, productivity multi-screen,
  video production, public screen sharing)
- Input event routing: input.device handler chain, Intuition consumption
  model, IDCMP flag reference table, event behavior during screen drag,
  Left-Amiga vs Right-Amiga shortcut convention, cross-screen routing
- Pitfalls: CloseScreen deadlock, IDCMP message leak, layer lock deadlock,
  screen pointer invalidation, interlace flicker, MOUSEMOVE flooding,
  hardcoded Display IDs — all with WRONG/RIGHT code examples
- Expanded best practices (10 items), SA_ tag reference, overscan modes,
  public screen lifecycle, DrawInfo querying, BestModeID() usage
 2026-04-23 16:59:14 -04:00
Ilia Sharin
94a3ad1614 doc: MUI framework documentation — whitepaper overview, SDK-derived architecture, layout mockups 
- README.md: comprehensive whitepaper-style overview with historical context,
  paradigm shift analysis, BOOPSI comparison, version history (Stefan Stuntz
  as sole author 1.0-3.8), licensing model breakdown, parallel evolution
  timeline (NeXTSTEP/Qt/MUI convergence), community-sourced developer values
- 02-architecture.md: complete rewrite from MUI 3.8 SDK sources — object
  lifecycle state machine, three-level resource binding, method dispatch chain,
  notification system with sequence diagrams, layout engine internals
  (3-pass constraint system), input handling, dynamic object linking,
  rendering model, tag ID namespace
- 05-layout-system.md: Mermaid visual mockups for VGroup, HGroup, nested
  groups, column grids, scrollgroups, file requester real-world example,
  layout algorithm and resize sequence diagrams
- frameworks/README.md: framework index with comparison table
- All content in American English
 2026-04-23 16:46:58 -04:00
Ilia Sharin
c79d5e8459 docs(amiga): expand Intuition architecture and math libraries 
09_intuition/README.md:
- Add system architecture diagram (Intuition ↔ graphics ↔ input ↔ hardware)
- Add keypress-to-application sequence diagram
- Add screen/window/gadget hierarchy with ownership rules
- Add IDCMP event system diagram and class reference table
- Add library interaction call graph
- Add screen display pipeline (Copper compositing)
- Add GadTools vs BOOPSI comparison
- Add refresh modes table and event loop examples

11_libraries/mathffp.md:
- Comprehensive rewrite covering all three numeric formats (FFP/IEEE SP/DP)
- Add developer decision flowchart for library selection
- Add FPU detection and transparent acceleration sequence diagram
- Add 68040/68060 CPU support layer (FPSP, Line-F trapping)
- Add CPU flavour table (full vs LC vs EC variants)
- Document third-party replacements: HSMathLibs, Mu680x0Libs, SoftIEEE, MuRedox
- Add complete function reference (basic + transcendental + conversion)
- Add compiler integration (SAS/C, GCC, vbcc)
- Fix diagram colors for readability
 2026-04-23 13:22:40 -04:00
Ilia Sharin
fca930d0db docs(amiga): make cross-references clickable markdown links 
Convert bare .md path references in 29 files to proper [name](relative/path)
markdown links for GitHub navigation.
 2026-04-23 12:24:21 -04:00
Ilia Sharin
551ebda2b1
Update README.md 2026-04-23 12:18:25 -04:00
Ilia Sharin
21751c0025 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.
 2026-04-23 12:17:35 -04:00
Ilia Sharin
f07a368bf1
Initial commit 2026-04-23 11:47:54 -04:00