mirror of
https://github.com/Alvin-Zilverstand/bob16.git
synced 2026-11-21 12:52:59 +01:00
220 lines
14 KiB
Markdown
220 lines
14 KiB
Markdown
# Kernel API
|
|
|
|
Include `runtime.h` in guest kernel source. The host bob16 compiler treats each
|
|
int, char and pointer as a single 16-bit word. These are guest routines, not the
|
|
host C library. Headers and source are compiled together by `kernel/kernel.c`.
|
|
|
|
## Console
|
|
|
|
| Function | Contract |
|
|
| --- | --- |
|
|
| `void print(char *text)` | Print an unpacked ASCII string up to its zero terminator |
|
|
| `void println(char *text)` | Print the string and one newline |
|
|
| `void print_dec(int number)` | Print a signed value, including -32768, without a newline |
|
|
| `void print_hex(int number)` | Print its raw 16 bits as `0x` and four uppercase hex digits |
|
|
| `int read_line(char *buffer, int capacity)` | Read/terminate a line; length on success, -1 for truncation/invalid capacity, -2 for EOF with no characters |
|
|
|
|
The caller must supply a writable buffer of at least capacity words. At most
|
|
capacity-1 characters are stored. Excess characters are consumed until newline,
|
|
so they do not leak into the next command. Newline/CR are not stored. Backspace
|
|
removes a stored character. A partial final line at EOF is returned normally;
|
|
the next read reports EOF. The host terminal supplies line editing and echo.
|
|
|
|
The low-level `bob_putc(int)` sends the low eight bits to stdout. `bob_getc()`
|
|
returns 0..255 or -1 at EOF. `bob_puts()` adds a newline; use print for prompts.
|
|
|
|
`bob_key()` (trap 8) reads a key: -1 EOF, byte character, or 256/257 up/down,
|
|
258/259 left/right, 260/261 home/end, 262 delete. Windows console input uses
|
|
unbuffered keys, converts Enter to newline, and treats Ctrl+D as EOF.
|
|
Ctrl+Z is an ordinary control character: shell EOF, full-screen editor undo.
|
|
Redirected input uses getchar. `bob_terminal()` (trap 9) returns 1 only when
|
|
both input/output are native Windows console handles; otherwise 0. Shell
|
|
history, completion and editing are guest code in `kernel/input.c`; the shell's
|
|
`history` command lists the same four recent entries. ANSI key
|
|
sequences in redirected regression fixtures exercise the same guest actions.
|
|
`bob_columns()` (trap 10) reports the console buffer width, or 80 as fallback.
|
|
The shell scrolls a long input line horizontally to keep redraw within it.
|
|
|
|
## Strings, memory and allocation
|
|
|
|
The kernel-only `bob_snapshot(int *descriptor, int operation)` is trap 7.
|
|
Operation 0 saves; 1 restores. The four-word descriptor contains pointers to
|
|
the 192-word names table, then eight-word length, kind and used tables. File
|
|
contents occupy the fixed `0xF000..0xFFFF` region. Descriptors can be on the
|
|
kernel stack; tables must be disjoint and below `0xA000` in bob16 mode. In
|
|
bob32 mode they may be in low kernel RAM or in the loaded kernel image, which
|
|
now resides above `0x10000`. The host validates
|
|
metadata, payload checksum and complete file length before committing a restore.
|
|
Returns 0 on success, 1 when restored binaries were omitted because the kernel
|
|
changed, -1 for storage errors, -2 for invalid data and -3 for invalid arguments.
|
|
Invocation by a supervised program faults and restores the shell. The default
|
|
host path is `bob-files.b16`; `BOB16_STORAGE` overrides it. See `C_OS.md` for the
|
|
user-facing save/restore workflow.
|
|
|
|
| Function | Contract |
|
|
| --- | --- |
|
|
| `int strlen(char *text)` | Count words before the zero terminator |
|
|
| `int strcmp(char *a, char *b)` | Negative, zero or positive according to the first differing ASCII character |
|
|
| `void memcpy(void *dst, void *src, int count)` | Copy count words forward; source and destination must not overlap |
|
|
| `void memset(void *dst, int value, int count)` | Fill count words with a 16-bit value |
|
|
| `int *alloc(int words)` | Return a zeroed heap block, or null for an invalid size or exhaustion |
|
|
|
|
String routines require terminated strings. Memory routines require valid
|
|
regions; they do not perform bounds checks for kernel callers. Counts are words,
|
|
not host bytes. The bob16 heap reserves 8,192 words from 0xC000; bob32 reserves
|
|
4,096 words from 0xD000 so the enlarged kernel and compatibility-program stack
|
|
fit below it. The heap is shared with loaded programs. There is no free or reset
|
|
operation.
|
|
|
|
## RAM filesystem
|
|
|
|
`file_find(name)` returns a slot or -1. `file_name(slot)` and
|
|
`file_content(slot)` return addresses into the filesystem buffers.
|
|
`file_write(name, data, length, kind)` copies data and creates/replaces a file,
|
|
returning its slot or -1 for a bad name, length or a full table. Kind 0 is text;
|
|
kind 1 is machine code, kind 2 is resident bob32 C code, and kind 3 is a packed
|
|
native B32K v2 image. Its copy appends a zero word, which is not part of length.
|
|
Names hold at most 23 characters. bob16 retains eight fixed 511-word slots;
|
|
bob32 packs files into a protected 8,192-word content region at `0x1E000`,
|
|
between the kernel and supervised-app regions. Text files remain limited to 511
|
|
words; resident programs and native images can use the remaining shared capacity
|
|
(up to 8,191 words per file). Valid slot indices are 0..7.
|
|
These are internal kernel APIs.
|
|
|
|
Failed size/name validation does not overwrite an existing file. Edits start
|
|
with the existing file contents in a scratch buffer and commit on :w, :wq or a
|
|
single dot line. :q protects unsaved changes; :q! or EOF discards them. Oversize
|
|
changes are rejected without modifying the current buffer.
|
|
Resident compilation similarly commits output only after successful parsing and
|
|
code generation. RAM contents disappear when bob.exe stops; save snapshots files for explicit restore in another session.
|
|
|
|
Interactive `edit` uses native `kernel/nano.c`: direct insertion, cursor motion,
|
|
Ctrl+O save, Ctrl+X safe exit with Y/N/Cancel, and Ctrl+Z one-change undo/redo.
|
|
The legacy colon-command interface is only a redirected/unsupported-terminal
|
|
fallback. Both share `0xE000..0xE1FF` text and `0xE200..0xE3FF` undo scratch.
|
|
Resident compilation reuses these regions for code/names/tokens/loop chains;
|
|
it must not run concurrently with editing. History uses `0xE400..0xE5FF`, with
|
|
kernel stack reserved at `0xE600..0xEFFF`. Input buffers are `0x0100..0x01FF`.
|
|
`bob_rows()` (trap 11) reports visible console height, with a 25-row fallback.
|
|
|
|
## Program execution
|
|
|
|
`bob_run(entry)` invokes emulator trap 6. In bob16 mode valid entries are
|
|
0xA000..0xBDFF. In bob32 mode kind-1 legacy entries are 0xC200..0xCFFF and
|
|
kind-2 native entries are 0x20000..0xEFFFF when the caller explicitly supplies
|
|
a wide entry. The shell places legacy programs at 0xC200 in bob32 mode to avoid
|
|
overwriting the bob32 kernel image, and native bob32 files at 0x20000. The entry executes
|
|
with r6 at the top of its protected stack region, r5=0, and r7 pointing to the
|
|
reserved return sentinel. In bob32 mode kind-1 apps use `0xC200..0xCFFF` because
|
|
the expanded kernel occupies the old bob16 program window. Compatibility apps
|
|
retain access to the shared `0xD000..0xDFFF` heap. The shell CPU state is
|
|
restored on completion. RET or TRAP 0 ends the program.
|
|
|
|
Return values -1, -2 and -3 are reserved for invalid entry/nested execution,
|
|
program fault, and timeout. Otherwise r0 is the program's exit status. A program
|
|
returning one of those reserved values is indistinguishable from that service
|
|
status. Five million cycles is the per-run limit. Programs may write only
|
|
their application and stack regions; bob16 and compatibility applications may
|
|
also write the shared heap. Kernel code, RAM files and the shell stack
|
|
are protected from their stores. Program and heap contents themselves are not
|
|
private or restored.
|
|
|
|
The resident compiler uses variable words at 0x9800..0x980F in bob16 mode and
|
|
0xF0000..0xF000F in bob32 mode; string data is inline in the program image.
|
|
In bob16 its files can contain at most 511 code/data words; bob32 compiler output
|
|
uses the available packed filesystem capacity. Console and arithmetic calls
|
|
use the separate program stack. Compiled resident programs depend on addresses
|
|
in the current kernel and should not be reused with a different kernel build.
|
|
|
|
`bob_address(function_name)` is a host-compiler intrinsic that inserts a kernel
|
|
function address. `bob_call(entry)` is an unchecked direct call for trusted
|
|
kernel code; ordinary shell programs use bob_run for recovery and write checks.
|
|
|
|
See [the OS guide](../C_OS.md) for commands, examples and C subset limits.
|
|
|
|
In bob32 mode, `import32 HOST_PATH NAME` validates and packs a B32K v2 image
|
|
into a guest RAM file; `run NAME` loads and executes it. B32S version 3
|
|
snapshots preserve the expanded filesystem; versions 1 and 2 remain readable
|
|
and are migrated to the current storage layout on restore. `run32 HOST_PATH` remains
|
|
available for direct host-path launches.
|
|
|
|
Native C applications can include `bob_string.h` for small app-side string
|
|
and parsing helpers. It provides bounded integer formatting, status-returning
|
|
decimal/hex parsing, and in-place quoted tokenization without depending on the
|
|
kernel's private runtime functions.
|
|
`bob_native.h` is an optional convenience include for the common native API
|
|
surface: core `bob.h` calls, strings, app-managed memory, filesystem, process,
|
|
time, and input events. Graphics and GUI remain opt-in via `bob_gfx.h` and
|
|
`bob_gui.h` so text-only apps do not pull in widget code.
|
|
`bob_memory.h` provides a caller-owned word arena. Keep an integer buffer and a
|
|
used-word counter, request word counts with `bob_arena_alloc`, inspect
|
|
used/remaining capacity, and reset the counter when its allocations are no longer
|
|
needed. Exhaustion and invalid sizes return null; no OS-global heap is reserved.
|
|
Native apps may define `main(int argc, char **argv)`; when launched by guest
|
|
filename, `argv[0]` is that filename and `argc` includes it. `run app first
|
|
"two words"` groups quoted words; backslash escapes the following character
|
|
and `""` supplies an empty argument.
|
|
|
|
`bob_fs.h` exposes the version 1 native-app filesystem service through
|
|
`bob_file_list`, `bob_file_read`, `bob_file_write`, `bob_file_delete`,
|
|
`bob_file_read_words`, `bob_file_write_words`, and `bob_file_kind`. Listing
|
|
returns kind and word-size metadata; `bob_file_kind` queries the kind directly
|
|
by name. Text reads/writes handle up to 511 characters. Word-file
|
|
helpers preserve binary values for bob16 and bob32 program kinds. Native B32K
|
|
images can be read as words, but must use the validated `import32` path to enter
|
|
the filesystem as runnable apps. Applications pass buffers in their own memory,
|
|
while the emulator validates and copies data to keep kernel tables private.
|
|
Files remain in the guest RAM filesystem and follow the normal B32S save/restore
|
|
flow. B32S v3 stores the expanded payload; v1 fixed-slot and v2 packed snapshots
|
|
remain readable.
|
|
`bob_system_info` reports the service version, app address-space size, mapped
|
|
pages, and filesystem slot/word usage through the same versioned boundary.
|
|
|
|
`bob_process.h` adds `bob_app_run(name, arguments, &exit_code)` through version 1
|
|
service operation 6. It launches a stored kind-3 B32K image with shell-style
|
|
quoted arguments, preserves the suspended caller's sparse application memory,
|
|
and separates launch errors from the child's exit code. Nested launches are
|
|
limited to eight active app frames. The API returns -1 when the app name is
|
|
missing, -2 for a non-native file, -4 for invalid data, and -5 when memory is
|
|
unavailable. The `launcher` app lists stored native images and can run one with
|
|
`run launcher APP [ARG ...]`.
|
|
|
|
`bob_time.h` exposes version 1 time operation 7. `bob_time_utc_seconds(words)`
|
|
fills two 32-bit words with the low and high halves of UTC seconds since the
|
|
Unix epoch and returns 2. It returns a negative status for an invalid request.
|
|
|
|
`bob_gfx.h` uses that OS boundary for an 80x25 cell framebuffer: enter/query,
|
|
clear, pixel, filled rectangle, line, text, transparent bitmap blit, present,
|
|
and leave. Each cell carries a 16-color foreground. Draw calls update a back
|
|
buffer; present renders it, and supervised app exit closes an unclosed canvas.
|
|
`bob_gfx_blit_color` accepts transparent row-major cells with an ASCII character
|
|
in bits 0..7 and a foreground color in bits 8..11; invalid cell values reject
|
|
the whole call before drawing.
|
|
`bob_font.h` adds an opt-in 5x7 bitmap font helper. `bob_gfx_bitmap_text`
|
|
rasterizes uppercase letters, digits, space, and common punctuation into the
|
|
canvas via the colored bitmap service; lowercase letters map to uppercase and
|
|
unsupported characters use `?`.
|
|
`bob_event.h` provides `bob_event_wait` and nonblocking `bob_event_poll` with
|
|
four-word events. Poll returns 1 for an event or 0 when the console queue is
|
|
empty; redirected input is left for the blocking wait and is not peeked.
|
|
Version 1 reports typed characters, special-key presses, key releases, mouse
|
|
movement and mouse button transitions when the Windows console provides those
|
|
records. Mouse coordinates are console-cell coordinates; redirected input
|
|
remains character based.
|
|
`bob_event_queue.h` adds an app-owned FIFO for those same four-word events.
|
|
Initialize a two-word `{head,count}` state, allocate four storage words per
|
|
queue slot, then use `bob_event_queue_push`/`pop`; push returns 0 when full
|
|
without overwriting older events, and pop returns 0 when empty. Invalid
|
|
capacity/state returns -1. The queue is optional and requires no OS memory.
|
|
`bob_wm.h` adds a small reusable window manager over caller-provided fixed
|
|
arrays. Initialize it with a window limit and screen size, then use create,
|
|
destroy, focus, raise, move, show/hide, and invalidate operations. Dispatch
|
|
returns a recipient ID, routes keys to the focused visible window, raises the
|
|
topmost clicked window, captures title-bar drags, and supplies window-local
|
|
mouse coordinates. `bob_wm_begin_draw` starts a redraw pass and repeated
|
|
`bob_wm_next_dirty` calls yield visible windows bottom-to-top; geometry and
|
|
stacking changes request a full redraw, while invalidation also marks any
|
|
overlapping windows so they repaint correctly. The manager stores no app-specific
|
|
titles or callbacks; applications keep their own state and draw their own
|
|
contents through `bob_gui.h` and `bob_gfx.h`.
|