Acorn ANFS 4.26

MOS dispatches JMP &8000 on language startup.

Service-only ROM (rom_type bit 6 clear). Per-byte detail is inline.

Reason code in A on entry:

MOS calls JMP &8003 for service-call dispatch — unrecognised * commands, OSWORDs, OSBYTEs, *HELP, filing-system init / select, paged-ROM scans, and many other events. The reason code arrives in A.

Delivers work deferred out of the Econet NMI receive handler. An execute-class immediate operation -- a remote JSR, a user/OS procedure call, halt or continue -- cannot safely JSR into user code or call an OS routine from NMI context, so the NMI handler records it instead: setup_sr_tx stores the operation type in tx_op_type and sets the Master 128 ACCCON IRR latch (bit 7 at &FE34) via TSB. The latch raises an ordinary IRQ once the NMI handler has returned, which reaches the ROM here as service call &05 (unrecognised interrupt) -- the normal IRQ path, where it is safe to run the deferred operation.

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 svc5_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 svc5_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 disable_net_nmis (the Master 128 INTOFF register at &FE38). 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 disable_net_nmis at entry, BIT enable_net_nmis before RTI) that toggles the Econet NMI-enable flip-flop, guaranteeing edge re-triggering on /NMI.

Workspace fields written:

Finally re-enables NMIs via INTON (enable_net_nmis 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 it against our station ID (the workspace copy in tx_src_stn).

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 net_frame_flags (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 net_frame_flags 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 net_frame_flags (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 econet_control1_or_status1. 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 econet_data_continue_frame, 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 net_frame_flags 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: &80CD (after init) and &80E4 (after error).

Checks whether a Tube transfer is active by ANDing bit 1 of tube_present with net_frame_flags (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 net_frame_flags (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 &81A7.

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 per-station protection mask prot_status to determine whether this station accepts the operation. If accepted, dispatches via the immediate-op dispatch table (PHA/PHA/RTS).

The execute-class operations (&83 JSR, &84 UserProc, &85 OSProc, &86 HALT, &87 CONTINUE) cannot run inside the NMI receive handler -- a JSR into user code or an OS call is unsafe there -- so they are not run inline. They are completed later from normal IRQ context: setup_sr_tx records the operation in tx_op_type and sets the Master 128 ACCCON IRR latch (bit 7 at &FE34), which raises an IRQ that the ROM picks up as service call &05 (svc5_irq_check) and dispatches via the svc5_dispatch_lo table. PEEK, POKE and machine-type (&81 / &82 / &88) only touch memory and reply immediately, so they run here.

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

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 via send_data_rx_ack.

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 POKE data-receive path at port_match_found. POKE (&82) only writes memory and replies, so it is serviced inline in the receive path -- not deferred like the execute-class operations &83-&87.

Sets up workspace offsets for a PEEK response: port_ws_offset = &2E, rx_buf_offset = &0D, rx_port = 2 (PEEK response status), then calls tx_calc_transfer to send the requested memory back to the requesting station. PEEK (&81) only reads memory and replies, so it is serviced inline in the receive path -- not deferred like the execute-class operations &83-&87.

Reached via the immediate-op dispatch table (imm_op_handler_lo_table) for control byte &81.

Builds the fixed machine-identity reply for a MachinePeek immediate operation (control byte &88). Copies the 3 identity bytes at machine_id_bytes into mc_reply_machine_id, copies spool_control_flag to mc_reply_status, points the reply buffer via open_port_buf and sets its length, then branches to set_tx_reply_flag to send it. Serviced inline (like PEEK/POKE), not deferred.

Reached only via the immediate-op dispatch table (imm_op_dispatch_lo) for control byte &88.

Eight low-byte entries at &8515-&851C indexed by the immediate-op control byte (&81-&88) via LDA imm_op_handler_lo_table,Y at the dispatch site (the table's nominal base imm_op_handler_lo_table so the entry for control byte N sits at that base plus N). Each byte is the low byte of (handler-1) so the PHA/PHA/RTS dispatch (constant high byte &84) lands on the handler in page &84xx. Per-entry inline comments identify each control byte's handler.

Stores the TX operation type in tx_op_type, then (at enable_irq_pending) sets the ACCCON IRR latch to arm the deferred dispatch -- see svc5_irq_check.

Raising bits 2-4 of the LSTAT protection mask is re-entrancy protection: while the deferred remote routine runs (it is a JSR into user code, or an OS call), the station will not accept another remote execute operation. The previous mask is preserved in prot_status_save so it can be restored once the call returns. (The bit pattern &1C happens to equal the System VIA ACR shift-register mode-field mask, but here it is applied to the LSTAT mask, not the VIA -- the Model B ROMs raise the same bits in a separate step on the dispatch side.) 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).

Executes the Econet Remote Subroutine Jump (immediate operation &83), now running in deferred IRQ context after svc5_irq_check picked up the ACCCON IRR latch -- so the JSR happens safely outside the NMI 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 &8044 (the SVC 5 IRQ-check path in svc5_irq_check), plus the JMPs at &8554, &8584, &858C, and the fall-through at &8578.

Prepares the buffer-transfer for a completed receive. Clears decimal mode, then seeds escapable from ACCCON with the transfer-mode bit set. Inspects RXCB[6..7] (buffer end address byte 2 and high) to classify the buffer:

Three callers: scout_complete (&819D), rx_imm_peek (&84D4), tx_ctrl_proc (&87A4).