Reorganize source tree: kernel/, v3/, v4/ split and board infrastructure
Source tree reorganization: - Move StarForth v3 engine to v3/ (src/, include/, Makefile) - Move kernel to kernel/ (src/, include/, linker/, Makefile) - Create v4/ skeleton for F18-ISA golden model (DECOMPOSITION.md, JUSTIFICATION.md) - Move FABRIC-0..4.md to docs/fabric/ - Move ONTOLOGY.md and ROADMAP.md to docs/ Board infrastructure: - Add boards/ser5/, boards/raspi/, boards/milkv/, boards/zynq7020/ - Each board has board.mk (ISA, CPU flags, boot recipe) and README.md - Root Makefile becomes thin dispatcher: boot_image, all, clean, docs take TARGET - make boot_image TARGET=SER5|RASPI|MILKV builds one GPT/MBR image per board - ZYNQ7020 target exists but stops with clear error (ARMv7 port not built yet) - scripts/mkdiskimage.sh builds disk images for all boards Docs pipeline: - docs/book/ with LaTeX master (main.tex) and Makefile - pandoc converts Markdown to LaTeX at build time - Two Lua filters: table-widths.lua (wide tables wrap), code-breaks.lua (inline code breaks) - make docs builds single PDF (754 pages, 0 missing characters) - make docs TARGET=<board> adds board appendix - build/docs/<book|board>/meta.tex stamps git commit into PDF Bug fixes: - 42 include paths that only worked by accident now use correct relative paths - clang-18 hardcode replaced with configurable CC variable (fixed aarch64 build) - Pi 5: kernel_2712.img linked at 0x80000, .bss zeroed, memory reserved - Doxyfile, .clang-tidy, README.md, Kconfig paths updated Verified: - Hosted v3 build passes 1012 tests, 0 failures - SER5 image boots in QEMU (OVMF), POST passes, K exact (65536 = Q48_ONE) - Milk-V image boots in QEMU (OpenSBI + U-Boot + bootefi), POST passes - make clean TARGET=<board> removes only that board and its ISA objects - make all builds all boards, hosted v3, and docs in one run Co-authored-by: Junie <junie@jetbrains.com>
This commit is contained in:
rajames
@@ -0,0 +1,237 @@
|
||||
/*
|
||||
StarForth — Steady-State Virtual Machine Runtime
|
||||
|
||||
Copyright (c) 2023–2025 Robert A. James
|
||||
All rights reserved.
|
||||
|
||||
This file is part of the StarForth project.
|
||||
|
||||
Licensed under the StarForth License, Version 1.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
|
||||
You may obtain a copy of the License at:
|
||||
https://github.com/star.4th@proton.me/StarForth/LICENSE.txt
|
||||
|
||||
This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
express or implied, including but not limited to the warranties of
|
||||
merchantability, fitness for a particular purpose, and noninfringement.
|
||||
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
StarForth — Steady-State Virtual Machine Runtime
|
||||
Copyright (c) 2023–2025 Robert A. James
|
||||
All rights reserved.
|
||||
|
||||
This file is part of the StarForth project.
|
||||
|
||||
Licensed under the StarForth License, Version 1.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
|
||||
You may obtain a copy of the License at:
|
||||
https://github.com/star.4th@proton.me/StarForth/LICENSE.txt
|
||||
|
||||
This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
express or implied, including but not limited to the warranties of
|
||||
merchantability, fitness for a particular purpose, and noninfringement.
|
||||
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
*/
|
||||
|
||||
/**
|
||||
* console.h - Serial console + framebuffer VT100 interface for StarKernel
|
||||
*
|
||||
* Output policy:
|
||||
* - Serial UART is always active (initialized by console_init).
|
||||
* - When console_fb_init() has been called and the framebuffer is ready,
|
||||
* every character is also rendered through the VT100 terminal on screen.
|
||||
* - Both outputs are always live simultaneously; serial cannot be disabled.
|
||||
*/
|
||||
|
||||
#ifndef STARKERNEL_CONSOLE_H
|
||||
#define STARKERNEL_CONSOLE_H
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stddef.h>
|
||||
#include "uefi.h"
|
||||
|
||||
/**
|
||||
* Initialize serial console (UART).
|
||||
* Must be called once during early kernel boot.
|
||||
*/
|
||||
void console_init(void);
|
||||
|
||||
/**
|
||||
* Initialize the framebuffer VT100 terminal.
|
||||
* Call after UEFI boot services have been exited and the GOP framebuffer
|
||||
* address is known (from BootInfo). Safe to call with info==NULL (no-op).
|
||||
* fmt: FB_PIXEL_BGRX32 is correct for most QEMU / real hardware GOP.
|
||||
*/
|
||||
#include "framebuffer.h"
|
||||
void console_fb_init(const FramebufferInfo *info, FbPixelFormat fmt);
|
||||
|
||||
/**
|
||||
* FABRIC-0.md item 4.4j: switch the framebuffer console's glyph backend from
|
||||
* font_8x16.c to TTF-TEXT's rasterizer. Thin wrapper over
|
||||
* vt100_enable_ttf() -- see that function's doc comment for the full
|
||||
* contract (lazy font load, cell-geometry/cols/rows recompute, screen
|
||||
* clear, one-shot). No-op if the framebuffer console was never
|
||||
* initialized (console_fb_init() not called, or it no-op'd on a NULL
|
||||
* framebuffer).
|
||||
*/
|
||||
void console_fb_enable_ttf(void);
|
||||
|
||||
/**
|
||||
* FABRIC-0.md item 4.4q: thin wrappers over vt100_scroll_back()/
|
||||
* vt100_scroll_fwd() -- see those functions' doc comments for the full
|
||||
* contract. No-op if the framebuffer console was never initialized.
|
||||
*/
|
||||
void console_fb_scroll_back(uint32_t n);
|
||||
void console_fb_scroll_fwd(uint32_t n);
|
||||
|
||||
/**
|
||||
* FABRIC-0.md item 4.4y-revised: thin wrapper over vt100_toggle_graphics()
|
||||
* -- see that function's doc comment for the full contract (the
|
||||
* Alt+TAB graphics/text state machine). No-op if the framebuffer console
|
||||
* was never initialized.
|
||||
*/
|
||||
void console_fb_toggle_graphics(void);
|
||||
|
||||
/**
|
||||
* Thin wrapper over vt100_draw_cursor() -- see that function's doc
|
||||
* comment for the full contract (a static block cursor at the terminal's
|
||||
* current position). No-op if the framebuffer console was never
|
||||
* initialized.
|
||||
*/
|
||||
void console_fb_draw_cursor(void);
|
||||
|
||||
/**
|
||||
* Thin wrapper over vt100_erase_cursor(). No-op if the framebuffer
|
||||
* console was never initialized.
|
||||
*/
|
||||
void console_fb_erase_cursor(void);
|
||||
|
||||
/**
|
||||
* Write a single character to serial console
|
||||
*/
|
||||
void console_putc(char c);
|
||||
|
||||
/**
|
||||
* Write a null-terminated string to serial console
|
||||
*/
|
||||
void console_puts(const char *s);
|
||||
|
||||
/**
|
||||
* Write a string with newline to serial console
|
||||
*/
|
||||
void console_println(const char *s);
|
||||
|
||||
/**
|
||||
* console_ensure_line_start - Make sure the *next real output* starts at
|
||||
* the beginning of a fresh output line, closing off whatever is currently
|
||||
* mid-line (e.g. a dangling prompt). No-op if already at line start.
|
||||
*
|
||||
* FABRIC-2.md §I.9 fix, 2026-09-05: the newline is DEFERRED, not emitted
|
||||
* immediately -- it only actually reaches the console on the next real
|
||||
* console_putc() call, and is silently dropped (never emitted at all) if
|
||||
* console_cancel_deferred_line_start() is called first instead. Before this
|
||||
* fix, an immediate, unconditional newline here meant any caller invoking
|
||||
* this function "just in case" (sk_repl_idle() being the one real caller)
|
||||
* would visibly snap a bare, unfinished prompt line to a fresh blank line
|
||||
* even when nothing was actually about to be printed -- indistinguishable
|
||||
* from Enter having already been pressed at that prompt. Deferring means a
|
||||
* caller that turns out to have nothing to print can cancel cleanly, with
|
||||
* zero visible effect, while a caller that does print gets the correct
|
||||
* "close the old line first" behavior for free, still counted by
|
||||
* console_tx_count() as real output (unlike the old always-silent inner
|
||||
* form) since it is realized through the normal console_putc() path.
|
||||
*/
|
||||
void console_ensure_line_start(void);
|
||||
|
||||
/**
|
||||
* console_cancel_deferred_line_start - Discard a pending deferred newline
|
||||
* from console_ensure_line_start() without ever emitting it. No-op if no
|
||||
* newline is currently deferred. Callers that speculatively deferred a line
|
||||
* break before checking whether they actually have anything to print
|
||||
* (sk_repl_idle()'s idle-beat check being the motivating case, FABRIC-2.md
|
||||
* §I.9) call this when the check comes back negative, so the console is
|
||||
* left exactly as it was -- no stray newline, no phantom blank line.
|
||||
*/
|
||||
void console_cancel_deferred_line_start(void);
|
||||
|
||||
/**
|
||||
* console_tx_count - Monotonic count of console_putc() calls delivered to
|
||||
* either output (serial and/or framebuffer). In use by the REPL to detect
|
||||
* that an idle bottom half (heartbeat, USB attach/detach) wrote to the
|
||||
* console while the top-level prompt was showing, so it can re-anchor the
|
||||
* prompt afterward. Never decreases.
|
||||
*/
|
||||
uint64_t console_tx_count(void);
|
||||
|
||||
/**
|
||||
* Read a single character from serial console (non-blocking)
|
||||
* Returns -1 if no character available
|
||||
*/
|
||||
int console_getc(void);
|
||||
|
||||
/**
|
||||
* Check if character is available for reading
|
||||
*/
|
||||
int console_poll(void);
|
||||
|
||||
/**
|
||||
* Set the active VM name shown as [Name] prefix on each output line.
|
||||
* Pass NULL to suppress the prefix (kernel-only output before any VM).
|
||||
* Copies into internal storage (FABRIC-2.md Phase F, 2026-08-28) -- the
|
||||
* caller's own pointer does not need to remain valid afterward.
|
||||
*/
|
||||
void console_set_vm_name(const char *name);
|
||||
const char *console_get_vm_name(void);
|
||||
|
||||
/**
|
||||
* console_save_vm_name - Copy the current active-VM name into the
|
||||
* caller's own buffer, for a later console_set_vm_name() restore.
|
||||
*
|
||||
* console_get_vm_name() alone is NOT safe for save-then-restore: it
|
||||
* returns a pointer into the single internal buffer console_set_vm_name()
|
||||
* copies into, so an intervening console_set_vm_name() call (the normal
|
||||
* "switch, do work, switch back" pattern every BIRTH/VM-EXEC/CONNECT-*
|
||||
* call site uses) overwrites the very bytes the saved pointer points at
|
||||
* before the restore ever runs -- found live 2026-08-28, the restore
|
||||
* silently no-ops. Copies at most cap-1 bytes plus a NUL terminator;
|
||||
* writes "" if there was no active name (NULL) to save.
|
||||
*
|
||||
* @param out Caller-owned buffer.
|
||||
* @param cap Its size in bytes.
|
||||
*/
|
||||
void console_save_vm_name(char *out, size_t cap);
|
||||
|
||||
/**
|
||||
* FABRIC-3.md SXXV follow-up (2026-09-13): the line prefix used to be a
|
||||
* bare "[VMName] ", ambiguous between a console-proxy VM and the actual
|
||||
* identity VM behind it (e.g. "rajames" the console vs. "rajames~user"
|
||||
* the real WIREBIND-restricted identity) -- confirmed live to cause real
|
||||
* confusion during testing. Unified to "[user@VMName] " when a user
|
||||
* context is available, still "[VMName] " when not (unauthenticated/
|
||||
* pre-login, unchanged from today).
|
||||
*
|
||||
* console.c is a clean HAL module with no dependency on capsule/WIREBIND
|
||||
* logic (zuse_session, capsule_wirebind_attached_username()) -- pulling
|
||||
* either in directly here would be a real layering violation, not just a
|
||||
* style preference. This callback lets repl.c (which already computes
|
||||
* exactly this for sk_print_prompt()) supply the "user" half without
|
||||
* console.c knowing anything about VMs, sessions, or WIREBIND. Returns
|
||||
* NULL/empty for "no user context" (falls back to the bare "[VMName] "
|
||||
* form); the returned pointer must remain valid until the next call
|
||||
* (matches console_get_vm_name()'s own single-buffer convention).
|
||||
*/
|
||||
typedef const char *(*console_user_prefix_fn)(void);
|
||||
void console_set_user_prefix_provider(console_user_prefix_fn fn);
|
||||
|
||||
/* Last FORTH word name set by the dispatcher before entry->func(vm).
|
||||
* Printed by the #GP fault handler to identify the faulting word. */
|
||||
extern volatile const char *g_sk_fault_word;
|
||||
|
||||
#endif /* STARKERNEL_CONSOLE_H */
|
||||
Reference in New Issue
Block a user