# HamsterOS

HamsterOS is a complete 32-bit desktop operating system that runs on a single
1.44 MB floppy disk. Minimum specification: 386 CPU, 2 MB RAM. 3 MB enables
the RAM disk and the full enhanced defaults; Sound Blaster and CD-ROM support
remain available at 2 MB. The system also installs to and boots from a hard
disk via the boot floppy's Install Or Upgrade menu.

## Project Policy

HamsterOS is a new project, not a fork of GentleOS/32.

GentleOS32Plus is useful as a reference for ideas and lessons, but HamsterOS
should use original code and its own architecture. Do not copy GPL source files
from GentleOS/32 into this tree.

The shipping boot path is a trimmed FreeDOS floppy.
FreeDOS starts `HAMLOAD.EXE`, which loads `HAMSTER.BIN`, switches to protected
mode, and hands off to the HamsterOS kernel. The desktop keeps hardware-safe
VGA `640x480x16` as its universal fallback, adds hardware-verified Cirrus
`800x600x16`, and offers RAM-gated VBE `640x480x256` and `800x600x256` modes
when the adapter supplies a usable linear or supported banked framebuffer.
Unsupported modes fall back automatically. FreeDOS is the committed long-term
boot wrapper; GRUB and Syslinux are retired and archived.

Any bootloader files distributed with HamsterOS images keep their own license
obligations separate from the original HamsterOS kernel and applications.

## Two boot paths: floppy and hard disk

- **Floppy boot (master, shipping).** `build/hamster.img` — FAT12 floppy; one
  image covers 2 MB, 3 MB, and larger systems. FreeDOS provides DOS
  compatibility, `HAMLOAD.EXE` loads the 32-bit kernel. This image also carries
  `/DOS/` programs and can quit to FreeDOS from the Special menu. DOS launches
  now load `/SYSTEM/DOSVM.APP` on demand for the VM86 DOS box, returning to
  the desktop and unloading the VM86 engine on exit;
  Programs > DOS opens a VM86 prompt with `DIR`, `CD`, `MD`, `RD`, `COPY`,
  `REN`, `CLS`, `HELP`, and `EXIT`. Unsupported programs can still fall back
  to the FreeDOS handoff.

- **Hard disk boot.** Choose **Install Or Upgrade Hamster OS** from the floppy
  boot menu, or run `A:\INSTALL\INSTALL.BAT` from FreeDOS. The boot-disk
  installer partitions and formats a blank disk when needed, copies the
  FreeDOS/Hamster payload, and runs `FDISK /MBR` plus `SYS C:` so BIOS boots
  from C: into FreeDOS -> `HAMLOAD.EXE` -> HamsterOS, with the kernel detecting
  the boot drive index passed by the loader.

### Installing HamsterOS to a hard disk

1. Back up anything important on drive C:. **Fresh Install permanently erases
   every file on C:.**
2. Boot the HamsterOS floppy and press **Esc** while the startup screen says
   “Press ESC now to enter the startup menu.”
3. Select **4. Install Or Upgrade Hamster OS**. From a FreeDOS prompt, the same
   installer can be started manually with `A:\INSTALL\INSTALL.BAT`.
4. Choose the appropriate setup mode:
   - **Fresh Install** formats C: and installs a clean, bootable HamsterOS system.
     If no usable partition exists, FreeDOS FDISK opens first. Create one Primary
     DOS Partition using the whole disk, restart with the HamsterOS floppy still
     inserted, and Setup resumes automatically.
   - **Leave Your Files Intact** does not format C: and preserves personal files
     and DOS/Windows programs, but replaces the boot system with FreeDOS and
     overwrites `CONFIG.SYS`, `FDCONFIG.SYS`, and `AUTOEXEC.BAT`.
   - **Upgrade Existing HamsterOS** refreshes HamsterOS system files, apps,
     games, tools, drivers, and resources without changing personal files or the
     disk layout.
5. Keep the floppy inserted while files are copied. When Setup reports success,
   remove the floppy and press a key to restart from C:.

Only the boot floppy offers the installation option. The installed hard-disk
startup menu intentionally contains normal, safe, command-prompt, and Enhanced
DOS choices instead.

