Acorn ANFS 4.21 (variant 1)

Reads the deferred-work flag at &0D65; if zero, returns early via PLX/PLY/RTS. Otherwise clears bit 7 of the Master 128 ACCCON register at &FE34 (TRB), zeros &0D65, then dispatches one of two ways depending on bit 7 of the saved Y:

Single-instruction JMP (evntv) that hands control to whatever handler is hooked into the MOS event vector. Called via service call &05 (svc5_irq_check) on a 'transmit complete' or 'receive complete' edge so user/MOS code can react to network events.

Builds an RTS-target on the stack from the tx_done_dispatch_lo low-byte table and a hard- coded high byte of &85, then falls through into the shared svc_5_unknown_irq RTS to land on the matching tx_done_dispatch_lo+Y page-&85 handler.

Bare RTS reused as the final step of every dispatch_svc5 entry. With the target's high/low bytes already pushed by the caller, RTS jumps to the selected handler. Also reached as the unclaimed-IRQ tail of the service-5 prologue when no ANFS handler matches.

Initialise ADLC hardware and Econet workspace. Disables NMIs via BIT master_intoff (the Master 128 INTOFF register at &FE38; the Model-B equivalent reads econet_station_id at &FE18 for the same side effect). Performs a full ADLC reset via adlc_full_reset, then probes for a Tube co-processor via OSBYTE &EA and stores the result in tube_present. Issues an NMI-claim service request (OSBYTE &8F, X=&0C). Falls through to init_nmi_workspace to copy the NMI shim to RAM.

Copies 32 bytes of NMI shim code from ROM (listen_jmp_hi) to the start of the NFS workspace RAM block, then patches the current ROM bank number into the self-modifying code at nmi_romsel (&0D07).

The shim includes the INTOFF/INTON pair (BIT econet_station_id at entry, BIT econet_nmi_enable before RTI) that toggles the IC97 NMI-enable flip-flop, guaranteeing edge re-triggering on /NMI.

Workspace fields written:

Finally re-enables NMIs via INTON (econet_nmi_enable read).

Default NMI handler for incoming scout frames. Checks whether the frame is addressed to us or is a broadcast. Installed as the NMI target during idle RX listen mode.

Tests SR2 bit 0 (AP = Address Present) to detect incoming data. Reads the first byte (destination station) from the RX FIFO and compares against our station ID. Reading econet_station_id (&FE18) also disables NMIs (INTOFF side effect).

Reads the second byte of an incoming scout (destination network).

Installs copy_scout_to_buffer as the scout-data reading loop handler.

Handles scout reception errors and end-of-frame conditions. Reads SR2 and tests AP|RDA (bits 0 and 7):

• Neither set – the frame ended cleanly; simply discard.
• Either set – unexpected data is present; perform a full ADLC reset.

Also serves as the common discard path for address/network mismatches from nmi_rx_scout and scout_complete – reached by 5 branch sites across the scout reception chain.

Processes a completed scout frame. Writes CR1=&00 and CR2=&84 to disable PSE and suppress FV, then tests SR2 for FV (frame valid). If FV is set with RDA, reads the remaining scout data bytes in pairs into the buffer at &0D3D.

Matches the port byte (&0D40) against open receive control blocks to find a listener:

• On match – calculates the transfer size via tx_calc_transfer, sets up the data RX handler chain, and sends a scout ACK.
• On no match or error – discards the frame via scout_error.

Sets scout_status=3 (match found) at rx_port, calls tx_calc_transfer to compute the transfer parameters from the RXCB, then triages:

Four inbound refs (one JSR from &84B9 and three branches from the scout_complete dispatch).

Switches the ADLC to TX mode for the scout ACK frame: writes CR1=&44 (RX_RESET | TIE), CR2=&A7 (RTS | CLR_TX_ST | FC_TDRA | PSE), then loads (A,Y) = (&B8, &81) – the address of data_rx_setup – and JMPs to ack_tx_write_dest which saves the pair into saved_nmi_lo/saved_nmi_hi (so the NMI handler will install it later) and writes the ACK destination address bytes to the TX FIFO.

Two callers: the dispatch in scout_complete at &81A2 and the immediate-op POKE path at &84AE (jmp_send_data_rx_ack).

NMI continuation entry installed by send_data_rx_ack (which pushes (&81B8 - 1) on the stack and routes it through ack_tx_write_dest). When the next NMI fires, this body writes CR1 = &82 (TX_RESET | RIE) to switch the ADLC from scout-ACK TX mode to data-frame RX mode, then JMPs to install_nmi_handler to install nmi_data_rx as the next NMI handler.

