108 lines
5.3 KiB
TeX
108 lines
5.3 KiB
TeX
%% SCRAP: architecture/03-architecture/hal/interfaces
|
|
%% SOURCE: docs/working/architecture/03-architecture/hal/interfaces.md
|
|
%% STATUS: WORKING
|
|
%% FITS: dev-guide/ch-platform
|
|
%% EDITORIAL: lifted — prose rewritten to press voice
|
|
|
|
\section{HAL Interface Specifications}
|
|
|
|
The HAL interfaces define the contract between StarForth's platform-agnostic
|
|
core and the platform layer beneath it. The interfaces are not optional
|
|
convenience wrappers; they are the only sanctioned path by which interpreter and
|
|
physics code reach platform resources. Each subsystem must be implemented with
|
|
identical semantics on every platform.
|
|
|
|
\subsection{Time and Timers (\texttt{hal\_time.h})}
|
|
|
|
The time subsystem supplies monotonic time, periodic and one-shot timers, and
|
|
calibration for the physics subsystems. \texttt{hal\_time\_init()} runs first;
|
|
it calibrates a high-resolution source, validates monotonicity, and panics if no
|
|
suitable source exists. \texttt{hal\_time\_now\_ns()} returns nanoseconds since
|
|
an arbitrary epoch and must be monotonic, ISR-safe, and thread-safe, with a
|
|
target cost under fifty cycles on x86-64. \texttt{hal\_time\_delay\_ns()} is a
|
|
busy-wait, not a sleep. The timer family --- \texttt{hal\_timer\_oneshot()},
|
|
\texttt{hal\_timer\_periodic()}, and \texttt{hal\_timer\_cancel()} --- schedules
|
|
callbacks that run in interrupt context and must complete quickly. The periodic
|
|
timer is the primary mechanism for the heartbeat ISR, so the platform must
|
|
minimize jitter to preserve experimental validity; the contract allows up to ten
|
|
percent drift and targets under one percent.
|
|
|
|
\begin{lstlisting}[language=C]
|
|
uint64_t hal_time_now_ns(void);
|
|
int hal_timer_periodic(uint64_t period_ns, hal_timer_callback_t cb, void *ctx);
|
|
int hal_timer_cancel(int timer_id);
|
|
\end{lstlisting}
|
|
|
|
Platform notes: Linux maps the clock to \texttt{clock\_gettime(CLOCK\_MONOTONIC)}
|
|
and the periodic timer to \texttt{timer\_create()} with a real-time signal,
|
|
accepting microsecond-scale signal jitter. L4Re uses the kernel info page clock
|
|
and an IPC-based timer with an IRQ object. StarKernel reads a calibrated TSC and
|
|
drives the local APIC timer.
|
|
|
|
\subsection{Interrupts (\texttt{hal\_interrupt.h})}
|
|
|
|
The interrupt subsystem enables and disables IRQs, registers ISRs, and reports
|
|
interrupt context. \texttt{hal\_irq\_disable()} returns the prior state so a
|
|
caller can restore it after a critical section; \texttt{hal\_irq\_register()}
|
|
binds one ISR per IRQ. \texttt{hal\_in\_interrupt\_context()} must be cheap
|
|
(under ten cycles) because it gates ISR-only behavior. On Linux these map onto
|
|
signals and a thread-local flag; on StarKernel they map onto \texttt{sti},
|
|
\texttt{cli}, the IDT, and the local APIC, with context tracked by an interrupt
|
|
nesting count.
|
|
|
|
\subsection{Memory (\texttt{hal\_memory.h})}
|
|
|
|
The memory subsystem allocates and frees heap memory, allocates contiguous
|
|
physical pages, and maps physical memory into the virtual address space.
|
|
\texttt{hal\_mem\_alloc()} returns zero-initialized, at-least-eight-byte-aligned
|
|
memory and is thread-safe but not ISR-safe. \texttt{hal\_mem\_map()} carries flag
|
|
bits for read, write, execute, and uncached MMIO mappings. On Linux the heap
|
|
calls wrap \texttt{malloc}, page allocation falls back to the heap, and mapping
|
|
is a no-op under the identity-mapping assumption. On StarKernel the calls bind to
|
|
the physical memory manager, the virtual memory manager, and \texttt{kmalloc}.
|
|
|
|
\subsection{Console (\texttt{hal\_console.h})}
|
|
|
|
The console subsystem provides character I/O for the REPL and diagnostics:
|
|
\texttt{hal\_console\_putc()} (blocking, ISR-safe for panic output),
|
|
\texttt{hal\_console\_puts()}, the blocking \texttt{hal\_console\_getc()}, and
|
|
the non-blocking \texttt{hal\_console\_has\_input()}. Linux uses standard I/O;
|
|
StarKernel drives a 16550 UART and, where available, a framebuffer.
|
|
|
|
\subsection{CPU (\texttt{hal\_cpu.h})}
|
|
|
|
The CPU subsystem reports identity and count, and exposes relax and halt hints.
|
|
\texttt{hal\_cpu\_id()} and \texttt{hal\_cpu\_relax()} are ISR-safe;
|
|
\texttt{hal\_cpu\_halt()} parks the processor until the next interrupt and is not
|
|
ISR-safe. The relax hint compiles to \texttt{pause} on x86, to \texttt{yield} on
|
|
ARM, and to \texttt{sched\_yield()} on Linux.
|
|
|
|
\subsection{Panic (\texttt{hal\_panic.h})}
|
|
|
|
\texttt{hal\_panic()} prints a message and never returns. On a kernel it disables
|
|
interrupts and halts; on a hosted platform it writes to standard error and
|
|
aborts. It is ISR-safe and reserved for unrecoverable errors.
|
|
|
|
\subsection{Concurrency Summary}
|
|
|
|
\begin{table}[h]
|
|
\centering
|
|
\begin{tabular}{llll}
|
|
\toprule
|
|
Subsystem & Key function & ISR-safe & Thread-safe \\
|
|
\midrule
|
|
Time & \texttt{hal\_time\_now\_ns()} & yes & yes \\
|
|
Time & \texttt{hal\_timer\_periodic()} & no & yes \\
|
|
Interrupt & \texttt{hal\_in\_interrupt\_context()} & yes & yes \\
|
|
Interrupt & \texttt{hal\_irq\_disable()} & yes & yes \\
|
|
Memory & \texttt{hal\_mem\_alloc()} & no & yes \\
|
|
Memory & \texttt{hal\_mem\_map()} & no & platform-dependent \\
|
|
Console & \texttt{hal\_console\_putc()} & yes & platform-dependent \\
|
|
Console & \texttt{hal\_console\_getc()} & no & no \\
|
|
CPU & \texttt{hal\_cpu\_id()} & yes & yes \\
|
|
CPU & \texttt{hal\_cpu\_relax()} & yes & yes \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{ISR and thread safety of the principal HAL entry points.}
|
|
\end{table}
|