System calls

Console and process.

Set the shell colours; values outside 0-15 keep the current one. Returns foreground | background << 8 | prompt << 16 | error << 24. Saving is the caller's job.

1 if a key is waiting (not taken).

Sleep without spinning. Keys arriving meanwhile stay buffered.

Key down/up events (unshifted identity, KOI_KEY_* for special keys). Returns 0 when none. Independent of the character queue. A program in a terminal gets none (its keys are the terminal's) unless it asks with KOI_KEYEVENT_SCREEN: it has a desktop window of its own, which has the keyboard (SDL).

Cursor position (columns, rows; see KOI_INFO_TEXT_COLUMNS/ROWS) and visibility.

Files. Handles are small non-negative integers; -1 means failure.

Move the file position.

Delete and rename.

Change this program's current drive (the shell's is unaffected). The directory resets to the root. Directory enumeration.

Does a path exist?

Make a directory.

Environment.

System information: one numeric and one text call, selected by item and index. Unknown items return -1.

Memory in whole pages, released automatically when the program exits.

Graphics. A program takes the screen, draws into its buffer, presents, and gives it back; the console is restored exactly. Nothing appears until SYS_GFX_PRESENT. The KOI_SCREEN buffer may be written directly.

Present one rectangle (clipped).

(point, text, colour, background | style << 32): bold, italic, underline.

Darken a rectangle; `keep` out of 256.

Copy a rectangle of pixels (stride in pixels).

Sound. One 48 kHz stereo stream always runs; a sound gets a voice, or -1. Samples are not copied: keep the buffer until the sound ends. Voices stop when the program exits.

Change volume or pan of a playing sound (-1 keeps).

Pointer: one snapshot per call. `scroll` is a running total; callers subtract.

Move the pointer.

Chaining: run a command line after this program exits, most recent request first: koi_chain("MIZU Z:\\GAMES"); runs second koi_chain("DOOM"); runs first koi_exit(0); The program restarts fresh; pass state as arguments. SYS_RUN keeps the caller in memory instead.

Clipboard: text in kernel memory, outliving the program. SYS_CLIP_GET with a null buffer returns the length.

Log: programs write into the kernel log. SYS_LOG_BYTES adds a hex dump. SYS_SECTOR_READ reads a raw sector (no write counterpart).

Run a command and return when it finishes (the caller stays in memory). A program holding the screen should give it back first.

Environment, read-only for programs. SYS_GETENV returns the value length (0 if none); SYS_ENVAT lists by index (0 past the end). Enable the Alt+Shift layout switch while this program runs (reset on exit).

Loadable modules: load and relocate an image without running it and return its entry point. The caller calls it like a function; its meaning is the caller's (Mizu applications). Same format and ABI check as programs. SYS_LOAD fills a KOI_MODULE and returns 0, or -1 with the reason printed. SYS_UNLOAD frees by `base` (unknown bases, and modules a thread is still in, are refused). Run a command and collect its console output into the caller's buffer (no screen change). Returns the bytes collected, zero-terminated. The caller waits; commands that wait for a key are stopped. For programs that draw, use SYS_RUN.

Whether Ctrl+C stops this program (0 makes it an ordinary character). Reset on exit.

Streaming sound: open a stream and queue decoded frames (copied into a kernel ring). Fewer frames taken than offered means the ring is nearly full.

Pause any voice; flush a stream's queue (for seeking).

Network for programs: DNS and TCP. Calls block with a timeout and poll the network. Addresses in host order.

TLS: the same calls over TLS. SYS_TLS_CONNECT also takes the host name (SNI and certificate check). SYS_TLS_CHECKED returns 1 when the server's identity was verified.

Threads: same memory and files, own stack (provided by the program, top passed in). No protection between threads; use the lock in koi.h.

Yield the rest of the time slice.

Set the calling thread's FS base (thread pointer), kept across switches (like arch_prctl(ARCH_SET_FS)).

virtio-gpu for programs (see kernel/virtio_gpu.h): SYS_GPU_INFO KOI_GPU_PRESENT, KOI_GPU_3D or KOI_GPU_CAPSETS SYS_GPU_COMMAND one command and its reply; returns the reply length or -1 (commands touching guest memory are refused) SYS_GPU_ATTACH backing memory for a resource; returns its address or 0 SYS_GPU_DETACH release it before unreferencing the resource

