acstorage/--background--
PURPOSE
ACStorage is the Zorro-II AutoConfig board through which a guest
reaches host folders. This file documents the board's registers
and commands, the contract between acscsi.device and the host.
Constants are in common/protocol/acstorage.h.
BOARD
Manufacturer 2011, product 2. All registers are 32-bit
big-endian.
0x0000 SIGNATURE reads 0x41435331 ("ACS1")
0x0004 VERSION 0x00010002 or later is required
0x0008 CAPABILITIES
0x000c STATUS IDLE 0, BUSY 1, COMPLETE 2, ERROR 4
0x0010 COMMAND write to start a command
0x0014 ARG0 unit: 0-7 = DH0-DH7, 8 = BOOT
0x0018 ARG1
0x001c RESULT ACSTORAGE_RESULT_xxx
0x0020 EVENT
0x0024 ARG2
0x002c LENGTH request or reply length in bytes
0x0030 FLAGS
0x0100 MAILBOX request and reply bytes
0xff00 BOOT ROM autoboot code (not part of the mailbox)
The mailbox runs from 0x0100 to 0xfeff, 65024 bytes.
SEQUENCE
1. Write the request bytes to the mailbox and their count to
LENGTH. Paths are UTF-8, volume-relative, with no leading slash.
2. Write ARG0, ARG1, ARG2 and FLAGS as the command needs.
3. Write COMMAND.
4. Poll STATUS until it is COMPLETE or ERROR.
5. Read RESULT. If it is OK, the reply is LENGTH bytes in the
mailbox, replacing the request.
The guest writes and the host reads the request through the same
addresses that later hold the reply; do not read the mailbox until
STATUS has left BUSY.
RESULT CODES
STATUS says whether the command ran. RESULT says what happened to
the filesystem. RESULT is not an HTTP status or an Exec io_Error.
0 OK 5 ACCESS 10 RANGE
1 NOT_FOUND 6 READ_ONLY 11 IO
2 EXISTS 7 INVALID_NAME 12 PROTOCOL
3 NOT_EMPTY 8 NO_SPACE
4 IN_USE 9 WRONG_TYPE
RECORDS
Reply records are big-endian. Each starts with a 4-byte signature
so a stale or misread mailbox is caught.
SEE ALSO
acscsi.device/--background--acstorage/ACSTORAGE_CMD_DELETE
NAME
ACSTORAGE_CMD_DELETE (0x17) -- delete a file or empty directory
REQUEST
ARG0 unit
MAILBOX path
REPLY
No data. RESULT only; NOT_EMPTY for a directory with contents.acstorage/ACSTORAGE_CMD_LIST
NAME
ACSTORAGE_CMD_LIST (0x12) -- one page of a directory
REQUEST
ARG0 unit
ARG1 index of the first entry
ARG2 most entries to return
MAILBOX directory path
REPLY
"ACL1" record:
0 signature 0x41434c31 "ACL1"
4 count
8 nextIndex 0xffffffff when there are no more
then count entries, each:
0 u16 nameBytes
2 u8 entryType 1 = file, 2 = directory
3 u8 reserved
4 u32 size
8 u32 mtime
12 name, nameBytes of UTF-8, no terminatoracstorage/ACSTORAGE_CMD_MKDIR
NAME
ACSTORAGE_CMD_MKDIR (0x16) -- create one directory
REQUEST
ARG0 unit
MAILBOX path
REPLY
No data. RESULT only.acstorage/ACSTORAGE_CMD_READ_FILE
NAME
ACSTORAGE_CMD_READ_FILE (0x13) -- read bytes from a file
REQUEST
ARG0 unit
ARG1 byte offset
ARG2 most bytes to return, up to the mailbox size
MAILBOX path
REPLY
The data. LENGTH is the byte count, less than ARG2 at end of file.acstorage/ACSTORAGE_CMD_RENAME
NAME
ACSTORAGE_CMD_RENAME (0x18) -- rename or move on one volume
REQUEST
ARG0 unit
MAILBOX old path, a 0 byte, new path
LENGTH old bytes + 1 + new bytes
REPLY
No data. RESULT only.acstorage/ACSTORAGE_CMD_SET_SIZE
NAME
ACSTORAGE_CMD_SET_SIZE (0x15) -- truncate or extend a file
REQUEST
ARG0 unit
ARG1 new size
MAILBOX path
REPLY
No data. RESULT only.acstorage/ACSTORAGE_CMD_STAT
NAME
ACSTORAGE_CMD_STAT (0x11) -- type, size and date of a path
REQUEST
ARG0 unit
MAILBOX path
REPLY
"ACS2" record, 16 bytes:
0 signature 0x41435332 "ACS2"
4 entryType 1 = file, 2 = directory
8 size
12 mtime seconds since 1 Jan 1970acstorage/ACSTORAGE_CMD_VOLUME_INFO
NAME
ACSTORAGE_CMD_VOLUME_INFO (0x10) -- describe a volume
REQUEST
ARG0 unit
LENGTH 0
REPLY
"ACV2" record, at least 32 bytes:
0 signature 0x41435632 "ACV2"
4 flags 1 = bootable, 2 = read-only
8 bootPriority (signed)
12 blockSize
16 cylinders
20 heads
24 sectorsPerTrack
28 lbaSectors
32 label, UTF-8, LENGTH - 32 bytes, no terminatoracstorage/ACSTORAGE_CMD_WRITE_FILE
NAME
ACSTORAGE_CMD_WRITE_FILE (0x14) -- write bytes to a file
REQUEST
ARG0 unit
ARG1 byte offset
ARG2 data bytes
FLAGS 1 = TRUNCATE first, 2 = CREATE if missing
MAILBOX path, a 0 byte, then the data
LENGTH path bytes + 1 + data bytes
REPLY
No data. RESULT only.
NOTES
acscsi.device splits a large write into several commands and sends
TRUNCATE only with the first.