DVX_GUI/dvxshell/README.md

DVX Shell

The DVX Shell (dvx.exe) is the host process for the DVX desktop environment. It initializes the GUI subsystem, loads DXE3 application modules at runtime, runs the cooperative main loop, and provides crash recovery so a faulting app does not take down the entire system. Think of it as the Windows 3.1 Program Manager and kernel combined into one executable.

Files

File	Purpose
shellMain.c	Entry point, main loop, crash recovery, logging, desktop update callbacks
shellApp.c	App loading (dlopen/dlsym), lifecycle state machine, reaping, resource tracking, config dirs
shellApp.h	ShellAppT, AppDescriptorT, AppStateE, DxeAppContextT, public shell API
shellExport.c	DXE export table (400+ symbols), wrapper functions for resource tracking
shellInfo.c	System information gathering (delegates to platform layer), caches result
shellInfo.h	shellInfoInit(), shellGetSystemInfo()
shellTaskMgr.c	Task Manager window -- list view, Switch To / End Task / Run buttons
shellTaskMgr.h	shellTaskMgrOpen(), shellTaskMgrRefresh()
Makefile	Cross-compile rules, links -ldvx -ltasks -lm

Building

make        # builds ../bin/dvx.exe (also builds libdvx.a, libtasks.a)
make clean  # removes objects and binary

Requires the DJGPP cross-compiler toolchain and the DXE3 tools (dxe3gen).

Startup Sequence

main() in shellMain.c performs initialization in this order:

1. Change to exe directory -- resolve the directory containing dvx.exe via argv[0] and platformChdir() so that relative paths (CONFIG/, APPS/, etc.) work regardless of where the user launched from.
2. Truncate log -- open dvx.log for write to clear it, then close. All subsequent writes use append-per-write (the file is never held open).
3. Load preferences -- prefsLoad("CONFIG/DVX.INI"). Missing file or keys silently fall back to compiled-in defaults.
4. dvxInit -- initialize VESA video (LFB), backbuffer, compositor, window manager, font, cursor, input subsystems. Reads video width/height/bpp from preferences (default 640x480x16).
5. Mouse config -- read wheel direction, double-click speed, acceleration from [mouse] section and call dvxSetMouseConfig().
6. Color scheme -- read [colors] section (20 RGB triplets), apply via dvxApplyColorScheme().
7. Wallpaper -- read [desktop] section for wallpaper path and mode (stretch/tile/center), load via dvxSetWallpaper().
8. Video mode log -- enumerate all available VESA modes to dvx.log.
9. Task system -- tsInit(), set shell task (task 0) to TS_PRIORITY_HIGH so the UI stays responsive under load.
10. System info -- shellInfoInit() gathers CPU, memory, drive info via the platform layer and logs it.
11. DXE exports -- shellExportInit() calls dlregsym() to register the export table. Must happen before any dlopen().
12. App slot table -- shellAppInit() zeroes the 32-slot fixed array.
13. Idle/hotkey callbacks -- wire up idleYield, ctrlEscHandler, titleChangeHandler on the AppContextT.
14. Desktop app -- shellLoadApp(ctx, "apps/progman/progman.app"). If this fails, the shell exits.
15. Crash handlers -- installCrashHandler() registers signal handlers for SIGSEGV, SIGFPE, SIGILL. Installed last so initialization crashes get the default DJGPP abort-with-register-dump instead of our recovery path.

Main Loop

The main loop runs until dvxQuit() sets ctx->running = false:

while (ctx->running) {
    dvxUpdate(ctx);         // (1)
    tsYield();              // (2)
    shellReapApps(ctx);     // (3)
    shellDesktopUpdate();   // (4)
}

