usb

type CtrlExchange struct {
	In        bool
	BRequest  uint8
	WValue    uint16
	WIndex    uint16
	Data      []byte // expected for OUT, ignored for IN
	Reply     []byte // returned for IN, ignored for OUT
	Err       error  // returned instead of completing the transfer
	N         int    // expected `n` for IN (0 = don't check)
	TimeoutOK bool   // when true, ignore the SUT's timeout arg
}

type Descriptor struct {
	Bus          uint8  // USB bus number
	Address      uint8  // device address on the bus
	VID, PID     uint16 // vendor / product ID
	Serial       string // iSerialNumber, may be empty
	Manufacturer string // iManufacturer, may be empty
	Product      string // iProduct, may be empty
	// Path is the implementation-defined locator (e.g. /dev/bus/usb/001/007
	// on Linux). Treat as opaque; pass back to [Enumerator.Open] verbatim.
	Path string
}

type Enumerator interface {
	// Name identifies the backend (e.g. "usbdevfs", "winusb", "iokit",
	// "mock"). Used in error messages and logs.
	Name() string

	// List returns every device that matches both vid and pid. A zero
	// value for either acts as a wildcard.
	List(vid, pid uint16) ([]Descriptor, error)

	// Open claims a device identified by a Descriptor previously
	// returned from List.
	Open(d Descriptor) (Transport, error)
}

type MockEnumerator struct {
	BackendName string       // override "mock" if set
	Devices     []Descriptor // returned by List, filtered by vid/pid
	OpenFunc    func(Descriptor) (*MockTransport, error)
}

type MockTransport struct {
	Script        []CtrlExchange
	Step          int
	Err           error
	ClaimedIfaces map[int]bool
	Closed        bool

	// ResetCalls counts invocations of Reset; tests use it to assert
	// the USBDEVFS_RESET recovery path ran. ClaimCalls counts
	// successful ClaimInterface invocations across all interfaces, so
	// tests can verify post-reset re-claim happened.
	ResetCalls int
	ClaimCalls int

	// ClaimErr, when non-nil, is returned by ClaimInterface instead of
	// succeeding — lets tests exercise the driver's claim-failure path
	// (e.g. an EBUSY that survives kernel-driver auto-detach).
	ClaimErr error

	BulkPackets  [][]byte
	BulkInterval time.Duration
	// BulkSimulateDeath, when true, makes the bulk-IN goroutine fire
	// onStreamDead (with BulkDeathErr, or ErrDeviceGone if nil) after
	// dispatching all BulkPackets instead of blocking on StopBulkIn.
	// Tests use it to assert drivers close their consumer channel when
	// the USB reaper dies unexpectedly (issue #345).
	BulkSimulateDeath bool
	BulkDeathErr      error
	// contains filtered or unexported fields
}

type Transport interface {
	// ControlIn issues a vendor-IN control transfer and returns up to n
	// bytes of response. The returned slice's length equals the number
	// of bytes the device actually delivered (≤ n).
	ControlIn(bRequest uint8, wValue, wIndex uint16, n int, timeoutMs int) ([]byte, error)

	// ControlOut issues a vendor-OUT control transfer.
	ControlOut(bRequest uint8, wValue, wIndex uint16, data []byte, timeoutMs int) error

	// ClaimInterface tells the kernel/driver that this transport owns
	// the given USB interface number. Must be called before any I/O.
	ClaimInterface(num int) error

	// ReleaseInterface relinquishes the interface; the device stays
	// open. Idempotent; calling on an unclaimed interface returns nil.
	ReleaseInterface(num int) error

	// StartBulkIn submits a ring of `ringBufs` bulk-IN URBs of `bufLen`
	// bytes each on endpoint epAddr (e.g. 0x81 for RTL-SDR's IQ stream).
	// onPacket is invoked from a dedicated reaper goroutine each time a
	// URB completes; the slice passed to it is owned by the transport
	// and reused once onPacket returns — callers must copy any bytes
	// they wish to retain.
	//
	// onStreamDead, when non-nil, is invoked exactly once when every URB
	// has died of an unrecoverable USB error (host controller hang,
	// ENODEV, EPROTO storm under load, ...) — i.e. the stream ended
	// **without** StopBulkIn being called. Implementations must not
	// invoke it on the normal StopBulkIn path, and must dispatch the
	// callback from a fresh goroutine — never from the reaper itself,
	// because the callback typically calls StopBulkIn (to close the
	// driver's consumer channel) and StopBulkIn waits for the reaper to
	// exit. Drivers use this hook to surface "stream died" to their IQ
	// consumer; without it, a silent reaper exit leaves the consumer
	// blocked forever (issue #345).
	StartBulkIn(epAddr byte, ringBufs, bufLen int, onPacket func([]byte), onStreamDead func(error)) error

	// StopBulkIn cancels every in-flight URB, drains the reaper, and
	// returns once the goroutine has exited. Safe to call concurrently
	// with reaper execution; idempotent.
	StopBulkIn() error

	// Reset performs a USB port reset. The device re-enumerates with
	// the same address (best effort) but configuration is lost.
	Reset() error

	// Close releases the device handle. Implies StopBulkIn and
	// ReleaseInterface for any still-held interfaces.
	Close() error
}