ROADMAP.md: scope M8 REPL keyboard wiring, design decisions resolved
Not implementation -- documentation-only. M8 is tracked outside Stadium (FABRIC.md §27.5), so this scoping lives in docs/lithosananke/ROADMAP.md rather than as new FABRIC.md 4.3.x items. Read the code before scoping, not assumed: the REPL already works interactively over serial (sk_repl_run(), repl.c) with working backspace/echo, and its on-screen text already renders via the existing VT100 console (vt100_init()/font_8x16.c) independent of both the stroke font and TrueType work -- neither was ever a REPL-strip prerequisite. What's actually missing: sk_readline()'s console_getc() is serial-UART-only, never touches KEY-EVENT (4.3.5f); KEY/?TERMINAL (io_words.c) are dead stubs (KEY calls a getchar() hardcoded to EOF in shim.c, ?TERMINAL always returns false). Resolved design decisions: minimal US-QWERTY scancode->ASCII layout with shift-state tracking (KEY-EVENT carries no modifier state today); merge keyboard into console_getc()'s poll with serial staying a co-equal source, not replaced (the entire acceptance/DoE harness injects over the serial socket -- breaking that breaks make qemu, DOE_INJECT, and every screendump technique used throughout 4.3.x); wire KEY/?TERMINAL to the same merged source for FORTH-79 compliance; CANVAS viewport sizing last, since it's presentation not input plumbing. Extended scancodes, autorepeat-as-character-repeat, arrow-key history explicitly out of scope for the "minimal" bar. FABRIC.md's existing "not yet scoped" notes (4.3.5f's landing-point note, 4.3.7f's closing note) updated to point here rather than duplicating the design content. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
ed8bf5460b
commit
8e2c5dae5f
@@ -4387,6 +4387,13 @@ document and committing that amendment as its own item.*
|
||||
> scoped. Whether the fix lands in `shim.c`'s `getchar()`, in `io_words.c` under
|
||||
> `#ifdef __STARKERNEL__`, or elsewhere is an open question for that later item, not
|
||||
> decided here.
|
||||
>
|
||||
> **Now scoped, 2026-08-11 — resolved in `docs/lithosananke/ROADMAP.md`'s M8 section,
|
||||
> not here.** M8 is "tracked outside Stadium" per §27.5, and its console-facing pieces
|
||||
> don't change this document's own scope, so the resolution lives there rather than as
|
||||
> new 4.3.x items. Short answer to the open question above: `io_words.c` under
|
||||
> `#ifdef __STARKERNEL__`, wired to the same merged serial+keyboard source the REPL uses
|
||||
> — see that section for the full design.
|
||||
|
||||
- [x] **4.3.6 — Em-square glyph coordinate convention.** `EM-UNITS 1000` (baseline Y=0,
|
||||
x-height ≈500, cap-height ≈700, ascender ≈750, descender ≈-250), plus `EM-X`/`EM-Y`/
|
||||
@@ -4954,6 +4961,17 @@ document and committing that amendment as its own item.*
|
||||
> TrueType rendering (4.3.7-4.3.7f) is now complete, adjunct to the stroke font per §27.7's
|
||||
> decision #4 -- both text paths coexist. Per this item's own posture (matching 4.3.6g),
|
||||
> stopping here before scoping REPL wiring (M8).
|
||||
>
|
||||
> **M8 scoped 2026-08-11 in `docs/lithosananke/ROADMAP.md`, not here** -- per §27.5, M8 is
|
||||
> tracked outside Stadium, so its design decisions live in that roadmap's own M8 section
|
||||
> rather than as new 4.3.x items. Key finding from that scoping pass, worth recording in
|
||||
> this document too since it bears on §27.6's CANVAS/REPL-strip framing: the REPL's
|
||||
> on-screen text already renders via the existing VT100 console
|
||||
> (`console_fb_init()`/`vt100_init()`, baked-in `font_8x16.c`), independent of both the
|
||||
> stroke font and TrueType work above -- neither 4.3.6-4.3.6g nor 4.3.7-4.3.7f was ever a
|
||||
> prerequisite for the REPL strip itself. What's still open for M8 is purely input-side:
|
||||
> `KEY-EVENT` (4.3.5f) isn't yet wired into the REPL's character source
|
||||
> (`console_getc()`), and `KEY`/`?TERMINAL` remain the dead stubs already noted above.
|
||||
|
||||
⋯ *(4.3.x is open-ended — more items get appended here as Console work is scoped item by*
|
||||
*item, developed on the fly per §25.0. 4.4 below is unaffected by anything added above*
|
||||
|
||||
@@ -236,13 +236,81 @@ APIC Timer: started
|
||||
|
||||
### M8: REPL + Interactive Forth
|
||||
|
||||
**Goal:** Type Forth at the kernel, get `ok` prompt
|
||||
**Status:** Scoped 2026-08-11 (this section). Substrate (interrupt-driven keyboard
|
||||
input, glyph rendering) already complete via Stadium's Console fabric work
|
||||
(FABRIC.md §25.5 items 4.3.5–4.3.7f) — see "What's already done" below. This
|
||||
scoping pass covers what's left: wiring the existing keyboard-event stream into
|
||||
the REPL's character input path.
|
||||
|
||||
**Goal:** Type Forth at the kernel *keyboard* (not just serial), get `ok` prompt.
|
||||
The REPL already works interactively over serial today (`sk_repl_run()`,
|
||||
`src/starkernel/repl.c`) — that is not what this milestone adds. What's missing
|
||||
is a second input source feeding the same loop.
|
||||
|
||||
**What's already done, read from the code before scoping this, not assumed:**
|
||||
- Interrupt-driven keyboard input on all three architectures (amd64 i8042,
|
||||
aarch64/riscv64 virtio-keyboard-pci + GIC/PLIC), converged behind one shared
|
||||
interface: `KEY-EVENT ( -- keycode pressed -1 | 0 )` in
|
||||
`src/word_source/keyboard_words.c`, `keycode` in the Linux input keycode
|
||||
namespace. FABRIC.md items 4.3.5–4.3.5f, verified live on all three
|
||||
architectures with real keypresses.
|
||||
- Glyph rendering, both paths: the stroke-drawn font (`TEXT`, capsule-based,
|
||||
113-glyph v1 repertoire, FABRIC.md 4.3.6–4.3.6g) and TrueType (`TTF-TEXT`,
|
||||
proportional spacing via real `hmtx` advance widths, FABRIC.md 4.3.7–4.3.7f).
|
||||
Neither is required for the REPL text itself, though — see the VT100 finding
|
||||
below.
|
||||
- **The REPL's on-screen text already renders independently of both of the
|
||||
above.** `console_fb_init()` (`src/starkernel/hal/console.c`) calls
|
||||
`vt100_init()`, which mirrors every `console_putc()`/`console_puts()` call to
|
||||
the framebuffer via the baked-in `font_8x16.c` raster font. This is *already
|
||||
live* — the REPL prompt and its output appear on screen today, serial-driven,
|
||||
no CANVAS/glyph-capsule dependency. This confirms §27.6's mockup: a fixed
|
||||
VT100 REPL strip (already working) plus a separate large CANVAS region above
|
||||
it (still unsized — see the last deliverable below).
|
||||
|
||||
**What's actually missing, confirmed by reading the code, not assumed:**
|
||||
`src/starkernel/repl.c`'s `sk_readline()` reads characters via
|
||||
`console_getc()` (`src/starkernel/hal/console.c`), which is serial-UART-only —
|
||||
it never looks at `KEY-EVENT`. Separately, the FORTH-79 words `KEY`/`?TERMINAL`
|
||||
(`src/word_source/io_words.c:84-108`, shared/vendored source) are dead in the
|
||||
kernel build: `KEY` calls libc `getchar()`, which the kernel shim
|
||||
(`src/starkernel/vm/host/shim.c:1206`) hardcodes to return `-1` (EOF);
|
||||
`?TERMINAL` is a literal stub that always returns false. Neither path has ever
|
||||
been wired to a real keyboard.
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Keyboard input (PS/2 or USB HID)
|
||||
- [ ] REPL loop integration
|
||||
- [ ] Line editing (backspace, minimal)
|
||||
- [ ] Word execution from console
|
||||
- [ ] Minimal scancode→ASCII layout: a small lookup table (US QWERTY,
|
||||
unshifted/shifted rows only — no dead keys, no locale switching) driven
|
||||
by `KEY-EVENT`'s Linux-namespace keycodes, plus shift-state tracking
|
||||
(`KEY_LEFTSHIFT`/`KEY_RIGHTSHIFT` press/release) since `KEY-EVENT` itself
|
||||
carries no modifier state today (confirmed by reading
|
||||
`keyboard_words.c` — deferred at 4.3.5f, not implemented anywhere).
|
||||
- [ ] Merge keyboard into `console_getc()`'s poll: extend it (or add a second
|
||||
function `sk_readline()` polls alongside it) to also drain `KEY-EVENT`
|
||||
and translate presses to ASCII via the layout table above. **Serial stays
|
||||
a co-equal input source, not replaced** — the entire acceptance/DoE
|
||||
harness injects FORTH commands over the serial socket
|
||||
(`socat ... UNIX-CONNECT:$SERIAL_SOCK`) and greps the serial log for
|
||||
`ok>`; breaking that path breaks `make qemu`, `DOE_INJECT`, and every
|
||||
screendump verification technique used throughout 4.3.x. Both sources
|
||||
feed the same byte stream into the existing `sk_readline()` — no new
|
||||
line-editing code needed, backspace/echo already work
|
||||
(`sk_readline()`, `repl.c:83-141`).
|
||||
- [ ] Wire `KEY`/`?TERMINAL` (`io_words.c`) to the same merged source under
|
||||
`#ifdef __STARKERNEL__`, for FORTH-79 compliance — any capsule calling
|
||||
these directly (not just the REPL) should get real input too, not a
|
||||
permanently-EOF stub. Small addition once the merge above exists.
|
||||
- [ ] CANVAS viewport sizing (§27.6's explicit deferral to this milestone): the
|
||||
large graphics region above the VT100 REPL strip needs an actual
|
||||
scrollable framebuffer viewport size decided (e.g. 640×480, per the
|
||||
original mockup) — layout/presentation, not input plumbing; do this
|
||||
last, after keyboard input works, since it doesn't block interactivity.
|
||||
|
||||
**Explicitly out of scope for this milestone (minimal bar, matches "Line
|
||||
editing (backspace, minimal)"):** extended (`0xE0`-prefixed) i8042 scancodes,
|
||||
virtio-input autorepeat (`value=2`) as actual character repeat, arrow-key
|
||||
cursor movement/history, non-US keyboard layouts. Deferred to a later item if
|
||||
ever needed — not blocking "type Forth at the kernel, get `ok`."
|
||||
|
||||
**Validation:**
|
||||
```
|
||||
@@ -250,6 +318,10 @@ LithosAnanke v0.3.0
|
||||
ok 1 2 + .
|
||||
3 ok
|
||||
```
|
||||
(via a real keypress on all three architectures, same live-keypress
|
||||
verification standard FABRIC.md 4.3.5f already established — not a
|
||||
serial-injected synthetic test, though serial injection must still work
|
||||
identically afterward.)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user