1. dvxUpdate -- processes mouse/keyboard input, dispatches widget and window callbacks, composites dirty rects, flushes to the LFB. This is the shell's primary job. When idle (no events, no dirty rects), dvxUpdate calls the registered idleCallback which yields to app tasks.
2. tsYield -- explicit yield to give app tasks CPU time even during busy frames with many repaints. Without this, a flurry of mouse-move events could starve app tasks because dvxUpdate would keep finding work.
3. shellReapApps -- scans the 32-slot app table for apps in AppStateTerminatingE. Calls the shutdown hook (if present), destroys all windows owned by the app, kills the task, closes the DXE handle, and cleans up temp files. Returns true if anything was reaped.
4. shellDesktopUpdate -- if apps were reaped, iterates the registered desktop update callback list so listeners (Program Manager, Task Manager) can refresh their UI.

Crash Recovery

The shell provides Windows 3.1-style fault tolerance using setjmp/longjmp:

1. installCrashHandler() registers crashHandler for SIGSEGV, SIGFPE, SIGILL.
2. setjmp(sCrashJmp) in main() establishes the recovery point.
3. If a signal fires (in any task), crashHandler logs the crash details (signal, app name, full register dump from __djgpp_exception_state_ptr), re-installs the handler (DJGPP uses SysV semantics -- handler resets to SIG_DFL after each delivery), then longjmp(sCrashJmp, 1).
4. longjmp restores the main task's stack frame to the setjmp point. This is safe because cooperative switching means the main task's stack is always intact -- it was cleanly suspended at a yield point.
5. tsRecoverToMain() fixes the task scheduler's currentIdx so it points back to task 0 instead of the crashed task.
6. The crashed app is force-killed via shellForceKillApp(), and a message box is displayed: "'AppName' has caused a fault and will be terminated."
7. The desktop update callbacks are notified so the UI refreshes.

The register dump logged includes EIP, CS, all GPRs (EAX-EDI), segment registers, and EFLAGS -- invaluable for post-mortem debugging.

App Lifecycle

DXE3 Loading

DXE3 is DJGPP's dynamic linking mechanism. Each .app file is a DXE3 shared object. The shell resolves symbols from the export table registered via dlregsym(). The load sequence in shellLoadApp():

1. Allocate a slot from the 32-entry fixed array (slot 0 is the shell).
2. Check if this DXE path is already loaded (findLoadedPath).
   • If the existing app's descriptor says multiInstance = true, copy the .app to a unique temp file (using TEMP/TMP env var) so dlopen gets an independent code+data image.
   • If multiInstance = false, block with an error message.