Intel graphics for programs (see kernel/i915.h): SYS_INTEL_INFO KOI_INTEL_DEVICE (0 without a driver) or KOI_INTEL_GTT_SIZE SYS_INTEL_ALLOC `size` zeroed bytes; returns the CPU address, writes the GPU address to *gpu, or returns 0 SYS_INTEL_FREE by CPU address SYS_INTEL_EXEC run the batch at a GPU address (ends in MI_BATCH_BUFFER_END); returns a sequence or 0 SYS_INTEL_WAIT 1 when the sequence finished, 0 on timeout

Network settings: SYS_NET_INFO fill a KOI_NET_INFO SYS_NET_START DHCP again (may take seconds): 1 with an address, else 0 SYS_NET_SET static: address, netmask, gateway << 32 | dns; 1 when set Not saved across restarts.

Devices on the PCI bus and the driver running each (Device Manager).

SHA-256 of `length` bytes into 32 (the kernel's, for passwords).

The command shell (COMMAND.EXE). SYS_CHDIR moves the one current drive and directory that programs and commands share ("X:" changes the drive): 1, or 0 no such drive, -1 not found, -2 not a directory. SYS_SETENV sets a variable, an empty value removes it: 1, or 0 when there is no room.

Serving: listen on a port, then accept connections (with a timeout).

Random bytes from the kernel's generator (the one TLS uses): for keys and nonces. At most 4096 per call. Returns the count, or -1.

Surfaces: pixels of the program's own (a window's, say), drawn into with the SYS_GFX_* calls and copied onto the screen. Numbers from 1; 0 is the screen. NEW a: KOI_POINT(width, height), b: KOI_SCREEN* to fill -> number, or -1 FREE a: number -> 0, or -1 TARGET a: number (0: the screen) for this thread's drawing calls -> the one before, or -1 COPY a: number, b: KOI_POINT where, onto the current target (clipped) -> 0 ORIGIN a: number, b: KOI_POINT: drawing at that point lands at the surface's (0, 0), so a window draws in screen places -> 0, or -1 The kernel frees a program's surfaces when it ends.

Messages between programs (19): a mailbox per program; a program is addressed by its id (KOI_INFO_PROGRAM_ID, slot and generation, so a reused slot is not mistaken for it). Messages are 1 to 4096 bytes and arrive in order. SYS_MESSAGE_SEND: 1 sent, 0 the mailbox is full (try again), -1 no such program. SYS_MESSAGE_RECEIVE waits up to the timeout: the length, 0 nothing came, -1 the buffer was too small (the message is dropped); the sender's id goes to `from`. SYS_MESSAGE_NAME registers this program under a name or finds the one holding it (names starting MIZU. only for programs of the system; the desktop is MIZU.DESKTOP).

Terminals (20): a window that a program (a shell) runs in. Everything the program and its children print comes to the window, which reads it with READ; keys the window passes with WRITE are what they read (a line is edited and echoed by the kernel). Ctrl+C (key 3) stops the program that has not turned it off; the shell gets it as a key. A program that draws on the screen is refused while attached to one. OPEN a: command line, b: KOI_POINT(columns, rows) -> terminal, or -1 READ a: terminal, b: buffer, c: size -> bytes (0 none yet), -1 the program ended and all it said has been read WRITE a: terminal, b: int keys, c: count -> keys taken SIZE a: terminal, b: KOI_POINT(columns, rows) -> 0 CLOSE a: terminal -> 0 (its programs stop at their next call)

A connection's state without waiting (21): the bytes waiting to be read in the low 32 bits, and flags. -1 for no such connection.

Pipes between programs (23). An end is a number the program owns until it closes it or ends. CREATE b: int[2] gets the reading and the writing end -> 0, or -1 READ b: end, c: buffer, d: size -> bytes, waiting for at least one; 0 once every writer has gone WRITE b: end, c: data, d: size -> bytes, waiting for room; -1 once every reader has gone CLOSE b: end -> 0 NEXT b: 0 stdin, 1 stdout, 2 stderr; c: an end, or 0 -> the next program this one starts gets it as that stream STANDARD b: 0, 1 or 2 -> this program's end for that stream, 0 if the stream is its terminal PENDING b: a reading end -> bytes waiting, -2 at the end, 0 none yet A program whose stdout is a pipe prints into it (SYS_PUTS and the rest); one whose stdin is a pipe reads its lines and keys from it.

