docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such
docs/CLAUDE.md Phase 2, 2026-10-14. All moves by git mv; every archived file carries a header saying what it is, why, and where to look instead. - docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL design, kernel args, hosted acceptance test, dictionary, primitives, ontology, L8 table -- previously spread over docs/, docs/lithosananke/ and docs/03-architecture/. - docs/working/archive/historical/: finished work (session plan, test-gap audit, birthing plan, fix write-ups, the January architecture draft). - docs/working/archive/superseded/: the Hermes-VM Tripod docs and July Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working doc already flagged superseded or obsolete. - docs/working/archive/dead/: the hal_* target contract (never adopted), L4Re, metrics-and-knobs. - Papers and proposals into docs/working/papers/. - References rewritten across the repo (not logs/, not docs/patent/); CLAUDE.md's documentation section rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
1a4b163861
commit
7aed588f78
@@ -0,0 +1,203 @@
|
||||
// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc.
|
||||
|
||||
// Moved from docs/src/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc to docs/working/scratch/src/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
== Dictionary Allocation Strategy for L4Re
|
||||
:toc: left
|
||||
:toc-title: Contents
|
||||
:toclevels: 3
|
||||
xref:../README.adoc[← Back to Documentation Index]
|
||||
|
||||
|
||||
|
||||
=== Current Implementation
|
||||
|
||||
StarForth currently uses `+malloc()+` and `+free()+` from the host C
|
||||
library for dictionary entry allocation:
|
||||
|
||||
* *Location*: `+src/dictionary_management.c:228+`
|
||||
* *Function*: `+vm_create_word()+` uses `+malloc(total)+` to allocate
|
||||
DictEntry structures
|
||||
* *Cleanup*: `+FORGET+` uses `+free(e)+` to deallocate entries (line 554
|
||||
in defining_words.c)
|
||||
|
||||
This works fine for hosted environments but creates a dependency on libc
|
||||
heap allocator.
|
||||
|
||||
=== Why This Matters for L4Re/StarshipOS
|
||||
|
||||
==== Issues with Current Approach:
|
||||
|
||||
[arabic]
|
||||
. *Heap Dependency*: Requires full malloc implementation in L4Re
|
||||
environment
|
||||
. *Non-Deterministic*: Heap fragmentation and unpredictable allocation
|
||||
behavior
|
||||
. *Separate Address Space*: Dictionary entries live outside VM memory
|
||||
model
|
||||
. *Hard to Introspect*: Can’t dump entire VM state as single memory
|
||||
region
|
||||
|
||||
==== Benefits of VM-Based Allocation:
|
||||
|
||||
[arabic]
|
||||
. *Zero External Dependencies*: No libc malloc needed
|
||||
. *Deterministic*: Simple bump allocator, predictable behavior
|
||||
. *Unified Address Space*: Everything in one 5MB VM memory region
|
||||
. *Easy Snapshots*: Can serialize entire VM state
|
||||
. *Better for Microkernel*: Aligns with L4Re dataspace model
|
||||
|
||||
=== Recommended Approach for L4Re
|
||||
|
||||
==== Strategy: Conditional Compilation
|
||||
|
||||
Add a compile-time flag to switch between malloc and VM-based
|
||||
allocation:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
// In dictionary_management.c
|
||||
#ifdef STARFORTH_VM_DICT_ALLOC
|
||||
/* VM-based allocation (for L4Re/embedded) */
|
||||
DictEntry *entry = dict_alloc_from_vm(vm, total);
|
||||
#else
|
||||
/* Standard malloc (for hosted environments) */
|
||||
DictEntry *entry = (DictEntry *) malloc(total);
|
||||
#endif
|
||||
----
|
||||
|
||||
==== Memory Layout (VM-Based Mode):
|
||||
|
||||
....
|
||||
vm->memory[0...VM_MEMORY_SIZE] (5MB):
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Dictionary Headers (256KB) │ ← dict_headers_used grows up
|
||||
│ - DictEntry structures │
|
||||
│ - Allocated via dict_alloc() │
|
||||
├──────────────────────────────────────────┤
|
||||
│ User Data & Code (variable) │ ← HERE grows up
|
||||
│ - Compiled definitions │
|
||||
│ - Variables, constants │
|
||||
│ - String literals │
|
||||
├──────────────────────────────────────────┤
|
||||
│ Block Storage (remainder) │
|
||||
│ - 1KB blocks for Forth block system │
|
||||
└──────────────────────────────────────────┘
|
||||
....
|
||||
|
||||
==== Implementation Steps:
|
||||
|
||||
[arabic]
|
||||
. *Add Dictionary Allocator* (256KB bump allocator at `+memory[0]+`):
|
||||
|
||||
[source,c]
|
||||
----
|
||||
static DictEntry *dict_alloc_from_vm(VM *vm, size_t total_bytes) {
|
||||
/* Align to cell_t boundary */
|
||||
size_t align = sizeof(cell_t);
|
||||
total_bytes = (total_bytes + align - 1) & ~(align - 1);
|
||||
|
||||
/* Check space */
|
||||
if (vm->dict_headers_used + total_bytes > DICT_HEADERS_MAX) {
|
||||
vm->error = 1;
|
||||
return NULL;
|
||||
}
|
||||
|
||||
/* Allocate from VM memory */
|
||||
DictEntry *entry = (DictEntry *)(vm->memory + vm->dict_headers_used);
|
||||
vm->dict_headers_used += total_bytes;
|
||||
return entry;
|
||||
}
|
||||
----
|
||||
|
||||
[arabic, start=2]
|
||||
. *Update FORGET* (no individual frees, just rewind):
|
||||
|
||||
[source,c]
|
||||
----
|
||||
/* Instead of free(e) loop, rewind allocator */
|
||||
size_t target_offset = (uint8_t*)target - vm->memory;
|
||||
vm->dict_headers_used = target_offset;
|
||||
----
|
||||
|
||||
[arabic, start=3]
|
||||
. *Adjust VM Initialization*:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
vm->dict_headers_used = 0; /* Headers start at memory[0] */
|
||||
vm->here = DICT_HEADERS_MAX; /* User data starts at 256KB */
|
||||
----
|
||||
|
||||
[arabic, start=4]
|
||||
. *No Changes to Fast-Lookup Cache*: Cache buckets still use malloc for
|
||||
the pointer arrays, but entries themselves are in VM memory.
|
||||
|
||||
==== Testing Strategy:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
# Test with standard malloc (current):
|
||||
make clean && make test
|
||||
|
||||
# Test with VM-based allocation:
|
||||
make clean
|
||||
CFLAGS="-DSTARFORTH_VM_DICT_ALLOC" make test
|
||||
|
||||
# Test L4Re minimal build:
|
||||
make clean
|
||||
CFLAGS="-DSTARFORTH_MINIMAL -DSTARFORTH_VM_DICT_ALLOC" make rpi4-cross
|
||||
----
|
||||
|
||||
=== Current Status
|
||||
|
||||
*Decision*: Keep using `+malloc()+` for now, document the abstraction
|
||||
point clearly.
|
||||
|
||||
*Rationale*:
|
||||
|
||||
* Current implementation is stable and well-tested
|
||||
* L4Re port can implement the switch when needed
|
||||
* Abstraction layer is simple and well-defined
|
||||
* No performance difference between approaches
|
||||
|
||||
*Action Items for L4Re Port*:
|
||||
|
||||
[arabic]
|
||||
. Define `+STARFORTH_VM_DICT_ALLOC+` in L4Re build
|
||||
. Implement `+dict_alloc_from_vm()+` function
|
||||
. Update `+FORGET+` to use rewind instead of free loop
|
||||
. Test with full test suite
|
||||
. Verify no memory leaks in microkernel environment
|
||||
|
||||
=== Minimal Code Changes Needed
|
||||
|
||||
The switch to VM-based allocation requires changes to only 3 functions:
|
||||
|
||||
[arabic]
|
||||
. *`+vm_create_word()+`* - Use `+dict_alloc_from_vm()+` instead of
|
||||
`+malloc()+`
|
||||
. *`+dictionary_word_forget()+`* - Rewind `+dict_headers_used+` instead
|
||||
of `+free()+` loop
|
||||
. *`+vm_init()+`* - Initialize `+dict_headers_used+` and offset `+HERE+`
|
||||
|
||||
Add to `+VM+` struct in `+include/vm.h+`:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
size_t dict_headers_used; /* Bytes used for dictionary headers (VM mode only) */
|
||||
----
|
||||
|
||||
*Estimated effort*: 4 hours to implement + 2 hours testing = *6 hours
|
||||
total*
|
||||
|
||||
=== References
|
||||
|
||||
* Current malloc usage: `+src/dictionary_management.c:228+`
|
||||
* Current free usage: `+src/word_source/defining_words.c:554+`
|
||||
* Fast-lookup cache: `+src/dictionary_management.c:43-67+` (unchanged)
|
||||
* L4Re dataspace docs: `+docs/L4RE_INTEGRATION.md+`
|
||||
|
||||
'''''
|
||||
|
||||
*Author*: R. A. James *Date*: 2025-10-01 *Status*: Documented,
|
||||
implementation deferred to L4Re port
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,349 @@
|
||||
// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc.
|
||||
|
||||
// Moved from docs/src/L4RE_INTEGRATION_TODO.adoc to docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
== L4Re Integration TODO
|
||||
:toc: left
|
||||
:toc-title: Contents
|
||||
:toclevels: 3
|
||||
|
||||
xref:./README.adoc[← Back to Documentation Index]
|
||||
|
||||
|
||||
=== Overview
|
||||
|
||||
The platform abstraction layer is complete and working for standalone
|
||||
POSIX builds. This document outlines the specific steps needed to
|
||||
integrate into the StarshipOS L4Re BID build system.
|
||||
|
||||
'''''
|
||||
|
||||
=== Pre-Integration Checklist
|
||||
|
||||
* [x] Platform abstraction layer implemented
|
||||
* [x] POSIX backend tested and working
|
||||
* [x] L4Re backend code written
|
||||
* [x] Standalone builds work with `+make L4RE=1+`
|
||||
* [ ] Platform files copied to StarshipOS tree
|
||||
* [ ] BID Makefile updated
|
||||
* [ ] L4Re build tested in StarshipOS tree
|
||||
|
||||
'''''
|
||||
|
||||
=== Integration Steps
|
||||
|
||||
==== 1. Copy Platform Files to StarshipOS
|
||||
|
||||
*Source Location:*
|
||||
`+/home/rajames/CLionProjects/StarForth/src/platform/+`
|
||||
|
||||
*Destination:*
|
||||
`+/home/rajames/CLionProjects/StarshipOS/l4/pkg/starforth/server/src/platform/+`
|
||||
|
||||
*Files to Copy:*
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
cd /home/rajames/CLionProjects/StarForth
|
||||
mkdir -p /home/rajames/CLionProjects/StarshipOS/l4/pkg/starforth/server/src/platform
|
||||
|
||||
cp src/platform/platform_init.c \
|
||||
/home/rajames/CLionProjects/StarshipOS/l4/pkg/starforth/server/src/platform/
|
||||
|
||||
cp src/platform/time_l4re.c \
|
||||
/home/rajames/CLionProjects/StarshipOS/l4/pkg/starforth/server/src/platform/
|
||||
|
||||
# Note: Do NOT copy time_posix.c - not needed in L4Re build
|
||||
----
|
||||
|
||||
*Header File:*
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
cp include/platform_time.h \
|
||||
/home/rajames/CLionProjects/StarshipOS/l4/pkg/starforth/server/include/
|
||||
----
|
||||
|
||||
'''''
|
||||
|
||||
==== 2. Update BID Makefile
|
||||
|
||||
*File:*
|
||||
`+/home/rajames/CLionProjects/StarshipOS/l4/pkg/starforth/server/src/Makefile+`
|
||||
|
||||
*Changes Needed:*
|
||||
|
||||
[source,makefile]
|
||||
----
|
||||
# Add platform sources to SRC_C list
|
||||
SRC_C = \
|
||||
main.c \
|
||||
log.c \
|
||||
io.c \
|
||||
vm.c \
|
||||
vm_debug.c \
|
||||
word_registry.c \
|
||||
device_map.c \
|
||||
stack_management.c \
|
||||
panic.c \
|
||||
repl_io.c \
|
||||
memory_management.c \
|
||||
dictionary_management.c \
|
||||
vm_api.c \
|
||||
bam.c \
|
||||
platform/platform_init.c \ # ← ADD THIS
|
||||
platform/time_l4re.c \ # ← ADD THIS
|
||||
word_source/arithmetic_words.c \
|
||||
# ... rest of existing files ...
|
||||
|
||||
# Add librtc to REQUIRES_LIBS
|
||||
REQUIRES_LIBS = libc_be_l4re libc l4re l4re_c l4sys l4util libsigma0 libblock-device librtc
|
||||
# ^^^^^^ ADD THIS
|
||||
----
|
||||
|
||||
*Note:* BID already sets `+-D__l4__+` at line 77-78, so platform
|
||||
selection happens automatically.
|
||||
|
||||
'''''
|
||||
|
||||
==== 3. Update Core Source Files in StarshipOS
|
||||
|
||||
These files need the same changes made to standalone StarForth:
|
||||
|
||||
*File:* `+server/src/log.c+`
|
||||
|
||||
* [ ] Add `+#include "../include/platform_time.h"+` to includes
|
||||
* [ ] Replace `+get_timestamp()+` implementation with platform API calls
|
||||
* [ ] Change: `+time(NULL)+` → `+sf_realtime_ns()+`
|
||||
* [ ] Change: `+localtime()+` + `+strftime()+` →
|
||||
`+sf_format_timestamp()+`
|
||||
|
||||
*File:* `+server/src/profiler.c+` (if it exists in L4Re version)
|
||||
|
||||
* [ ] Add `+#include "../include/platform_time.h"+` to includes
|
||||
* [ ] Replace `+get_time_ns()+` implementation
|
||||
* [ ] Change: `+clock_gettime(CLOCK_MONOTONIC)+` → `+sf_monotonic_ns()+`
|
||||
|
||||
*File:* `+server/src/main.c+`
|
||||
|
||||
* [ ] Add `+#include "platform_time.h"+` to includes
|
||||
* [ ] Add `+sf_time_init();+` call at start of `+main()+` (before any
|
||||
logging)
|
||||
|
||||
'''''
|
||||
|
||||
==== 4. Verify RTC Library Availability
|
||||
|
||||
*Check RTC package exists:*
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
cd /home/rajames/CLionProjects/StarshipOS
|
||||
ls -la l4/pkg/rtc/
|
||||
ls -la l4/build-x86_64/lib/*/librtc.a
|
||||
----
|
||||
|
||||
*Expected files:*
|
||||
|
||||
* `+l4/pkg/rtc/lib/client/librtc.cc+` - RTC client library
|
||||
* `+l4/pkg/rtc/include/rtc+` - C++ header
|
||||
* `+l4/pkg/rtc/include/rtc.h+` - C header
|
||||
* `+l4/build-x86_64/lib/amd64_gen/l4f/librtc.a+` - Compiled library
|
||||
|
||||
*If missing:*
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
cd l4/pkg/rtc
|
||||
make
|
||||
----
|
||||
|
||||
'''''
|
||||
|
||||
==== 5. Update Loader Configuration
|
||||
|
||||
*File:* Choose your loader script (e.g., `+l4/conf/modules.list+` or a
|
||||
`+.lua+` file)
|
||||
|
||||
*Add RTC server startup:*
|
||||
|
||||
[source,lua]
|
||||
----
|
||||
-- Start RTC server (needed for wall-clock time)
|
||||
ld:start({
|
||||
caps = {
|
||||
vbus = vbus_l4re,
|
||||
icu = L4.default_loader:new_channel(),
|
||||
},
|
||||
log = L4.Env.log:m("rws", "magenta"),
|
||||
}, "rom/rtc");
|
||||
|
||||
-- StarForth with RTC capability
|
||||
ld:start({
|
||||
caps = {
|
||||
rtc = ld:wait("rtc", 1000), -- Wait for RTC server, timeout 1s
|
||||
-- ... other caps ...
|
||||
},
|
||||
log = L4.Env.log:m("rws", "cyan"),
|
||||
}, "rom/starforth");
|
||||
----
|
||||
|
||||
*Note:* StarForth will work without RTC capability, but timestamps will
|
||||
show epoch (1970).
|
||||
|
||||
'''''
|
||||
|
||||
==== 6. Build and Test
|
||||
|
||||
*Clean build:*
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
cd /home/rajames/CLionProjects/StarshipOS
|
||||
make clean-l4
|
||||
make l4
|
||||
----
|
||||
|
||||
*Check for platform files in build:*
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
ls -la l4/build-x86_64/pkg/starforth/server/OBJ-amd64_gen/platform/
|
||||
# Should see: platform_init.o, time_l4re.o
|
||||
----
|
||||
|
||||
*Launch in QEMU:*
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
scripts/runos.sh
|
||||
----
|
||||
|
||||
*Verify in StarForth REPL:*
|
||||
|
||||
* Logging should show timestamps (may be 1970-01-01 if no RTC server)
|
||||
* Profiler should work (uses KIP clock, doesn’t need RTC)
|
||||
* No crashes or missing symbol errors
|
||||
|
||||
'''''
|
||||
|
||||
=== Verification Tests
|
||||
|
||||
==== Test 1: Basic Functionality
|
||||
|
||||
[source,forth]
|
||||
----
|
||||
\ In StarForth REPL:
|
||||
1 2 + . \ Should print 3
|
||||
: TEST 42 . ; \ Should work
|
||||
TEST \ Should print 42
|
||||
----
|
||||
|
||||
==== Test 2: Profiler (Monotonic Time)
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
# From shell:
|
||||
./build-x86_64/bin/amd64_gen/l4f/starforth --profile 2 --run-tests --profile-report
|
||||
----
|
||||
|
||||
Should show timing information without errors.
|
||||
|
||||
==== Test 3: Logging (Real Time)
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
./build-x86_64/bin/amd64_gen/l4f/starforth --log-debug
|
||||
----
|
||||
|
||||
Should show timestamps in log output (may be 1970 epoch if no RTC).
|
||||
|
||||
==== Test 4: RTC Server Integration
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
# In QEMU, after starting with RTC server
|
||||
# Check for RTC capability
|
||||
grep "RTC" /proc/l4re/caps
|
||||
----
|
||||
|
||||
If RTC server is running and capability provided, timestamps should be
|
||||
correct.
|
||||
|
||||
'''''
|
||||
|
||||
=== Troubleshooting
|
||||
|
||||
==== Build Errors
|
||||
|
||||
*Error:* `+platform_init.c: No such file or directory+` *Fix:* Check
|
||||
that platform directory was created and files copied correctly
|
||||
|
||||
*Error:* `+undefined reference to l4_kip_clock_ns+` *Fix:* Make sure
|
||||
linking against `+l4re+` library (should be in REQUIRES_LIBS)
|
||||
|
||||
*Error:* `+undefined reference to L4rtc::Rtc::get_timer+` *Fix:* Add
|
||||
`+librtc+` to REQUIRES_LIBS
|
||||
|
||||
*Error:* `+fatal error: platform_time.h: No such file or directory+`
|
||||
*Fix:* Copy header to `+server/include/+` directory
|
||||
|
||||
==== Runtime Errors
|
||||
|
||||
*Warning:* "`RTC server not found, assuming 1.1.1970`" *Fix:* Add RTC
|
||||
server to loader configuration and provide `+rtc+` capability
|
||||
|
||||
*Issue:* Timestamps show 1970-01-01 *Fix:* Either RTC server not
|
||||
running, or capability not provided to StarForth
|
||||
|
||||
*Issue:* Profiler shows 0 elapsed time *Fix:* Check that
|
||||
`+sf_monotonic_ns()+` is being called (shouldn’t need RTC)
|
||||
|
||||
'''''
|
||||
|
||||
=== Rollback Plan
|
||||
|
||||
If integration fails, revert by:
|
||||
|
||||
[arabic]
|
||||
. Remove platform files from `+SRC_C+` in Makefile
|
||||
. Remove `+librtc+` from `+REQUIRES_LIBS+`
|
||||
. Revert changes to `+log.c+`, `+profiler.c+`, `+main.c+`
|
||||
. Delete `+platform/+` directory
|
||||
. Rebuild: `+make clean-l4 && make l4+`
|
||||
|
||||
The L4Re build will work as before (using direct POSIX calls via libc).
|
||||
|
||||
'''''
|
||||
|
||||
=== Notes
|
||||
|
||||
* *BID build system* automatically sets `+-D__l4__+` flag (line 77-78 in
|
||||
Makefile)
|
||||
* *Platform selection* happens at compile-time based on `+__l4__+`
|
||||
define
|
||||
* *No conditional Makefiles needed* - BID handles everything
|
||||
* *RTC is optional* - StarForth works without it (uses epoch time)
|
||||
* *Profiler always works* - uses KIP clock, independent of RTC
|
||||
|
||||
'''''
|
||||
|
||||
=== Success Criteria
|
||||
|
||||
* [ ] StarForth builds cleanly in L4Re tree
|
||||
* [ ] No linker errors for platform functions
|
||||
* [ ] REPL starts without crashes
|
||||
* [ ] Logging shows timestamps (even if 1970)
|
||||
* [ ] Profiler works with `+--profile+` flag
|
||||
* [ ] Tests pass with `+--run-tests+`
|
||||
* [ ] If RTC server running: correct wall-clock time
|
||||
* [ ] If no RTC: graceful fallback to epoch time
|
||||
|
||||
'''''
|
||||
|
||||
=== Future Enhancements
|
||||
|
||||
* [ ] Add RTC FORTH words (GET-TIME, SET-TIME)
|
||||
* [ ] Expose monotonic timer to FORTH (for benchmarking)
|
||||
* [ ] Add timezone support (currently UTC only)
|
||||
* [ ] Support for RTC alarm/wakeup features
|
||||
* [ ] Performance comparison: POSIX vs L4Re backend
|
||||
@@ -0,0 +1,193 @@
|
||||
// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc.
|
||||
|
||||
// Moved from docs/src/platform-integration/l_4_re_blkio_endpoints.adoc to docs/working/scratch/src/platform-integration/l_4_re_blkio_endpoints.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
== StarForth Block I/O — L4Re Porting Endpoints
|
||||
:toc: left
|
||||
:toc-title: Contents
|
||||
:toclevels: 3
|
||||
xref:../README.adoc[← Back to Documentation Index]
|
||||
|
||||
|
||||
|
||||
This document explains how the existing `+blkio+` API maps cleanly onto
|
||||
L4Re, what you need to implement, and where your VM and Forth block
|
||||
words connect. The idea is: the *northbound API never changes*; you only
|
||||
swap in different backends (dataspace or IPC service) when porting to
|
||||
L4Re.
|
||||
|
||||
'''''
|
||||
|
||||
=== 1. Northbound API (unchanged)
|
||||
|
||||
Your VM and block words always call:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
int blkio_open (blkio_dev_t *dev, const blkio_vtable_t *vt, const blkio_params_t *p);
|
||||
int blkio_close(blkio_dev_t *dev);
|
||||
int blkio_read (blkio_dev_t *dev, uint32_t fblock, void *dst);
|
||||
int blkio_write(blkio_dev_t *dev, uint32_t fblock, const void *src);
|
||||
int blkio_flush(blkio_dev_t *dev);
|
||||
int blkio_info (blkio_dev_t *dev, blkio_info_t *out);
|
||||
----
|
||||
|
||||
No matter what backend you use, these remain stable. That’s your ABI.
|
||||
|
||||
'''''
|
||||
|
||||
=== 2. In-process L4Re Dataspace Backend
|
||||
|
||||
Use when your VM can directly attach a dataspace. This gives you the
|
||||
fastest path: no IPC.
|
||||
|
||||
*Symbols you implement:*
|
||||
|
||||
[source,c]
|
||||
----
|
||||
size_t blkio_l4ds_state_size(void);
|
||||
int blkio_l4ds_init_state(void *state_mem, size_t state_len,
|
||||
l4_cap_idx_t ds_cap,
|
||||
l4_addr_t attach_addr,
|
||||
l4_size_t attach_size,
|
||||
uint32_t total_blocks,
|
||||
uint32_t fbs,
|
||||
uint8_t read_only,
|
||||
void **out_opaque);
|
||||
const blkio_vtable_t *blkio_l4ds_vtable(void);
|
||||
----
|
||||
|
||||
*State struct:*
|
||||
|
||||
[source,c]
|
||||
----
|
||||
typedef struct {
|
||||
l4_cap_idx_t ds; /* dataspace cap */
|
||||
void *base; /* attached VA */
|
||||
l4_size_t size; /* mapped length */
|
||||
uint32_t fbs; /* block size */
|
||||
uint32_t blocks; /* #blocks */
|
||||
uint8_t ro;
|
||||
} blkio_l4ds_state_t;
|
||||
----
|
||||
|
||||
*Ops:*
|
||||
|
||||
* `+open+`: `+l4re_rm_attach()+` dataspace, derive block count.
|
||||
* `+read/write+`: `+memcpy+` from attached region.
|
||||
* `+flush+`: NOP (or `+l4re_ds_op+` if needed).
|
||||
* `+close+`: `+l4re_rm_detach()+`.
|
||||
|
||||
'''''
|
||||
|
||||
=== 3. Out-of-process Block Server (IPC Backend)
|
||||
|
||||
Use when storage is owned by a different task (e.g., AHCI, NVMe, eMMC
|
||||
server).
|
||||
|
||||
*Client-side symbols:*
|
||||
|
||||
[source,c]
|
||||
----
|
||||
size_t blkio_l4svc_state_size(void);
|
||||
int blkio_l4svc_init_state(void *state_mem, size_t state_len,
|
||||
l4_cap_idx_t server_cap,
|
||||
l4_cap_idx_t bounce_ds,
|
||||
uint32_t fbs,
|
||||
uint8_t read_only,
|
||||
void **out_opaque);
|
||||
const blkio_vtable_t *blkio_l4svc_vtable(void);
|
||||
----
|
||||
|
||||
*IPC protocol (example):*
|
||||
|
||||
[source,c]
|
||||
----
|
||||
enum bsvc_op {
|
||||
BSVC_INFO = 1,
|
||||
BSVC_READ = 2,
|
||||
BSVC_WRITE = 3,
|
||||
BSVC_FLUSH = 4,
|
||||
BSVC_PING = 5
|
||||
};
|
||||
----
|
||||
|
||||
Transport choices:
|
||||
|
||||
* Shared dataspace (preferred): server + client map the same page(s).
|
||||
* Inline IPC (simpler, less efficient): block payload in IPC message.
|
||||
|
||||
*Ops mapping:*
|
||||
|
||||
* `+read+`: send op + fblock, server fills shared buffer.
|
||||
* `+write+`: copy into shared buffer, send op + fblock.
|
||||
* `+info+`: query block size, count, flags.
|
||||
|
||||
'''''
|
||||
|
||||
=== 4. Factory Helpers on L4Re
|
||||
|
||||
You can add overloads to `+blkio_factory+` for clarity:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
int blkio_factory_open_l4ds (blkio_dev_t *dev, l4_cap_idx_t ds_cap, uint32_t fbs, uint8_t ro);
|
||||
int blkio_factory_open_file (blkio_dev_t *dev, const char *path, uint32_t fbs, uint8_t ro);
|
||||
int blkio_factory_open_l4svc(blkio_dev_t *dev, l4_cap_idx_t server_cap, l4_cap_idx_t bounce_ds, uint32_t fbs, uint8_t ro);
|
||||
----
|
||||
|
||||
This way `+main.c+` can pick a backend cleanly depending on CLI args and
|
||||
environment.
|
||||
|
||||
'''''
|
||||
|
||||
=== 5. CLI Semantics on L4Re
|
||||
|
||||
* `+--disk-img=<path>+` → Either:
|
||||
** VFS+file server that returns a dataspace → *l4ds backend*
|
||||
** Or connect to a block server → *l4svc backend*
|
||||
* `+--ram-disk=<MB>+` → Allocate RAM dataspace, use *l4ds backend*.
|
||||
|
||||
Fallback: if no `+--disk-img+`, create RAM disk from allocator.
|
||||
|
||||
'''''
|
||||
|
||||
=== 6. Composite Backends (RAM + Disk, 4 KiB packing)
|
||||
|
||||
Your design needs:
|
||||
|
||||
* Blocks 0–1023 → RAM backend.
|
||||
* Blocks ≥1024 → Disk backend.
|
||||
* All wrapped in a composite vtable that dispatches based on `+fblock+`.
|
||||
|
||||
Later: add an outer wrapper that packs 3×1 KiB + 1 KiB metadata into 4
|
||||
KiB pages for device alignment. Still the same five ops.
|
||||
|
||||
'''''
|
||||
|
||||
== TL;DR — Endpoints to Implement for L4Re
|
||||
|
||||
*New backends:*
|
||||
|
||||
[source,c]
|
||||
----
|
||||
/* In-proc dataspace */
|
||||
blkio_l4ds_state_size();
|
||||
blkio_l4ds_init_state(...);
|
||||
blkio_l4ds_vtable();
|
||||
|
||||
/* IPC client/server */
|
||||
blkio_l4svc_state_size();
|
||||
blkio_l4svc_init_state(...);
|
||||
blkio_l4svc_vtable();
|
||||
----
|
||||
|
||||
*Optional factory helpers:*
|
||||
|
||||
[source,c]
|
||||
----
|
||||
blkio_factory_open_l4ds(...);
|
||||
blkio_factory_open_l4svc(...);
|
||||
----
|
||||
|
||||
*Everything else stays the same*: VM calls only `+blkio_read+`,
|
||||
`+blkio_write+`, etc. You swap backends, not call sites.
|
||||
Reference in New Issue
Block a user