Documentation Website Español Try it in your browser

The protocol of the EXT: drive and of remote loading

This document is for anyone who wants to write a server for the EXT: drive (a program that serves a folder to the ZX-V: on a PC, a Raspberry Pi, a phone, another machine...) or to talk to the board through its J5 header on their own. zxv-link (in sdk/tools/link, MIT) is the reference implementation of the two sides that belong to the PC: zxvlink.c (the frames), linkcore.c (remote loading) and extserve.c (the EXT: server).

What EXT: is for the machine's programs (the paths, the names, the file numbers) is in the specification, §7.7 (in Spanish). Here, what travels.

The frames

Each message goes in a frame: its bytes in COBS, followed by a zero. The receiver picks up again by itself at the next zero even if something is lost. Before COBS, in little endian:

Offset What
+0 The channel (below)
+1 The type: the request's; in its reply, the same with bit 7 set (plus 0x80)
+2 The request number (0-255): set by the one who asks, and the reply repeats it
+3 The data: up to 516 bytes
... The CRC-32 of everything before it (zlib's: polynomial 0xEDB88320, starting and ending with 0xFFFFFFFF)

A frame with a wrong CRC, cut short or longer than fits is thrown away without a reply: the one who asked repeats the request when its wait runs out.

Replies always start with a status (i32): 0 or more, fine (in some, a number: bytes, a position); negative, a machine error (ZXV_E_*, see Error codes; for example, −1 does not exist).

The channels

Channel Value Who asks What for
CTRL 0 The outside device Remote loading: sending files to the card, running, debugging; and announcing itself as the EXT: server
LOG 1 Nobody: the machine sends it on its own The machine's report (UTF-8 text, type 0x40): it is not answered
EXT 2 The machine What programs ask of the EXT: drive

Each side numbers its own requests, and on each channel there is at most one pending request: the next one is not sent until the reply has arrived (or until giving up).

Announcing itself as a server

A server tells the machine it is there with a request on the CTRL channel:

Type Data Reply
SERVE (10) u8: 1 I serve EXT:, 0 I stop serving it status; the machine's boot number (u32)

What the machine asks (EXT channel)

The machine asks on the EXT channel and the server replies with the same type plus 0x80 and the same number. If the same request arrives again (the same number, after a reply that was lost), the server repeats the reply without doing it again: writing, deleting or renaming twice would not be the same. The machine waits half a second for each reply, asks up to three times and, if there is still nothing, considers the drive lost (ZXV_E_OFFLINE) until the next SERVE.

Open files and folders go by slot: the machine has 8 file slots (0-7) and 4 folder slots (0-3) on EXT:, and says which one in each request. The server keeps what is in each one.

Type Data Reply, after the status
OPEN (1) slot (u8), mode (u32: the ZXV_O_* of file_open), path —
READ (2) slot (u8), how many (u16, up to 512) Status = bytes read (0, the end); after it, those bytes
WRITE (3) slot (u8), the bytes (up to 512) Status = bytes written
CLOSE (4) slot (u8) —
SEEK (5) slot (u8), offset (i32), from (u8: 0 the start, 1 where it is, 2 the end) Status = the new position
STAT (6) path Size (u32) and attributes (u32: bit 0, folder)
REMOVE (7) path — (deletes a file or an empty folder)
RENAME (8) source path, a 0, destination path —
MKDIR (9) path —
OPENDIR (10) folder slot (u8), path —
READDIR (11) folder slot (u8) Status = 1 and the entry: size (u32), attributes (u32) and name (without the zero); 0, no more
CLOSEDIR (12) folder slot (u8) —

The machine keeps the current folder: changing folder is a STAT that checks that it exists and is a folder.

The paths

What the outside device asks (CTRL channel)

Remote loading, for anyone who wants to do it on their own (zxv-link is the reference one):

Type Data Reply, after the status
HELLO (1) — Protocol version (u16), whether BASIC is waiting for a command (u8), specification version (u32) and firmware version (text)
OPEN (2) size (u32), path on the card — (what arrives is written aside and gets its name when closed)
DATA (3) position (u32), up to 512 bytes The next position (u32). Out of order: ZXV_E_INVAL and the one it expects; with no file open, ZXV_E_BADF
CLOSE (4) CRC-32 of everything (u32) — (if it does not match, ZXV_E_IO and nothing is written)
RUN (5) the text that is typed, with Enter after it — (with a program running, status 1: below)
STAT (6) path on the card Size (u32) and CRC-32 (u32)
READY (7) — — (when BASIC is waiting for a command; with a program running, status 1)
DBG_READ (8) from (u16), how many (u16) Those bytes of the BASIC debugger's mailbox
DBG_WRITE (9) from (u16), the bytes —
SERVE (10) above above

Status 1 in RUN and READY: a program was running and the machine restarts completely, as with Ctrl+Alt+Del; what was asked is not done. It answers again after a boot (one or two seconds): send HELLO until it says that BASIC is waiting for a command, and ask again.

The versions

HELLO gives the machine's protocol version. This is 4: the EXT: drive (the EXT channel and SERVE). Version 3 brought the machine restart in RUN and READY; version 2, STAT, READY and the debugger. An EXT: server needs a machine with 4 or later.