Signals and process groups (24), Linux's signal numbers. A signal is acted on at the program's next system call. Handled ones are ORed into the word the program named (bit 1 << signal); ignored ones go; the rest end it with 128 + the signal, except CHLD, CONT, URG, WINCH and the stopping ones, which do nothing. Ctrl+C is SIGINT to the terminal's foreground group; a program that ends sends SIGCHLD to the one that started it. WATCH b: the word, c: handled mask, d: ignored mask -> 0 SEND b: a program's name, or -group, or 0 for its own group; c: the signal (0 to ask if it is there) -> 0, or -1 SELF -> its name (the pid) PARENT -> its parent's, 0 none GROUP b: a name, 0 itself -> its group SET_GROUP b: itself (0) or a child; c: a group, 0 its own -> 0 or -1 SESSION b: a name, 0 itself -> its session NEW_SESSION -> a session and group of its own, their name FOREGROUND -> its terminal's foreground group, 0 without a terminal SET_FOREGROUND b: a group -> 0, or -1

A futex: threads of one program waiting on a word of its memory. WAIT b: the word (4 bytes), c: the value it must still hold, d: milliseconds at most (<= 0: a long while) -> 0 woken or the time ran out, -1 the word held another value WAKE b: the word, c: how many to wake -> how many were woken A wait may also end for no reason; the caller looks at the word again. Added in build 150 without a new interface version: before it, the call answers -1 for both, and a caller gives its turn away and looks again.

Disk count and sector size.

Set the clock: (KOI_DATE_ARG(year, month, day), KOI_TIME_ARG(hour, minute, second)) -> 1, or 0 if invalid.

SYS_SCREEN_SET: change the screen size now (Intel Sandy Bridge, QEMU std VGA; modes that `screen` lists). Only the caller may hold the screen; if it does, *screen gets the new buffer. Not saved (use `screen WxH`). Returns 1 done, 0 not possible, -1 another program holds the screen.

Installing onto a disk (Setup /I). SYS_DISKS every disk: KOI_DISK_INFO into `array`, up to `max` SYS_PARTITIONS partitions of disk `disk`: KOI_PARTITION_INFO SYS_INSTALL install as KOI_INSTALL says; blocks until done SYS_INSTALL_STATUS progress of a running SYS_INSTALL (from another thread)

Packages (DOSGET.EXE). The kernel fetches from the package server, checks signatures with its own key, and writes system updates; the rest is the program's.

Input from elsewhere (remote desktop), fed in as if typed or moved. KOI_INPUT_POINTER: (point, buttons | wheel << 8), absolute position. KOI_INPUT_KEY: (key, typed | KOI_KEY_RELEASED): `key` is the key's identity as in SYS_KEYEVENT, `typed` what it types (0 for none): a KOI_KEY_ value, a control code, or a character (Unicode, not passed through the layout).

The kernel log (what `log` shows) from `offset`: bytes copied, 0 at the end.

Turn profiler: marks the start of a unit of work; the one before, if it took `slow_ms` or more, is logged ("SLOW:") with where its time went.

Pointer drawn and moved by the kernel over the caller's screen level, so it moves while the program is busy. KOI_SPRITE_SHAPE: data = { width, height, pixels... } (at most 32 x 32; opaque where the top byte is set).

(what) -> -1 if the machine stayed on: KOI_POWER_OFF or KOI_POWER_RESTART. File operations in progress end first, the rest wait; disk caches are written out.

Keyboard layouts (kernel/layout.h): what a := KOI_LAYOUT_*. GET the one typing now, as two letters packed ('r' << 8 | 'u') LIST the set into b ("en ru el", size c) SET_LIST the set from b; 1 if any code was known SWITCH how to switch (b: KOI_LAYOUT_SWITCH_*, -1 asks) NEXT the next one in the set Not saved: the SYSTEM settings `layouts` and `layout_switch` are.

Sound outputs (the built-in device, USB ones plugged in): what a := COUNT how many NAME the name of output b into buffer c (64 bytes) CURRENT the one playing (an index) SELECT play through output b CHANGES a count that moves when one comes or goes

Flight recorder: what the kernel did lately, as 32-byte records (time in microseconds since boot, kind, processor, task), and copies of it from around each hitch (a desktop turn over the threshold, or Ctrl+Alt+M: the last three seconds, kept by hand). What a := RECENT the newest records into c (KOI_TRACE_MAX), oldest first -> count HITCHES the kept hitches' headers into c (KOI_HITCH_KEEP) -> count HITCH hitch b's records into c (KOI_TRACE_MAX) -> count THRESHOLD set it to b ms (0: leave it) -> the threshold LINES log line times into c (KOI_LINE_MAX pairs: offset, time) -> count LOG_START the oldest log offset still kept after the boot part, and the boot part's length in c (two numbers) -> 0 NAMES the tasks' names now into c (KOI_TRACE_TASKS x 32 bytes) -> 0

Devices on USB, hubs included, from every controller (Device Manager).