3. dlopen(loadPath, RTLD_GLOBAL) -- load the DXE.
4. dlsym(handle, "_appDescriptor") -- resolve the metadata struct.
5. dlsym(handle, "_appMain") -- resolve the entry point.
6. dlsym(handle, "_appShutdown") -- resolve the optional shutdown hook.
7. Fill in the ShellAppT slot (name, path, handle, state, etc.).
8. Derive appDir (directory containing the .app file) and configDir (CONFIG/<apppath>/ -- mirrors the app's directory structure under CONFIG/).
9. Set sCurrentAppId to the slot index.
10. Launch:
    • Callback-only (hasMainLoop = false): call entryFn() directly in task 0. The app creates windows, registers callbacks, and returns.
    • Main-loop (hasMainLoop = true): call tsCreate() to make a cooperative task with the descriptor's stack size and priority. The task wrapper sets sCurrentAppId, calls entryFn(), and marks the app AppStateTerminatingE when it returns.
11. Reset sCurrentAppId to 0. Set state to AppStateRunningE. Notify desktop update callbacks.

AppDescriptorT

Every DXE app exports a global AppDescriptorT:

Field	Type	Description
name	char[64]	Display name (Task Manager, title bars)
hasMainLoop	bool	true = dedicated cooperative task; false = callback-only
multiInstance	bool	true = allow multiple simultaneous instances via temp file copy
stackSize	int32_t	Task stack in bytes (SHELL_STACK_DEFAULT = use default)
priority	int32_t	TS_PRIORITY_LOW / TS_PRIORITY_NORMAL / TS_PRIORITY_HIGH

Callback vs Main-Loop Apps

Callback-only (hasMainLoop = false):

• appMain() runs in the shell's task 0, creates windows, registers event callbacks, and returns immediately.
• All subsequent work happens through callbacks dispatched by dvxUpdate().
• Lifecycle ends when the last window is closed (detected by the shellWrapDestroyWindow wrapper).
• No task stack allocated -- simpler and cheaper.
• Examples: Program Manager, Notepad, Control Panel, DVX Demo, Image Viewer.

Main-loop (hasMainLoop = true):

• A cooperative task is created via tsCreate().
• appMain() runs in that task with its own loop calling tsYield().
• Needed when the app has ongoing work that cannot be expressed purely as event callbacks (polling, computation, animation).
• Lifecycle ends when appMain() returns.
• Example: Clock (polls time() each second).

Multi-Instance Support

DXE3's dlopen is reference-counted per path -- loading the same .app twice returns the same handle, sharing all globals and statics. For apps that set multiInstance = true, the shell copies the .app to a temp file (e.g., C:\TEMP\_dvx02.app) before dlopen, giving each instance its own code and data segment. Temp files are cleaned up on app termination.

App State Machine

Free -> Loaded -> Running -> Terminating -> Free

• Free: slot available.
• Loaded: DXE loaded, entry point not yet called (transient).
• Running: entry point called, app is active.
• Terminating: app's task returned or last window closed; awaiting reap.

Resource Tracking

sCurrentAppId is a global set before calling any app code (entry, shutdown, callbacks). The shell's dvxCreateWindow wrapper stamps every new window with win->appId = sCurrentAppId. This is how the shell knows which windows belong to which app, enabling:

• Per-app window cleanup on crash or termination (walk the window stack, destroy all windows with matching appId).
• The last-window-closes-app rule for callback-only apps: when shellWrapDestroyWindow detects that a callback-only app has no remaining windows, it marks the app AppStateTerminatingE.

sCurrentAppId is a simple global (not thread-local) because cooperative multitasking means only one task runs at a time.

Task Manager

shellTaskMgr.c implements a shell-level Task Manager accessible via Ctrl+Esc regardless of which app is focused or whether the desktop app is running. It is owned by the shell (appId = 0), not by any DXE app.

Features:

• ListView with 5 columns: Name, Title, File, Type (Task/Callback), Status.
• Switch To -- find the app's topmost window, restore if minimized, raise and focus it.
• End Task -- force-kill the selected app via shellForceKillApp().
• Run... -- open a file dialog filtered to *.app, load the selected file.
• Status bar -- shows running app count and memory usage (total/free MB).
• Registers with shellRegisterDesktopUpdate so the list auto-refreshes when apps load, terminate, or crash.

Desktop Update Callbacks

shellRegisterDesktopUpdate(fn) adds a function pointer to a dynamic array (managed via stb_ds arrput/arrdel). shellDesktopUpdate() iterates the array and calls each registered function.

This is the mechanism by which the shell notifies interested parties (Program Manager status bar, Task Manager list) when app state changes -- without polling. Multiple listeners are supported. Listeners should call shellUnregisterDesktopUpdate() before they are destroyed.

App Config Storage

Each app gets a dedicated writable config directory under CONFIG/. The path mirrors the app's location under APPS/:

App path:    APPS/PROGMAN/progman.app
Config dir:  CONFIG/PROGMAN/

API:

• shellEnsureConfigDir(ctx) -- create the directory tree via platformMkdirRecursive(). Returns 0 on success.
• shellConfigPath(ctx, "settings.ini", buf, sizeof(buf)) -- build a full path to a file in the config directory.

Apps use the standard preferences system (prefsLoad/prefsSave) pointed at their config directory for persistent settings.

DXE Export Table

shellExport.c contains the ABI contract between the shell and apps. Three categories of exports:

1. Wrapped functions (3): dvxCreateWindow, dvxCreateWindowCentered, dvxDestroyWindow. These are intercepted to stamp win->appId for resource ownership tracking. Apps see them under their original names -- the wrapping is transparent.

2. Direct exports (200+): all other dvx*, wgt*, wm*, ts*, drawing, preferences, platform, and shell API functions. Safe to call without interception.

3. libc / libm / runtime exports (200+): DXE3 modules are relocatable objects, not fully linked executables. Every C library function a DXE calls must be explicitly listed so the loader can resolve it at dlopen time. This includes:

   • Memory (malloc, calloc, realloc, free)
   • String operations (str*, mem*)
   • Formatted I/O (printf, snprintf, fprintf, sscanf, etc.)
   • File I/O (fopen, fread, fwrite, fclose, etc.)
   • Directory operations (opendir, readdir, closedir, mkdir)
   • Time (time, localtime, clock, strftime)
   • Math (sin, cos, sqrt, pow, floor, ceil, etc.)
   • stb_ds internals (arrput/arrfree/hm* macro backends)
   • stb_image / stb_image_write
   • libgcc 64-bit integer helpers (__divdi3, __moddi3, etc.)
   • DJGPP stdio internals (__dj_stdin, __dj_stdout, __dj_stderr)

The table is registered once via dlregsym() before any dlopen().

System Hotkeys

These are always active regardless of which app is focused:

Hotkey	Action
Alt+Tab	Cycle windows forward (rotate top to bottom of stack)
Shift+Alt+Tab	Cycle windows backward (pull bottom to top)
Alt+F4	Close the focused window (calls its onClose callback)
Ctrl+F12	Full screen screenshot -- prompts for save path (PNG/BMP/JPG)
Ctrl+Shift+F12	Focused window screenshot -- prompts for save path
Ctrl+Esc	Open/raise the Task Manager (shell-level, always available)
F10	Activate/toggle the focused window's menu bar
Alt+Space	Open/close the system menu on the focused window

Screenshot System

Two screenshot functions are available, both accessible from the system menu (Alt+Space) or via hotkeys:

• interactiveScreenshot(ctx) -- captures the full screen (composited backbuffer), then opens a Save As file dialog filtered to PNG/BMP/JPG/TGA. Called by Ctrl+F12 or the "Screenshot..." system menu item.
• interactiveWindowScreenshot(ctx, win) -- captures just the focused window's content buffer. Called by Ctrl+Shift+F12 or the "Window Shot..." system menu item.

The system menu also includes standard window operations: Restore, Move, Size, Minimize, Maximize, and Close.

Logging

shellLog(fmt, ...) appends a printf-formatted line to dvx.log. The file is opened, written, and closed on each call (append-per-write) so:

• The file is never held open, allowing Notepad to read it while the shell runs.
• Writes are flushed immediately, important for crash diagnostics.
• The file is truncated once at startup.

Log output includes: startup sequence, preferences applied, video modes enumerated, system information, app load/reap events, crash details with full register dumps.

Shell API Summary

Function	Description
shellAppInit()	Zero the 32-slot app table
shellLoadApp(ctx, path)	Load and start a DXE app. Returns app ID (>= 1) or -1
shellReapApps(ctx)	Clean up terminated apps (call each frame). Returns true if any reaped
shellReapApp(ctx, app)	Gracefully shut down one app (calls shutdown hook)
shellForceKillApp(ctx, app)	Forcibly kill an app -- skips shutdown hook
shellTerminateAllApps(ctx)	Kill all running apps (shell shutdown)
shellGetApp(appId)	Get app slot by ID (NULL if invalid/free)
shellRunningAppCount()	Count running apps (excluding the shell)
shellLog(fmt, ...)	Append to dvx.log
shellEnsureConfigDir(ctx)	Create an app's config directory tree
shellConfigPath(ctx, name, buf, size)	Build path to file in app's config dir
shellExportInit()	Register DXE symbol export table via dlregsym()
shellRegisterDesktopUpdate(fn)	Register callback for app state changes
shellUnregisterDesktopUpdate(fn)	Remove a previously registered callback
shellDesktopUpdate()	Notify all registered listeners
shellTaskMgrOpen(ctx)	Open or raise the Task Manager window
shellTaskMgrRefresh()	Refresh the Task Manager list and status
shellInfoInit(ctx)	Gather and log system hardware information
shellGetSystemInfo()	Return cached system info text