Files
2026-10-08 23:36:34 +02:00

641 lines
37 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# bob16 OS
The kernel, shell and resident C compiler run as native bob16 instructions.
All project code is C or BASM. No Python or Python packages are used.
## Run now
Start the supplied `bob.exe`, then enter `kernel.basm` at its source-file prompt.
The kernel prints `bob!` and opens `bob>`. Type `help` for commands.
If the emulator starts in another directory, enter the full path to `kernel.basm`.
The supplied emulator has been rebuilt for the new kernel services; older
executables lack the character-input and supervised-program traps.
Alternatively run `bob.exe --boot build/kernel.b16` from the repository root.
To build and boot the native 32-bit kernel, close the current emulator session
and run `build.exe --run32`. The build also creates `build/kernel32.b32`, which
can be started directly with `bob32.exe --boot build/kernel32.b32`. The native
kernel supports the shell, RAM files, editor, resident C compiler, supervised
bob16 applications and B32S snapshots. In B32 mode, `cc` and `go` compile the
resident C subset to native bob32 programs with 32-bit `int`; kind-1 bob16 apps
still run with 16-bit arithmetic compatibility. The host `bobcc --wide` option
also emits native bob32 application images for direct boot.
The host compiler also emits a runnable bob32 BASM listing; start it with
`bob32.exe --asm32 build/program.basm`.
To build a native bob32 application for the running bob32 OS, preprocess the C
source and compile it with `--wide-app`:
```text
gcc -E -P -nostdinc -undef -I kernel app.c -o build/app.i
build/bobcc build/app.i build/app.basm build/app.b32 --wide-app
```
Then start the B32 OS with `build.exe --run32` and enter `run32 build/app.b32`.
The application uses the supervised high-memory region and its own 32-bit
stack. `run32` validates the B32K v2 header, range, checksum and file length
before loading it. The image limit is 65,536 words. Apps load from the emulator
host's working directory and are not stored in the guest snapshot. To keep an
image in the guest filesystem, use `import32 build/app.b32 myapp`, then launch
it with `run myapp`. `save` includes imported applications in the B32S snapshot;
after `restore yes`, run them again without re-importing. `run32` remains
available for direct host-path launches.
Native applications may define either `int main(void)` or the conventional
`int main(int argc, char **argv)`. For the latter, `argv[0]` is the guest app
name and `argc` includes it. Pass arguments with `run myapp first "two words"`;
quotes group spaces and backslash escapes the next character. Empty quoted
arguments are preserved. This applies to imported guest files; direct host-path
`run32` launches currently start without command-line arguments.
Native applications can use `bob_fs.h` for guest RAM files. Its version 1
service supports listing names/kinds/sizes, direct kind lookup by filename,
reading and writing text files and
raw bob16/bob32 program words, and deleting files. Text writes are bounded to
the text-file limit; binary writes accept only program kinds. Native B32K apps
must enter storage through validated import. The OS keeps filesystem tables
private to the kernel. See [the native app examples](apps/README.md)
for `echo`, `ls`, `cat`, `sysinfo`, and the snapshot-friendly `notes` app.
`launcher` lists stored native bob32 applications and runs one with arguments;
native apps can use `bob_process.h` to launch another stored app and receive its
exit code. The emulator preserves the suspended app's memory while a child runs.
`bob_memory.h` provides a small caller-owned word arena for temporary app data.
Give it an integer buffer, allocate in target words, inspect used/remaining space,
and reset it for reuse. Allocation returns null for invalid requests or when the
buffer is full; it reserves no global OS heap.
Native apps can include `bob_time.h` to read UTC seconds through the versioned
OS-service boundary. The result is returned as low and high 32-bit words.
`bob_system.h` reports the system-service version, cell-framebuffer presence
and size, and whether keyboard and mouse input are available. `sysinfo` displays
these device capabilities alongside the filesystem and application-memory
usage.
For convenience, `bob_native.h` includes the common string, memory, filesystem,
process, time, system-capability, and input-event APIs. Add `bob_gfx.h` and
`bob_gui.h` separately when building graphical apps.
`bob_gfx.h` provides the first graphics abstraction: apps draw into an 80x25
cell framebuffer, then present it through the emulator’s terminal backend.
The API includes resolution, pixels, rectangles, lines, text, transparent
bitmap cells with per-cell foreground colors, clear, present and leave.
`bob_font.h` adds a 5x7 bitmap text renderer for uppercase letters, digits,
space, and common punctuation.
`apps/graphics_demo.c` draws a sample
screen, waits for a key through `bob_event_wait`, and returns to the shell.
The GUI demo's Window B includes a keyboard- and mouse-driven native app
launcher; it runs stored apps through `bob_process.h` and shows their exit status.
Press `?` for a bitmap-font help panel; Escape or its Close button returns to
the desktop.
Event version 1 delivers character and special-key down/up events. On Windows
console input it also delivers mouse movement and button transitions with
screen-cell coordinates, plus signed mouse-wheel deltas. `bob_event_wait`
blocks; `bob_event_poll` checks the console queue without blocking. Redirected
input remains character based and is consumed by the blocking path. This
cell-based backend establishes the app boundary before adding a true pixel
surface.
`bob_event_queue.h` provides a caller-owned FIFO for buffering these events;
overflow is reported without overwriting queued input.
`bob_wm.h` provides the reusable bob32 window manager. Applications give it fixed
arrays for window records and stacking order; it owns allocation, visibility,
focus, z-order, hit testing, title-bar dragging, event routing, and dirty-window
tracking. `bob_wm_dispatch` returns the window ID for an event, routes keyboard
input only to the focused visible window, and rewrites mouse coordinates to be
relative to the recipient. `bob_wm_begin_draw` and `bob_wm_next_dirty` return
visible dirty windows in stacking order; moving, hiding, raising, or destroying
a window requests a safe full redraw, while content invalidation marks the
affected window and overlaps. `bob_gui.h` adds reusable window, button,
popup-menu, single-line text-field, and multiline text-area widgets.
`apps/gui_demo.c` uses the manager for its editor and file-browser windows and
draws only the dirty windows during normal interaction; modal help, launcher,
and menu panels use full redraws. It draws a desktop
with a multiline text editor and file browser. The editor starts with `new.txt`
and `bob!`, supports mouse caret placement, insertion, deletion, Enter for new
lines, arrow/Home/End navigation, vertical movement, mouse-wheel scrolling,
and horizontal scrolling for long lines. Tab cycles through the filename field,
text area, and file browser; Ctrl+S saves the current text file. Press `e` in
the file browser to load the selected text file into the editor, then Ctrl+S to
save changes. The browser immediately lists the saved file and can preview or
delete text files with confirmation. Clicking a window raises it, dragging its
title bar moves it, and Escape returns to the
shell. Dragging is clamped to
the screen edges. A clickable button in Window A focuses Window B. Window B lists guest filesystem entries and previews selected text files; use
`n`/`p` or the mouse to change selection and Up/Down or `u`/`d` to scroll the
preview. Press `x` to show Yes/Cancel controls; click one or press `y`/`n`.
Window B also has a File popup opened with `m` or by clicking its title area;
the menu supports keyboard and mouse selection to open or delete the selected
text file, or close the popup. It follows Window B when dragged and clamps to
the screen edges.
Set `BOB16_TRACE_FAULT=1` before launching the emulator to log the address and
instruction when a supervised application faults.
The updated emulator also accepts `bob.exe --os` from that directory to boot
the supplied image directly. The welcome message points to `help` and `go bob.c`.
## Small application string library
Native C applications may include `bob_string.h` along with `bob.h`. The string
header supplies word-addressed `bob_strlen`, `bob_strcpy`, `bob_strcmp`,
`bob_strcat`, and `bob_strchr`, plus `bob_isspace`, `bob_parse_int`,
`bob_format_int`, and `bob_token_next`. It is included in the app translation
unit, so the compiler emits only helpers reachable from that app; no separate
library link step is needed. The caller provides enough space for copy/append
destinations. `bob_parse_int` accepts signed decimal or `0x` hexadecimal with
surrounding whitespace and reports validity through its second argument.
`bob_format_int` returns the character count or -1 when the output buffer is
too small. `bob_token_next` edits a writable command buffer in place, groups
single- or double-quoted text, honors backslash escapes, and returns 1 for a
token, 0 at end, or -1 for an unclosed quote.
## Commands
| Command | Behavior |
| --- | --- |
| `help` / `help COMMAND` | Show commands or detailed usage and examples |
| `echo bob!` | Print text |
| `clear` | Clear an ANSI-capable terminal |
| `mem` | Show heap usage and memory regions |
| `peek 0xC000` | Read a word |
| `poke 0xC000 98` | Write a word in the heap (bob16 mode) |
| `alloc 32` | Allocate and zero 32 words; print their address |
| `list` | List RAM files, lengths and kinds |
| `ls` / `dir` | Aliases for list, with the same RAM-file view |
| `copy old new` | Copy text or program contents to a new name |
| `rename old new` | Change a name, including when all slots are full |
| `delete name` | Permanently remove a RAM file and free its slot |
| `read name` | Print a text file |
| `write name bob!` | Create or replace a one-line text file |
| `edit name` | Open/create text in the full-screen editor (Windows console) |
| `cc bob.c bob` | Compile a C source file inside the emulator |
| `cc bob.c` | Compile to the default program file `app` |
| `go bob.c` | Compile to `app` and run only if compilation succeeds |
| `go bob.c bob` | Compile and run with an explicit output name |
| `save` | Save all files to a host snapshot |
| `restore yes` | Validate/load that snapshot, replacing the RAM files |
| `load name 0x4001 ...` | Store raw bob16 machine words as a program file |
| `run name` | Load a program into reserved RAM and run it; native apps accept arguments |
| `run32 path` | Load and run a native B32K v2 image from a host path or guest filename |
| `import32 path name` | Import a host B32K v2 image into bob32 RAM files |
| `halt` | Stop the emulator |
Command lines hold up to 127 characters. Longer lines are completely consumed
and rejected so their tail cannot become another command. Input is terminated
and handles CRLF, backspace and EOF. Decimal input accepts -32768..65535;
positive values above 32767 represent their 16-bit bit pattern. Hex accepts
0x0000..0xFFFF. Addresses are word addresses; allocation sizes must be positive.
## Shell keys
In a native Windows console, the shell supplies editing and redraw itself:
| Key | Action |
| --- | --- |
| Up / Down | Browse the four most recent nonempty commands; Down restores the draft |
| Left / Right | Move within the command |
| Home / End or Ctrl+A / Ctrl+E | Move to the start/end |
| Backspace / Delete | Remove before/at the cursor |
| Ctrl+U | Clear the line |
| Tab | Complete a unique command or filename; list ambiguous matches |
| Ctrl+D / Ctrl+Z | End input |
Completion operates on the word at the end of the line. Type more characters
when matches are ambiguous. The `history` builtin lists the same four recent
commands. History is session-only, includes failed commands,
and skips consecutive duplicates. `edit` opens its own full-screen view in a
Windows console. Redirected input emits no
redraw or candidate lists. Other terminals use ordinary input; full interactive
key handling currently targets the native Windows console.
The RAM filesystem has eight slots and names up to 23 characters. bob16 keeps
eight fixed 511-word slots. bob32 packs files into 8,192 words total; text and
resident programs remain limited to 511 words, while native apps use six
metadata words plus payload and a terminator, sharing space with other files.
A character occupies one word. `bob.c` occupies one slot initially. Unsaved
files and allocations are lost on exit. Use `save` to retain
files between sessions. Allocation is a zeroing bump allocator with no freeing. `poke` is
restricted to heap RAM so it cannot corrupt the shell.
Copy and rename refuse to overwrite an existing destination. Choose a new
name or explicitly delete the destination first. Delete has no undo. Names
cannot contain spaces. Both commands preserve whether a file is text or a
program; copying requires a free slot, while renaming does not.
To try the supplied example, enter `go bob.c`; its output is `bob!`, followed
by `Exit 0`. The compiler refuses to replace its own source. On failure it
leaves an existing output intact and `go` does not run that old program.
Diagnostics report the first detected error's character offset, line and
column (one based); the location can be just after the token that caused it.
## Keep files between sessions
Run from the repository directory, then enter:
```text
write note bob!
go bob.c
save
halt
```
Start the emulator again, enter `kernel.basm` (or use `--os`), and enter
`restore yes`, then `read note` or `run app`. Restore is explicit; startup does
not automatically replace the supplied `bob.c` or other RAM files.
The default snapshot is `bob-files.b16` in the emulator's working directory.
`save` replaces the previous snapshot, first writing `bob-files.b16.tmp` and
then replacing the destination. Keep a copy of the snapshot for older versions.
Set the host environment variable `BOB16_STORAGE` to choose another file path;
the parent directory must already exist. Messages mention this override.
Restoring replaces **all** RAM files; use `save` first if current files matter.
An invalid, truncated, corrupt or unreadable snapshot leaves RAM unchanged.
The snapshot includes text and program files, not heap allocations or history.
Current bob32 snapshots use B32S v3 for the 8,192-word filesystem; B32S v1
fixed-slot and v2 packed snapshots remain readable and migrate on restore.
Native programs contain kernel helper addresses. If the kernel image differs
from the one used to save, restore keeps text and omits binary programs.
Run `go SOURCE` to compile them again. BASM and binary boots of the same kernel
share the same identity. Guest programs cannot invoke the storage service.
## Edit existing files
In a native Windows console, `edit name` opens a nano-like, non-modal view:
type directly into the file and use the arrow keys to move. The title shows the
filename and `*` when modified; the bottom row lists shortcuts. The view scrolls
vertically and horizontally to keep the cursor visible.
| Key | Effect |
| --- | --- |
| Ctrl+O | Save to the RAM filesystem and continue editing |
| Ctrl+X | Exit; if modified, ask whether to save |
| Y / N at the exit prompt | Save and exit / discard and exit |
| Ctrl+C at the exit prompt | Cancel and continue editing |
| Ctrl+Z | Toggle undo/redo of the last insertion or deletion |
| Arrows | Move through characters and lines |
| Home / End or Ctrl+A / Ctrl+E | Move to the start/end of the current line |
| Backspace / Delete | Delete before/at the cursor |
| Enter | Insert a newline |
| Tab | Insert a space |
For example, enter `edit bob.c`, move to the text you want to change, type,
then press Ctrl+O and Ctrl+X. Enter `go bob.c` at the shell to compile/run it.
There are no insert/command modes or colon commands in this view. A failed
save keeps changes in the editor. The file limit remains 511 characters;
additional input is rejected without truncating existing text. Ctrl+D follows
the same safe exit path as Ctrl+X. Saves are to RAM; use shell `save` for disk.
### Scripted/other-terminal fallback
For redirected input or terminals without native Windows console support,
the original line interface remains available for scripts:
`edit name` loads the current text, displays numbered lines and opens `edit>`.
Typing ordinary text appends a line; existing content is retained. The editor
uses a scratch buffer, so opening a file does not immediately change it.
| Editor command | Effect |
| --- | --- |
| `:p` | Show all lines with numbers |
| `:p N` | Show only line N for easier navigation |
| `:a TEXT` | Append a line, including text beginning with a colon |
| `:i N TEXT` | Insert a line before line N; a final empty line position allows appending |
| `:r N TEXT` | Replace line N |
| `:d N` | Delete line N |
| `:u` | Toggle undo/redo of the most recent successful text change |
| `:w` | Save while continuing to edit |
| `:wq` or `.` | Save and return to bob> |
| `:q` | Quit if unchanged; otherwise explain how to save or discard |
| `:q!` | Explicitly discard changes since the last save and return to bob> |
For example, `edit bob.c`, `:r 1 int main(void) { println("bob!"); return 0; }`,
then `:wq` changes the existing source rather than recreating it from scratch.
Each edit line has the same 127-character input limit as the shell. Oversize
changes and invalid line numbers are rejected while the editor remains open.
EOF discards unsaved changes. Binary program files cannot be opened as text.
This fallback is a line editor. Interactive Windows sessions use the full-screen
view described above.
## Compile C inside bob16
The initial RAM file `bob.c` contains:
```c
int main(void) { println("bob!"); return 0; }
```
At `bob>` enter:
```text
cc bob.c bob
run bob
```
The program prints `bob!`, reports `Exit 0` and returns to the shell. No host
compiler is involved: the resident compiler parses C and generates bob16
machine words in RAM, rather than interpreting the source.
To write another program, enter `edit count.c`, then:
```c
int main(void) {
int n = 0;
while (n < 3) { n = n + 1; }
if (n == 3) println("bob!");
return 0;
}
```
Enter `.` on its own line, followed by `cc count.c count` and `run count`.
The resident compiler supports one zero-argument `int main(void)` plus up to
15 additional `int` functions with integer parameters. Calls may be forward,
nested or recursive, and may be used as expression statements; each function
gets its own parameter/local stack frame.
The compiler supports up to 16 functions, 16 parameters per function and 16
simultaneously visible local/parameter names. B32 stack frames can reserve up
to 32 local slots across nested scopes; a further declaration is rejected
because frame loads/stores use signed six-bit offsets. It also supports
assignments and compound
assignments, decimal/hex/character/string literals, parentheses, unary `+ - ! ~`, prefix/postfix increment
and decrement, arithmetic, bitwise operators, shifts, short-circuit `&&`/`||`,
comparisons with C operator precedence, blocks, `if`/`else`, `while`, `for`,
`break`, `continue`, and `return`. For-loop initialization can declare an int;
its increment can assign, compound-assign or increment/decrement a variable.
It supports `print`, `println`, `print_dec`, `print_hex`
and `bob_putc` calls with one argument, comments and common string escapes.
Variables follow block scope, including declarations in `for` initializers;
inner blocks may shadow outer names, while duplicate names in one block are
rejected. Compound assignments support `+= -= *= /= %= &= |= ^=`; shift
assignments and assignments inside expressions are unsupported in bob16. Strings hold up to
63 characters and nesting is bounded at 32 parser frames. Both source and
output must fit RAM-file limits. Invalid or unsupported syntax reports an error
without replacing the output file.
The bob32 resident compiler additionally supports C's right-associative `?:`
conditional expression, including evaluation of only the selected branch. This
operator is not enabled in bob16 because its kernel image is at the address
limit; bob16's compiler behavior is unchanged. B32 resident C also supports
`do/while`, including `break` and `continue` (which proceeds to the condition),
assignment expressions (including right-associative chains), and `<<=`/`>>=`.
Both resident compilers provide `print`, `println`, `print_dec`, and `print_hex`
as one-argument built-ins; bob32 source can call them without a prior prototype.
This is a small C subset, not a complete C implementation. Resident includes,
macros, pointers, globals, structs, floating point and a standard library are
unsupported. The bob32 resident compiler supports `int` function prototypes
with integer parameters (prototype parameter names are optional); incompatible
parameter counts are rejected, and a referenced function still needs a
definition. Empty `f()` declarations retain unspecified-parameter status and
may be followed by a typed declaration or definition; calls made through that
declaration must match the eventual definition's arity. bob16 resident
prototypes remain unsupported. The bob32 resident
compiler supports fixed-size,
one-dimensional local `int` arrays with indexed reads and assignment statements;
their elements use the function's 32-word stack-slot budget. Indexed prefix and
postfix increment/decrement work in expressions; indexed compound assignments
work in statements.
Brace initializer lists accept scalar expressions and a trailing comma; omitted
elements are zero-filled and excess elements are rejected. The bob32 resident
compiler accepts one-dimensional `int` array parameters as `values[]` or with a
fixed bound, passing the word-addressed pointer through the ordinary argument
stack. Helpers can index or modify the caller's elements and forward the array
to another helper. Nested/multidimensional arrays and bob16 resident array
parameters remain unsupported.
Local `int` declarations may contain comma-separated scalar and fixed-array
declarators, each with its own initializer.
The bob32 resident compiler also supports local pointers to integer-returning
functions with integer parameters. Initialize or assign one from a previously
declared matching function, copy it to a compatible local pointer, or assign
null (`0`), then call indirectly. Mismatched signatures and integer values are
rejected. Function-pointer parameters, returns, globals, pointer arithmetic
and bob16 resident function pointers remain unsupported.
Programs call the current kernel's
console/arithmetic routines and belong to the kernel build that compiled them.
In bob32 mode the same syntax emits native 32-bit instructions and kind-2 RAM
program files, which can be run with `run` and retained in B32S snapshots. B32
resident programs start at `0x20000` and use variables at `0xF0000..0xF000F`;
their output can use the remaining shared 8,192-word filesystem space. Source
text files remain limited to 511 words. In bob16 mode files remain kind 1 and
use 16-bit integers and the `0xA000` program region. The bob32 shell also runs
kind-1 legacy programs at `0xC200`, clear of the expanded kernel image.
## Native programs and recovery
`run` clears the program region and copies in the binary RAM file at `0xA000`
in bob16 mode or `0xC200` in bob32 mode.
`RET` (`0xE000`) returns to the shell with r0 as the exit status. `TRAP 0` also
ends the running program without ending the shell. The emulator saves/restores
the shell's CPU state, supplies a separate program stack, stops execution after
five million cycles, and rejects writes outside the legacy app/heap range
(`0xA000..0xDFFF` in bob16, `0xC200..0xDFFF` for bob32 compatibility apps).
Native bob32 apps write only their supervised application and stack region.
Invalid
instructions and forbidden services return a program fault.
In bob32 mode `run` also accepts resident kind-2 programs, loading them at
`0x20000` with 32-bit arithmetic. Their compiler variables occupy
`0xF0000..0xF000F`; the host `run32 PATH` command remains available for larger
external B32K images.
Programs can write their program region and the shared heap. This is not process
isolation, and input services can wait for input. The raw `load` command accepts
what fits in a single command line; use the resident compiler for larger programs.
## Kernel routines and memory
- `kernel/runtime.c`: print, println, signed decimal/four-digit hex printing,
bounded line input, strlen, strcmp, word-based memcpy/memset and alloc.
- `kernel/files.c`: RAM filesystem.
- `kernel/compiler.c`: resident C compiler.
- `kernel/shell.c`: commands.
- `kernel/kernel.c`: includes these as one translation unit and runs the shell.
| Word addresses | Use |
| --- | --- |
| `0x0000..0x00FF` | Boot ROM and reserved return sentinel |
| `0x0100..0x01FF` | Shell and fallback editor input buffers |
| `0x0300..0x9FFF` | Kernel code, globals and strings in bob16; current image ends at `0x90E4` |
| `0xA000..0xBFFF` | Loaded program, variables and downward program stack in bob16 |
| `0x0300..0x9FFF` | bob32 low-memory shell data and compatibility space |
| `0xA000..0xCFFF` | Loaded bob16 compatibility program at `0xC200..0xCFFF` |
| `0xD000..0xDFFF` | bob32 heap and compatibility stack region |
| `0xE000..0xEFFF` | Editor/compiler scratch, history and shell stack |
| `0xF000..0xFFFF` | bob16 file contents; bob32 scratch space |
| `0x10000..0x1DFFF` | Native bob32 kernel code, globals and strings |
| `0x1E000..0x1FFFF` | Protected packed bob32 filesystem contents |
| `0x20000..0xEFFFF` | Supervised native bob32 program entry/code region |
| `0xF0000..0xFFFFF` | Native app data and compiler variables; stack starts at `0x100000` |
There are no interrupts, multitasking or hardware memory protection. The write
checks and cycle limits are emulator services. Keep kernel recursion within its
reserved stack. Each guest int, char and pointer occupies one 16-bit word;
strings are unpacked ASCII. Arithmetic wraps to 16 bits, division truncates
toward zero and right shift is arithmetic. Arithmetic helpers return zero for
division by zero or invalid shift counts.
## Rebuild using C and GCC
The supplied `bob.exe` and `kernel.basm` require no build step. To edit and
rebuild the kernel, use GCC from the repository root:
Close running `bob.exe` sessions before rebuilding: Windows locks executable
files while they are running. Rebuilding replaces `bob.exe` and `kernel.basm`;
it does not preserve the volatile RAM files from a previous session.
```powershell
& 'C:\msys64\ucrt64\bin\gcc.exe' -std=c11 -O2 tools/build.c -o build.exe
./build.exe
./build.exe --test
```
The C build utility detects MSYS2 GCC on Windows. It builds `bob.exe`,
`bob32.exe` and `build/bobcc.exe`, preprocesses guest C with GCC, and generates
both `kernel.basm`/`build/kernel.b16` and `build/kernel32.basm`/
`build/kernel32.b32`. `./build.exe --run` boots bob16; `./build.exe --run32`
boots bob32.
On Linux/macOS compile the utility as `build-tool`, then run `./build-tool`.
GCC builds host executables and preprocesses guest C only; `tools/bobcc.c` does
the bob16 code generation. The host compiler supports a broader subset:
signed ints/chars, word pointers and casts, fixed arrays, constant global
initialization, functions and recursion, assignments/compound assignments,
arithmetic/bitwise/shift operators, short-circuit logic, comparisons,
including all arithmetic/bitwise compound assignments and `<<=`/`>>=`,
increment/decrement, if, while, do/while, for, break, continue, function-scoped
labels/goto and returns. Blocks permit shadowing; for-loop declarations have
loop scope. Duplicate declarations in the same scope are rejected.
Switch/case/default support fall-through, nesting and break; continue targets
the surrounding loop. Integer constant expressions support arithmetic, bitwise,
comparison, logical and conditional operators in bounds/initializers/case labels.
Invalid constant division and shifts are rejected.
Comma-separated declarations work at file/block scope and in for initializers;
each declarator has its own pointer stars and array bounds. Global pointer
initializers can reference strings, global objects and array elements, with
constant offsets scaled to their pointee size. Nested element addresses and
arrays of pointers use relocations as well.
File-scope function prototypes are retained and checked against definitions for
the current scalar/character/pointer kinds and parameter counts. Array parameters
adjust to pointers to their element or row type; the outer bound may be omitted.
Unused prototypes need no definition. Pointer descriptors distinguish current
pointee kinds and indirection depth in prototype checks. Qualifier compatibility,
complete expression checking and linking external definitions remain incomplete.
Repeated function declarations merge compatible incomplete/complete array bounds
through pointer types; differing known bounds, element types or depths reject.
Compound assignments validate pointer offsets and integer operands, including
within sizeof. Assignment/increment operands in sizeof must be modifiable scalar
lvalues; their side effects remain unevaluated. Const enforcement and full
assignment conversion checks remain incomplete.
Multidimensional arrays support indexing, row pointers, scaled pointer arithmetic,
increments and pointer differences. Objects are limited to 4096 words and 16
dimensions. Global/local initializer lists accept nested braces and brace
elision, with omitted elements zero-filled. Excess initializers are rejected.
Array designators such as `[3] = 7` and `[1][2] = 9` select elements; subsequent
entries continue after the selected subobject. Later initializers replace earlier
values for the same elements. Designators also support pointer arrays and inferred
outer bounds. Indices must be constant and within the array bounds. Initializer
braces are limited to 64 nested levels.
Initialized arrays may omit their outer bound. Character arrays accept string
initializers, with inferred bounds or zero-filled padding. A bound equal to the
text length omits the terminator; character-array rows may initialize from
strings, with or without braces. String literals and concatenation preserve
embedded zero characters, including their contribution to sizeof.
Conditional `?:` and comma expressions preserve branch/sequence behavior.
`sizeof` handles the current word-sized scalar/pointer types, declared arrays
and string literals without evaluating its operand; void operands are rejected.
Typedef declarations support current scalar, pointer and array types at file and
block scope. Aliases work in parameters, casts, sizeof and further declarations;
void aliases can specify a no-argument function. Compatible identical typedef
redeclarations are accepted; namespace conflicts reject. Inner objects or aliases
can shadow an outer alias, which is restored when the inner scope ends.
Structs, short integer types and floating point remain unsupported. The host
compiler accepts typed function pointers in local and file-scope objects,
function-pointer parameters, address-of function designators and indirect calls
on both targets. Function-pointer/object-pointer conversions and mismatched
signatures are rejected. Returning function pointers and variadic function
pointers are unsupported. The host compiler's bob32 `--wide` target accepts `long` and
`long long` as 32-bit aliases of `int`, consistent with the word-addressed ABI;
`sizeof` reports addressable words (one byte per word). Enums support tagged/anonymous definitions, explicit constant
values, automatic increments, typedef aliases and block/loop tag shadowing.
Enumerators are scoped integer constants usable in bounds, case labels and
initializers. Enum objects use signed 16-bit int storage; distinct enum types
remain distinct in declaration checks and are compatible with this chosen int
representation. Automatic values exceeding 32767 reject. Enum tags must already
be defined when referenced; incomplete enum extensions are unsupported.
Variadics and most standard headers are unsupported; the host C workflow provides
`<stdbool.h>` and `<stddef.h>` with `_Bool`, `size_t`, `ptrdiff_t` and `NULL`.
`sizeof` has the unsigned `size_t` type and tracks array/pointer
expression types, including *&array and array decay in comma/conditional
expressions. Recursive object declarators support grouped names, pointers to
arrays such as `int (*rows)[3]`, and arrays of those pointers. Abstract declarators
in casts and sizeof support these forms too; sizeof array type names uses the
complete storage size. Pointers to incomplete arrays can be declared, but their
pointee has no size for sizeof or arithmetic. Declarators have limits of 32
parenthesis levels and 64 derived types. Function pointer declarators, functions
returning pointers to arrays, and complete C type checking remain unsupported.
Host tools themselves use ordinary host C types.
The host compiler supports `_Bool` as a one-word type. Initializers, assignment,
casts, returns and arguments to boolean parameters convert zero to 0 and nonzero
to 1. Boolean arrays, typedef aliases and static objects use the same conversion;
increment/decrement and compound assignments preserve normalized storage. The
host workflow includes `<stdbool.h>` with `bool`, `true` and `false` definitions.
Unsigned 16-bit int is available as `unsigned` or `unsigned int`, with `u`/`U`
literal suffixes. Mixed int/unsigned arithmetic uses unsigned comparisons,
division and remainder; right shifts of unsigned values fill with zeros.
Arithmetic storage wraps modulo 65536. Unsigned helpers are included only when
explicit unsigned types/literals are used. Unsuffixed literal selection retains
the earlier compiler behavior; full C literal selection, unsigned char/short/long
and all declaration-specifier orderings remain incomplete.
Sizeof is accepted in constant initialization; local static initializers may
query automatic-object types without evaluating their values. Type/literal sizeof
works in bounds and case labels. Named-object sizeof in those contexts uses
parser type bindings with block/for scope and parameter array adjustment.
Objects must already be declared and complete; later or escaped bindings reject.
File-scope object declarations support `extern`, compatible repeated tentative
definitions and a single initialized definition. Incomplete array declarations
merge with known bounds; an uncompleted tentative array reserves one element.
Unused extern objects need no definition, while referenced ones must be defined
in this source unit. Block-scope extern object declarations refer to that same
storage without allocating stack slots. They can shadow an outer local, and
names introduced only in a block do not escape it. Block extern initializers
and conflicts with a local in the same scope reject. Block function declarations,
separate-unit linking remain unsupported. File-scope static objects/functions
use internal linkage within the current source unit. Later extern declarations
inherit prior internal linkage; conflicting external/internal declarations
reject. Function declarations without a storage class retain an earlier static
declaration's linkage. Internal tentative arrays need a complete bound.
Block-scope static objects have private persistent storage initialized once,
including arrays and pointers to other static objects. Initializers must use
supported constant expressions or static addresses; automatic-object addresses
and runtime calls are rejected. Equal names in different blocks/functions remain
independent, and a static object's name is scoped to its declaring block.
To compile another standalone guest source from the repository root:
```powershell
gcc -E -P -nostdinc -undef -DBOBC_LEGACY=0 -I kernel my_program.c -o build/program.i
./build/bobcc.exe build/program.i program.basm build/program.b16
```
Host-compiled BASM starts at address zero as a standalone guest. It is not a
RAM file for the shell's run command, whose programs use a different load
address. Host arithmetic helpers are in `tools/arithmetic.c`, also written
in the supported guest C subset.
`tests/test_os.c` checks console/commands, input bounds, memory/string routines,
heap exhaustion, file limits, resident compilation/execution, raw programs,
fault/time-limit recovery, host compilation, binary-image validation and the
interactive BASM route. Successful guest examples print `bob!`.
Function contracts and execution status codes are documented in
[the kernel API](kernel/API.md).
## Emulator services and boot image
Traps 0-3 retain halt, character output, string output and bounded string input.
Trap 4 reads the simulated boot disk; trap 5 returns a character or -1 at EOF;
trap 6 runs a loaded guest. The compiler exposes them through `bob.h`.
A binary kernel contains `B16K` and five little-endian 16-bit fields: version 1,
origin, entry, word count and sum of payload words modulo 65536, then the payload.
The host validates it and installs the boot ROM, which loads it through trap 4
and jumps to startup. Startup initializes the stack and calls main. The BASM
route loads the same instructions through `.fill` and a startup jump.