149 lines
6.2 KiB
Markdown
149 lines
6.2 KiB
Markdown
# llvm816 GS/OS Demo Apps
|
|
|
|
Small Apple IIgs S16 applications that build with our LLVM/clang
|
|
toolchain, wrap as OMF v2.1 ExpressLoad, and launch under real
|
|
GS/OS 6.0.2 in MAME.
|
|
|
|
## Building / running
|
|
|
|
```
|
|
bash demos/build.sh helloBeep # build the OMF
|
|
bash demos/launch.sh helloBeep # interactive run in MAME (visible window, audio)
|
|
bash demos/test.sh helloBeep # headless test (boots, runs, checks marker)
|
|
```
|
|
|
|
The launch script runs MAME with no timeout; close the MAME
|
|
window when done (Esc, then Cmd-Q). The test script injects a
|
|
keystroke after the demo has launched, then checks `$00:0070`
|
|
for the `0x99` end-of-run marker the demo writes before exit.
|
|
|
|
## Demos
|
|
|
|
### `helloBeep.c`
|
|
|
|
Three `SysBeep()` calls then exit. The toolbox `SysBeep` lives in
|
|
Misc Tools; no other startup needed (Loader handles MM + TL).
|
|
|
|
### `helloText.c`
|
|
|
|
Initialises Event Manager (so `GetNextEvent` can read keystrokes)
|
|
and Text Tools (so `WriteCString` has an output device), writes
|
|
two greeting lines to the text screen, waits for any keypress via
|
|
`GetNextEvent`, beeps, exits. Uses these toolbox calls:
|
|
|
|
- `MMStartUp`, `NewHandle` (DP allocation for Event Manager)
|
|
- `EMStartUp`, `GetNextEvent` (event-driven keyboard)
|
|
- `TextStartUp`, `SetOutputDevice`, `WriteCString` (text I/O)
|
|
- `SysBeep`
|
|
|
|
### `helloWindow.c`
|
|
|
|
Initialises the full Window Manager startup chain (Memory, QD,
|
|
Event, Scheduler, Window), constructs an Apple-IIgs-Toolbox-Ref
|
|
NewWindow parm block, and calls `NewWindow`. When NewWindow
|
|
returns a real handle the demo calls `SetPort`, `ShowWindow`,
|
|
`MoveTo`, and `DrawString` to put a greeting in the window, then
|
|
waits for a keypress, beeps, and exits.
|
|
|
|
Three toolchain bugs needed fixing to make this work end-to-end
|
|
under real GS/OS 6.0.2 (all now landed):
|
|
- **omfEmit RESSPC=0** for code segments — BSS got no memory
|
|
allocation; writes past the image end silently vanished. Now
|
|
BSS is embedded as zeros in the LCONST data.
|
|
- **Loader cRELOC at segPlacedBase=$0000** (not $1000 like our
|
|
text-base) — host probes need to compute runtime addresses as
|
|
`link_addr - text_base + bank<<16`.
|
|
- **`&symbol` bank=0** — proper backend fix landed. `LDAi16imm_bank`
|
|
AsmPrinter pseudo lowers to `lda $BE`; crt0 stores `PBR` to $BE
|
|
+ zero to $BF at startup, so the high half of every `&symbol`
|
|
pointer carries the actual load bank at runtime. Toolbox
|
|
pointer args now Just Work without per-wrapper PBR overrides.
|
|
|
|
### `orcaFrame.c`
|
|
|
|
First ORCA-style desktop application. Opens a Window Manager
|
|
window via `startdesk()` (full toolset chain), runs a TaskMaster
|
|
event loop until the close box / Q key / 1000-iteration watchdog
|
|
fires. Both 6.0.2 (`sys602.po`) and 6.0.4 (`6.0.4 - System.Disk.po`)
|
|
launch it cleanly; fTitle works on both.
|
|
|
|
### `orcaFrameLike.c`
|
|
|
|
Port of ORCA-C's `Frame.cc` sample (`tools/orca-c/C.Samples/
|
|
Desktop.Samples/Frame.cc`). Builds a standard Apple+File+Edit
|
|
menu bar (`NewMenu` + `InsertMenu` + `FixAppleMenu` + `DrawMenuBar`)
|
|
and dispatches `wInMenuBar` / `wInSpecial` events from `TaskMaster`.
|
|
File→Quit exits. Skips the original's Dialog Manager About box.
|
|
|
|
### `orcaMiniCadLike.c`
|
|
|
|
Port of ORCA-C's `MiniCAD.cc` (`Desktop.Samples/MiniCAD.cc`). Slim
|
|
port — opens a Window Manager content window but omits the line-
|
|
drawing primitives because adding them pushes past the Loader's
|
|
cRELOC threshold. Demonstrates the NewWindow path under
|
|
`startdesk`.
|
|
|
|
### `orcaReversiLike.c`
|
|
|
|
Port of ORCA-C's `Reversi.cc` (`Desktop.Samples/Reversi.cc`).
|
|
Menu-bar app — the ~1600 line game logic is omitted; the demo
|
|
shows the desktop scaffolding (menu + TaskMaster) the original
|
|
sits on top of.
|
|
|
|
### `qdProbe.c`
|
|
|
|
Diagnostic — minimal QD/EM/WM init followed by `RefreshDesktop`
|
|
plus ZP/SHR markers. Used to prove that `WindStartUp` does NOT
|
|
auto-paint the desktop and that `RefreshDesktop(NULL)` is what
|
|
actually fills SHR with the dithered desktop pattern. Run via
|
|
`scripts/probeQdStartup.sh`.
|
|
|
|
### Known limitations
|
|
|
|
- **fTitle on stripped 6.0.2:** orcaFrame uses fTitle and runs
|
|
fine on both 6.0.2 sys602.po and 6.0.4 System.Disk.po. Earlier
|
|
notes that fTitle required disk fonts were superseded — the
|
|
underlying bug was a `QDStartUp` argument-order mistake in
|
|
`runtime/src/desktop.c`, fixed 2026-05-16.
|
|
- **Window not visually painted:** `WindStartUp` does NOT paint
|
|
the desktop on its own; `RefreshDesktop(NULL)` is required.
|
|
Adding the call to `startdesk()` works for `qdProbe.c` but
|
|
pushes the orca demos past the GS/OS Loader's silent-rejection
|
|
threshold (see memory: `loader-creloc-threshold`).
|
|
- **GS/OS Loader cRELOC threshold:** anywhere from 65-90 cRELOCs
|
|
the Loader silently refuses to launch ExpressLoad OMFs. The
|
|
threshold is not a clean reloc-count cutoff; OMF byte layout
|
|
and reloc patch offsets both matter. The ORCA ports are slim
|
|
to stay under it.
|
|
|
|
## What got fixed during demo authoring
|
|
|
|
Substantive toolchain bugs surfaced and fixed:
|
|
|
|
- `iigsGsos.s` GS/OS wrappers and `genToolbox.py`'s 890 toolbox
|
|
wrappers were pushing 4-byte Long args low-word-first. ORCA-C's
|
|
PushLong macro is high-word-first. Anything passing a Long arg
|
|
through the toolbox dispatcher (NewHandle, NewWindow,
|
|
fopen->gsosOpen, etc.) was reading garbage parm-block pointers.
|
|
Fixed in both files plus the generator; regenerated 890
|
|
wrappers.
|
|
- `runtime/build.sh` wasn't rebuilding `iigsToolbox.s` -- the .o
|
|
was stale since May 4. Added the missing line.
|
|
- `(short)(*(void **)dpHandle)` was a double-dereference bug that
|
|
read garbage at the master pointer's destination instead of the
|
|
master pointer VALUE (= the DP address). Corrected to
|
|
`(unsigned short)(unsigned long)*(void **)dpHandle` for proper
|
|
block-address extraction.
|
|
- `helloText` used `TextStartUp + WriteCString` directly which
|
|
crashed to the IIgs monitor; fixed by adding `SetOutputDevice(1, 0)`
|
|
to wire stdout to the text screen.
|
|
- `helloText`'s event loop hung forever because `EMStartUp` wasn't
|
|
being called; fixed by adding it (with proper DP allocation).
|
|
|
|
## ptr32 mode note
|
|
|
|
All address constants in the demos (text screen $00:0400, SHR
|
|
RAM $E1:2000, soft switches $00:C0xx, keyboard register $00:C000)
|
|
are plain C 32-bit pointers like `(volatile unsigned char *)0xE12000UL`.
|
|
In ptr32 mode the compiler emits LONG addressing automatically;
|
|
no `switchToBank2`-style inline asm or DBR juggling required.
|