Receives the data frame after the scout ACK has been sent. First checks AP (Address Present) for the start of the data frame. Reads and validates the first two address bytes (dest_stn, dest_net) against our station address, then installs continuation handlers to read the remaining data payload into the open port buffer.

Handler chain: this routine (AP + dest-stn check) → nmi_data_rx_net (dest-net check) → nmi_data_rx_skip (skip ctrl + port) → nmi_data_rx_bulk (bulk data read) → data_rx_complete (completion).

NMI continuation entry installed by nmi_data_rx once the AP and dest-station bytes have validated. Polls SR2 (BIT econet_control23_or_status2); on no RDA, branches to nmi_error_dispatch. Otherwise reads the dest- network byte from the ADLC FIFO and falls through to the control/port skip step.

NMI continuation entry that consumes the control and port bytes of the data frame (already known from the scout) and proceeds to the bulk-data-read continuation. Polls SR2 for RDA on entry; on no RDA, branches to nmi_error_dispatch.

Selects between the normal bulk-RX handler at nmi_data_rx_bulk and the Tube RX handler at nmi_data_rx_tube based on bit 1 of rx_src_net (tx_flags).

In the bulk path, after loading the handler address, checks SR1 bit 7. If IRQ is already asserted (more data waiting), jumps directly to nmi_data_rx_bulk to avoid NMI re-entry overhead. Otherwise installs the handler via set_nmi_vector (the (A,Y) pair becomes the NMI dispatch target) and returns via RTI.

Common error/abort entry used by 11 call sites. The dispatch byte at rx_src_net doubles as a TX-state flag here: bit 7 distinguishes whether the NMI handler reached this point on an RX-error path or a TX not-listening path.

Reads data payload bytes from the RX FIFO and stores them into the open port buffer at (open_port_buf),Y. Reads bytes in pairs (like the scout data loop), checking SR2 between each pair.

• SR2 non-zero (FV or other) → completion via data_rx_complete.
• SR2 = 0 → RTI, wait for next NMI to continue.

Reached when SR2 non-zero during data RX (FV detected). Same pattern as scout completion: disables PSE (CR2=&84, CR1=&00), then tests FV and RDA. If FV+RDA, reads the last byte; if extra data is available and buffer space remains, stores it. Proceeds to send the final ACK via ack_tx.

NMI continuation entry for the Tube data-RX path. Polls SR2 for RDA, reads the next data byte from the ADLC RX FIFO, and writes it to the Tube data register, advancing the Tube transfer pointer each iteration. Tests for end-of-frame via FV and either continues the tight inner loop or returns via RTI. Reached only via the NMI vector after install_tube_rx configures the handler.

Sends a scout ACK or final ACK frame as part of the four-way handshake. Tests bit 7 of rx_src_net (used as TX-flags here): if set this is a final ACK and completion runs through tx_result_ok. Otherwise configures for TX (CR1=&44, CR2=&A7) and writes the ACK address frame: destination station from scout_buf, destination network from scout_src_net, source station from the workspace copy tx_src_stn, and src_net=0. The ACK frame has no data payload -- just address bytes.

After writing the address bytes to the TX FIFO, installs the next NMI handler from saved_nmi_lo/saved_nmi_hi (saved by the scout/data RX handler via ack_tx_write_dest) and sends TX_LAST_DATA (CR2=&3F) to close the frame.

First step of the four-byte ACK frame transmission. Saves the caller-supplied (A=lo, Y=hi) next-NMI handler address into saved_nmi_lo / saved_nmi_hi, loads the destination station from scout_buf and tests SR1 bit 6 (TDRA, TX Data Register Available) via BIT adlc_cr1. If TDRA is clear the TX FIFO isn't ready and control branches to dispatch_nmi_error to abort.

When TDRA is set, writes the destination station and network bytes (from scout_src_net) into adlc_tx, then installs nmi_ack_tx_src as the next NMI handler via set_nmi_vector -- that handler will write the source-address pair on the next NMI.

Two callers: send_data_rx_ack's tail JMP and imm_op_build_reply.

Continuation of ACK frame transmission, reached via NMI after ack_tx_write_dest installed it as the next handler. Reads our station ID from the workspace copy tx_src_stn, tests TDRA via SR1, and writes (station, network=0) to the TX FIFO -- completing the 4-byte ACK address header.

Then dispatches on rx_src_net bit 7 (which the caller uses as a TX-flags byte):

Called after the scout ACK has been transmitted. Processes the received scout data stored in the buffer starting at rx_src_stn (scout-ACK destination addresses). Checks the port byte at rx_port against open receive blocks to find a matching listener.

