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,205 @@
|
||||
/*
|
||||
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 ***
|
||||
|
||||
rolling_window_knobs.h - Tunable Adaptive Shrinking Control
|
||||
|
||||
Knobs that control how the rolling window automatically learns and adapts
|
||||
its size during execution. These are NOT the initial window size - they
|
||||
control the self-tuning behavior.
|
||||
|
||||
All knobs are tunable via Makefile:
|
||||
make ADAPTIVE_SHRINK_RATE=30 (shrink by 30% instead of default)
|
||||
make ADAPTIVE_MIN_WINDOW_SIZE=512 (never shrink below 512)
|
||||
etc.
|
||||
|
||||
*/
|
||||
|
||||
#ifndef ROLLING_WINDOW_KNOBS_H
|
||||
#define ROLLING_WINDOW_KNOBS_H
|
||||
|
||||
#include "starforth_config.h"
|
||||
|
||||
/* ============================================================================
|
||||
* Knob #8: ADAPTIVE_SHRINK_RATE - How aggressively to shrink the window
|
||||
* ============================================================================
|
||||
*
|
||||
* When pattern diversity plateaus, the window shrinks by this percentage.
|
||||
*
|
||||
* Value: 0-99 (percentage to retain, not discard)
|
||||
* ADAPTIVE_SHRINK_RATE=75 → shrink to 75% of current size (discard 25%)
|
||||
* ADAPTIVE_SHRINK_RATE=50 → shrink to 50% of current size (discard 50%)
|
||||
* ADAPTIVE_SHRINK_RATE=90 → shrink to 90% of current size (discard 10%)
|
||||
*
|
||||
* Rationale:
|
||||
* Higher (90+): Conservative, slow learning, larger final window
|
||||
* Default (75): Balanced - learns in 3-4 shrink cycles
|
||||
* Lower (50): Aggressive, fast learning, minimal final window
|
||||
*
|
||||
* Trade-off:
|
||||
* Higher = safer (more pattern capture margin, slower adaptation)
|
||||
* Lower = leaner (less memory overhead, faster optimization)
|
||||
*
|
||||
* Default: see starforth_config.h (STARFORTH_CONFIG_ADAPTIVE_SHRINK_RATE_DEFAULT)
|
||||
* Range: 50-95 (below 50 is too aggressive, above 95 barely shrinks)
|
||||
*
|
||||
* Tuning: make ADAPTIVE_SHRINK_RATE=80
|
||||
*/
|
||||
|
||||
/* ============================================================================
|
||||
* Knob #9: ADAPTIVE_MIN_WINDOW_SIZE - Minimum window size (safety floor)
|
||||
* ============================================================================
|
||||
*
|
||||
* The window will never shrink below this size, even if diversity plateaus.
|
||||
* Prevents over-optimization that might miss emerging patterns.
|
||||
*
|
||||
* Value: 64-2048 (in word IDs, not bytes)
|
||||
* ADAPTIVE_MIN_WINDOW_SIZE=256 → don't shrink below 256
|
||||
* ADAPTIVE_MIN_WINDOW_SIZE=128 → don't shrink below 128
|
||||
* ADAPTIVE_MIN_WINDOW_SIZE=512 → don't shrink below 512
|
||||
*
|
||||
* Rationale:
|
||||
* Smaller (128): Lean optimization, accept lower pattern capture
|
||||
* Default (256): Balanced - typical workload needs 200-250 patterns
|
||||
* Larger (512): Conservative, handles complex workloads
|
||||
*
|
||||
* Trade-off:
|
||||
* Smaller = less memory, risk of missing edge-case patterns
|
||||
* Larger = more memory, safer for unpredictable workloads
|
||||
*
|
||||
* Default: see starforth_config.h (STARFORTH_CONFIG_ADAPTIVE_MIN_WINDOW_SIZE_DEFAULT)
|
||||
* Range: 64-1024
|
||||
*
|
||||
* Tuning: make ADAPTIVE_MIN_WINDOW_SIZE=512
|
||||
*/
|
||||
|
||||
/* ============================================================================
|
||||
* Knob #10: ADAPTIVE_CHECK_FREQUENCY - How often to check diversity
|
||||
* ============================================================================
|
||||
*
|
||||
* The system checks pattern diversity every N executions.
|
||||
* More frequent checks = faster response to saturation, more overhead.
|
||||
*
|
||||
* Value: 32-1024 (execution count between checks)
|
||||
* ADAPTIVE_CHECK_FREQUENCY=128 → check after every 128 executions
|
||||
* ADAPTIVE_CHECK_FREQUENCY=256 → check after every 256 executions
|
||||
* ADAPTIVE_CHECK_FREQUENCY=512 → check after every 512 executions
|
||||
*
|
||||
* Rationale:
|
||||
* More frequent (128): Responsive learning, detects saturation quickly
|
||||
* Default (256): Balanced - good responsiveness, minimal overhead
|
||||
* Less frequent (512): Lazy learning, smaller monitoring overhead
|
||||
*
|
||||
* Trade-off:
|
||||
* More = faster adaptation, slightly more computation
|
||||
* Less = slower adaptation, minimal overhead
|
||||
*
|
||||
* Default: see starforth_config.h (STARFORTH_CONFIG_ADAPTIVE_CHECK_FREQUENCY_DEFAULT)
|
||||
* Range: 32-1024
|
||||
*
|
||||
* Tuning: make ADAPTIVE_CHECK_FREQUENCY=128
|
||||
*/
|
||||
|
||||
/* ============================================================================
|
||||
* Knob #11: ADAPTIVE_GROWTH_THRESHOLD - Pattern growth rate that signals saturation
|
||||
* ============================================================================
|
||||
*
|
||||
* When pattern diversity growth drops below this rate, window can shrink.
|
||||
* Expressed as percentage (0-100).
|
||||
*
|
||||
* Value: 0-10 (as percentage, 0=0%, 10=10%)
|
||||
* ADAPTIVE_GROWTH_THRESHOLD=1 → shrink when growth < 1% (aggressive)
|
||||
* ADAPTIVE_GROWTH_THRESHOLD=2 → shrink when growth < 2% (default, balanced)
|
||||
* ADAPTIVE_GROWTH_THRESHOLD=5 → shrink when growth < 5% (conservative)
|
||||
*
|
||||
* Rationale:
|
||||
* Lower (0.5%): Very aggressive, assumes patterns found early
|
||||
* Default (1%): Balanced - empirically tested, works well
|
||||
* Higher (5%): Conservative, waits for stronger saturation signal
|
||||
*
|
||||
* Trade-off:
|
||||
* Lower = eager shrinking, risk of missing late-arriving patterns
|
||||
* Higher = cautious shrinking, longer time to final window size
|
||||
*
|
||||
* Default: see starforth_config.h (STARFORTH_CONFIG_ADAPTIVE_GROWTH_THRESHOLD_DEFAULT)
|
||||
* Range: 0-10
|
||||
*
|
||||
* Note: Internally, this is applied as: growth_rate < (threshold / 100.0)
|
||||
* E.g., ADAPTIVE_GROWTH_THRESHOLD=1 means growth_rate < 0.01
|
||||
*
|
||||
* Tuning: make ADAPTIVE_GROWTH_THRESHOLD=2
|
||||
*/
|
||||
|
||||
/* ============================================================================
|
||||
* Summary Table: How Knobs Interact
|
||||
* ============================================================================
|
||||
*
|
||||
* Scenario 1: "Fast Learning, Lean Final Size"
|
||||
* ADAPTIVE_SHRINK_RATE=50
|
||||
* ADAPTIVE_MIN_WINDOW_SIZE=128
|
||||
* ADAPTIVE_CHECK_FREQUENCY=128
|
||||
* ADAPTIVE_GROWTH_THRESHOLD=0
|
||||
* → Shrinks aggressively, frequently, to minimal size
|
||||
* → Best for: Memory-constrained systems, simple workloads
|
||||
*
|
||||
* Scenario 2: "Balanced (Default)" -- see starforth_config.h for the exact
|
||||
* shipped default of each knob; illustrative values below.
|
||||
* ADAPTIVE_SHRINK_RATE=50
|
||||
* ADAPTIVE_MIN_WINDOW_SIZE=256
|
||||
* ADAPTIVE_CHECK_FREQUENCY=512
|
||||
* ADAPTIVE_GROWTH_THRESHOLD=5
|
||||
* → Good balance, typical FORTH programs
|
||||
* → Best for: General-purpose systems
|
||||
*
|
||||
* Scenario 3: "Conservative, Safe"
|
||||
* ADAPTIVE_SHRINK_RATE=90
|
||||
* ADAPTIVE_MIN_WINDOW_SIZE=512
|
||||
* ADAPTIVE_CHECK_FREQUENCY=512
|
||||
* ADAPTIVE_GROWTH_THRESHOLD=5
|
||||
* → Slow, cautious shrinking, large safety margin
|
||||
* → Best for: Complex workloads, unpredictable patterns
|
||||
*
|
||||
*/
|
||||
|
||||
#endif /* ROLLING_WINDOW_KNOBS_H */
|
||||
Reference in New Issue
Block a user