LithosAnanake/kernel/include/starkernel/console.h

/*
  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 */