• Match – sets up the data-RX handler chain for the four-way- handshake data phase.
• No match – discards the frame.

Adds the transfer count to the RXCB buffer pointer (4-byte addition). If a Tube transfer is active, re-claims the Tube address and sends the extra RX byte via R3, incrementing the Tube pointer by 1.

Reads:

• tx_flags bit 1 – data transfer in progress
• tx_flags bit 5 – Tube transfer
• 4-byte transfer count from net_tx_ptr,Y (Y=8..&0B)
• RXCB pointer at (port_ws_offset),Y

Updates the RXCB in place. Clobbers A and Y; preserves X across the Tube branch (saved/restored via stack).

Installed by ack_tx_configure via saved_nmi_lo / saved_nmi_hi. Fires as an NMI after the ACK frame (CRC + closing flag) has been fully transmitted by the ADLC. Dispatches on scout_port:

Called from nmi_post_ack_dispatch after the final ACK has been transmitted. Finalises the received data transfer:

1. Calls advance_rx_buffer_ptr to update the 4-byte buffer pointer with the transfer count (and handle Tube re-claim if needed).
2. Stores the source station, network, and port into the RXCB.
3. ORs &80 into the RXCB control byte (bit 7 = complete).

This is the NMI-to-foreground synchronisation point: wait_net_tx_ack polls bit 7 of the RXCB control byte to detect that the reply has arrived.

Falls through to discard_reset_rx to reset the ADLC to idle RX-listen mode.

Three-stage idle-restore chain:

1. discard_reset_listen – abandon any in-flight scout and release a held Tube claim.
2. reset_adlc_rx_listen – call adlc_rx_listen (reset CR1/CR2 and re-arm RX).
3. set_nmi_rx_scout – install nmi_rx_scout as the active NMI handler and JMP out via set_nmi_vector.

Used as the standard "something went wrong, get back to listening" exit.

Tail of the discard_reset_rx chain entered directly when no scout needs discarding. Calls adlc_rx_listen to reset CR1/CR2 to RX-only mode, then falls through to set_nmi_rx_scout.

Two inbound JSRs plus one fall-through (from discard_reset_rx).

Loads (A=&9B, Y=&80) -- the address of nmi_rx_scout -- and JMPs to set_nmi_vector, which writes both bytes into the NMI JMP-target slot at nmi_jmp_lo/nmi_jmp_hi. Tail of the discard_reset_rx / reset_adlc_rx_listen chain, used to put the NMI vector back to scout-handling after a discard or reset.

Two callers: &80CB (after init) and &80E2 (after error).

Checks whether a Tube transfer is active by ANDing bit 1 of tube_present with rx_src_net (tx_flags). If a Tube claim is held, calls release_tube to free it before returning.

Used as the clean-up path after RXCB completion and after ADLC reset to ensure no stale Tube claims persist.

Five-instruction prologue that prepares to copy scout-payload bytes (offsets 4..&0B) from scout_buf into the open port buffer. Saves X on the stack, loads X=4 (the first scout-data offset) and A=&02 (Tube-flag mask), then BITs rx_src_net (tx_flags) so the immediately following BNE in save_acccon_for_shadow_ram can dispatch:

Both paths walk the four-byte buffer pointer and end via scout_copy_done which restores X and returns. Single caller: port_match_found at &81A4.

Saves the current acccon value, sets ACCCON for the upcoming (open_port_buf),Y stores (so writes go to the right shadow / main RAM bank on the Master 128), performs the copy, then restores the saved ACCCON before returning. Wraps the inner copy loop with shadow-RAM gating so scout-buffer writes land in the caller's address space rather than the FS-private HAZEL window.

Tests bit 7 of prot_flags -- the bit ANFS uses to track whether the Tube is currently still claimed:

Both paths end at clear_release_flag which LSRs prot_flags (shifting bit 7 to 0) before returning.

Called after completed RX transfers and during discard paths to ensure no stale Tube claims persist.

Idempotent: safe to call when the Tube has already been released. Clobbers A; preserves X and Y.

Checks the control byte at scout_ctrl for immediate-operation codes:

For &81..&86, converts the code to a 0-based index and tests against the immediate-op mask at econet_flags to determine whether this station accepts the operation. If accepted, dispatches via imm_op_dispatch_lo (PHA/PHA/RTS).

Builds the reply by storing data length, station / network, and control byte into the RX buffer header.

Eight low-byte entries at &848B-&8492 indexed by the immediate-op control byte (&81-&88) via LDA imm_op_dispatch_lo-&81,Y at the dispatch site. Each entry is the low byte of (handler-1) so PHA/PHA/RTS dispatch lands on the handler. The high byte pushed by the dispatcher is constant (&84), so all targets sit in &84xx. Per-entry inline comments identify each control byte's handler.