- **Blank install target -- 20 MiB FAT hard disk.** `build/install-target-20mb.img`
  is a synthetic IDE disk image for testing the boot-disk installer
  without waiting on in-guest partitioning/formatting tools.

## Status

HamsterOS is a small but genuinely usable desktop OS. It is past the "can it
boot" stage and has a complete first-generation app suite, multi-drive storage,
Sound Blaster audio, native ISA/PCI Ethernet with shared plain HTTP/1.1
networking, and a working hard-disk install/update path.

**Boot & kernel**
- FreeDOS-backed floppy boot through `HAMLOAD.EXE` / `HAMSTER.BIN`; HD boot via
  installed C: drive with `HamNativeInfo.boot_drive_idx` handoff
- Boot drive detected by `HAMLOAD` via INT 21h fn 19h; kernel selects boot
  volume (floppy A: or ATA C:) accordingly
- A first installed boot shows a clear preparation message while compressed
  applications are expanded; later boots skip both the work and the message
- CMOS crash counter: ≥3 panics in a row forces safe-mode VGA 640×480×16 on
  next boot with a dialog; counter resets once the input loop is running
- Recoverable external-app faults: CPU faults whose instruction address is
  inside a loaded `.APP` callback quarantine and unload that app, restore the
  desktop, and show a nonfatal error. Kernel/driver faults still panic.
- I/O stall detection: main loop heartbeat; stalls > 8 s surface a nonfatal dialog
- RAM-adaptive multitasking: the 2 MB profile retains the compact cooperative
  event loop; 4 MB+ expands task/timer capacity and frame budgets; 8 MB+ enables
  Hybrid Preemptive scheduling. Only registered worker code inside an app-safe
  region may be interrupted by the timer; input, drawing, window callbacks,
  kernel/driver services, and legacy apps remain on the guarded cooperative
  path. The same app binaries run on every tier.
- PIT (Programmable Interval Timer) driver, PC speaker driver

**Desktop shell**
- Full z-order window manager with title bars, close/maximize, and resize grips
- Active window has navy blue title bar; background windows show dark gray
- Alt+Tab / Alt+Shift+Tab centered icon bar that remains visible until both
  keys are released, then activates the selected window
- Top menu bar (File / Edit / Hamster / Special) with hover-switching
- Directory-backed Programs menu with colourful application icons
- File manager windows with View by Name / View by Icon; up to 5 open at once
- File/folder drag-and-drop between File Manager windows, writable drive or
  folder icons, and Trash; same-volume drops move and cross-volume drops copy
- Mouse wheel scrolling in File Manager on PS/2 IntelliMouse-compatible hardware
- Streamed large-file copies with byte-level progress, including long-named
  ISO-9660/Joliet files copied from CD to writable VFAT volumes
- PROGRAMS is the canonical app tree; Games, Tools, User, and Startup live as
  subfolders and the Programs menu follows files moved between them
- Dynamic desktop drive icons for all mounted volumes with 3D bevel selection
- Double-click `.ZIP` files in File Manager to extract stored/Deflate contents
  into the current folder, including safe 8.3 directory creation
- Screen savers: Flying Hamsters (16-colour sprites), Stars, Text Bounce
- Desktop file icons from `(boot drive:)/DESKTOP`; positions saved to `DESKTOP.CFG`
- System recovery: per-app CPU-fault quarantine, CMOS crash counter,
  repeated-crash safe mode, and stall dialog

**Productivity apps**
- Notepad: load/save/save-as, 4-step undo, find/replace, line numbers,
  word count, go-to-line, shared text clipboard, Ctrl+Z/S/F/G/Q shortcuts,
  and paginated printing through the shared LPT1 queue
- HamsterWrite: formatted document editing, load/save, undo, find/replace,
  spelling, statistics, print preview, printer-ready file export, and direct
  paginated LPT1 printing
- HamsterSheets: formulas, formatting, row/column selection, templates,
  CSV/text interchange, and width-aware horizontal/vertical print pagination
- Help: F1 / Hamster > Help opens `HELP.HTM` in HamsterNet with local links,
  browser navigation, scrolling, and images.
- Paint: full-screen 16-colour BMP editor — pencil, fill, line, rectangle,
  ellipse, eraser, selection with cut/copy/paste, Ctrl+Z undo, and
  ordered-dither raster printing
- Image Viewer: shared image decoding, fit/zoom viewing, and scaled
  ordered-dither raster printing
