// Moved from docs/src/L4RE_INTEGRATION_TODO.adoc to docs/working/scratch/src/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
