277 lines
11 KiB
Markdown
277 lines
11 KiB
Markdown
# DVX -- DOS Visual eXecutive
|
|
|
|
A windowed GUI compositor and desktop shell for DOS, built with
|
|
DJGPP/DPMI. DVX combines a Motif-style window manager, dirty-rectangle
|
|
compositor, cooperative task switcher, and DXE3 dynamic application
|
|
loading into a multitasking desktop environment where applications are
|
|
`.app` shared libraries loaded at runtime.
|
|
|
|
Targets real and emulated 486+ hardware with VESA VBE 2.0+ linear
|
|
framebuffer. No bank switching -- LFB or fail.
|
|
|
|
|
|
## Features
|
|
|
|
- Motif/GEOS-style beveled window chrome with drag, resize, minimize,
|
|
maximize, and restore
|
|
- Dirty-rectangle compositor -- only changed regions are flushed to video
|
|
memory, critical for acceptable frame rates on 486/Pentium hardware
|
|
- 32 widget types: buttons, text inputs, list boxes, tree views, list
|
|
views, tab controls, sliders, spinners, progress bars, dropdowns,
|
|
combo boxes, splitters, scroll panes, ANSI terminal emulator, and more
|
|
- Flexbox-style automatic layout engine (VBox/HBox containers with
|
|
weighted space distribution)
|
|
- Dropdown menus with cascading submenus, checkbox and radio items,
|
|
keyboard accelerators, and context menus
|
|
- Modal dialogs: message box (OK/Cancel/Yes/No/Retry) and file
|
|
open/save with directory navigation and filter dropdown
|
|
- 20-color theme system with live preview and INI-based theme files
|
|
- Wallpaper support: stretch, tile, or center with bilinear scaling and
|
|
16bpp ordered dithering
|
|
- Live video mode switching without restart
|
|
- Mouse wheel support (CuteMouse Wheel API)
|
|
- Screenshots (full screen or per-window) saved as PNG
|
|
- Clipboard (copy/cut/paste within DVX)
|
|
- Timer widget for periodic callbacks
|
|
- Cooperative task switcher for apps that need their own main loop
|
|
- DXE3 dynamic application loading with crash recovery (SIGSEGV,
|
|
SIGFPE, SIGILL caught and isolated per-app)
|
|
- INI-based preferences system with typed read/write accessors
|
|
- Encrypted serial networking stack (DH key exchange, XTEA-CTR cipher)
|
|
- Platform abstraction layer -- DOS/DJGPP production target, Linux/SDL2
|
|
development target
|
|
|
|
|
|
## Target Hardware
|
|
|
|
- **CPU**: 486 baseline, Pentium-optimized paths where significant
|
|
- **Video**: VESA VBE 2.0+ with linear framebuffer
|
|
- **OS**: DOS with DPMI (CWSDPMI or equivalent)
|
|
- **Supported depths**: 8, 15, 16, 24, 32 bpp
|
|
- **Test platform**: 86Box with PCI video cards
|
|
|
|
|
|
## Architecture
|
|
|
|
The shell runs as a single DOS executable (`dvx.exe`) that loads
|
|
applications dynamically via DJGPP's DXE3 shared library system.
|
|
|
|
```
|
|
+-------------------------------------------------------------------+
|
|
| dvx.exe (Task 0) |
|
|
| +-------------+ +-----------+ +------------+ |
|
|
| | shellMain | | shellApp | | shellExport| |
|
|
| | (event loop)| | (lifecycle| | (DXE symbol| |
|
|
| | | | + reaper)| | export) | |
|
|
| +-------------+ +-----------+ +------------+ |
|
|
| | | | |
|
|
| +------+-------+ +----+-----+ +----+----+ |
|
|
| | libdvx.a | |libtasks.a| | libdxe | |
|
|
| | (GUI/widgets)| |(scheduler)| | (DJGPP) | |
|
|
| +--------------+ +----------+ +---------+ |
|
|
+-------------------------------------------------------------------+
|
|
| |
|
|
+---------+ +---------+
|
|
| app.app | | app.app |
|
|
| (Task N)| | (Task M)|
|
|
+---------+ +---------+
|
|
```
|
|
|
|
### App Types
|
|
|
|
**Callback-only** (`hasMainLoop = false`): `appMain` creates windows,
|
|
registers callbacks, and returns. The app lives through event callbacks
|
|
in the shell's main loop. No dedicated task or stack needed.
|
|
|
|
**Main-loop** (`hasMainLoop = true`): A cooperative task is created for
|
|
the app. `appMain` runs its own loop calling `tsYield()` to share CPU.
|
|
Used for apps that need continuous processing (clocks, terminal
|
|
emulators, games).
|
|
|
|
### Crash Recovery
|
|
|
|
The shell installs signal handlers for SIGSEGV, SIGFPE, and SIGILL. If
|
|
an app crashes, the handler `longjmp`s back to the shell's main loop,
|
|
the crashed app is force-killed, and the shell continues running.
|
|
Diagnostic information (registers, faulting EIP) is logged to `dvx.log`.
|
|
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
dvxgui/
|
|
dvx/ GUI compositor library (libdvx.a)
|
|
platform/ Platform abstraction (DOS/DJGPP, Linux/SDL2)
|
|
widgets/ Widget system (32 types, one file per type)
|
|
thirdparty/ stb_image.h, stb_image_write.h
|
|
tasks/ Cooperative task switcher (libtasks.a)
|
|
thirdparty/ stb_ds.h
|
|
dvxshell/ Desktop shell (dvx.exe)
|
|
apps/ DXE app modules (.app files)
|
|
progman/ Program Manager -- app launcher grid
|
|
notepad/ Text editor with file I/O
|
|
clock/ Digital clock (multi-instance, main-loop)
|
|
dvxdemo/ Widget system showcase / demo app
|
|
cpanel/ Control Panel -- themes, wallpaper, video, mouse
|
|
imgview/ Image Viewer -- BMP/PNG/JPEG/GIF display
|
|
rs232/ ISR-driven UART serial driver (librs232.a)
|
|
packet/ HDLC framing, CRC-16, Go-Back-N (libpacket.a)
|
|
security/ DH key exchange, XTEA-CTR cipher (libsecurity.a)
|
|
seclink/ Secure serial link wrapper (libseclink.a)
|
|
proxy/ Linux SecLink-to-telnet proxy (secproxy)
|
|
termdemo/ Encrypted ANSI terminal demo (termdemo.exe)
|
|
themes/ Color theme files (.thm)
|
|
wpaper/ Bundled wallpaper images
|
|
bin/ Build output (dvx.exe, apps/, config/)
|
|
lib/ Build output (static libraries)
|
|
releases/ Release archives
|
|
```
|
|
|
|
|
|
## Building
|
|
|
|
Requires the DJGPP cross-compiler (`i586-pc-msdosdjgpp-gcc`).
|
|
|
|
```bash
|
|
# Build everything (dvx lib, tasks lib, shell, all apps)
|
|
make
|
|
|
|
# Build individual components
|
|
make -C dvx # builds lib/libdvx.a
|
|
make -C tasks # builds lib/libtasks.a
|
|
make -C dvxshell # builds bin/dvx.exe
|
|
make -C apps # builds bin/apps/*/*.app
|
|
|
|
# Clean all build artifacts
|
|
make clean
|
|
```
|
|
|
|
Set `DJGPP_PREFIX` in the component Makefiles if your toolchain is
|
|
installed somewhere other than `~/djgpp/djgpp`.
|
|
|
|
|
|
## Deployment
|
|
|
|
### CD-ROM ISO (86Box)
|
|
|
|
The primary deployment method is an ISO image mounted as a CD-ROM in
|
|
86Box:
|
|
|
|
```bash
|
|
./mkcd.sh
|
|
```
|
|
|
|
This builds everything, then creates an ISO 9660 image with 8.3
|
|
filenames at `~/.var/app/net._86box._86Box/data/86Box/dvx.iso`. Mount
|
|
it in 86Box as a CD-ROM drive and run `D:\DVX.EXE` (or whatever drive
|
|
letter is assigned).
|
|
|
|
### Floppy Image
|
|
|
|
For boot floppy setups with CD-ROM drivers:
|
|
|
|
```bash
|
|
mcopy -o -i <floppy.img> bin/dvx.exe ::DVX.EXE
|
|
mcopy -s -o -i <floppy.img> bin/apps ::APPS
|
|
mcopy -s -o -i <floppy.img> bin/config ::CONFIG
|
|
```
|
|
|
|
The `apps/` and `config/` directory structures must be preserved on the
|
|
target -- Program Manager recursively scans `apps/` for `.app` files at
|
|
startup.
|
|
|
|
|
|
## Configuration
|
|
|
|
DVX reads its configuration from `CONFIG\DVX.INI` on the target
|
|
filesystem. The INI file uses a standard `[section]` / `key = value`
|
|
format. Settings are applied at startup and can be changed live from the
|
|
Control Panel app.
|
|
|
|
```ini
|
|
[video]
|
|
width = 640
|
|
height = 480
|
|
bpp = 16
|
|
|
|
[mouse]
|
|
wheel = normal
|
|
doubleclick = 500
|
|
acceleration = medium
|
|
|
|
[desktop]
|
|
wallpaper = C:\DVX\WPAPER\SWOOP.JPG
|
|
wallpaperMode = stretch
|
|
theme = C:\DVX\THEMES\WIN31.THM
|
|
```
|
|
|
|
### Video Section
|
|
|
|
- `width`, `height` -- requested resolution (closest VESA mode is used)
|
|
- `bpp` -- preferred color depth (8, 15, 16, 24, or 32)
|
|
|
|
### Mouse Section
|
|
|
|
- `wheel` -- `normal` or `reversed`
|
|
- `doubleclick` -- double-click speed in milliseconds (200--900)
|
|
- `acceleration` -- `off`, `low`, `medium`, or `high`
|
|
|
|
### Desktop Section
|
|
|
|
- `wallpaper` -- path to wallpaper image (BMP, PNG, JPEG, GIF)
|
|
- `wallpaperMode` -- `stretch`, `tile`, or `center`
|
|
- `theme` -- path to color theme file (.thm)
|
|
|
|
|
|
## Bundled Applications
|
|
|
|
| App | File | Type | Description |
|
|
|-----|------|------|-------------|
|
|
| Program Manager | `progman.app` | Callback | App launcher grid with icons; also provides the Task Manager (Ctrl+Esc) for switching between running apps |
|
|
| Notepad | `notepad.app` | Callback | Text editor with File/Edit menus, open/save dialogs, clipboard, and undo |
|
|
| Clock | `clock.app` | Main-loop | Digital clock display; multi-instance capable |
|
|
| DVX Demo | `dvxdemo.app` | Callback | Widget system showcase demonstrating all 32 widget types |
|
|
| Control Panel | `cpanel.app` | Callback | System settings: color themes with live preview, wallpaper selection, video mode switching, mouse configuration |
|
|
| Image Viewer | `imgview.app` | Callback | Displays BMP, PNG, JPEG, and GIF images with file dialog |
|
|
|
|
|
|
## Serial / Networking Stack
|
|
|
|
A layered encrypted serial communications stack for connecting DVX to
|
|
remote systems (BBS, etc.) through 86Box's emulated UART:
|
|
|
|
| Layer | Library | Description |
|
|
|-------|---------|-------------|
|
|
| rs232 | `librs232.a` | ISR-driven UART driver with FIFO support, automatic UART type detection (8250 through 16750), configurable baud rate |
|
|
| packet | `libpacket.a` | HDLC framing with byte stuffing, CRC-16 integrity checks, Go-Back-N sliding window for reliable delivery, 255-byte max payload |
|
|
| security | `libsecurity.a` | 1024-bit Diffie-Hellman key exchange (RFC 2409 Group 2), XTEA-CTR stream cipher, XTEA-CTR DRBG random number generator |
|
|
| seclink | `libseclink.a` | Convenience wrapper: multiplexed channels (0--127), per-packet encryption flag, bulk send helper |
|
|
| proxy | `secproxy` | Linux-side bridge: 86Box emulated serial port <-> secLink <-> telnet BBS; socket shim replaces rs232 API |
|
|
|
|
|
|
## Third-Party Dependencies
|
|
|
|
All third-party code is vendored as single-header libraries with no
|
|
external dependencies:
|
|
|
|
| Library | Location | Purpose |
|
|
|---------|----------|---------|
|
|
| stb_image.h | `dvx/thirdparty/` | Image loading (BMP, PNG, JPEG, GIF) |
|
|
| stb_image_write.h | `dvx/thirdparty/` | Image writing (PNG export for screenshots) |
|
|
| stb_ds.h | `tasks/thirdparty/` | Dynamic array and hash map (used by task manager) |
|
|
|
|
|
|
## Component Documentation
|
|
|
|
Each component directory has its own README with detailed API reference:
|
|
|
|
- [`dvx/README.md`](dvx/README.md) -- GUI library architecture and API
|
|
- [`tasks/README.md`](tasks/README.md) -- Task switcher API
|
|
- [`dvxshell/README.md`](dvxshell/README.md) -- Shell internals and DXE app contract
|
|
- [`apps/README.md`](apps/README.md) -- Writing DXE applications
|
|
- [`rs232/README.md`](rs232/README.md) -- Serial port driver
|
|
- [`packet/README.md`](packet/README.md) -- Packet transport protocol
|
|
- [`security/README.md`](security/README.md) -- Cryptographic primitives
|
|
- [`seclink/README.md`](seclink/README.md) -- Secure serial link
|
|
- [`proxy/README.md`](proxy/README.md) -- Linux SecLink proxy
|
|
- [`termdemo/README.md`](termdemo/README.md) -- Encrypted terminal demo
|