rajames/LithosAnanke
1
1
Fork 0
Code Issues 60 Pull Requests Actions Packages Projects Releases Activity

Reorganize source tree: kernel/, v3/, v4/ split and board infrastructure

Browse Source 
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
2026-10-01 15:40:09 -04:00
co-authored by Junie
parent 3c709c115b
commit a8b70e88d3
630 changed files with 2646 additions and 2036 deletions
Download Patch File Download Diff File Expand all files Collapse all files
v3/src/word_source/include/README.md
+11
View File
@@ -0,0 +1,11 @@
# src/word_source/include/
Public headers for `src/word_source/`, one per `.c` file there (see
`src/word_source/README.md` for the category breakdown), plus
`control_words.h` and `mama_forth_words.h`:
- `control_words.h` — declarations for `control_words.c`'s `IF`/`THEN`/
`ELSE`/`BEGIN`/`DO`/`LOOP` family.
- `mama_forth_words.h` — declares the Mama VM word bindings implemented in
`src/starkernel/capsule/mama_forth_words.c` (kernel-only; the header
lives here for consistency with the rest of the word-category headers).
v3/src/word_source/include/acl_words.h
+8
View File
@@ -0,0 +1,8 @@
#pragma once
#include "vm.h"
/* Register all ACL C primitive words into the VM dictionary */
void register_acl_words(VM *vm);
/* Direct C entry point for birth inheritance (no stack manipulation needed) */
void acl_inherit_entry(DictEntry *src, DictEntry *dst);
v3/src/word_source/include/arithmetic_words.h
+90
View File
@@ -0,0 +1,90 @@
/*
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.
*/
#ifndef ARITHMETIC_WORDS_H
#define ARITHMETIC_WORDS_H
#include "vm.h"
/* FORTH-79 Arithmetic Words:
* + ( n1 n2 -- n3 ) Add n1 and n2
* - ( n1 n2 -- n3 ) Subtract n2 from n1
* * ( n1 n2 -- n3 ) Multiply n1 and n2
* / ( n1 n2 -- n3 ) Divide n1 by n2
* MOD ( n1 n2 -- n3 ) Remainder of n1/n2
* /MOD ( n1 n2 -- n3 n4 ) n3=remainder, n4=quotient of n1/n2
* NEGATE ( n1 -- n2 ) Negate n1
* ABS ( n1 -- n2 ) Absolute value of n1
* MIN ( n1 n2 -- n3 ) Minimum of n1 and n2
* MAX ( n1 n2 -- n3 ) Maximum of n1 and n2
* 1+ ( n1 -- n2 ) Add 1 to n1
* 1- ( n1 -- n2 ) Subtract 1 from n1
* 2* ( n1 -- n2 ) Multiply n1 by 2 (left shift)
* 2/ ( n1 -- n2 ) Divide n1 by 2 (right shift)
* STAR-SLASH ( n1 n2 n3 -- n4 ) Multiply n1*n2, divide by n3
*/
/**
* @brief Registers all FORTH-79 arithmetic words with the virtual machine
*
* Registers the following words:
* - + (add)
* - - (subtract)
* - * (multiply)
* - / (divide)
* - MOD (modulo)
* - /MOD (divide with remainder)
* - NEGATE
* - ABS (absolute)
* - MIN
* - MAX
* - 1+ (increment)
* - 1- (decrement)
* - 2* (multiply by 2)
* - 2/ (divide by 2)
* - STAR-SLASH (multiply then divide)
*
* @param vm Pointer to the Forth virtual machine instance
*/
void register_arithmetic_words(VM * vm);
#endif /* ARITHMETIC_WORDS_H */
v3/src/word_source/include/block_words.h
+196
View File
@@ -0,0 +1,196 @@
/*
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.
*/
/**
* @file block_words.h
* @brief FORTH-79 Block and Buffer System Implementation
*
* This file implements the standard FORTH-79 block and buffer words:
* @li BLOCK ( u -- addr ) Get block buffer address
* @li BUFFER ( u -- addr ) Get empty buffer for block
* @li UPDATE ( -- ) Mark current block as modified
* @li SAVE-BUFFERS ( -- ) Save all modified blocks
* @li EMPTY-BUFFERS ( -- ) Mark all buffers as empty
* @li FLUSH ( -- ) Save buffers and empty them
* @li LIST ( u -- ) List block contents
* @li LOAD ( u -- ) Load and interpret block
* @li SCR ( -- addr ) Variable: screen/block being listed
* @li THRU ( u1 u2 -- ) Load blocks from u1 to u2
* @li --> or → ( -- ) Continue to next block
*/
#ifndef BLOCK_WORDS_H
#define BLOCK_WORDS_H
#include "vm.h"
/** @name Block System Configuration
* @{
*/
/** @brief Size of each block in bytes (1KB) */
#define BLOCK_SIZE 1024
/** @brief Maximum number of blocks (1024 blocks from 1MB memory) */
#define MAX_BLOCKS (VM_MEMORY_SIZE / BLOCK_SIZE)
/** @brief Number of block buffers in memory */
#define BUFFER_COUNT 4
/** @} */
/**
* @brief Block buffer types for different storage mechanisms
*/
typedef enum {
BUFFER_TYPE_MEMORY, /**< Direct memory access (current implementation) */
BUFFER_TYPE_HARDWARE, /**< Future: Hardware register blocks */
BUFFER_TYPE_STORAGE, /**< Future: Persistent storage blocks */
BUFFER_TYPE_NETWORK /**< Future: Network packet buffers */
} buffer_type_t;
/**
* @brief Block buffer structure maintaining buffer state
*/
typedef struct {
unsigned char data[BLOCK_SIZE]; /**< Block content buffer */
int block_number; /**< Currently loaded block number (-1 = empty) */
int dirty; /**< Modified flag for write-back */
int accessed; /**< LRU counter for buffer management */
buffer_type_t type; /**< Buffer type for storage mechanism */
uintptr_t hw_address; /**< Future: Hardware backing address */
} BlockBuffer;
/**
* @brief Registers all block and buffer words with the virtual machine
* @param vm Pointer to the Forth virtual machine instance
*/
void register_block_words(VM * vm);
/**
* @brief Initializes the block system
* @param vm Pointer to the Forth virtual machine instance
*/
void init_block_system(VM * vm);
/*
* @brief Gets a buffer containing the specified block
* @param vm Pointer to the Forth virtual machine instance
* @param block_num Block number to retrieve
* @return Pointer to the block buffer data
*/
unsigned char *get_block_buffer(VM *vm, int block_num);
/*
* @brief Gets an empty buffer for the specified block
* @param vm Pointer to the Forth virtual machine instance
* @param block_num Block number to allocate
* @return Pointer to the empty buffer data
*/
unsigned char *get_empty_buffer(VM *vm, int block_num);
/**
* @brief Marks the current buffer as modified
* @param vm Pointer to the Forth virtual machine instance
*/
void mark_buffer_dirty(VM * vm);
/*
* @brief Saves all modified buffers to storage
* @param vm Pointer to the Forth virtual machine instance
*/
void save_all_buffers(VM * vm);
/**
* @brief Sync every dirty VM block-window slot to the C-layer block cache,
* then flush the whole block subsystem to physical media --
* the complete SAVE-BUFFERS implementation (unlike
* save_all_buffers() above, which only calls blk_flush() and so
* misses any BUFFER-modified-but-not-yet-UPDATE'd content still
* sitting only in vm->memory's window). Cheap to call when nothing
* is dirty -- every check inside is a small fixed-size scan, no
* I/O happens unless something actually needs writing. Safe to
* call from outside word dispatch (e.g. a periodic idle-tick
* auto-flush); vm must be non-NULL.
* @param vm Pointer to the Forth virtual machine instance
*/
void blk_vm_flush_all(VM * vm);
/*
* @brief Marks all buffers as empty
* @param vm Pointer to the Forth virtual machine instance
*/
void empty_all_buffers(VM * vm);
/**
* @brief Discards vm->blk_vm_lbn[]/cbuf[]/dirty[] if the device chain has
* changed since last validated (see this function's own doc comment in
* block_words.c for why). Exposed (Phase 8 v3, 2026-09-23) so callers
* outside this file that read vm->blk_vm_lbn[] directly (MOVE/CMOVE's
* cross-device block-copy check, memory_words.c/string_words.c) go through
* the same invalidation contract blk_vm_find() already uses internally,
* rather than a second, divergent copy of this logic.
* @param vm Pointer to the Forth virtual machine instance
*/
void blk_vm_check_epoch(VM *vm);
/**
* @brief Does `addr` fall inside the block I/O window? Pure address
* arithmetic against the window's fixed compile-time base/size -- no VM
* state needed. Exposed (Phase 8 v3, 2026-09-23) for MOVE/CMOVE/CMOVE>'s
* cross-device block-copy check.
* @param addr VM offset to test
* @return slot index (0..BLK_VM_SLOTS-1) if inside the window, -1 otherwise
*/
int blk_vm_slot_for_addr(vaddr_t addr);
/**
* @brief True if addr1/addr2 are both block-window addresses currently
* loaded from two different physical devices (Phase 8 v3, 2026-09-23) --
* the check MOVE/CMOVE/CMOVE> call before copying to refuse a same-VM,
* cross-device raw block copy. See this function's own doc comment in
* block_words.c for exactly what is and isn't flagged.
* @param vm VM performing the copy
* @param addr1 first VM offset (source or destination, order doesn't matter)
* @param addr2 second VM offset
* @return 1 if this copy should be refused, 0 otherwise
*/
int blk_vm_is_cross_device_copy(VM *vm, vaddr_t addr1, vaddr_t addr2);
#endif /* BLOCK_WORDS_H */
v3/src/word_source/include/control_words.h
+127
View File
@@ -0,0 +1,127 @@
/*
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.
*/
#ifndef CONTROL_WORDS_H
#define CONTROL_WORDS_H
#include "vm.h"
/**
* @defgroup control_words FORTH-79 Control Flow Words
* @{
* @brief Standard FORTH-79 control flow words implementation
*
* @def IF ( flag -- )
* Conditional execution based on flag
*
* @def THEN ( -- )
* End of IF conditional block
*
* @def ELSE ( -- )
* Alternative execution path
*
* @def BEGIN ( -- )
* Start of indefinite loop
*
* @def UNTIL ( flag -- )
* End loop if flag is true
*
* @def AGAIN ( -- )
* End infinite loop
*
* @def WHILE ( flag -- )
* Test condition in BEGIN loop
*
* @def REPEAT ( -- )
* End of WHILE loop
*
* @def DO ( limit start -- )
* Start definite loop
*
* @def LOOP ( -- )
* End DO loop, increment by 1
*
* @def +LOOP ( n -- )
* End DO loop, increment by n
*
* @def I ( -- n )
* Get current loop index
*
* @def J ( -- n )
* Get outer loop index
*
* @def LEAVE ( -- )
* Exit current loop
*
* @def UNLOOP ( -- )
* Discard loop parameters
*
* @def EXIT ( -- )
* Exit current word
*
* @def ABORT ( -- )
* Abort execution
*
* @def QUIT ( -- )
* Return to interpreter
*
* @def EXECUTE ( xt -- )
* Execute word at address
*
* @def BRANCH ( -- )
* Unconditional branch
*
* @def 0BRANCH ( flag -- )
* Branch if flag is zero
*
* @def (LIT) ( -- n )
* Push inline literal
* @}
*/
/**
* @brief Registers all control flow words with the Forth virtual machine
* @param vm Pointer to the Forth virtual machine instance
*/
void register_control_words(VM * vm);
#endif /* CONTROL_WORDS_H */
v3/src/word_source/include/defer_words.h
+17
View File
@@ -0,0 +1,17 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0.
*/
#ifndef DEFER_WORDS_H
#define DEFER_WORDS_H
#include "../../../include/vm.h"
void register_defer_words(VM *vm);
#endif /* DEFER_WORDS_H */
v3/src/word_source/include/defining_words.h
+77
View File
@@ -0,0 +1,77 @@
/*
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.
*/
#ifndef DEFINING_WORDS_H
#define DEFINING_WORDS_H
#include "vm.h"
/**
* @defgroup DefiningWords FORTH-79 Defining Words
* @{
* @brief Standard FORTH-79 defining words
*
* @details These words are used for creating new dictionary entries and defining words:
* - : ( -- ) Start colon definition
* - ; ( -- ) End colon definition
* - CREATE ( -- ) Create dictionary entry
* - DOES> ( -- ) Define runtime behavior
* - <BUILDS ( -- ) Create word with <BUILDS/DOES>
* - CONSTANT ( n -- ) Define constant
* - VARIABLE ( -- ) Define variable
* - 2CONSTANT ( d -- ) Define double constant
* - 2VARIABLE ( -- ) Define double variable
* - USER ( n -- ) Define user variable
* - IMMEDIATE ( -- ) Make most recent word immediate
* - [COMPILE] ( -- ) Force compilation of immediate word
* - COMPILE ( -- ) Compile inline code
* - FORGET ( -- ) Remove word and all after it
* @}
*/
/*
* @brief Registers all FORTH-79 defining words with the virtual machine
* @param vm Pointer to the virtual machine instance
*/
void register_defining_words(VM * vm);
#endif /* DEFINING_WORDS_H */
v3/src/word_source/include/dictionary_heat_diagnostic_words.h
+60
View File
@@ -0,0 +1,60 @@
/*
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.
*/
/*
* dictionary_heat_diagnostic_words.h
*
* FORTH interface for dictionary heat optimization diagnostics
*/
#ifndef DICTIONARY_HEAT_DIAGNOSTIC_WORDS_H
#define DICTIONARY_HEAT_DIAGNOSTIC_WORDS_H
#include "vm.h"
/**
* Register all dictionary heat diagnostic words with the VM
*/
void register_dictionary_heat_diagnostic_words(VM *vm);
#endif /* DICTIONARY_HEAT_DIAGNOSTIC_WORDS_H */
v3/src/word_source/include/dictionary_manipulation_words.h
+111
View File
@@ -0,0 +1,111 @@
/*
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.
*/
#ifndef DICTIONARY_MANIPULATION_WORDS_H
#define DICTIONARY_MANIPULATION_WORDS_H
#include "vm.h"
/**
* @defgroup dictionary_words FORTH-79 Dictionary Manipulation Words
* @{
* @brief Standard FORTH-79 words for dictionary manipulation
*
* @par [ ( -- )
* Enter interpretation mode. Switches the system to interpret incoming words.
*
* @par ] ( -- )
* Enter compilation mode. Switches the system to compile incoming words.
*
* @par STATE ( -- addr )
* Variable containing current compilation state. Returns address of STATE variable.
*
* @par SMUDGE ( -- )
* Toggle smudge bit of latest defined word. Used during word definition.
*
* @par >BODY ( xt -- addr )
* Convert execution token to parameter field address.
*
* @par >NAME ( xt -- addr )
* Convert execution token to name field address.
*
* @par NAME> ( addr -- xt )
* Convert name field address to execution token.
*
* @par >LINK ( addr -- addr )
* Get link field address from name field address.
*
* @par LINK> ( addr -- addr )
* Get next word's address from link field.
*
* @par CFA ( addr -- xt )
* Get code field address from name field address.
*
* @par LFA ( addr -- addr )
* Get link field address from name field address.
*
* @par NFA ( addr -- addr )
* Get name field address from any field address.
*
* @par PFA ( addr -- addr )
* Get parameter field address from name field address.
*
* @par TRAVERSE ( addr n -- addr )
* Move through name field by n characters.
*
* @par INTERPRET ( -- )
* Text interpreter - process input stream.
* @}
*/
/**
* @brief Register all dictionary manipulation words with the virtual machine
*
* @param vm Pointer to the virtual machine instance
*
* This function registers all FORTH-79 standard dictionary manipulation words
* with the provided virtual machine instance. These words are essential for
* dictionary management and word definition functionality.
*/
void register_dictionary_manipulation_words(VM * vm);
#endif /* DICTIONARY_MANIPULATION_WORDS_H */
v3/src/word_source/include/dictionary_words.h
+73
View File
@@ -0,0 +1,73 @@
/*
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.
*/
#ifndef DICTIONARY_WORDS_H
#define DICTIONARY_WORDS_H
#include "vm.h"
/**
* @defgroup dictionary FORTH-79 Dictionary & Compilation Words
* @{
*
* @brief Dictionary and compilation words as defined in FORTH-79 Standard
*
* @word HERE ( -- addr ) Returns address of next free dictionary space
* @word ALLOT ( n -- ) Allocates n bytes in dictionary
* @word , ( n -- ) Compiles n into dictionary
* @word C, ( c -- ) Compiles character into dictionary
* @word 2, ( d -- ) Compiles double into dictionary
* @word PAD ( -- addr ) Returns address of temporary text buffer
* @word SP! ( addr -- ) Sets data stack pointer
* @word SP@ ( -- addr ) Gets data stack pointer
* @word LATEST ( -- addr ) Returns address of most recent definition
* @}
*/
/**
* @brief Registers all dictionary and compilation words with the Forth VM
*
* @param vm Pointer to the Forth virtual machine instance
*/
void register_dictionary_words(VM * vm);
#endif /* DICTIONARY_WORDS_H */
v3/src/word_source/include/double_words.h
+78
View File
@@ -0,0 +1,78 @@
/*
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.
*/
#ifndef DOUBLE_WORDS_H
#define DOUBLE_WORDS_H
#include "vm.h"
/* FORTH-79 Double Number Words:
* S>D ( n -- d ) Convert single to double
* D+ ( d1 d2 -- d3 ) Add double numbers
* D- ( d1 d2 -- d3 ) Subtract double numbers
* DNEGATE ( d1 -- d2 ) Negate double number
* DABS ( d1 -- d2 ) Absolute value of double
* DMAX ( d1 d2 -- d3 ) Maximum of two doubles
* DMIN ( d1 d2 -- d3 ) Minimum of two doubles
* D< ( d1 d2 -- flag ) Compare doubles: d1 < d2
* D= ( d1 d2 -- flag ) Compare doubles: d1 = d2
* 2DROP ( d -- ) Drop double from stack
* 2DUP ( d -- d d ) Duplicate double
* 2SWAP ( d1 d2 -- d2 d1 ) Swap two doubles
* 2OVER ( d1 d2 -- d1 d2 d1 ) Copy second double to top
* 2ROT ( d1 d2 d3 -- d2 d3 d1 ) Rotate three doubles
* 2>R ( d -- ) ( R: -- d ) Move double to return stack
* 2R> ( -- d ) ( R: d -- ) Move double from return stack
* 2R@ ( -- d ) ( R: d -- d ) Copy double from return stack
* D0= ( d -- flag ) Test if double is zero
* D0< ( d -- flag ) Test if double is negative
* D2* ( d1 -- d2 ) Multiply double by 2
* D2/ ( d1 -- d2 ) Divide double by 2
*/
/*
* @brief Registers all double precision number manipulation words with the Forth virtual machine
* @param vm Pointer to the Forth virtual machine instance
*/
void register_double_words(VM * vm);
#endif /* DOUBLE_WORDS_H */
v3/src/word_source/include/editor_words.h
+125
View File
@@ -0,0 +1,125 @@
/*
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.
*/
#ifndef EDITOR_WORDS_H
#define EDITOR_WORDS_H
#include "vm.h"
/**
* @defgroup editor_words FORTH-79 Line Editor Words
* @{
*
* @brief Line editor commands implementation
*
* @fn void L ( -- )
* @brief List current screen
*
* @fn void T ( n -- )
* @brief Type line n of current screen
* @param[in] n Line number to type
*
* @fn void E ( n -- )
* @brief Edit line n of current screen
* @param[in] n Line number to edit
*
* @fn void S ( n addr -- )
* @brief Replace line n with string at addr
* @param[in] n Line number to replace
* @param[in] addr Address of replacement string
*
* @fn void I ( n -- )
* @brief Insert before line n
* @param[in] n Line number to insert before
*
* @fn void R ( n -- )
* @brief Replace line n
* @param[in] n Line number to replace
*
* @fn void D ( n -- )
* @brief Delete line n
* @param[in] n Line number to delete
*
* @fn void P ( n -- )
* @brief Position to line n
* @param[in] n Line number to position to
*
* @fn void COPY ( n1 n2 -- )
* @brief Copy line n1 to line n2
* @param[in] n1 Source line number
* @param[in] n2 Destination line number
*
* @fn void M ( n1 n2 -- )
* @brief Move line n1 to line n2
* @param[in] n1 Source line number
* @param[in] n2 Destination line number
*
* @fn void TILL ( c -- )
* @brief Search for character c
* @param[in] c Character to search for
*
* @fn void N ( -- )
* @brief Search for next occurrence
*
* @fn void WHERE ( -- )
* @brief Show current position
*
* @fn void TOP ( -- )
* @brief Go to top of screen
*
* @fn void BOTTOM ( -- )
* @brief Go to bottom of screen
*
* @fn void CLEAR ( -- )
* @brief Clear current screen
*
* @}
*/
/**
* @brief Register all editor words with the Forth virtual machine
*
* @param vm Pointer to the Forth virtual machine instance
*/
void register_editor_words(VM * vm);
#endif /* EDITOR_WORDS_H */
v3/src/word_source/include/format_words.h
+76
View File
@@ -0,0 +1,76 @@
/*
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.
*/
#ifndef FORMAT_WORDS_H
#define FORMAT_WORDS_H
#include "vm.h"
/* FORTH-79 Formatting & Conversion Words:
* . ( n -- ) Print signed number
* .R ( n width -- ) Print signed number right-justified
* U. ( u -- ) Print unsigned number
* U.R ( u width -- ) Print unsigned number right-justified
* D. ( d -- ) Print double number
* D.R ( d width -- ) Print double number right-justified
* .S ( -- ) Print stack contents
* ? ( addr -- ) Print value at address
* DUMP ( addr u -- ) Hex dump u bytes from addr
* <# ( -- ) Begin numeric conversion
* # ( ud1 -- ud2 ) Convert one digit
* #> ( ud -- addr u ) End numeric conversion
* #S ( ud -- 0 0 ) Convert all remaining digits
* HOLD ( c -- ) Insert character in conversion
* SIGN ( n -- ) Insert sign if negative
* BASE ( -- addr ) Variable containing number base
* DECIMAL ( -- ) Set base to 10
* HEX ( -- ) Set base to 16
* OCTAL ( -- ) Set base to 8
*/
/*
* @brief Registers all formatting and conversion words with the Forth virtual machine
* @param vm Pointer to the Forth virtual machine instance
*/
void register_format_words(VM * vm);
#endif /* FORMAT_WORDS_H */
v3/src/word_source/include/framebuffer_words.h
+38
View File
@@ -0,0 +1,38 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
#ifndef FRAMEBUFFER_WORDS_H
#define FRAMEBUFFER_WORDS_H
#include "vm.h"
/**
* @defgroup framebuffer_words Framebuffer Words
* @{
*
* @brief Raw hardware-boundary FORTH words for the Console drawing fabric
* (FABRIC-0.md item 4.3.3). Deliberately raster-native -- no Cartesian
* awareness, no policy. That lives in capsules/fabric.4th instead, per the
* compose-in-FORTH-first rule.
*
* Kernel-only: no-op on hosted builds (no framebuffer exists there).
*
* @par PLOT ( x y color -- )
* Write one pixel at raster coordinates (top-left origin, Y-down).
* Out-of-bounds writes are silently ignored (inherited from fb_put_pixel).
*
* @par FB-WIDTH ( -- n )
* @par FB-HEIGHT ( -- n )
* Push the framebuffer's pixel width / height.
* @}
*/
void register_framebuffer_words(VM *vm);
#endif /* FRAMEBUFFER_WORDS_H */
v3/src/word_source/include/inference_words.h
+25
View File
@@ -0,0 +1,25 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
/**
* inference_words.h — Module 26: SSM inference engine + Jacquard FORTH words
*/
#ifndef INFERENCE_WORDS_H
#define INFERENCE_WORDS_H
#include "vm.h"
/**
* Register all inference engine / Jacquard FORTH words with the VM.
* Module 26 in register_forth79_words().
*/
void register_inference_words(VM *vm);
#endif /* INFERENCE_WORDS_H */
v3/src/word_source/include/io_words.h
+73
View File
@@ -0,0 +1,73 @@
/*
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.
*/
#ifndef IO_WORDS_H //!< Include guard
#define IO_WORDS_H //!< Include guard
#include "vm.h"
/* FORTH-79 I/O & Terminal Words:
* EMIT ( c -- ) Output character c
* CR ( -- ) Output carriage return
* KEY ( -- c ) Input character from keyboard
* ?TERMINAL ( -- flag ) True if key pressed
* TYPE ( addr u -- ) Output u characters from addr
* SPACE ( -- ) Output one space
* SPACES ( n -- ) Output n spaces
*/
/**
* @brief Registers all I/O related FORTH words with the virtual machine
* @param vm Pointer to the virtual machine instance
*
* Registers the following FORTH-79 I/O & Terminal Words:
* - EMIT ( c -- ) Output character c
* - CR ( -- ) Output carriage return
* - KEY ( -- c ) Input character from keyboard
* - ?TERMINAL ( -- flag ) True if key pressed
* - TYPE ( addr u -- ) Output u characters from addr
* - SPACE ( -- ) Output one space
* - SPACES ( n -- ) Output n spaces
*/
void register_io_words(VM * vm);
#endif /* IO_WORDS_H */
v3/src/word_source/include/keyboard_words.h
+78
View File
@@ -0,0 +1,78 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
#ifndef KEYBOARD_WORDS_H
#define KEYBOARD_WORDS_H
#include "vm.h"
/**
* @defgroup keyboard_words Keyboard Words
* @{
*
* @brief Raw hardware-boundary FORTH word for verifying the interrupt-driven
* keyboard path (FABRIC-0.md item 4.3.5). Deliberately a diagnostic peek at
* the raw scancode ring buffer -- no set-2 translation, no REPL wiring.
* Those belong to the later REPL keyboard-input work noted in FABRIC-0.md.
*
* Kernel-only, amd64-only today (i8042 is amd64 hardware); no-op elsewhere
* so dictionary parity across all three architectures is unaffected.
*
* @par KBD-SCAN ( -- c -1 | 0 )
* Pop one raw scancode off the interrupt-fed ring buffer. Pushes the
* scancode and -1 (true) if one was available, or just 0 (false) if the
* buffer was empty.
*
* @par KBD-DEBUG ( -- isr_count spurious_count )
* Standing diagnostic: count of real keyboard IRQs serviced and count of
* LAPIC spurious-vector interrupts, both since boot.
*
* @par VKBD-EVENT ( -- code value -1 | 0 )
* Items 4.3.5c (riscv64) / 4.3.5e (aarch64). Pop one decoded EV_KEY event
* (Linux input-event code/value pair) off the virtio-input interrupt-fed
* ring buffer. Kernel-only, riscv64/aarch64 (virtio-keyboard-pci); no-op
* on amd64 (i8042 hardware instead, see KBD-SCAN).
*
* @par VKBD-DEBUG ( -- isr_count )
* Standing diagnostic: count of virtio-input ISR invocations since boot.
*
* @par KEY-EVENT ( -- keycode pressed -1 | 0 )
* Item 4.3.5f convergence checkpoint. One shared event shape across all
* three architectures: keycode in the Linux input keycode namespace
* (identical numbering to amd64's raw XT Set-1 scancode for the
* non-extended key range, by historical design, not translated arbitrarily
* -- see the implementation's own doc comment), pressed is 1 or 0. This is
* the word the later REPL keyboard-input work (M8) is expected to build
* on; KBD-SCAN/VKBD-EVENT remain as lower-level per-device diagnostics.
*
* @par ALT+TAB ( -- )
* FABRIC-0.md item 4.4y-revised. Programmatic equivalent of the physical
* Alt+TAB graphics/text toggle -- calls the same state-machine transition
* (console_fb_toggle_graphics() / vt100_toggle_graphics()) the keyboard
* interception in repl.c uses, so there is exactly one place the toggle
* actually happens.
* @}
*/
void register_keyboard_words(VM *vm);
/**
* FABRIC-0.md item 4.4v: shared C-level poll, one converged event stream
* (Linux input keycode namespace, all three architectures) -- see
* KEY-EVENT's doc comment above for the full per-arch translation
* rationale. Used by both kbw_key_event() (the FORTH word) and the REPL
* keyboard bridge (repl.c), so there is exactly one implementation.
*
* @param keycode Written with the Linux input keycode on success.
* @param pressed Written with 1 (press/repeat) or 0 (release) on success.
* @return 1 if an event was available, 0 otherwise.
*/
int sk_key_event_poll(uint16_t *keycode, int *pressed);
#endif /* KEYBOARD_WORDS_H */
v3/src/word_source/include/log_words.h
+62
View File
@@ -0,0 +1,62 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
#ifndef LOG_WORDS_H
#define LOG_WORDS_H
#include "vm.h"
/**
* @defgroup log_words Log Words
* @{
*
* @brief FORTH words for log-level control and structured string emission.
*
* @par Level constants ( -- n )
* Push the corresponding LogLevel integer onto the stack.
* LOG-ERROR ( -- 0 )
* LOG-WARN ( -- 1 )
* LOG-INFO ( -- 2 )
* LOG-TEST ( -- 3 )
* LOG-DEBUG ( -- 4 )
*
* @par LOG-LEVEL! ( n -- )
* Set the current log level to n. Values outside 0–4 clamp to LOG-DEBUG.
*
* @par LOG-LEVEL@ ( -- n )
* Push the current log level.
*
* @par LOG-INFO" ( "ccc<quote>" -- ) IMMEDIATE
* @par LOG-WARN" ( "ccc<quote>" -- ) IMMEDIATE
* @par LOG-ERROR" ( "ccc<quote>" -- ) IMMEDIATE
* @par LOG-TEST" ( "ccc<quote>" -- ) IMMEDIATE
* @par LOG-DEBUG" ( "ccc<quote>" -- ) IMMEDIATE
* Parse the string literal up to the closing double-quote and emit it
* via log_message() at the corresponding level. Works in both interpret
* and compile mode (like ."). The level filter is applied at runtime so
* DEBUG messages are free when the level is INFO.
*
* @par LOG-INFO-STR ( c-addr u -- )
* @par LOG-WARN-STR ( c-addr u -- )
* @par LOG-ERROR-STR ( c-addr u -- )
* @par LOG-TEST-STR ( c-addr u -- )
* @par LOG-DEBUG-STR ( c-addr u -- )
* Consume a counted string from the stack (as produced by S") and emit
* it via log_message() at the corresponding level.
*
* @par Runtime words (not for direct use)
* (do-log-error) (do-log-warn) (do-log-info)
* (do-log-test) (do-log-debug)
* Threaded-code runtime helpers compiled by the LOG-*" immediates.
* @}
*/
void register_log_words(VM *vm);
#endif /* LOG_WORDS_H */
v3/src/word_source/include/logical_words.h
+78
View File
@@ -0,0 +1,78 @@
/*
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.
*/
#ifndef LOGICAL_WORDS_H
#define LOGICAL_WORDS_H
#include "vm.h"
/**
* @defgroup logical_ops FORTH-79 Logical Operations
* @{
*
* @brief FORTH-79 Standard logical and comparison operations
*
* @details Implementation of the following FORTH-79 words:
* - AND ( n1 n2 -- n3 ) Bitwise AND
* - OR ( n1 n2 -- n3 ) Bitwise OR
* - XOR ( n1 n2 -- n3 ) Bitwise XOR
* - NOT ( n1 -- n2 ) Bitwise NOT
* - 0= ( n -- flag ) True if n is zero
* - 0< ( n -- flag ) True if n is negative
* - 0> ( n -- flag ) True if n is positive
* - = ( n1 n2 -- flag ) True if n1 equals n2
* - < ( n1 n2 -- flag ) True if n1 < n2
* - > ( n1 n2 -- flag ) True if n1 > n2
* - U< ( u1 u2 -- flag ) True if u1 < u2 (unsigned)
* - U> ( u1 u2 -- flag ) True if u1 > u2 (unsigned)
* - WITHIN ( n low high -- flag ) True if low <= n < high
* @}
*/
/*
* @brief Registers all logical and comparison words with the Forth virtual machine
*
* @param vm Pointer to the Forth virtual machine instance
*/
void register_logical_words(VM * vm);
#endif /* LOGICAL_WORDS_H */
v3/src/word_source/include/mama_forth_words.h
+185
View File
@@ -0,0 +1,185 @@
/*
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.
*/
/**
* @file mama_forth_words.h
* @brief Mama FORTH vocabulary words for kernel capsule system (M7.1)
*
* This header defines the Mama FORTH vocabulary - kernel-only words
* for the LithosAnanke capsule birth protocol.
*
* These words are ONLY available in __STARKERNEL__ builds.
* Hosted StarForth builds do not include capsule functionality.
*
* Mama FORTH Vocabulary:
* CAPSULE-COUNT ( -- n ) Number of capsules in directory
* CAPSULE@ ( idx -- desc ) Get descriptor address by index
* CAPSULE-HASH@ ( desc -- hash ) Get capsule content hash
* CAPSULE-FLAGS@ ( desc -- flags ) Get capsule flags
* CAPSULE-LEN@ ( desc -- len ) Get payload length
* CAPSULE-BIRTH ( hash -- vm-id ) Birth baby VM from (p) capsule
* CAPSULE-RUN ( hash -- ) Run (e) capsule on Mama
* MAMA-VM-ID ( -- 0 ) Mama's VM ID (always 0)
* VM-COUNT ( -- n ) Number of live VMs
*/
#ifndef MAMA_FORTH_WORDS_H
#define MAMA_FORTH_WORDS_H
#include "../../../include/vm.h"
#ifdef __STARKERNEL__
/**
* @brief Register Mama FORTH vocabulary words with the VM
*
* Creates the MAMA vocabulary and registers all capsule-related words.
* Only available in kernel builds.
*
* @param vm Pointer to the VM instance
*/
void register_mama_forth_words(VM *vm);
/* Individual word implementations (kernel-only) */
/**
* @brief CAPSULE-COUNT ( -- n )
* Push number of capsules in the capsule directory.
*/
void mama_word_capsule_count(VM *vm);
/**
* @brief CAPSULE@ ( idx -- desc )
* Get capsule descriptor address by index.
*/
void mama_word_capsule_fetch(VM *vm);
/**
* @brief CAPSULE-HASH@ ( desc -- hash )
* Get content hash from capsule descriptor.
*/
void mama_word_capsule_hash_fetch(VM *vm);
/**
* @brief CAPSULE-FLAGS@ ( desc -- flags )
* Get flags from capsule descriptor.
*/
void mama_word_capsule_flags_fetch(VM *vm);
/**
* @brief CAPSULE-LEN@ ( desc -- len )
* Get payload length from capsule descriptor.
*/
void mama_word_capsule_len_fetch(VM *vm);
/**
* @brief CAPSULE-BIRTH ( capsule-id -- vm-id )
* Birth a baby VM from a production (p) capsule.
* Returns the new VM's ID, or -1 on failure.
*/
void mama_word_capsule_birth(VM *vm);
/**
* @brief CAPSULE-RUN ( capsule-id -- )
* Run an experiment (e) capsule on Mama.
*/
void mama_word_capsule_run(VM *vm);
/**
* @brief MAMA-VM-ID ( -- 0 )
* Push Mama's VM ID (always 0).
*/
void mama_word_mama_vm_id(VM *vm);
/**
* @brief VM-COUNT ( -- n )
* Push number of registered VMs.
*/
void mama_word_vm_count(VM *vm);
/**
* @brief BIRTH ( c-addr u -- )
* Birth a named VM from its capsule. Idempotent if already live.
*/
void mama_word_birth(VM *vm);
/**
* @brief KILL ( c-addr u -- )
* Destroy a named VM. Hera cannot be killed. Idempotent if dead.
*/
void mama_word_kill(VM *vm);
/**
* @brief START ( c-addr u -- )
* Enter a named VM's REPL synchronously. Blocks until target STOPs.
*/
void mama_word_start(VM *vm);
/**
* @brief STOP ( -- )
* Self-stop: set vm->halted so the REPL loop exits. Registered in
* every VM (including child VMs) so any VM can stop itself.
*/
void mama_word_stop(VM *vm);
/**
* @brief USE ( c-addr u -- )
* Redirect REPL input to a named VM without C stack push.
* USE Hera resets to default (Mama).
*/
void mama_word_use(VM *vm);
/**
* @brief EXEC ( c-addr u -- )
* Execute a named capsule on the current VM. Registered in both Mama
* and all child VMs so any VM can load a capsule (e.g. doe.4th).
*/
void mama_word_exec(VM *vm);
/**
* @brief CAPSULE-TEST ( -- )
* Print diagnostic message confirming capsule system is active.
*/
void mama_word_capsule_test(VM *vm);
/**
* @brief Register minimal word set for child VMs: STOP and EXEC.
*
* Call from capsule_vm_alloc_hook() instead of passing mama_word_stop /
* mama_word_exec as cross-TU function pointers (which generate
* R_X86_64_REX_GOTPCRELX relocations not relaxed by the PE32+ linker).
*/
void register_child_vm_words(VM *vm);
#else /* !__STARKERNEL__ */
/**
* @brief Stub for hosted builds - does nothing
*/
static inline void register_mama_forth_words(VM *vm) {
(void)vm;
/* Mama FORTH words are kernel-only */
}
#endif /* __STARKERNEL__ */
#endif /* MAMA_FORTH_WORDS_H */
v3/src/word_source/include/memory_words.h
+75
View File
@@ -0,0 +1,75 @@
/*
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.
*/
#ifndef MEMORY_WORDS_H
#define MEMORY_WORDS_H
#include "vm.h"
/**
* @defgroup memory_ops FORTH-79 Memory Operations
* @{
* @brief Memory operation words defined in FORTH-79 standard
*
* @par Available operations:
* - ! ( n addr -- ) Store n at addr
* - @ ( addr -- n ) Fetch n from addr
* - C! ( c addr -- ) Store character at addr
* - C@ ( addr -- c ) Fetch character from addr
* - +! ( n addr -- ) Add n to value at addr
* - 2! ( d addr -- ) Store double at addr
* - 2@ ( addr -- d ) Fetch double from addr
* - FILL ( addr u c -- ) Fill u bytes at addr with c
* - MOVE ( addr1 addr2 u -- ) Move u bytes from addr1 to addr2
* - CMOVE ( addr1 addr2 u -- ) Move u bytes, low to high addresses
* - CMOVE> ( addr1 addr2 u -- ) Move u bytes, high to low addresses
* - ERASE ( addr u -- ) Fill u bytes at addr with zeros
* @}
*/
/*
* @brief Registers all memory operation words with the Forth virtual machine
* @param vm Pointer to the virtual machine instance
*/
void register_memory_words(VM * vm);
#endif /* MEMORY_WORDS_H */
v3/src/word_source/include/mixed_arithmetic_words.h
+61
View File
@@ -0,0 +1,61 @@
/*
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.
*/
#ifndef MIXED_ARITHMETIC_WORDS_H
#define MIXED_ARITHMETIC_WORDS_H
#include "vm.h"
/* FORTH-79 Mixed Arithmetic Words (single/double precision):
* M+ ( d1 n -- d2 ) Add single to double
* M- ( d1 n -- d2 ) Subtract single from double
* M-STAR-SLASH ( d1 n1 n2 -- d2 ) Multiply double by single, divide by single
* SM/REM ( d n1 -- n2 n3 ) Symmetric divide/remainder
* FM/MOD ( d n1 -- n2 n3 ) Floored divide/mod
* UM* ( u1 u2 -- ud ) Unsigned multiply to double
* UM/MOD ( ud u1 -- u2 u3 ) Unsigned divide/mod
* STAR-SLASH-MOD ( n1 n2 n3 -- n4 n5 ) Intermediate multiply/divide/mod
*/
void register_mixed_arithmetic_words(VM * vm);
#endif /* MIXED_ARITHMETIC_WORDS_H */
v3/src/word_source/include/physics_benchmark_words.h
+59
View File
@@ -0,0 +1,59 @@
/*
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.
*/
/*
* physics_benchmark_words.h
*
* FORTH words for benchmarking hot-words cache impact
*/
#ifndef PHYSICS_BENCHMARK_WORDS_H
#define PHYSICS_BENCHMARK_WORDS_H
#include "vm.h"
/**
* Register all physics benchmark words with the VM
*/
void register_physics_benchmark_words(VM *vm);
#endif /* PHYSICS_BENCHMARK_WORDS_H */
v3/src/word_source/include/physics_diagnostic_words.h
+79
View File
@@ -0,0 +1,79 @@
/*
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.
*/
/*
* physics_diagnostic_words.h
*
* Interactive FORTH words for live physics feedback loop demonstration.
*/
#ifndef PHYSICS_DIAGNOSTIC_WORDS_H
#define PHYSICS_DIAGNOSTIC_WORDS_H
#include "vm.h"
/**
* Display detailed physics metrics for the most recently executed word
*/
void forth_PHYSICS_WORD_METRICS(VM *vm);
/**
* Calculate and show knob adjustments based on current thermal metrics
*/
void forth_PHYSICS_CALC_KNOBS(VM *vm);
/**
* Execute a word repeatedly (burn) and show thermal feedback
*/
void forth_PHYSICS_BURN(VM *vm);
/**
* Display the complete feedback loop: inputs → math → knobs → effect
*/
void forth_PHYSICS_SHOW_FEEDBACK(VM *vm);
/**
* Register all physics diagnostic words with the VM
*/
void register_physics_diagnostic_words(VM *vm);
#endif /* PHYSICS_DIAGNOSTIC_WORDS_H */
v3/src/word_source/include/physics_freeze_words.h
+60
View File
@@ -0,0 +1,60 @@
/*
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.
*/
/*
* physics_freeze_words.h
*
* Phase 2 Freeze/Decay Control Words for physics-driven adaptive runtime
*/
#ifndef PHYSICS_FREEZE_WORDS_H
#define PHYSICS_FREEZE_WORDS_H
#include "vm.h"
/**
* Register all Phase 2 freeze/decay control words with the VM
*/
void register_physics_freeze_words(VM *vm);
#endif /* PHYSICS_FREEZE_WORDS_H */
v3/src/word_source/include/physics_pipelining_diagnostic_words.h
+61
View File
@@ -0,0 +1,61 @@
/*
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.
*/
/*
* physics_pipelining_diagnostic_words.h
*
* Declarations for pipelining metrics diagnostic words.
* Phase 1: Display word-to-word transition statistics collected during execution.
*/
#ifndef PHYSICS_PIPELINING_DIAGNOSTIC_WORDS_H
#define PHYSICS_PIPELINING_DIAGNOSTIC_WORDS_H
#include "vm.h"
/**
* Register all pipelining diagnostic words
* Called during VM initialization
*/
void register_physics_pipelining_diagnostic_words(VM *vm);
#endif /* PHYSICS_PIPELINING_DIAGNOSTIC_WORDS_H */
v3/src/word_source/include/q48_words.h
+25
View File
@@ -0,0 +1,25 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
/**
* q48_words.h — Module 25: Q48.16 fixed-point FORTH words
*/
#ifndef Q48_WORDS_H
#define Q48_WORDS_H
#include "vm.h"
/**
* Register all Q48.16 FORTH words with the VM.
* Module 25 in register_forth79_words().
*/
void register_q48_words(VM *vm);
#endif /* Q48_WORDS_H */
v3/src/word_source/include/return_stack_words.h
+81
View File
@@ -0,0 +1,81 @@
/*
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.
*/
#ifndef RETURN_STACK_WORDS_H
#define RETURN_STACK_WORDS_H
#include "vm.h"
/**
* @defgroup ReturnStackOps FORTH-79 Return Stack Operations
* @{
*
* @def >R
* @brief Move item from data to return stack
* Stack effect: ( n -- ) ( R: -- n )
*
* @def R>
* @brief Move item from return to data stack
* Stack effect: ( -- n ) ( R: n -- )
*
* @def R@
* @brief Copy top of return stack to data stack
* Stack effect: ( -- n ) ( R: n -- n )
*
* @def RP!
* @brief Set return stack pointer
* Stack effect: ( addr -- )
*
* @def RP@
* @brief Get return stack pointer
* Stack effect: ( -- addr )
* @}
*/
/*
* @brief Registers all return stack manipulation words with the virtual machine
*
* @param vm Pointer to the virtual machine instance
*/
void register_return_stack_words(VM * vm);
#endif /* RETURN_STACK_WORDS_H */
v3/src/word_source/include/scroll_words.h
+36
View File
@@ -0,0 +1,36 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
#ifndef SCROLL_WORDS_H
#define SCROLL_WORDS_H
#include "vm.h"
/**
* @defgroup scroll_words REPL Scrollback Words
* @{
*
* @brief `SCROLL-BACK`/`SCROLL-FWD`, the REPL scrollback controls
* (FABRIC-0.md item 4.4q). Kernel-only; no-op on hosted builds (no
* framebuffer console there).
*
* @par SCROLL-BACK ( n -- )
* Move the scrollback view back @c n lines (toward older output) and
* redraw. Clamped at the oldest stored line -- no error on over-request,
* it just stops there.
*
* @par SCROLL-FWD ( n -- )
* Move the scrollback view forward @c n lines (toward live output) and
* redraw. Clamped at the live view.
* @}
*/
void register_scroll_words(VM *vm);
#endif /* SCROLL_WORDS_H */
v3/src/word_source/include/stack_words.h
+75
View File
@@ -0,0 +1,75 @@
/*
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.
*/
#ifndef STACK_WORDS_H
#define STACK_WORDS_H
#include "vm.h"
/**
* @defgroup stack_ops FORTH-79 Stack Operations
* @{
*
* @brief Standard FORTH-79 stack manipulation words
*
* @details The following FORTH words are implemented for stack manipulation:
* - DROP ( n -- ) Remove top stack item
* - DUP ( n -- n n ) Duplicate top stack item
* - ?DUP ( n -- n n | n -- 0 ) Duplicate if non-zero
* - SWAP ( n1 n2 -- n2 n1 ) Exchange top two stack items
* - OVER ( n1 n2 -- n1 n2 n1 ) Copy second stack item to top
* - ROT ( n1 n2 n3 -- n2 n3 n1 ) Rotate top three stack items
* - -ROT ( n1 n2 n3 -- n3 n1 n2 ) Reverse rotate top three items
* - DEPTH ( -- n ) Return number of stack items
* - PICK ( n -- stack[n] ) Copy nth stack item to top
* - ROLL ( n -- ) Move nth stack item to top
* @}
*/
/*
* @brief Registers all stack operation words with the virtual machine
*
* @param vm Pointer to the virtual machine instance
*/
void register_stack_words(VM * vm);
#endif /* STACK_WORDS_H */
v3/src/word_source/include/starforth_words.h
+131
View File
@@ -0,0 +1,131 @@
/*
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.
*/
#ifndef STARFORTH_WORDS_H
#define STARFORTH_WORDS_H
#include "vm.h"
/** @name StarForth Implementation Vocabulary Words */
///@{
/**
* @brief Fetch entropy value from address
* @param vm Pointer to VM instance
* @stack ( addr -- n )
*/
void starforth_word_entropy_fetch(VM * vm);
/**
* @brief Store entropy value to address
* @param vm Pointer to VM instance
* @stack ( n addr -- )
*/
void starforth_word_entropy_store(VM * vm);
/**
* @brief Calculate word entropy
* @param vm Pointer to VM instance
* @stack ( -- )
*/
void starforth_word_word_entropy(VM * vm);
/**
* @brief Reset entropy values
* @param vm Pointer to VM instance
* @stack ( -- )
*/
void starforth_word_reset_entropy(VM * vm);
/*
* @brief Display top N words by entropy
* @param vm Pointer to VM instance
* @stack ( n -- )
*/
void starforth_word_top_words(VM * vm);
/*
* @brief Shebang-style comment for init-4.4th metadata
* @param vm Pointer to VM instance
* @stack ( -- )
*/
void starforth_word_paren_dash(VM * vm);
/*
* @brief Initialize system from init-4.4th
* @param vm Pointer to VM instance
* @stack ( -- )
*/
void starforth_word_init(VM * vm);
/*
* @brief Set PRNG seed for reproducible random sequences
* @param vm Pointer to VM instance
* @stack ( n -- )
*/
void starforth_word_seed(VM * vm);
/**
* @brief Generate bounded random number
* @param vm Pointer to VM instance
* @stack ( lo hi -- n )
* @note Returns random value in inclusive range [lo, hi]
*/
void starforth_word_random(VM * vm);
/*
* @brief Wait/sleep for specified milliseconds
* @param vm Pointer to VM instance
* @stack ( n -- )
* @note General-purpose delay, also useful for VM cooling between benchmarks
*/
void starforth_word_wait(VM * vm);
///@}
/*
* @brief Register all StarForth words with VM
* @param vm Pointer to VM instance where words will be registered
*/
void register_starforth_words(VM * vm);
#endif /* STARFORTH_WORDS_H */
v3/src/word_source/include/string_words.h
+152
View File
@@ -0,0 +1,152 @@
/*
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.
*/
#ifndef STRING_WORDS_H
#define STRING_WORDS_H
#include "vm.h"
/** @file string_words.h
* @brief FORTH-79 Standard string and text processing words implementation
*
* This file contains the implementation of FORTH-79 standard string and text processing words.
* These words provide functionality for string manipulation, input handling, and parsing.
*/
/** @name FORTH-79 String & Text Processing Words
* @{
*/
/**
* @brief COUNT ( addr1 -- addr2 u ) Get string length and address
* Returns the character count and address of a counted string
*/
/**
* @brief EXPECT ( addr u -- ) Accept input line
* Accepts up to u characters of input and stores them at addr
*/
/**
* @brief SPAN ( -- addr ) Variable: number of characters input
* Contains the count of characters actually received by EXPECT
*/
/**
* @brief QUERY ( -- ) Accept input into TIB
* Accepts a line of input into the Terminal Input Buffer
*/
/**
* @brief TIB ( -- addr ) Terminal input buffer address
* Returns the address of the Terminal Input Buffer
*/
/**
* @brief WORD ( c -- addr ) Parse next word, delimited by c
* Parses the next word from input stream using c as delimiter
*/
/**
* @brief >IN ( -- addr ) Input stream pointer
* Contains the offset into the input buffer
*/
/**
* @brief SOURCE ( -- addr u ) Input source specification
* Returns current input buffer address and length
*/
/**
* @brief BL ( -- c ) ASCII space character (32)
* Pushes ASCII space character value onto stack
*/
/**
* @brief FIND ( addr -- addr flag ) Find word in dictionary
* Searches dictionary for word, returns status flag
*/
/**
* @brief ' ( -- xt ) Get execution token of next word
* Returns execution token of next word in input stream
*/
/**
* @brief ['] ( -- xt ) Compile execution token
* Compiles execution token as literal
*/
/**
* @brief LITERAL ( n -- ) Compile literal number
* Compiles top stack value as literal
*/
/**
* @brief [LITERAL] ( n -- ) Compile literal at compile time
* Compiles literal during compilation
*/
/**
* @brief CONVERT ( d1 addr1 -- d2 addr2 ) Convert string to number
* Converts string starting at addr1 to number
*/
/**
* @brief NUMBER ( addr -- n flag ) Convert string to single number
* Converts string to single precision number
*/
/**
* @brief ENCLOSE ( addr c -- addr1 n1 n2 n3 ) Parse for delimiter
* Parses string for delimiter character
*/
/** @} */
/**
* @brief Register all string processing words with VM
* @param vm Pointer to VM instance where words will be registered
*/
void register_string_words(VM * vm);
#endif /* STRING_WORDS_H */
v3/src/word_source/include/system_words.h
+99
View File
@@ -0,0 +1,99 @@
/*
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.
*/
#ifndef SYSTEM_WORDS_H
#define SYSTEM_WORDS_H
#include "vm.h"
/**
* @defgroup system_words FORTH-79 System & Environment Words
* @{
*
* @brief System and environment control words for FORTH-79
*
* @details The following words provide system and environment control functionality:
*
* @par COLD ( -- )
* Performs a cold start of the system, reinitializing all system variables
*
* @par WARM ( -- )
* Performs a warm start of the system, preserving some system state
*
* @par BYE ( -- )
* Exits the FORTH system and returns to the host operating system
*
* @par SAVE-SYSTEM ( -- )
* Saves the current system image to disk
*
* @par WORDS ( -- )
* Lists all words in the current vocabulary
*
* @par VLIST ( -- )
* Lists all words in all vocabularies
*
* @par ?STACK ( -- )
* Checks the stack depth and reports any stack errors
*
* @par PAGE ( -- )
* Clears the screen or outputs a form feed
*
* @par NOP ( -- )
* Performs no operation
*
* @par 79-STANDARD ( -- )
* Ensures FORTH-79 standard compliance
* @}
*/
/**
* @brief Registers all system words with the virtual machine
*
* @param vm Pointer to the virtual machine instance
*
* @details This function registers all FORTH-79 system and environment words
* with the specified virtual machine instance, making them available for use
* in the FORTH environment.
*/
void register_system_words(VM * vm);
#endif /* SYSTEM_WORDS_H */
v3/src/word_source/include/ttf_words.h
+38
View File
@@ -0,0 +1,38 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
#ifndef TTF_WORDS_H
#define TTF_WORDS_H
#include "vm.h"
/**
* @defgroup ttf_words TrueType Text Words
* @{
*
* @brief `TTF-TEXT`, the TrueType-backed text entry point (FABRIC-0.md item
* 4.3.7e). Kernel-only; no-op on hosted builds (no framebuffer/capsule
* system exists there).
*
* @par TTF-TEXT ( c-addr u x y size color -- )
* Render a UTF-8 string via the v1 default font capsule
* (`fonts:JetBrainsMono-Regular.ttf`, loaded and cached lazily on first
* use). (x,y) is raster pixel space (top-left origin, Y-down) -- NOT
* capsules/fabric.4th's Cartesian Y-up convention used by the stroke
* font's `TEXT` (4.3.6f); the two are deliberately different coordinate
* systems, not interchangeable. (x,y) is the first glyph's baseline-left
* origin. `size` is capped at `TTF_CACHE_MAX_SIZE_PX` (see ttf.h).
* Advances proportionally per glyph via the font's real hmtx advance
* width, scaled to pixels.
* @}
*/
void register_ttf_words(VM *vm);
#endif /* TTF_WORDS_H */
v3/src/word_source/include/vocabulary_words.h
+101
View File
@@ -0,0 +1,101 @@
/*
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.
*/
#ifndef VOCABULARY_WORDS_H
#define VOCABULARY_WORDS_H
#include "vm.h"
/**
* @defgroup vocabulary FORTH-79 Vocabulary System Words
* @{
* @brief Standard vocabulary manipulation words
*
* @par VOCABULARY ( -- )
* Create new vocabulary
* @par DEFINITIONS ( -- )
* Set current vocabulary
* @par CONTEXT ( -- addr )
* Variable: search vocabulary pointer
* @par CURRENT ( -- addr )
* Variable: definition vocabulary pointer
* @par FORTH ( -- )
* Select FORTH vocabulary
* @par ONLY ( -- )
* Set minimal search order
* @par ALSO ( -- )
* Duplicate top of search order
* @par ORDER ( -- )
* Display search order
* @par PREVIOUS ( -- )
* Remove top of search order
* @par (FIND) ( addr -- addr flag )
* Find word in dictionary (primitive)
* @}
*/
/*
* @brief Registers all vocabulary-related words in the Forth system
* @param vm Pointer to the virtual machine instance
*/
void register_vocabulary_words(VM * vm);
/**
* @brief Direct vocabulary creation (kernel bootstrap)
* @param vm Pointer to the virtual machine instance
* @param name Vocabulary name
*/
void vocabulary_create_vocabulary_direct(VM *vm, const char *name);
/*
* @brief DEFINITIONS word implementation (kernel bootstrap)
* @param vm Pointer to the virtual machine instance
*/
void vocabulary_word_definitions(VM *vm);
/*
* @brief FORTH word implementation - selects FORTH vocabulary
* @param vm Pointer to the virtual machine instance
*/
void vocabulary_word_forth(VM *vm);
#endif /* VOCABULARY_WORDS_H */