sana2loop 1.1

Hardware-free SANA-II loopback device

Short:        Hardware-free SANA-II loopback device
Author:       simond@irrelevant.org (Simon Dick)
Uploader:     simond irrelevant org (Simon Dick)
Type:         comm/net
Version:      1.1
Architecture: m68k-amigaos
Distribution: Aminet

sana2loop builds loopback.device, a hardware-free SANA-II network
device for AmigaOS: echo, crossover, and pcap replay/capture modes,
plus companion Shell tools (SanaInfo, SanaDump, SanaSend, SanaConform).
It gives any network stack, shim, or driver-consuming software a
deterministic test partner - with zero hardware and zero emulator
network support required.

(Prior art: nullsana (Aminet comm/tcp/nullsana, 2000), a binary-only
virtual SANA-II device, was found only after sana2loop's first release.
sana2loop is open source, runs on Kickstart 1.3, and adds pcap
replay/record, fault injection, and conformance tooling.)

Features
--------
  - Echo mode: a CMD_WRITE is delivered straight back to a matching queued
    CMD_READ (typed, orphan, or a bounded rxqueue), with real SANA-II
    src/dst address semantics.
  - Crossover mode: pair two units so traffic written to one is
    delivered to the other, with real unswapped addressing and
    unicast/broadcast/multicast/promiscuous receive filtering.
  - Real SANA-II buffer-management hooks (S2_CopyToBuff/CopyFromBuff/
    PacketFilter, the last genuinely dispatched per candidate delivery),
    broadcast/multicast writes and group membership, S2_ONEVENT,
    global/type/special stats, and per-unit config files (ENV:/S:
    sana2loop/unitN.config).
  - Multi-open fan-out: open a unit more than once (a stack plus a
    passive monitor, sanamon-style) and every open with a matching
    typed read gets its own independent copy, gated per-open by its own
    S2_PacketFilter if negotiated -- plus SANA2OPF_MINE exclusive-open
    enforcement.
  - Fault injection pipeline, all off by default: packet drop (percent
    or 1-in-N), duplicate, truncate, reorder, simulated link latency and
    jitter (delay=/deviation=, VBlank-tick delivery delay with optional
    symmetric scatter), forced online/offline flapping, visible TX-error
    injection (1-in-N writes fail with S2ERR_TX_FAILURE and fire
    S2EVENT_TX|ERROR - the loud failure class the silent knobs can't
    produce), and an "oversilent" PMTUD black hole - an overlong
    crossover write vanishes silently instead of erroring, so a stack's
    actual PMTUD black-hole detection/recovery can be tested, not just
    assumed - all seeded and reproducible.
  - Operator-pinned station addresses (addr=) for reproducible captures
    and topology-mimicking crossover pairs.
  - pcap replay (on-demand or real-time VBlank-scheduled) and pcap
    recording, both driven off a hand-rolled classic pcap reader/writer
    with no host dependency.
  - Wire-type emulation (wire=ethernet|slip|cslip|ppp): a unit can report
    a point-to-point serial wire with 4-byte IP-style addressing, so a
    stack's SLIP/PPP paths are testable too; plus per-unit reported link
    speed (bps=) and a minimum-write-size floor (mintu=) for catching
    missing minimum-frame padding.
  - SANA-II Rev 2/3/4/7 conformance: wider buffer-management hooks
    (S2_CopyToBuff16/32, genuinely invoked, not just accepted),
    S2_GETPEERADDRESS/S2_GETDNSADDRESS, Sana2DeviceQuery.RawMTU, and Rev 7
    DMA hook negotiation (accepted and counted, gracefully never invoked).
  - Companion Shell tools: SanaInfo (open/query/online-offline a unit),
    SanaDump (capture a unit's traffic to a pcap file, plus a live
    console packet view), SanaSend (replay a pcap file's frames onto a
    unit), SanaConform (probes a unit's SANA-II Rev 2/3/4/7 conformance
    and reports what it finds, including whether a negotiated
    S2_PacketFilter hook actually gets invoked, not just accepted). All
    four target any SANA-II driver via DEVICE=, not just loopback.device,
    with opt-in CONFIG/ONLINE for pointing at real hardware safely.
  - Targets plain 68000 and Kickstart 1.3 for the device itself - a test
    tool's value is universality, and nothing here needs more.

Requirements
------------
  - loopback.device: any Amiga, from a stock 68000 upwards, Kickstart 1.3
    (V34) or later, 2 MB RAM minimum. No utility.library, no dos.library
    calls from the unit's own I/O path.
  - SanaInfo/SanaDump/SanaSend/SanaConform: AmigaOS 2.04 (V37) or later
    (CreateMsgPort()/CreateIORequest() are V36+ Exec calls, but V36 itself
    never shipped outside early pre-release hardware, so 2.04 is the
    realistic floor). No additional libraries or archives to install.

Installation
------------
  Copy "loopback.device" to DEVS:. Copy "SanaInfo", "SanaDump", "SanaSend",
  and "SanaConform" to a directory on your PATH (e.g. C:). No reboot is
  required - a device is picked up the next time something opens it by
  name.

  If you also want a real network stack (AmiTCP, AmiTCP_NG, Roadshow) to
  find and use it, additionally copy "loopback.device" to DEVS:Networks/
  - the conventional location a stack's own network configuration expects
  a SANA-II driver in. This is a SEPARATE step, not a replacement:
  OpenDevice() only ever searches plain DEVS: for a bare device name; a
  stack's own config instead opens the full path
  (DEVS:Networks/loopback.device) itself once you point it there.

  Optional per-unit configuration lives in ENV:sana2loop/unit<N>.config
  (falling back to S:sana2loop/unit<N>.config) - see the included
  sana2loop.guide for the full key reference (mode, peer, mtu, rxqueue,
  fault-injection knobs, replay/record).

Quick start
-----------
  SanaInfo 0                          open unit 0, print DEVICEQUERY info
  SanaDump UNIT=0 FILE=capture.pcap   capture unit 0's traffic to a file
  SanaSend UNIT=0 FILE=capture.pcap   replay a pcap file's frames onto
                                       unit 0
  SanaConform 0                       probe unit 0's SANA-II Rev 2/3/4/7
                                       conformance

AI disclosure
-------------
  Be aware: sana2loop was written largely by an AI coding agent
  (Anthropic's Claude, via Claude Code), working under human direction,
  review, and on-hardware/on-emulator testing. The entire source is
  BSD-licensed and open for review.

Documentation
-------------
  The full protocol reference, per-mode configuration guide, fault
  injection cookbook, and troubleshooting notes are online at
  https://sidick.github.io/sana2loop/ and included as sana2loop.guide in
  this archive (AmigaGuide/MultiView, OS 2.x+) for offline/on-Amiga
  reading -- same source, both forms.

Source and licence
-------------------
  Free and open source, BSD 2-Clause. Full source, documentation and issue
  tracker: https://github.com/sidick/sana2loop