devsoak.readme

Short:        Destructive trackdisk driver soak tester
Author:       simond@irrelevant.org (Simon Dick)
Uploader:     simond@irrelevant.org (Simon Dick)
Type:         dev/misc
Version:      1.0
Architecture: m68k-amigaos >= 1.3
Requires:     68000

*** WARNING: THIS IS A DESTRUCTIVE TESTING TOOL ***

devsoak deliberately overwrites every sector in the range you point it at,
issues edge-case and malformed commands, and drives a driver to its
limits for hours at a time. It is built for developers and testers who
understand block device internals and have deliberately chosen a sector
range, partition, or whole device they do not mind losing. Point it at
the wrong unit number and it WILL destroy live data - there is no
confirmation beyond the -y flag you pass it yourself, and no undo.

If you are not comfortable identifying your target device's unit number
with certainty, back up first, or do not run this tool.

devsoak is a destructive correctness and soak tester for trackdisk-style
AmigaOS block device drivers. One run answers two questions: does every
command the driver accepts do the right thing - including the edge cases
(bounds, alignment, zero length, the 64-bit offset high word, stale ETD
change counts, unsupported commands) - and does it keep doing the right
thing for hours while several tasks issue overlapping reads, writes and
housekeeping commands with multiple requests in flight.

devsoak works a fixed sector range so it can hold per-sector state and
prove *content* correctness under sustained concurrent load, not just
whether a driver accepts a command. It complements devtest
(https://github.com/cdhooper/amiga_devtest), which probes acceptance and
sweeps whole devices.

This release ships:

  devsoak         - the tester, a single static binary
  devsoak.quirks  - the seed quirks file (known driver-specific behaviour
                     to skip, expect, or pin rather than treat as a bug -
                     see README.md's Quirks section); devsoak looks for
                     this file beside its own binary

Requirements
------------
  - AmigaOS, Kickstart 1.3 or later, or AROS m68k, 68000 or better.
    devsoak probes the driver under test at startup and exercises
    whichever command dialects (CMD/ETD/TD64/NSD/NSD-ETD) it actually
    advertises - so a 1.3-era driver simply advertises fewer dialects
    itself, rather than devsoak testing less on 1.3.
  - A block device to test, and a sector range on it you do not need.

Quick start
-----------
  devsoak scsi.device 0 -d -r 0,8M -t 30s -y
  devsoak lide.device 0 -d -r 0,64M -w 4 -q 4 -t 8h -A 15 -y

See https://sidick.github.io/devsoak/ for the full CLI reference, the
quirks-file format, and the fingerprinting workflow.

AI disclosure
-------------
  devsoak is written largely by an AI coding agent (Anthropic's Claude /
  Claude Code), under human direction, review and emulator/on-hardware
  testing. Full source is open (BSD 2-Clause) for review.

Documentation, source and licence
---------------------------------
  Free and open source, BSD 2-Clause. Full documentation (versioned per
  release), source and issue tracker:
      https://sidick.github.io/devsoak/
      https://github.com/sidick/devsoak