Sets up the port buffer to receive remote-procedure data. Copies the 2-byte remote address from scout_data into the execution-address workspace at exec_addr_lo / exec_addr_hi, then jumps to the common data-receive path at &81C1.

Used for operation types &83 (JSR), &84 (UserProc), and &85 (OSProc).

Sets up workspace offsets for receiving POKE data: port_ws_offset = &2E, rx_buf_offset = &0D. Jumps to the common data-receive path at &81AF.

Sets up the response buffer for a machine-type query immediate operation (4-byte response: machine code + version digits). Falls through to set_rx_buf_len_hi to configure the buffer dimensions, then branches to set_tx_reply_flag.

Writes &0D2E to port_ws_offset / rx_buf_offset, sets scout_status = 2, then calls tx_calc_transfer to send the PEEK response data back to the requesting station.

Writes the reply-frame header for a port-0 immediate operation into the RX buffer at offsets &7F..&81:

Then loads the control byte from scout_ctrl into A and falls through into setup_sr_tx, which stores A as tx_op_type and configures the ADLC for the SR phase of the reply. Reached via the immediate-op dispatch path.

Stores the TX operation type in tx_op_type.

The shadow is flushed to the real VIA ACR/SR registers later in the Master IRQ path. Single caller (&83E2 in scout_complete).

Adds 1 to the 4-byte counter at &A2..&A5 (port_buf_len lo/hi, open_port_buf lo/hi), cascading overflow through all four bytes. Called after each byte is stored during scout-data copy and data-frame reception to track the current write position in the receive buffer.

Preserves A, X, Y (uses INC zp throughout).

Low bytes of PHA/PHA/RTS dispatch targets for TX operation types &83-&87. Read by the dispatch at dispatch_svc5 via LDA tx_done_dispatch_lo-&83,Y (the operand lands mid-instruction inside set_rx_buf_len_hi). The dispatch trampoline pushes &85 as the high byte, so targets are &85xx+1. Entries for Y < &83 read from preceding code bytes and are not valid operation types. Per-entry inline comments identify each TX operation type's handler.

Pushes (tx_done_exit - 1) on the stack so RTS returns to tx_done_exit when the remote routine completes, then does JMP indirect through exec_addr_lo to call the remote-supplied JSR target. When that routine returns via RTS, control resumes at tx_done_exit which tidies up TX state.

Handler for TX operation type &84. Loads the remote address from exec_addr_lo / exec_addr_hi into X / A and sets Y=8 (Econet event number), then falls through to tx_done_fire_event to call OSEVEN.

Reached only via PHA/PHA/RTS dispatch from tx_done_dispatch_lo / hi. The dispatcher pushed the caller's X and Y onto the stack before transferring control, and the shared tx_done_exit restores them via PLA/TAY/PLA/TAX before returning A=0.

Calls the ROM service entry point with X = exec_addr_lo, Y = exec_addr_hi. This invokes an OS-level procedure on behalf of the remote station, then exits via tx_done_exit.

Reached only via PHA/PHA/RTS dispatch from tx_done_dispatch_lo / hi.

Sets bit 2 of econet_flags, enables interrupts, and spin-waits until bit 2 is cleared (by a CONTINUE from the remote station). If bit 2 is already set, skips to exit.

Reached only via PHA/PHA/RTS dispatch from tx_done_dispatch_lo / hi. Falls through to tx_done_continue after the spin completes; on the already-halted path it branches directly to tx_done_exit.

Clears bit 2 of econet_flags, releasing any station that is halted and spinning in tx_done_halt.

Reached either as a fall-through from tx_done_halt or directly via PHA/PHA/RTS dispatch from tx_done_dispatch_lo / hi. Falls through to tx_done_exit which restores X and Y from the stack and returns A=0.

Common cleanup tail used by every entry in the tx_done_dispatch_lo table. Pulls the saved Y and X off the stack (the dispatcher pushed them before the PHA/PHA/RTS jump), loads A=0 (success status), and RTS to the caller.

Five inbound refs: a tail-jump from &8042 (the SVC 5 IRQ-check path in svc5_irq_check), plus the JMPs at &8554, &8560, &8568, and the fall-through at &8578.

Main TX initiation entry point (called via the NETV trampoline).

1. Copies destination station / network from the TXCB to the scout buffer.
2. Dispatches: control byte ≥ &81 → immediate-op setup; else normal data transfer.
3. Calculates transfer sizes via tx_calc_transfer; copies extra parameters into the workspace.
4. Enters the INACTIVE polling loop at inactive_poll.