215 lines
9.0 KiB
C
215 lines
9.0 KiB
C
/*
|
||
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 */ |