GNU Chess 3D: BaseBox low-memory test reproduction

Profile

3D-basebox-640k.conf contains the common settings used with the supplied
Linux BaseBox BLD285 binary: normal 386 core, fixed 3000 cycles, XMS/EMS/UMB
disabled, and an unscaled 800x600 window. The cycle setting is an emulator
workload limit; it is not a claim of exact equivalence to a physical CPU.

Use the NC geode with the NC Ensemble target and the EC geode with the EC
target. Install only one language edition of a given build in that target's
WORLD directory. Remove USERDATA/GCHESS3D.VM when testing the language built
into the geode. Keep separate copies of the supplied target for NC and EC.

Mount the parent of the Ensemble directory as C:, then change into ENSEMBLE.
This is required for the supplied EC target to boot reliably. The supplied
runtime has GEOS disk swap enabled through:

[diskswap]
size = 4096

Example Linux invocation from the project root (replace both paths):

BASEBOX_BIN=/path/to/basebox
TARGET_ROOT=/path/to/target-parent
"$BASEBOX_BIN" -noprimaryconf -conf docs/evidence/3D-basebox-640k.conf \
    -c "mount c \"$TARGET_ROOT\"" -c "c:" -c "mem > MEM640.TXT" \
    -c "cd ensemble" -c "loader"

For EC, replace the last command with "loaderec". TARGET_ROOT must contain
an ensemble subdirectory, not be the ensemble directory itself.

Inspect TARGET_ROOT/MEM640.TXT before accepting the profile as a 640 KiB
test. In the supplied targets, DOS MEM reported 640K conventional total,
7K used and 633K free, with a largest free block of 647104 bytes. Those
figures describe DOS before GEOS starts; they are not the application heap.
No XMS or EMS was available to GEOS in this profile.

On a Linux desktop, normal absolute mouse input follows the window. In a
dummy X11 test display with no desktop environment variables, this BaseBox
build disabled its absolute mouse interface. The test harness supplied
XDG_SESSION_TYPE=x11 and XDG_CURRENT_DESKTOP=GNOME and used
mouse_raw_input=false. A normal desktop does not require the dummy-display
harness. Use visible guest pointer coordinates to verify input alignment.

For pressure tests, start Chess first and then open other applications.
Use a depth-four search, switch to GeoWrite, type into a document, and return
to Chess while Thinking is still visible. Allow a complete redraw before
comparing the board. At 3000 cycles, a partial paint can remain visible for
several seconds. See docs/TEST-RESULTS.md for observed results and limitations.

Optional Linux swap-file traffic counter

3D-swapio.c is the small host-only LD_PRELOAD counter used for swap evidence.
It is not linked into a geode and is not required to build or run Chess.
Compile it with the host C compiler:

cc -shared -fPIC -O2 -o /absolute/path/swapio.so \
    docs/evidence/3D-swapio.c -ldl -pthread

Start a fresh log, then prefix the BaseBox command above with:

GNUCHESS_SWAP_LOG=/absolute/path/nc-swapio.log \
LD_PRELOAD=/absolute/path/swapio.so \
"$BASEBOX_BIN" ...

Do not preload the counter into the compiler or other build tools. A new
run appends to an existing log, so rename or remove that log before each
run if separate totals are wanted. The filter matches a host file path
ending in /privdata/SWAP, as in the supplied targets. If the host directory
uses different casing or the swap file has a different name, adjust the
comparison in record() before using the counter.

Each line contains monotonic time, operation, successful bytes, and the
file descriptor offset sampled after the operation. The supplied BaseBox
produced read/write records for the GEOS swap file. Successful reads of that
file and successful writes to it establish swap traffic. These are file
operations at the host boundary; the host OS may cache the data. The log
does not prove physical disk platter or SSD traffic and does not identify
which GEOS application's blocks were swapped.

Summarize a log with:

python3 docs/evidence/3D-swapstats.py /absolute/path/nc-swapio.log

The summary keeps read/write and fread/fwrite separate. Do not add the
stdio counts to syscall counts: an operation may be visible at both layers.
Use the read/write totals when present. Preserve the raw log alongside the
summary so the workload interval and counts can be checked. Instrumented
runs are useful for traffic evidence; do not treat them as uninstrumented
performance benchmarks.
