Skip to content

<fs/protocols/fsd.h>

fsd's protocol: sessions, requests and the shared buffer.

fsd (fs daemon) is the zuzuOS VFS. It talks to a block driver through a filesystem backend shim and serves clients over a port registered as "/svc/fsd".

Sessions. A caller reaches fsd on an unmarked handle (from LookupService), which may only send FSD_ATTACH, granting a shared page it created (the client pays for it; the page size rides in FsdRequest.data_len). fsd allocates a session, maps the page and replies granting a PERM_SEND|PERM_TXFR duplicate of its own port stamped with a marker, FSD_BADGE(generation, slot). Every later request goes on that badged handle; fsd reads the marker from the receive result and rejects anything that does not match a live session, so a session cannot be guessed or forged. FSD_DETACH frees the session; so does the death of the client, once it has sent FSD_WATCH with a port it owns. fds are per session.

Requests. The payload is an FsdRequest in the message buffer. Paths and file data live in the shared page at data_off >= FSD_DATA_OFF; fsd checks data_off/data_len against the page and copies a path out before using it. The reply payload is an FsdResponse in the message buffer; READ, STAT, READDIR results are placed in the shared page at resp.data_off.

#include <fs/protocols/fsd.h>

Constants

Name Value Description
FSD_DATA_OFF 128u Payloads start at or after this offset in the shared buffer.
FSD_PAGE_SIZE 4096u Shared buffers are sized in pages of this many bytes.
FSD_SHM_MIN 4096u Smallest shared buffer fsd accepts.
FSD_SHM_DEFAULT (64 * 1024) Suggested shared buffer size.
FSD_SHM_MAX (4 * 1024 * 1024) Largest shared buffer fsd accepts.
FSD_BADGE(gen, slot) Session marker: generation above bit 8, session slot below.
FSD_BADGE_SLOT(badge) Session slot of a marker.
FSD_BADGE_GEN(badge) Session generation of a marker.
FSD_MODE_READ 0x01 OPEN: read access.
FSD_MODE_WRITE 0x02 OPEN: write access.
FSD_MODE_CREATE_NEW 0x04 OPEN: create the file; fail if it exists.
FSD_MODE_CREATE_ALWAYS 0x08 OPEN: create the file, or truncate it if it exists (O_CREAT | O_TRUNC).
FSD_MODE_OPEN_ALWAYS 0x10 OPEN: create the file if it is missing (O_CREAT).
FSD_MODE_OPEN_APPEND 0x30 OPEN: open or create, positioned at the end (O_APPEND).

Enumerations

FsdWhence

What a SEEK offset is relative to.

Name Value Description
FSD_SEEK_SET 0 The start of the file.
FSD_SEEK_CUR 1 The current position.
FSD_SEEK_END 2 The end of the file.

FsdFileType

Kind of a directory entry.

Name Value Description
FSD_TYPE_FILE 0 Regular file.
FSD_TYPE_DIR 1 Directory.
FSD_TYPE_SYMLINK 2 Symbolic link.

FsdCommand

Request commands.

Name Value Description
FSD_ATTACH 1 On the unmarked handle: grants the shared buffer, data_len = its size; replies with the session's badged port.
FSD_OPEN 2 Path in the buffer, mode; replies fd.
FSD_CLOSE 3 fd.
FSD_READ 4 fd, data_len = count; replies count, data in the buffer.
FSD_WRITE 5 fd, data_len = count, data in the buffer; replies count.
FSD_SEEK 6 fd, offset, whence; replies the new offset.
FSD_STAT 7 Path in the buffer; replies an FsdStat in the buffer.
FSD_FSTAT 8 fd; replies an FsdStat in the buffer.
FSD_READDIR 9 Path in the buffer, offset = first entry; replies FsdDirEntry records and count.
FSD_UNLINK 10 Path in the buffer.
FSD_RENAME 11 Two paths in the buffer.
FSD_DETACH 12 Ends the session.
FSD_WATCH 13 Grants a port the client owns (PERM_WAIT | PERM_TXFR); fsd frees the session when it dies.
FSD_READ_OBJ 14 Grants a memory object (PERM_MAP | PERM_WRITE | PERM_TXFR); fd, data_off = offset into the object, data_len = count. Replies count; the data lands in the object.

Structures

FsdRequest

A request, in the message buffer.

Field Type Description
size uint32_t sizeof(FsdRequest); the client sets it, fsd checks it.
cmd uint32_t An FsdCommand.
data_off uint32_t Offset of the payload in the shared buffer, at least FSD_DATA_OFF.
data_len uint32_t Payload length, or the byte count for READ and WRITE.
offset int64_t SEEK offset, or the first entry for READDIR.
fd uint32_t File descriptor, for commands on an open file.
whence uint32_t SEEK: an FsdWhence.
mode uint32_t OPEN: FSD_MODE_* flags.
flags uint32_t Reserved; 0.

FsdResponse

A reply, in the message buffer.

Field Type Description
size uint32_t sizeof(FsdResponse); fsd sets it.
status Err ZUZU_OK, or an error code.
data_off uint32_t Where fsd put the payload in the shared buffer.
data_len uint32_t Payload length.
offset int64_t SEEK: the new absolute position.
count uint32_t Bytes for READ and WRITE, entries for READDIR.
fd uint32_t OPEN: the new file descriptor.
flags uint32_t Reserved.
_rsv uint32_t Reserved.

FsdDirEntry

One READDIR entry in the shared buffer; 64 bytes.

Field Type Description
name char NUL-terminated UTF-8 name.
size uint32_t File size in bytes.
type uint8_t An FsdFileType.
_pad uint8_t Padding.

FsdStat

STAT and FSTAT result in the shared buffer.

Field Type Description
size uint32_t File size in bytes.
type uint8_t An FsdFileType.
_pad uint8_t Padding.
mtime uint32_t FAT date << 16 | FAT time; 0 when the backend cannot say.