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
|
aminet net>