- Calculator, Calendar, Analog Clock (resizable, second hand, digital readout)
- Preferences: RTC clock editor (SET TIME & DATE — H/M/S and Y/M/D spinners,
  writes directly to CMOS hardware clock via `rtc_write_datetime()`), plus
  Network settings for DHCP or manual IP/subnet/gateway/DNS, and a Disk panel
  for RAM-disk size, hard-disk caching, and FAT32 + long-filename support.
  Gameport provides live X/Y calibration and an eight-position button test;
  Printer reports LPT1 status and sends a bounded raw-text test page.
  The shared print service queues owner-tracked text and 1-bit raster jobs,
  reports progress without blocking input, supports Cancel, decodes
  offline/paper/error status, and cleans up jobs when an app closes or crashes.
- HamsterNet: local help plus plain HTTP/1.1 browsing through the shared native
  ISA/PCI Ethernet stack
- Check for Updates: Settings menu updater with current/new version display,
  installed-version ledger filtering, scrollable update lists, and hard reboot
  for kernel/driver/root boot-file updates

**Entertainment & tools**
- Piano: on-screen keyboard; SB16 uses OPL3 FM notes and a DEMO song; falls
  back to PC speaker square-wave tones
- Audio Player: WAV, MP3, VOC, raw PCM, MOD, and MIDI playback with
  play/pause/stop/restart and seeking
- CD Audio Player: Red Book audio with track listing and time display
- FreeCell, Video Poker (Jacks or Better), Minesweeper, Snake, Sliding Puzzle,
  Moon Lander, Slot Machine
- HCommand on Hamster Extras: illustrated full-screen real-time strategy with
  solo AI, local LAN, HamNet matchmaking, three maps, construction, production,
  harvesting, repair/sell commands, fog of war, and synchronized play
- Find tool: recursive filename search across all mounted drives

**Storage & disk utilities**
- A: floppy (FAT12); B: optional floppy (CMOS auto-detect); R: RAM disk (≥3 MB)
- C: onward: discovered ATA, SCSI, PicoMEM, and USB FAT volumes in mount order;
  an HD boot keeps its boot partition at C:
- VFAT long filenames (up to 63 displayed/created characters) on FAT12/16/32
  when enabled; FAT32 + long names default off at 2 MB and on at 3 MB+
- Up to 2 optical volumes use the next free letters after mounted disks and
  support ISO-9660/Joliet data plus Red Book audio
- Disk Copier: sector-exact floppy copy (A:B:, B:A:, A:A: single-drive)
- Format Tool: quick FAT12 format of A: or B: with custom volume label
- Boot-disk installer: full HD install — FreeDOS partitions and formats blank
  disks, copies FreeDOS + Hamster payload, and finalizes C: with FDISK/SYS

**Sound**
- Sound Blaster DSP-compatible audio: auto-detects common family bases
  (0x220/0x230/0x240/0x250/0x260/0x280), including a CT1680/SB Pro 2 moved between its
  supported 0x220 and 0x240 settings. Pre-SB16 cards retain the compatible
  IRQ5/DMA1 defaults because their jumper-selected IRQ/DMA cannot be read safely.
  SB16-class cards also report and use IRQ2/9, IRQ5, IRQ7, or IRQ10 and
  8-bit DMA0, DMA1, or DMA3 from their mixer resource registers.
- Standalone AdLib/OPL2 at 0x388 is detected as an FM-only fallback when no
  Sound Blaster DSP is present; it never claims an IRQ or DMA channel.
- PicoMEM/PicoMEM 2 is officially supported through `PICOMEM.DRV`. It safely
  detects the control interface, preserves an existing Sound
  Blaster, or enables the PicoMEM SB at 0x240/IRQ5/DMA1 before the generic
  audio driver probes it. PicoMEM 2 requires matching physical IRQ5 and DMA1
  jumpers for native protected-mode WAV playback; CMS at 0x220 remains a
  separate Game Blaster-compatible synthesizer. Early PicoMEM fixed-disk boot
  support keeps the 256 MB BIOS image available as C: in protected
  mode; HAMLOAD asks the option ROM for its exact legacy/current shared-memory
  layout, `PICOMEM.DRV` supplies sectors, and HamsterOS handles the FAT volume.
  The image is not treated as removable media, and normal ATA/IDE remains the
  preferred primary-disk path.
