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,215 @@
|
||||
/*
|
||||
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.
|
||||
|
||||
*/
|
||||
|
||||
/*
|
||||
*** StarForth ***
|
||||
|
||||
physics_runtime.h - Phase 1 physics runtime services
|
||||
|
||||
Provides host snapshot shims (POSIX + L4Re) and analytics heap scaffolding
|
||||
for physics-aware scheduling. The interface is intentionally lightweight so
|
||||
future governance-approved modules can extend it without ABI churn.
|
||||
|
||||
============================================================================
|
||||
IMPORTANT SYNC NOTE (projects using git hooks / governance mirror):
|
||||
• If you change HOLA protocol fields, magic, or version numbers below, also
|
||||
update the governance export docs so the L4Re mirror stays aligned.
|
||||
• Daemons touching this header can throw a warning when HOLA_PROTOCOL_* or
|
||||
HOLA_SHARED_MAGIC change to catch accidental ABI drifts early.
|
||||
• Reference: docs/src/internal/GOVERNANCE_EXPORT_NOTES.adoc
|
||||
============================================================================
|
||||
*/
|
||||
|
||||
#ifndef STARFORTH_PHYSICS_RUNTIME_H
|
||||
#define STARFORTH_PHYSICS_RUNTIME_H
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/** Default analytics heap size (10 MiB) */
|
||||
#define PHYSICS_ANALYTICS_DEFAULT_HEAP_BYTES (10u * 1024u * 1024u)
|
||||
|
||||
/** Magic tag for HOLA analytics heap headers ('HOLA') */
|
||||
#define HOLA_SHARED_MAGIC 0x484f4c41u
|
||||
|
||||
/** HOLA protocol version (major.minor) */
|
||||
#define HOLA_PROTOCOL_MAJOR 0x0001u
|
||||
#define HOLA_PROTOCOL_MINOR 0x0000u
|
||||
|
||||
/** Host backend identifier */
|
||||
typedef enum physics_host_backend {
|
||||
PHYSICS_HOST_BACKEND_POSIX = 0,
|
||||
PHYSICS_HOST_BACKEND_L4RE = 1, /* HISTORICAL: no backend sets this anymore; L4Re removed as an active target. Value kept stable for the HOLA analytics data format. */
|
||||
PHYSICS_HOST_BACKEND_FAKE = 2
|
||||
} physics_host_backend_t;
|
||||
|
||||
/** Analytics channel ids */
|
||||
#define PHYSICS_ANALYTICS_CHANNEL_HOST_SNAPSHOT 0x00000002u
|
||||
|
||||
/** Host snapshot flag bits */
|
||||
#define PHYSICS_HOST_FLAG_PSI 0x0001u
|
||||
#define PHYSICS_HOST_FLAG_CGROUP 0x0002u
|
||||
#define PHYSICS_HOST_FLAG_CPU_STAT 0x0004u
|
||||
|
||||
/**
|
||||
* @brief Snapshot of scheduler-adjacent host signals.
|
||||
*
|
||||
* Fields are intentionally fixed width to maximise portability and allow the
|
||||
* governance repository to consume binary dumps without per-platform quirks.
|
||||
*/
|
||||
typedef struct physics_host_snapshot {
|
||||
physics_host_backend_t backend; /**< Selected backend (POSIX/L4Re/other) */
|
||||
uint32_t scheduler_policy; /**< OS-specific scheduler policy identifier */
|
||||
uint32_t scheduler_priority; /**< Nominal thread priority */
|
||||
uint32_t scheduler_quantum_ns; /**< Reported quantum in nanoseconds (0 if unknown) */
|
||||
uint32_t runnable_threads; /**< Runnable entities on this CPU set (best effort) */
|
||||
uint32_t cpu_count; /**< Online logical CPU count */
|
||||
uint32_t load_avg_milli; /**< Smoothed load average (×1000) */
|
||||
uint32_t flags; /**< Backend-specific flags */
|
||||
uint32_t psi_cpu_some_avg10_milli; /**< CPU PSI some avg10 ×1000 */
|
||||
uint32_t psi_cpu_some_avg60_milli; /**< CPU PSI some avg60 ×1000 */
|
||||
uint32_t psi_cpu_some_avg300_milli; /**< CPU PSI some avg300 ×1000 */
|
||||
uint32_t psi_cpu_full_avg10_milli; /**< CPU PSI full avg10 ×1000 */
|
||||
uint32_t psi_cpu_full_avg60_milli; /**< CPU PSI full avg60 ×1000 */
|
||||
uint32_t psi_cpu_full_avg300_milli; /**< CPU PSI full avg300 ×1000 */
|
||||
uint32_t psi_io_some_avg10_milli; /**< IO PSI some avg10 ×1000 */
|
||||
uint32_t psi_io_some_avg60_milli; /**< IO PSI some avg60 ×1000 */
|
||||
uint32_t psi_io_some_avg300_milli; /**< IO PSI some avg300 ×1000 */
|
||||
uint32_t psi_io_full_avg10_milli; /**< IO PSI full avg10 ×1000 */
|
||||
uint32_t psi_io_full_avg60_milli; /**< IO PSI full avg60 ×1000 */
|
||||
uint32_t psi_io_full_avg300_milli; /**< IO PSI full avg300 ×1000 */
|
||||
uint32_t psi_mem_some_avg10_milli; /**< Memory PSI some avg10 ×1000 */
|
||||
uint32_t psi_mem_some_avg60_milli; /**< Memory PSI some avg60 ×1000 */
|
||||
uint32_t psi_mem_some_avg300_milli; /**< Memory PSI some avg300 ×1000 */
|
||||
uint64_t monotonic_time_ns; /**< Monotonic clock reading */
|
||||
uint64_t realtime_ns; /**< Wall-clock timestamp (0 if unavailable) */
|
||||
uint64_t backend_seq; /**< Backend-provided sequence counter */
|
||||
uint64_t cpu_total_jiffies; /**< /proc/stat total jiffies snapshot */
|
||||
uint64_t cpu_idle_jiffies; /**< /proc/stat idle jiffies snapshot */
|
||||
uint64_t cgroup_cpu_usage_us; /**< cgroup v2 cpu.stat usage_usec (0 if unavailable) */
|
||||
uint64_t cgroup_memory_current_bytes; /**< cgroup v2 memory.current (0 if unavailable) */
|
||||
} physics_host_snapshot_t;
|
||||
|
||||
/** Event header written into the analytics ring buffer. */
|
||||
typedef struct physics_analytics_event_header {
|
||||
uint32_t channel; /**< Logical channel identifier */
|
||||
uint16_t payload_bytes; /**< Size of event payload */
|
||||
uint16_t reserved; /**< Reserved for alignment */
|
||||
uint64_t timestamp_ns; /**< Producer timestamp */
|
||||
} physics_analytics_event_header_t;
|
||||
|
||||
/** Analytics heap header seen by both producer (VM) and consumer (HOLA). */
|
||||
typedef struct physics_analytics_header {
|
||||
uint32_t magic; /**< HOLA_SHARED_MAGIC */
|
||||
uint16_t version_major; /**< Protocol major version */
|
||||
uint16_t version_minor; /**< Protocol minor version */
|
||||
uint32_t heap_bytes; /**< Total heap size */
|
||||
uint32_t ring_offset; /**< Offset to event ring */
|
||||
uint32_t ring_bytes; /**< Event ring length */
|
||||
uint32_t summary_offset; /**< Offset to summary/scratch region */
|
||||
uint32_t summary_bytes; /**< Summary region length */
|
||||
uint32_t scratch_offset; /**< Offset to reserved scratch area */
|
||||
uint32_t scratch_bytes; /**< Scratch area length */
|
||||
uint64_t produce_seq; /**< Monotonic sequence for producers */
|
||||
uint64_t consume_seq; /**< Consumer-visible sequence */
|
||||
uint32_t write_offset; /**< Producer write cursor */
|
||||
uint32_t read_offset; /**< Consumer read cursor */
|
||||
uint32_t dropped_events; /**< Count of dropped events */
|
||||
uint32_t flags; /**< Heap flags (see docs) */
|
||||
} physics_analytics_header_t;
|
||||
|
||||
/** Simple view onto the analytics heap layout. */
|
||||
typedef struct physics_analytics_heap {
|
||||
uint8_t *base; /**< Base pointer (owned by runtime) */
|
||||
size_t bytes; /**< Total bytes reserved */
|
||||
physics_analytics_header_t *header; /**< Shared header */
|
||||
uint8_t *ring; /**< Event ring base */
|
||||
size_t ring_bytes; /**< Event ring span */
|
||||
uint8_t *summary; /**< Summary/statistics region */
|
||||
size_t summary_bytes; /**< Summary region span */
|
||||
uint8_t *scratch; /**< Scratch/reserved region */
|
||||
size_t scratch_bytes; /**< Scratch region span */
|
||||
} physics_analytics_heap_t;
|
||||
|
||||
/*
|
||||
* @brief Initialise physics runtime services.
|
||||
* @param analytics_heap_bytes Desired heap size (0 -> default 10 MiB)
|
||||
* @return 0 on success, -1 on failure
|
||||
*/
|
||||
int physics_runtime_init(size_t analytics_heap_bytes);
|
||||
|
||||
/**
|
||||
* @brief Tear down physics runtime services and release heap storage.
|
||||
*/
|
||||
void physics_runtime_shutdown(void);
|
||||
|
||||
/*
|
||||
* @brief Capture a host snapshot.
|
||||
* @param out Output buffer
|
||||
* @return 0 on success, -1 on failure
|
||||
*/
|
||||
int physics_host_snapshot(physics_host_snapshot_t *out);
|
||||
|
||||
/*
|
||||
* @brief Publish an event into the analytics ring buffer.
|
||||
* @param channel Logical event channel
|
||||
* @param payload Pointer to payload bytes
|
||||
* @param payload_bytes Payload length (<= ring size)
|
||||
* @return 0 on success, -1 if the payload could not be enqueued
|
||||
*/
|
||||
int physics_analytics_publish_event(uint32_t channel, const void *payload, uint16_t payload_bytes);
|
||||
|
||||
/**
|
||||
* @brief Retrieve the analytics heap descriptor.
|
||||
* @return Pointer to heap descriptor (NULL if runtime not initialised)
|
||||
*/
|
||||
const physics_analytics_heap_t *physics_analytics_heap_info(void);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* STARFORTH_PHYSICS_RUNTIME_H */
|
||||
Reference in New Issue
Block a user