Skip to main content

Guidance to Programmers

Source

Adapted from Guidance to programmers.

This guidance is mainly for assembly language programmers, but C programmers using low-level Spectranet calls should also follow it. BASIC programmers normally do not need these details because BASIC extensions hide the paging rules.

Memory layout assumptions​

Spectranet memory is arranged in 4K pages mapped into the lower 16K of the Spectrum address space. Two pages are fixed when Spectranet memory is visible:

  • flash page 0 at 0x0000 to 0x0FFF
  • SRAM page 0 at 0x3000 to 0x3FFF

The middle two pages are paging area A (0x1000 to 0x1FFF) and paging area B (0x2000 to 0x2FFF). Code in extra ROM pages typically runs from area B; data, W5100 buffers, and temporary pages commonly use area A.

Use public entry points​

Public ROM entry points are reached through a jump table copied to stable RAM addresses. This avoids forcing programs to be rebuilt for every firmware revision, and it gives the ROM a place to override or intercept calls.

Use the documented gateways:

  • HLCALL, entered through the CALL 0x3FFA mechanism
  • IXCALL, entered through the CALL 0x3FFD mechanism
  • PAGEIN, entered through CALL 0x3FF9
  • UNPAGE, entered through the page-out address at 0x007C

Avoid direct OUT instructions unless there is a strong reason. ROM routines such as SETPAGEA and SETPAGEB keep the Spectranet system variables synchronized with the hardware and protect code from hardware revisions.

Staying paged in​

For a sequence of Spectranet calls, it can be faster to page Spectranet in once, call the jump table directly, and unpage when done:

call PAGEIN

.poll
ld a, (sockethandle)
call POLLFD
jr z, .poll

call UNPAGE

This should be used carefully. Code that returns to BASIC or calls Spectrum ROM routines must ensure the correct ROM is visible.

Calling the Spectrum ROM​

When Spectranet is paged in, a normal CALL to a Spectrum ROM address will not work because the Spectrum ROM is hidden. Use the Spectranet CALLBAS mechanism instead:

ld a, 2
rst CALLBAS
defw 0x1601

This temporarily calls into the Spectrum ROM and restores Spectranet memory on return.