UnapiNet bridge protocol v2

Status: implemented — this is the reference. This document was agreed as a proposal before it turned into code; what follows is the protocol the device and the driver (unapinet.com, Z80) actually speak, and the golden-byte tests pin every reply struct's layout to it. As promised while it was under review, the v1 document it replaces is folded in below as a historical appendix — still the byte-level reference for the parameter-block layouts, which v2 keeps. Functional testing added one clause the proposal had left unstated: UDP_OPEN falls back to an ephemeral port when the host refuses the requested one (see UDP below).

The driver and this device ship from the same source project and are updated together. v1 has four users, all personally reachable; there is no installed base to migrate. v2 is therefore a clean break, with detection designed so that any old/new mismatch fails cleanly at installation time (analysis, and one caveat, under "Migration and failure analysis" below).

Design rules

v1's problems are catalogued at the end of the v1 appendix; they reduce to one sentence: every command grew its own conventions. v2 replaces them with four rules:

1. Every reply begins with a status byte. 0x00 = success. Any other value is the MSX-UNAPI TCP/IP error code the driver should hand to its caller, verbatim. The device speaks UNAPI error codes natively; the driver stops translating.
2. An error reply is exactly one byte — the status. No partial payloads: if the status is non-zero, there is nothing else to read.
3. Parameter blocks are validated for exact size. Too short, too long, or inconsistent with a declared payload length → ERR_INV_PARAM, and the command has no effect.
4. No valid status byte is 0xFF. Reading the data port past the end of a reply (or with no reply pending) returns 0xFF — the same value an absent device yields from the bus pull-ups, and never a valid status (success is 0x00, and no UNAPI error code is 0xFF). A driver reading a status position and seeing 0xFF knows it is desynchronized or talking to nothing — never "OK". (v1 returned 0x00 there, which is indistinguishable from success — Wouter's observation.) Bytes inside a reply are length-delimited and unconstrained: an IP octet, a payload byte or the DNS failed-lookup marker may legitimately be 0xFF.

Error codes on the wire

The status byte uses the MSX-UNAPI TCP/IP error space. The device emits this subset (the values match the error table the driver already defines; the device side is what v2 added):

Rule 3 applies to every opcode, parameterless ones included: a malformed or stray parameter block answers {4} regardless of the command, and the per-command "err" lists below do not repeat that. Where a list names 4 explicitly, a well-formed block can still be semantically invalid there. One check precedes rule 3: opcode dispatch — an unknown opcode answers {1} whether or not stray parameter bytes accompany it (there is no expected size to validate against). In both cases the parameter buffer is cleared, as after every command.

Validation order is fixed: form first (rule 3, {4}, together with the semantic {4}s — an invalid value inside a well-formed block); then capability ({1}, the ICMP commands); then handle ({11}); then connection state ({12}, and DNS's busy {5}); then the data check ({3}, the RECV queues). The host operation runs last, so its errors ({2}, {13} — plus the TCP write-failure {12}, the one post-operation use of that code) imply every earlier check passed. In the OPEN commands the free-slot check ({9}) precedes the host socket work ({2}).

The status register is gone — the command port is write-only

The driver's only use of the v1 status register is "did my command produce a result?" — with rule 1 that information is the reply's first byte, so the register is redundant as a mechanism, and v2 removes it entirely rather than keeping a mirror nobody needs (Wouter's suggestion). The device registers the command port for writes only; reading it decodes to the open bus (0xFF on a standard MSX), exactly as if no device were present. The status byte lives in one place — the reply — so there is nothing to poll, nothing that can disagree with it, and nothing extra to document. The three v1 situations that raised STATUS_ERROR in the register become ordinary single-byte error replies (unknown opcode → 1, empty hostname → 4, DNS busy → 5).

What does not change — and two things that do

Unchanged from v1: ports and decoding (base 0x28: command, base+1: parameter/result — the command port's read side is gone, see above), the synchronous transaction model, parameter accumulation, the parameter-buffer cap, opcode numbers (except 0x10, retired — below), parameter block layouts, handles (1-based, 1..4, TCP and UDP independent), handle 0 = close all transient in the CLOSE commands (v2 extends the same form to TCP_ABORT — see the handles notes), MAX_TRANSFER/MAX_RECV_BUF/MAX_SEND_BUF, the graceful-close semantics, and the receive-side backpressure. Byte order stays as it is: IPs as network-order octets, 16-bit quantities little-endian.

Two v1 statements are explicitly superseded — a reader must NOT carry them over from the v1 document:

• v1's transaction model says reading past the end returns 0x00 and gates each command on status register == STATUS_DATA (2). In v2, past-end reads return 0xFF (rule 4) and the register does not exist — the port reads as open bus (0xFF), so a v1-style == 2 gate can never pass.
• v1's DNS_QUERY takes a NUL-terminated name (terminator effectively optional, trailing bytes ignored). v2 drops the terminator entirely: the parameter block is the hostname. This is the only change at the block-form level; no other layout moved. (One value check is also new — TCP_OPEN's undefined flag bits answer {4} where v1 ignored them. And one value gains meaning: v1 destroyed a datagram unread on UDP_RECV maxlen 0; v2 makes that TCPIP_UDP_RCV's deliberate DE=0 discard, reporting the source and size while copying nothing.)

The recovery rule is kept and completed: writing a parameter byte while a result is pending discards the unread result (as in v1), and writing a command opcode while a result is pending abandons it too — the new reply replaces it. A driver never has to drain a reply it has lost interest in.

DETECT (0x00) — replaces PING and QUERY_CAP

Wouter suggested merging the two, and the merge solves three things at once: the confusing "PING" name (it is not ICMP), the version byte nobody reads, and the magic bump v2 needs anyway.

DETECT, opcode 0x00, no parameters. Success reply, 5 bytes:

The driver accepts the device if and only if bytes 0-2 are exactly 00 55 02. Bytes 3-4 are data, not part of the acceptance rule: a driver must tolerate unknown capability bits (and any value in byte 4), or it will reject future devices for advertising more. Byte 2 is the upgrade path: a hypothetical v3 reports 3 there, a v2 driver rejects it cleanly, and a v3 driver may accept both if v3 is a superset.

Capabilities are honest and enforced: bit4 (ICMP) is set only when the host can actually ping — platform support compiled in and the ICMP channel opening successfully at device start (today that means: Windows, and IcmpCreateFile() succeeded); it is latched once at start. If bit4 is clear, the ICMP commands answer ERR_NOT_IMP. Bits 0-3 are always set on this device today (byte 3 reads 0x0F or 0x1F); they are informational, and no command is gated on them.

One corner is worth a recipe: a crashed predecessor may have left stray parameter bytes buffered, and a strict DETECT would then answer {4} — yet DETECT is also the stream-resynchronization command, so it must work from any state. Wouter's resolution: keep DETECT strict, and have the driver issue it twice unconditionally, reading only the second reply. The first either succeeds and is abandoned (issuing a command discards a pending result — the recovery rule) or answers {4} and clears the stray block; either way the second DETECT runs on a clean buffer. No conditional on either side.

Opcode 0x10 (QUERY_CAP) is retired and answers ERR_NOT_IMP like any other unknown opcode.

Command reference (v2 replies)

Parameter layouts are unchanged from v1 (see the v1 appendix for byte detail); this table gives the v2 reply, status byte included. Where a row shows {0, Struct}, the v2 wire struct is the v1 struct with the status byte prepended as its new first member — sizes grow by one, and the count shown already includes it — except ICMP_RECV, where the status replaces v1's hasData marker byte (still 12). "err:" lists the codes each command can emit besides 0 and besides the universal {4} of rule 3.

Handles, slots, and what survives a close

• Handles are 1..4. Handle 0 is out of range ({11}) everywhere except TCP_CLOSE, UDP_CLOSE and TCP_ABORT, where it means "close (or abort) all transient" — and succeeds ({0}) even when nothing is open. The ABORT form is new in v2: UNAPI defines it (TCPIP_TCP_ABORT, B = 0), but v1 silently no-opped it — the device rejected handle 0 and the driver never looked at the reply, so the caller got ERR_OK with nothing aborted.
• ERR_NO_CONN (11) means the handle is out of range — or, for the commands that act on a live connection (SEND, CLOSE, ABORT, and all of UDP), that no open connection sits on it. TCP_STATE and TCP_RECV answer for any in-range handle, open or closed: a closed connection keeps its final state, its close reason and its undrained receive data until TCP_OPEN reuses the slot. That is deliberate v1 behavior, kept on purpose — the tail of a connection that died stays readable (TCP_ABORT included), and the driver can still see why it died. What 11 removes is v1's ambiguity: a zeroed struct or a zero length no longer doubles as "bad handle".
• A never-used in-range slot answers TCP_STATE with closeReason 1 (NeverUsed) and every other field zero, and TCP_RECV with length 0 — same frame as v1, minus the bad-handle overload.
• Slot allocation: lowest-numbered free slot first. A closed slot holding a sticky tail is free — it does not count toward {9}, and reusing it destroys the tail. A slot consumed by a failed TCP_OPEN ({2}) is released, not left in ConnectFailed (that state belongs to the asynchronous connect path only).

TCP

• TCP_SEND may send in Established and CloseWait; any other existing connection state answers {12}; no connection at all answers {11}. A length beyond MAX_TRANSFER (4096) answers {4}; length 0 is a valid no-op ({0}). {13} is all-or-nothing: nothing was queued, the same command may be retried verbatim later. A socket write failure resets the connection (closeReason 4, ConnectionReset) and answers {12}.
• TCP_RECV: maxlen is a ceiling request — a value beyond 4096 is clamped, not an error (contrast TCP_SEND, where length states a fact about the payload that follows and must be exact). maxlen 0 answers {0, 0, 0} and consumes nothing. Length 0 with a live connection is normal stream behavior; poll TCP_STATE to tell "live but idle" from "finished".
• TCP_CLOSE is graceful: FinWait1, FIN once everything queued has been sent, handle freed when the peer closes too — or after 30 s. Buffered received data stays readable throughout (and after, per the sticky-slot rule). Closing a Listen handle is valid and frees it. A second CLOSE while the close is in progress is idempotent ({0}). TCP_ABORT drops immediately (closeReason 3); handle 0 aborts every transient connection, mirroring UNAPI's TCPIP_TCP_ABORT.
• TCP_OPEN: the timeout field stays in the layout, is accepted with any value, and is ignored (reserved). Undefined flag bits (2-7) must be 0; a set one answers {4}. Remote IP / port are not semantically validated — an active open to 0.0.0.0 or port 0 is handed to the host and fails there ({2} or, asynchronously, ConnectFailed). Passive open: a non-zero remote IP filters the peer; a non-matching peer is accepted and immediately dropped, and the listener keeps listening; on a match the handle becomes the connection (Listen → Established — the listener is gone, one connection per passive open).

UDP

• Every UDP socket is transient. The UNAPI residency concept has no wire representation in UdpOpenParams, so UDP_CLOSE 0 closes every open UDP socket. (The device keeps an internal resident flag for future use; nothing can set it today.)
• UDP_CLOSE discards the socket's queued datagrams — unlike TCP, nothing UDP stays readable after close.
• UDP_SEND: an oversized datagram is not a form error — the host refuses it and the reply is {2} (as is a short kernel write). A failed send leaves the socket open and usable. Length 0 sends an empty datagram ({0}).
• UDP_RECV: the head datagram is consumed whole. len in the reply is the datagram's size as received, and the payload that follows is the first min(len, maxlen) bytes — the excess, if any, is discarded with the datagram. This is exactly TCPIP_UDP_RCV's contract: its BC output is "the datagram data size as it was received, which may be larger than the number of bytes actually retrieved", and its DE=0 ("no data will be copied at all") is a deliberate discard — so maxlen 0 is valid: header only, datagram gone. Contrast TCP_RECV, where maxlen 0 consumes nothing — a stream has no unit to destroy, a datagram is all-or-nothing. An empty datagram (0 data bytes) is a normal datagram: UDP makes it visible to the receiver, so it queues and is delivered with len 0. Datagrams were already truncated to 2 KiB at receive time and queue at most 16 deep (v1 behavior, unchanged).
• UDP_STATE answers the head datagram's size, which is 0 both for an empty queue and for an empty datagram at its head — "UDP_RECV until {3}" is the idiom that tells them apart, and it is TCPIP_UDP_STATE's own advice (its datagram count must not be relied upon).
• UDP_OPEN: local port 0xFFFF requests an ephemeral port; local port 0 reaches the host bind() where it also yields an ephemeral port — the two coincide by different routes. A requested port the host refuses to bind falls back to an ephemeral one too, silently: the host OS itself may own the very port the MSX asks for — Windows' time service holds UDP 123, which is exactly what an SNTP client requests — a collision that cannot exist on the real-hardware UNAPI stacks this bridge stands in for, and a client's local port carries no meaning for the peer. (The first v2 build answered {2} there, in the name of honesty; functional testing vetoed it — SNTP broke on every Windows host whose time service was running — so v1's silent fallback is restored, and this time written down.) {2} remains the answer when the ephemeral bind fails as well.

ICMP

• With caps bit4 clear, ICMP_SEND and ICMP_RECV answer {1} — v1 accepted the request, dropped it silently, and let ICMP_RECV report "no data" forever; the capability bit becomes enforced, not decorative.
• The echo-size field keeps v1's clamp to 512. On a capable host a well-formed ICMP_SEND cannot fail: {0} acknowledges queueing to the worker, not delivery — an unreachable destination simply never yields a reply.
• Replies queue FIFO, at most 16 deep; when the queue is full the oldest reply is dropped — a reply nobody polled for is worth less than the fresh one the current program is waiting for (v1 dropped the newest; that was code, not design). Each successful ICMP_RECV consumes exactly one. The device does not correlate replies with requests — matching identifier/sequence is the driver's job.

Miscellaneous

• GET_LOCALIP answers 0.0.0.0 when the host lookup fails (still a success reply — v1 parity). On a multi-homed host, which address is reported is implementation-defined.
• NET_STATE keeps its constant answer ({0, 2}); it exists because the driver calls it, and inventing semantics for it is not this redesign's job.
• In UnapiNetWire.hh, every result struct gains uint8_t status = 0; as its first member — the hardcoding Wouter suggested: the correct value is baked into the type, T{} produces a valid success frame, and the golden-bytes tests verify it like any other field.

DNS

DNS_QUERY — parameters: the hostname itself. The whole parameter block is the name; there is no terminator (the block length already delimits it — v1's NUL was redundant, as Wouter noted). The device applies no syntax or charset rules to the hostname — beyond the dotted-quad fast path below, the bytes go to the host resolver as-is. The two bounds are transport, not syntax: a block longer than 253 bytes (the DNS presentation-form name limit) is "too long" under rule 3 → {4}, and a block with an embedded NUL is malformed → {4} — the host resolver API speaks C strings and cannot carry the name past the NUL, so no lookup could ever see it; rejecting the block beats resolving a silently truncated prefix. A block that parses as a strict dotted-quad (a.b.c.d, four decimal octets 0-255) resolves immediately → {0, 1, ip4}, and arms the sticky Complete state exactly as an asynchronous success does. Anything else starts the resolver thread → {0, 0}. An empty hostname (an empty block), one beyond the length cap, or one with an embedded NUL answers {4}; a lookup already running answers {5}; all of these leave the DNS state and any running lookup untouched.

DNS_STATUS (no parameters) reports the lookup, and its reply is data, not a command error — a well-formed DNS_STATUS always succeeds:

The completed/failed state is sticky until the next DNS_QUERY or a device reset, so the driver may re-read it freely. Keeping the failure inside a successful reply preserves rule 2 (command errors are single-byte) while still carrying the sub-code the driver's callers display to users.

Reset

A device reset (power-on, MSX reset) restores the ground state: every TCP and UDP connection is closed and freed — resident ones included — all receive buffers, send queues, datagram queues and ICMP replies are discarded, any pending reply and accumulated parameter bytes are dropped, and the DNS state returns to idle. The ICMP capability stays as latched at device start; reset does not re-probe it.

Migration and failure analysis

Both halves ship together; the four v1 users get the new unapinet.com with the new openMSX build. The interesting cases are the mismatches:

• v1 driver, v2 device. The driver sends opcode 0x00 (its PING) and expects the register to read STATUS_DATA (2) and the data port to yield 0xAB. On the v2 device the register read hits an unregistered port and returns 0xFF, and the data port yields 0x00 0x55 .... Both checks fail on the first byte → the driver prints "extension not found" and exits. Nothing misbehaves quietly.
• v2 driver, v1 device. DETECT goes out as opcode 0x00, which v1 treats as PING and answers 0xAB. The v2 driver requires the first byte to be 0x00 — 0xAB fails immediately. Same clean exit.
• No device. Every read returns 0xFF from the pull-ups, which v2 defines as never-valid at a status position. (This is why past-end reads also return 0xFF: "absent device" and "desynchronized driver" become the same, safe, diagnosis.)

One caveat for completeness: the analysis above covers detection, i.e. installation time — the only supported pairing path. A resident v1 TSR carried into a v2 device by other means (a savestate taken on an old openMSX and restored on a new one) is not served, but it fails safe: v1's per-call gate is status register == 2, and on a v2 device that read returns 0xFF from the unregistered port, so every call reports failure instead of half-working. Re-running the driver's installer is the answer; the spec simply does not promise more.

How the open points resolved

The proposal closed with three points for review; for the record:

1. The magic value (0x55) and the capability bit assignments stood unchallenged, and are final.
2. NET_STATE keeps its constant answer. Real semantics — or retirement — remain a question for after v2, deliberately not bundled into this redesign.
3. The err column and the validation order became the contract the TSR was written against, as intended, and the golden-byte tests pin the layout of every reply struct (the two-byte replies DNS and NET_STATE assemble inline are covered by the spec table alone). The one place where reality pushed back is recorded above: UDP_OPEN's ephemeral fallback.

Appendix — the v1 protocol (historical)

The v1 document follows — verbatim below its old title, headings demoted one level — as it stood the day v2 replaced it. It stays authoritative for the parameter-block layouts, which v2 did not move (DNS_QUERY's dropped terminator is the one exception), and its closing catalogue of v1 inconsistencies is the list this redesign set out to fix. Where it contradicts v2 — past-end reads, the status register, the detection handshake, the error conventions — everything above supersedes it. Its code references describe the v1-era sources.

This document describes the private wire protocol between the Z80 MSX-UNAPI TCP/IP driver (unapinet.com) and the UnapiNet device in openMSX. It is not the MSX-UNAPI specification: UNAPI defines what MSX software sees when it calls the driver; everything below is how the driver talks to the bridge behind the scenes. The driver and the device are developed and released together - the compatibility notes below rely on that - but only the device lives in the openMSX tree.

The C++ implementation is src/network/UnapiNet.cc; the byte-exact layouts of every parameter and result block are the structs in src/network/UnapiNetWire.hh. Where a struct name appears below, that struct is the layout.

Protocol version described here: v1 (bridge version byte 4, as reported by QUERY_CAP). Known inconsistencies of v1, and the plan to fix them in v2, are collected at the end.

I/O ports

The device claims two consecutive I/O ports, base 0x28 (share/extensions/ unapinet.xml, <io base="0x28" num="2"/>). Decoding is on bit 0 of the port number:

Transaction model

Every operation is one synchronous transaction:

1. The MSX writes the parameter block, one byte at a time, to port 0x29.
2. The MSX writes the command opcode to port 0x28. The device processes the command inside that I/O write: by the time the OUT instruction completes, the result is ready. The MSX never has to wait or poll for command completion. (Operations that take real time - DNS lookups, connection establishment, ICMP echo - return immediately and are polled with their own dedicated commands; see "Asynchronous operations".)
3. The MSX reads the status register (port 0x28). 0x02 (STATUS_DATA) means the result is ready to be read.
4. The MSX reads the result, one byte per IN, from port 0x29. Each read consumes one byte; reading past the end returns 0x00.

Bookkeeping rules, all enforced by the device:

• The parameter buffer is always cleared after a command executes, whether it succeeded or not.
• Writing a parameter byte while a result is still pending discards the unread result (a new transaction implicitly abandons the old one). This is the recovery path if the MSX program is interrupted mid-read: the next transaction starts clean.
• The parameter buffer is capped (64 KiB + 16). Excess bytes are dropped; the command's own size check then reports an error. A runaway MSX program cannot exhaust host memory.

Status register values

STATUS_ERROR is raised in exactly three situations: unknown opcode, DNS_QUERY with an empty host name, and DNS_QUERY while a lookup is already running. Every other error is reported inside a normal result block. In practice the driver only ever performs one check on this register: "did the command I just issued produce a result?" (status == STATUS_DATA).

Detection handshake

The driver detects the device at installation time:

1. PING (0x00, no parameters) must answer STATUS_DATA with the single magic byte 0xAB. Anything else means the extension is not present.
2. QUERY_CAP (0x10, no parameters) answers two bytes: a capability summary (0x0F = PING + DNS + TCP + UDP) and the bridge version (4).

v1 quirk: the current driver only performs step 1; nothing reads the version byte today.

Data types

• IPv4 address - 4 bytes, the octets of a.b.c.d in order (network/big-endian; Endian::UA_B32 in the structs).
• port / length / id / seq - 2 bytes, low byte first (little-endian, Z80-natural; Endian::UA_L16).
• handle - 1 byte. TCP and UDP handles are independent ranges, both 1-based on the wire: 1..4 (MAX_TCP = MAX_UDP = 4). In results, handle 0 means "could not open".

Command reference

Any other opcode raises STATUS_ERROR.

TCP

TCP_OPEN - TcpOpenParams: remote IP (4), remote port (2), local port (2), timeout (2, reserved: never read), flags (1; bit 0 = passive open, bit 1 = resident). An active open starts a non-blocking connect() and returns the handle immediately; the driver polls TCP_STATE until the state leaves SynSent. A passive open (bit 0) listens on the local port; remote IP, if non-zero, filters which peer may connect.

TCP_SEND - header {handle (1), length (2)} followed by exactly length payload bytes. The driver keeps to 4096 bytes (MAX_TRANSFER) per command by convention, but the bridge does not enforce that bound on the send side (a v1 quirk; only TCP_RECV clamps to it). Result 2 ("send buffer full") is a recoverable condition: the bridge queues up to 64 KiB (MAX_SEND_BUF) that the kernel has not yet accepted, and the driver should retry later. Result 1 is a real failure (bad handle/state/length, or a connection error while queueing).

TCP_RECV - {handle (1), maxlen (2)}. Answers {actualLen (2)} followed by actualLen bytes taken from the connection's receive buffer, at most 4096 per command. actualLen 0 means "nothing buffered right now" - poll TCP_STATE to distinguish an empty buffer on a live connection from a finished one. v1 quirk: a bad handle also answers actualLen 0.

TCP_STATE - answers TcpStateResult: state (1), bytes available to read (2), close reason (1), remote IP (4), remote port (2), local port (2). An invalid or missing handle answers all-zero fields with closeReason = 1 (NeverUsed).

State values (TCP-standard names): 0 Closed, 1 Listen, 2 SynSent, 3 SynRecv, 4 Established, 5 FinWait1, 6 FinWait2, 7 CloseWait, 8 Closing, 9 LastAck, 10 TimeWait.

Close reasons: 0 None, 1 NeverUsed, 2 ClosedByUser, 3 Aborted, 4 ConnectionReset, 6 ConnectFailed.

TCP_CLOSE vs TCP_ABORT - CLOSE is graceful: the connection enters FinWait1, the FIN goes out once everything the MSX queued has actually been sent, and the handle is freed when the peer closes too - or after a 30 s timeout, so a silent peer cannot pin a handle forever. Received data still buffered stays readable meanwhile. ABORT drops the connection immediately. Handle 0 in TCP_CLOSE (and UDP_CLOSE) closes every open non-resident connection at once - the driver uses it on program exit; resident connections (TCP_OPEN flags bit 1) survive it.

UDP

UDP_OPEN - local port (2), 0xFFFF = ephemeral. UDP_STATE answers the size of the first queued datagram (2 bytes; 0 = queue empty, or bad handle - same v1 quirk as TCP_RECV). UDP_SEND - header {handle (1), destination IP (4), destination port (2), length (2)} + payload; result 1 also covers a short kernel write. UDP_RECV - {handle (1), maxlen (2)}; answers {source IP (4), source port (2), actualLen (2)} + payload. Datagram semantics apply: if the first queued datagram is larger than maxlen, the excess of that datagram is discarded.

ICMP

ICMP_SEND - {destination IP (4), TTL (1), identifier (2), sequence (2), size (2, clamped to 512)}. No payload follows: the bridge fabricates the echo data itself. The request is queued to a worker thread; the result byte only acknowledges the queueing. ICMP_RECV polls for replies: 1 byte 0 = none yet, otherwise {1, source IP (4), TTL (1), identifier (2), sequence (2), dataLen (2)} - header only, the echo payload is not returned. Current limitation: the ICMP worker is implemented with the Windows ICMP API; on other host platforms ICMP_RECV never reports data.

Asynchronous operations

DNS. DNS_QUERY takes the hostname as its parameter block, NUL-terminated (the terminator and anything after it are ignored). If the name parses as a dotted-quad IP it answers immediately with 5 bytes {1, ip}. Otherwise it starts a resolver thread and answers a single byte 0 ("started"); the driver then polls DNS_STATUS, which answers one byte 0/1 (idle / in progress), 5 bytes {2, ip} on success, or 2 bytes {0xFF, 3} on failure (the only failure reported is "no such host", UNAPI error 3). The completed status is sticky: it stays readable until the next DNS_QUERY or a device reset. Issuing DNS_QUERY while a lookup is running raises STATUS_ERROR without disturbing the running lookup.

TCP connect is polled via TCP_STATE (SynSent → Established or Closed + ConnectFailed).

Receive path. A background thread moves incoming TCP data into a per-connection buffer of up to 64 KiB (MAX_RECV_BUF), from which TCP_RECV reads. When the buffer is full the bridge stops reading from the socket, the kernel buffer fills, and TCP flow control throttles the peer - no TCP data is ever dropped. UDP is best-effort, as datagrams are: they are read into a 2 KiB buffer (larger ones are truncated at receive time) and queued per socket up to 16 deep; beyond that, new arrivals are read and discarded.

Known v1 inconsistencies, and the v2 plan

These grew one command at a time and are preserved here so the next reader does not have to rediscover them:

1. Three error conventions coexist. OPEN commands answer a handle where 0 = failure; most other commands answer 0 = OK / 1 = error (and TCP_SEND adds 2 = buffer full); STATUS_ERROR covers only the three protocol-level cases listed above.
2. "No data" and "bad handle" are indistinguishable in TCP_RECV, UDP_STATE and UDP_RECV.
3. Parameter blocks are validated as "at least this long", not exactly; trailing garbage is silently accepted.
4. QUERY_CAP is implemented but never issued by the driver, so the version byte is dead on the wire.
5. NET_STATE answers a constant.
6. TcpOpenParams.timeout is never read.
7. MAX_TRANSFER is enforced on TCP_RECV but not on TCP_SEND - the 4096-byte bound on sends is a driver-side convention the bridge silently trusts.

The planned v2, coordinated with the driver (both halves ship from the same repository): every reply starts with a status byte (0 = OK, otherwise the UNAPI error code the driver should return, ERR_BUFFER included); handles stop doubling as error codes; parameter blocks are validated for exact size; the PING magic is bumped so an old driver fails detection cleanly instead of misbehaving quietly; and the driver reads QUERY_CAP for real. With a status byte on every reply the status register becomes redundant (the driver's only use of it is the == STATUS_DATA check after each command); whether to repurpose or retire it is an open design point.