DVX_GUI/shell

DVX Shell

The DVX Shell (dvxshell.lib) is a DXE module loaded by the DVX loader at startup. 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.

The shell is not a standalone executable. The loader maps it into memory via dlopen, resolves its entry point (shellMain), and calls it. All symbols the shell needs -- libdvx, libtasks, widgets, libc -- are resolved at load time from DXE modules already loaded by the loader and the loader's own dlregsym table.

Files

File	Purpose
shellMain.c	Entry point (shellMain), main loop, crash recovery, logging
shellApp.c	App loading via dlopen/dlsym, lifecycle, reaping
shellApp.h	ShellAppT, AppDescriptorT, AppStateE, DxeAppContextT, API
shellExport.c	3 DXE wrapper overrides for window resource tracking
shellInfo.c	System info gathering
shellInfo.h	shellInfoInit(), shellGetSystemInfo()
shellTaskMgr.c	Task Manager window
shellTaskMgr.h	shellTaskMgrOpen(), shellTaskMgrRefresh()
Makefile	Cross-compile rules, produces dvxshell.lib and dvxshell.dep

Building

make        # builds ../bin/libs/dvxshell.lib and ../bin/libs/dvxshell.dep
make clean  # removes objects, binary, and deployed config files

CFLAGS: -O2 -Wall -Wextra -march=i486 -mtune=i586 -I../core -I../core/platform -I../tasks -I../tasks/thirdparty

The shell is compiled to object files and packaged into a DXE via dxe3gen. It exports _shell so the loader can resolve shellMain. All other symbols are unresolved imports (-U) satisfied at load time.

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

Dependencies

dvxshell.dep lists the modules the loader must load before the shell:

libtasks
libdvx
box
button
checkbox
dropdown
label
listbox
listview
radio
separator
spacer
statbar
textinpt

The loader reads this file, loads each module via dlopen with RTLD_GLOBAL, then loads the shell itself. This is how all symbols (dvx*, wgt*, ts*, etc.) become available without the shell statically linking anything.

Startup Sequence

shellMain() in shellMain.c is called by the loader after all dependencies are loaded. It performs initialization in this order:

1. 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).
2. Load preferences -- prefsLoad("CONFIG/DVX.INI"). Missing file or keys silently fall back to compiled-in defaults.
3. dvxInit -- initialize VESA video (LFB), backbuffer, compositor, window manager, font, cursor, input subsystems. Reads video width/height/bpp from preferences (default 640x480x16).
4. Mouse config -- read wheel direction, double-click speed, acceleration from [mouse] section and call dvxSetMouseConfig().
5. Color scheme -- read [colors] section (20 RGB triplets), apply via dvxApplyColorScheme().
6. Wallpaper -- read [desktop] section for wallpaper path and mode (stretch/tile/center), load via dvxSetWallpaper().
7. Video mode log -- enumerate all available VESA modes to dvx.log.
8. Task system -- tsInit(), set shell task (task 0) to TS_PRIORITY_HIGH so the UI stays responsive under load.
9. System info -- shellInfoInit() gathers CPU, memory, drive info via the platform layer and logs it.
10. DXE exports -- shellExportInit() calls dlregsym() to register the 3 wrapper overrides. Must happen before any dlopen() of app DXEs.
11. App slot table -- shellAppInit() zeroes the 32-slot fixed array.
12. Idle/hotkey callbacks -- wire up idleYield, ctrlEscHandler, titleChangeHandler on the AppContextT.
13. Desktop app -- shellLoadApp(ctx, "apps/progman/progman.app"). If this fails, the shell exits.
14. 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 shellMain() 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. Symbols are resolved from the loaded RTLD_GLOBAL modules (libdvx, libtasks, widgets) and the shell's 3 wrapper overrides 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.

DXE Export Table

shellExport.c registers 3 wrapper functions via dlregsym() that override the real implementations for subsequently loaded app DXEs:

1. dvxCreateWindow -- stamps win->appId for resource ownership tracking.
2. dvxCreateWindowCentered -- stamps win->appId for resource ownership tracking.
3. dvxDestroyWindow -- checks if the destroyed window was a callback-only app's last window and marks it for reaping.

The key mechanic: dlregsym takes precedence over RTLD_GLOBAL exports. Since libdvx (which has the real functions) was loaded before shellExportInit() registers these wrappers, libdvx keeps the real implementations. But any app DXE loaded afterward gets the wrappers, which add resource tracking transparently.

All other symbol exports -- dvx*, wgt*, ts*, platform*, libc, libm -- come from the DXE modules loaded with RTLD_GLOBAL by the loader. They no longer need to be listed in the shell's export table.

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.

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
shellMain(argc, argv)	Entry point called by the DVX loader
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 3 DXE wrapper overrides 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