- Startup chime and notification doot; volume slider in header bar
- PC speaker fallback with Beep/Tone/None modes

**Networking**
- Card-independent `NETCORE.DRV` supplies ARP, DHCP/manual configuration, DNS,
  TCP, resilient downloads, and HTTP/1.1 to HamsterNet and Update.app.
- `NE2000.DRV` checks the common fixed ISA bases 0x300, 0x320, 0x340, 0x360,
  0x380, and 0x280. Each address must pass a passive DP8390/RTL8019 plausibility
  gate before the driver performs its reset and PROM validation. PROM layout
  selects byte-wide or word-wide Remote DMA automatically, covering PicoMEM's
  8-bit adapter as well as ordinary 16-bit NE2000 cards.
- If no NE2000-compatible adapter validates, the network loader moves on to
  `3C509.DRV` for a 3Com EtherLink III. This detects already configured hardware;
  HamsterOS does not reassign ISA resources.
- Update channel target: plain HTTP S3 website manifest at
  `http://updates.meanhamster.com/hamsteros/updates/manifest.txt`
  once the bucket public-read policy is enabled

**Drivers**
- Floppy (A: and B:); ATA/IDE (all 4 positions); ATAPI CD-ROM; PicoMEM fixed
  disk; NCR53C400, Adaptec AHA-154x, and IBM Micro Channel SCSI
- WCH CH375B ISA USB storage; PCI UHCI USB boot mouse/keyboard; PS/2 and serial
  mice; keyboard; RTC; serial/debug; VGA/Cirrus/VBE; PC speaker; PIT
- BIOS-detected analog gameport joystick at 0x201 and basic LPT1 raw-text
  printer output, both with dedicated Control Panel test pages
- Sound Blaster/CT1680; AdLib/OPL2; PicoMEM/PicoMEM 2 storage/audio initializer
- RTL8100C/RTL8139 PCI Ethernet, NE2000/RTL8019AS and 3Com 3C509 ISA Ethernet,
  plus the shared `NETCORE.DRV` protocol layer

## Building And Running

On Windows, use the batch files from the repository root:

- `hamster.bat` rebuilds `build\hamster.img`
- `run-hamster.bat` immediately runs the existing `build\hamster.img` in QEMU
- `run-hamster-2mb.bat` runs that same master image with a 2 MB QEMU machine
- `run-hamster-install.bat` boots the floppy with a blank 20 MiB IDE disk
  attached as C: for boot-disk installer testing

The old macOS `.command` runners are retired from the current tree.

## Building

The toolchain lives in the Docker builder image. Keep the private HamNet
repository beside HamsterOS; HamsterOS mounts and compiles the canonical
HamsterOS client directly from that checkout:

```
E:\MHS-Repository\HamsterOS
E:\MHS-Repository\HamNet
```

```
docker compose run --rm builder make          # compile build/compiled_elfs/hamster.elf
docker compose run --rm builder make floppy   # build hamster.img
docker compose run --rm builder make install-target  # build blank 20 MiB test C: disk
docker compose run --rm builder make extras-package  # build storefront ZIP + SHA-256
docker compose run --rm builder make run      # build and boot in QEMU
docker compose run --rm builder make install-test-run  # boot floppy with blank IDE C:
docker compose run --rm builder make boot-check  # headless 12s serial smoke test
```

Python 3 + Pillow are available natively for quick asset iteration
(`tools/mkasset.py`, `tools/mkicon.py`, `tools/mkfreedosfloppy.py`, etc.)
without Docker.

HamNet and HamChat compile their shared protocol code directly from the
adjacent HamNet checkout. See `docs/HAMNET_INTEGRATION.md` for ownership and
release-revision rules.

## Current Focus

See `docs/ROADMAP.md` for the current project record. Current top priorities:

- Real-hardware validation for VBE 256-colour modes on additional adapters;
  Tandy/Cirrus `800x600x16` is already verified and stable
- Real-hardware APM power-off and Adaptec AHA-154x SCSI I/O validation
- Per-program DOS-session policies for mouse capture, joystick reporting,
  current directories, sound ownership, and video ownership
- Native `hamboot` loader diagnostics and real-486 validation
