# DVX — DOS Visual eXecutive

A Windows 3.x-style desktop shell for DOS, built with DJGPP/DPMI. Combines a
windowed GUI compositor, cooperative task switcher, and DXE3 dynamic loading to
create a multitasking desktop environment where applications are `.app` shared
libraries loaded at runtime.

## Components

```
dvxgui/
  dvx/          GUI compositor library          -> lib/libdvx.a
  tasks/        Cooperative task switcher        -> lib/libtasks.a
  dvxshell/     Desktop shell (Program Manager)  -> bin/dvxshell.exe
  apps/         DXE app modules (.app files)     -> bin/apps/*.app
  rs232/        ISR-driven UART serial driver     -> lib/librs232.a
  packet/       HDLC framing, CRC, Go-Back-N     -> lib/libpacket.a
  security/     DH key exchange, XTEA-CTR cipher  -> lib/libsecurity.a
  seclink/      Secure serial link wrapper        -> lib/libseclink.a
  proxy/        Linux SecLink-to-telnet proxy     -> bin/secproxy
  termdemo/     Encrypted ANSI terminal demo      -> bin/termdemo.exe
```

## Building

Requires the DJGPP cross-compiler (`i586-pc-msdosdjgpp-gcc`).

```
make -C dvx         # builds lib/libdvx.a
make -C tasks       # builds lib/libtasks.a
make -C dvxshell    # builds bin/dvxshell.exe
make -C apps        # builds bin/apps/*.app
```

Set `DJGPP_PREFIX` in the Makefiles if your toolchain is installed somewhere
other than `~/djgpp/djgpp`.

## Architecture

The shell runs as a single DOS executable (`dvxshell.exe`) that loads
applications dynamically via DJGPP's DXE3 shared library system. Each app
is a `.app` file exporting an `appDescriptor` and `appMain` entry point.

```
+-------------------------------------------------------------------+
|                        dvxshell.exe (Task 0)                       |
|  +-------------+  +-----------+  +----------+  +----------------+ |
|  | shellMain   |  | shellApp  |  | shellDxe |  | shellDesktop   | |
|  | (event loop)|  | (lifecycle|  | (DXE     |  | (Program Mgr)  | |
|  |             |  |  + 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`.

## Sample Apps

| App | Type | Description |
|-----|------|-------------|
| `progman.app` | Callback | Program Manager: app launcher grid, Task Manager |
| `notepad.app` | Callback | Text editor with file I/O |
| `clock.app` | Main-loop | Digital clock (multi-instance capable) |
| `dvxdemo.app` | Callback | Widget system showcase |

## Target Platform

- **CPU**: 486 baseline, Pentium-optimized paths where significant
- **Video**: VESA VBE 2.0+ with linear framebuffer
- **OS**: DOS with DPMI (CWSDPMI or equivalent)
- **Test platform**: 86Box

## Deployment

```
mcopy -o -i <floppy.img> bin/dvxshell.exe ::DVXSHELL.EXE
mcopy -o -i <floppy.img> bin/apps/*.app ::APPS/
```

## 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