dos64smp

KO | EN

gitlite — search

#react #ai #typescript #llm #golang #rust #deep-learning #docker #awesome #cli #awesome-list #pytorch #mcp #open-source

(★ 16)

x86-64 symmetric multiprocessing MS-DOS extender

dos64smp Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DOS64SMP - x86-64 DOS Extender
**A Program That Should Not Be Existing (But Does Anyway)**

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![License: Commercial](https://img.shields.io/badge/License-Commercial-green.svg)](https://raw.githubusercontent.com/TheWhiteAmbit/dos64smp/main/)

## Table of Contents

- [Introduction](#introduction)
- [Building from Source](#building-from-source)
- [Usage as TSR](#usage-as-tsr)
  - [Mailbox Protocol](#mailbox-protocol)
- [BSP Code Flow](#bsp-code-flow-dos64smpasm)
- [AP Code Flow](#ap-code-flow-application-processor-initialization)
- [Worker Code](#worker-code-the-aps-main-loop)
- [Final Notes](#final-notes)
- [License](#license)

---

## Introduction

This is an **x86-64 DOS extender with SMP (Symmetric Multi-Processing) support** running as a **TSR (Terminate and Stay Resident)** program. This type of software should really not be existing in 2025, but it does - created purely for fun, academic research, and to challenge revived old-school assembler skills.

The program demonstrates starting a secondary processor (Application Processor) in 64-bit long mode from 16-bit real mode DOS, managing it through a simple mailbox protocol, and leaving it running as a TSR without consuming additional conventional memory.

---

## Building from Source

To compile the programs, you need **NASM (Netwide Assembler)**. Use the following commands:

```bash
nasm -f bin dos64smp.asm -o DOS64SMP.COM
nasm -f bin dos64use.asm -o DOS64USE.COM
```

The `-f bin` option tells NASM to produce a flat binary file (DOS .COM format).
- `DOS64SMP.COM` is the main TSR program
- `DOS64USE.COM` is an example program that demonstrates how to use the TSR

---

## Usage as TSR

After `dos64smp.com` runs and installs itself as TSR, other programs can detect and communicate with the running AP (Application Processor) through a simple command/acknowledgment protocol. See `dos64use.asm` for a usage example.

### Mailbox Protocol

The TSR uses PSP offsets `0x80-0xFF` as a mailbox for communication:

#### Command Byte (PSP+0xFF)

| Command | Description |
|---------|-------------|
| `0` | Idle (AP is probably running worker loop) |
| `1/0` | Acknowledgment from AP (command completed/command failed) |
| `2` | Jump to address provided in `0x80-0x87` (most will only use `0x84-0x87` for 32-bit) |
| `3` | Provoke Div by 0 Exception in AP (AP will acknowledge with 1, BSP leaves it like it is, because the AP became unusable) |
| `4` | Provide safe reentry address in `0x80-0x87` for AP recovery (AP stores it, acknowledges with 1, BSP should reset to 0) |
| `32/64` | Return 32/64-bit capability (AP will acknowledge with 0 or 1, BSP should return to 0) |
| `255` | Halt command (AP will acknowledge with 1, BSP leaves it like it is, because the AP became unusable) |

#### Mailbox Area (PSP+0x80 to PSP+0x87)

- 8 bytes available for data exchange between BSP and AP
- Can be used for passing parameters or status information
- Currently reserved for memory address transfers

#### To Find the TSR

1. Enumerate DOS TSRs by walking the MCB (Memory Control Block) chain
2. Look for program name "DOS64SMP" or specific signature
3. Access PSP+0xFF for commands and PSP+0x80-0x87 for data exchange

---

## BSP Code Flow (dos64smp.asm)

The Bootstrap Processor (BSP) code handles the complex initialization process to start the Application Processor in 32/64-bit mode and then return to DOS.

### 1. Startup in 16-bit Real Mode

The program starts as a standard DOS .COM file at offset `0x100` in the PSP. 8KB of space are reserved inside the COM file to guarantee that we can find a 4KB-aligned block starting at an absolute 4KB memory boundary.

#### Why 8KB Reservation?

In a .COM file, our code starts at `PSP+0x100`. The PSP is aligned to a 16-byte paragraph boundary, but we need 4KB (4096 byte) physical alignment for the trampoline code that the AP will execute.

By reserving 8KB, we are mathematically guaranteed to find a 4KB-aligned address within this range, regardless of where DOS loads our PSP. The trampoline code remains at this dynamically-calculated address within the COM file's memory space.

#### The Trampoline Code and Stack Sharing

This 4KB block is used for two purposes:
- **BOTTOM HALF**: Minimal trampoline code (16-bit real mode AP startup code)
- **TOP HALF**: Intermediate stack used by AP during initialization

The trampoline code is tiny (~100 bytes), and the stack grows downward from the top of the 4KB block. The AP only does a few push/pop operations during initialization, so the stack never grows large enough to interfere with the code section at the bottom.

### 2. A20 Gate Enabling

Before entering protected mode, we must enable the A20 gate to access memory above 1MB. The code tries multiple methods:
- BIOS method (`INT 15h, AX=2401h`)
- Keyboard controller method (port `0x64/0x60`)

Each method is tested by reading back the A20 status. This is critical because without A20, addresses above 1MB wrap around to low memory.

### 3. Interrupt Disabling

Before transitioning to protected mode, we disable maskable interrupts (`CLI`). This is essential because:
- Real mode interrupt vectors don't work in protected mode
- We haven't installed protected mode interrupt handlers yet
- Any interrupt during transition could triple-fault the system

Interrupts remain disabled during critical transitions and are re-enabled only after setting up proper IDT (Interrupt Descriptor Table) entries.

### 4. GDT Setup and Protected Mode Entry

We set up a Global Descriptor Table with the following segments (in order):
- Null descriptor (required by x86 architecture)
- 16-bit code segment (used by BSP for returning to real mode)
- 16-bit data segment (used by BSP for returning to real mode)
- 32-bit code segment (4GB, base 0, executable, readable)
- 32-bit data segment (4GB, base 0, writable)
- 64-bit code segment (always present, used by AP when in 64-bit mode)
- 64-bit data segment (always present, used by AP when in 64-bit mode)

#### Unified GDT Format

The GDT is designed in a "unified format" that works for both BSP initialization and AP startup, reducing code duplication. The same GDT structure is used by:
- **BSP**: Uses only 16-bit and 32-bit segments (for entering protected mode and returning to real mode; never enters 64-bit mode)
- **AP**: Uses only 32-bit and 64-bit segments (never uses 16-bit segments since AP never returns to real mode)

This unified approach means we only need to define one GDT structure that both processors can share, with each processor using only the segments it needs.

After loading the GDT, we enter protected mode by setting `CR0.PE` (bit 0). A far jump immediately follows to flush the instruction prefetch queue and load the new code segment selector.

### 5. APIC Detection and Initialization

The code detects the presence of APIC (Advanced Programmable Interrupt Controller) using CPUID:
- `CPUID.01h.EDX` bit 9 indicates APIC support
- Without APIC, we cannot start additional processors

#### APIC Base Address

Read from MSR `0x1B` (`IA32_APIC_BASE`). Default is usually `0xFEE00000`.

#### x2APIC Mode

If `USE_X2APIC` is defined, the code enables x2APIC mode (MSR-based APIC access) instead of memory-mapped APIC. x2APIC is faster and supports more processors.

#### APIC Initialization

- Enable APIC by setting bit 8 of Spurious Interrupt Vector Register
- Set up Local APIC ID
- Configure interrupt delivery modes

### 6. Trampoline Code Preparation

The trampoline code is the small piece of 16-bit real mode code that the AP will execute when it starts. It must be located at a 4KB-aligned physical address (the alignment is required for SIPI vector calculation).

#### Locating the Trampoline

The trampoline code resides at a dynamically-calculated 4KB-aligned address within the 8KB reserved buffer in our COM file. This involves:
- Finding the first 4KB-aligned address within the `trampoline_buffer`
- Calculating the physical address based on where DOS loaded our PSP
- Copying the trampoline code bytes

#### Patching the Trampoline

The trampoline code contains placeholders that must be patched with actual runtime addresses:
- GDT address (linear physical address)
- Jump target addresses
- Stack pointer values

#### The Role of tramp_data_linear_base

This variable stores the linear (physical) base address where our COM file is loaded in memory. The trampoline code uses offsets assembled relative to the COM origin, but needs actual physical addresses at runtime.

For example, if we assembled a reference to `gdt_table`, the assembler generates an offset relative to our COM origin. But the trampoline needs the actual physical address. We calculate this as:

```
physical_address = tramp_data_linear_base + (assembled_offset - COM_ORG_OFFSET)
```

This translation is done for every address embedded in the trampoline code that references data structures in the COM file.

### 7. AP Startup Sequence

Starting the Application Processor involves sending IPI (Inter-Processor Interrupt) messages through the APIC:

#### INIT IPI

First, send an INIT IPI to reset the AP to a known state. This puts the AP into "wait-for-SIPI" mode.

#### Delay

Wait at least 10 milliseconds for INIT to complete. Timing is **CRITICAL** here.

#### Startup IPI (SIPI)

Send a SIPI (Startup IPI) with the vector pointing to the trampoline code address. The vector is calculated as: `physical_address / 4096`.

For example, if the trampoline is at physical address `0x9000`, the vector would be `0x09`.

The SIPI tells the AP to start executing at physical address `(vector * 4096)`. Since the trampoline address is 4KB-aligned, this calculation always produces the correct vector.

#### Second SIPI

Intel specification recommends sending two SIPIs for compatibility. Some older processors require this.

#### Delays Between IPIs

Wait 200 microseconds between SIPIs. Use of appropriate delay method:
- **PIT** (Programmable Interval Timer) - traditional, reliable
- **APIC timer** - faster but requires APIC configuration
- **TSC** (Time Stamp Counter) - fastest but requires calibration

### 8. Critical Timing Issues

#### Broadwell-EP Processors

Some Intel Xeon Broadwell-EP processors are extremely picky about IPI timing. If delays are too short, the AP may not start. If delays are too long, the system may hang. The code includes calibrated delays specifically tested on these processors.

#### Timer Options

- `PIT_DELAY`: Uses port `0x43/0x40` programmable interval timer (slowest, most compatible)
- `APIC_TIMER_DELAY`: Uses APIC timer one-shot mode (faster, requires APIC setup)
- `TSC_DELAY`: Uses RDTSC instruction (fastest, requires TSC frequency)

#### APIC Delivery Status

After sending each IPI, poll the APIC Interrupt Command Register (ICR) to check the "Delivery Status" bit. This bit is cleared when the IPI has been accepted. Timeout if it takes too long (indicates APIC problem).

### 9. Waiting for AP Completion

After sending the SIPIs, the BSP waits for the AP to signal completion by toggling the `ap_ready` byte from 0 to 1. The code polls this byte with a timeout:
- **Success**: AP sets `ap_ready = 1` (initialization complete)
- **Timeout**: `ap_ready` stays 0 (AP didn't start within expected time, display error)

### 10. Return to Real Mode (with Unreal Mode Option!)

After the AP is running, the BSP must return to real mode to hand control back to DOS:

#### Unreal Mode (For Fun)

The code offers an option to return in "Unreal Mode" (also called "Big Real Mode"). This is a quirky x86 feature where:
- The processor is in real mode (`CR0.PE = 0`)
- BUT segment registers still have 32-bit limits from protected mode
- Allows 4GB addressing in "real mode"!

Unreal mode is enabled by:
1. Entering protected mode
2. Loading segment registers with 32-bit descriptors
3. Returning to real mode (clear `CR0.PE`)
4. Segment limits stay at 4GB!

This is mostly useless but **FUN** to demonstrate.

#### Real Mode (What We Actually Want)

For normal DOS operation, we return to pure real mode:
1. Load 16-bit segment selectors
2. Clear `CR0.PE` to exit protected mode
3. Reload segment registers with real mode values
4. Restore original interrupt vector table (IVT)
5. Re-enable interrupts (`STI`)

### 11. TSR Installation (No Additional Memory Needed!)

The program installs itself as TSR using `INT 21h, AH=31h, DX=0x10`.

The clever part: `DX=0x10` means keep only 16 paragraphs (`16*16 = 256 bytes`), which is exactly the size of the PSP itself. We keep the PSP but no additional program code or data in conventional memory.

#### The Mailbox at 0x80-0xFF

DOS doesn't use PSP offsets `0x80-0xFF` for important data in TSR programs. These 128 bytes are traditionally used for command-line arguments, but a TSR doesn't have command-line arguments after installation!

We use this space as a mailbox:
- `0xFF` = Command byte (communication with AP)
- `0x80-0x87` = 8-byte data area for future extensions

The AP code knows the physical address of this PSP region and can read/write it directly, even from 64-bit mode.

### 12. No DPMI (Important!)

This DOS extender intentionally does **NOT** use DPMI (DOS Protected Mode Interface).

#### Why?

- DPMI is a service provided by DOS extenders (DOS4GW, CWSDPMI, etc.)
- Windows 3.x through Windows ME also provide DPMI
- If we install our own DPMI handler, we would interfere with these systems

By avoiding DPMI, our TSR can coexist peacefully with:
- DOS extenders (DOS4GW, DOS32A, PMODE/W, etc.)
- Windows 3.0, 3.1, 3.11, 95, 98, ME running in DOS mode
- Games and applications that use DPMI

We directly manipulate `CR0`, `CR3`, `CR4`, `GDT`, and `IDT` ourselves, bypassing any DPMI services entirely.

---

## AP Code Flow (Application Processor Initialization)

The Application Processor starts executing the trampoline code at a 4KB-aligned physical address in 16-bit real mode. This address varies from run to run based on where the 4KB-aligned `trampoline_bytes` block is found within our COM file.

### 1. AP Entry in 16-bit Real Mode (Trampoline Code)

The AP begins execution at the SIPI vector address (4KB-aligned trampoline). At this point:
- CPU is in 16-bit real mode
- `CS:IP` points to the trampoline physical address (varies by run)
- No stack is set up yet
- All other segment registers are undefined
- Interrupts are disabled

#### First Actions

- Disable interrupts (`CLI`) - should already be off, but make sure
- Set up segment registers (`DS`, `ES`, `SS`) to point to trampoline data
- Load a temporary stack pointer (using the top half of the 4KB block)

### 2. GDT Setup (Unified Format)

The AP loads the same unified GDT that the BSP prepared. The GDT physical address was patched into the trampoline code by the BSP.

The unified GDT contains (in order):
- Null descriptor (required by x86 architecture)
- 16-bit code segment - unused by AP (only used by BSP for real mode return)
- 16-bit data segment - unused by AP (only used by BSP for real mode return)
- 32-bit code segment (4GB, base 0, executable, readable) - used by AP
- 32-bit data segment (4GB, base 0, writable) - used by AP
- 64-bit code segment - used by AP when in 64-bit long mode
- 64-bit data segment - used by AP when in 64-bit long mode

`LGDT` instruction loads the GDT register with the base address and limit.

### 3. Transition to 32-bit Protected Mode

Set `CR0.PE` (bit 0) to enter protected mode. Immediately perform a far jump to load CS with the 32-bit code segment selector and flush the prefetch queue.

The AP is now in 32-bit protected mode with paging disabled.

#### Leaving the Trampoline

After entering protected mode, the AP jumps from the trampoline code (at the 4KB-aligned physical address) back to code in the COM file. This is done via a far jump using addresses that were patched by the BSP during initialization. From this point, the AP runs from the same code segment as the original COM file, but in 32-bit protected mode.

### 4. Page Table Setup at 1.5MB (Intermediate Location)

Page tables are initially set up at physical address 1.5MB (`0x180000`) as a temporary location. These page tables are required for 64-bit long mode, but may also be used in 32-bit protected mode with paging enabled (for memory protection, process hiding, etc.). **Note**: These page tables are later copied to the worker code area in high memory (see section 8).

#### Why 1.5MB?

- Below 1MB: Real mode IVT, BIOS data, VGA memory (`0x00000-0xFFFFF`)
- 1MB-1.5MB: Extended BIOS data, option ROMs, free space
- 1.5MB+: Usually free memory, safe for our page tables
- **IMPORTANT**: 1.5MB is always available when the first 2MB are identity-mapped in the page tables, which should always be done to ensure low memory access

#### Page Table Hierarchy (if using 4-level paging)

- **PML4** (Page Map Level 4) at `0x180000` (1 page = 4KB)
- **PDPT** (Page Directory Pointer Table) at `0x181000` (1 page = 4KB)
- **PD** (Page Directory) at `0x182000` (1+ pages, depends on mapped memory)
- **PT** (Page Table) entries - optional, for 4KB page granularity

#### Identity Mapping

We create an identity map where virtual address = physical address. This simplifies the transition to 64-bit mode because our code can continue running at the same addresses.

**NOTE**: This is only fully true when `GAP_SIZE_IN_2MB = 0` (no gap). If a gap is defined, memory is identity-mapped UP TO the gap position, then the gap range has no mappings (causing page faults), then identity mapping resumes after the gap.

#### PT_HEADER_PAGES (Mapping Beyond 1GB)

By default, we map the first 1GB of memory. If `PT_HEADER_PAGES` is defined to a value > 1, we create additional page directory entries to map more memory. Each page directory entry maps 2MB with 2MB pages.

For example:
- `PT_HEADER_PAGES = 1`: Map first 1GB (512 * 2MB entries)
- `PT_HEADER_PAGES = 2`: Map first 2GB (1024 * 2MB entries)
- `PT_HEADER_PAGES = 4`: Map first 4GB (2048 * 2MB entries)

#### GAP in Page Tables (Hiding Above 4GB)

`GAP_POSITION_IN_2MB` and `GAP_SIZE_IN_2MB` allow creating a "gap" in the page table mappings. This is useful for:
- Testing page fault handlers
- Hiding memory regions from 32-bit DOS programs
- Creating protected memory areas

**How the Gap Works**: If `GAP_SIZE_IN_2MB > 0`, the code skips creating page table entries for the specified range. Any access to these virtual addresses will cause a page fault.

**Hiding 32-bit Processes Above 4GB**: An interesting use case: If we leave the AP in 32-bit protected mode but set up a gapped page table that maps memory above 4GB (with the gap below 4GB), the AP can run "invisibly" in high memory.

32-bit DOS programs are limited to 4GB address space and cannot see or access memory above 4GB. The AP, using page tables, can map its code/data to physical addresses above 4GB, making it virtually inaccessible to other DOS programs!

### 5. Enable Paging and Enter Long Mode (64-bit)

Steps to enter 64-bit long mode:

1. Load `CR3` with PML4 physical address (`0x180000`)
2. Set `CR4.PAE` (bit 5) = 1 to enable Physical Address Extension
3. Set `EFER.LME` (bit 8) = 1 to enable Long Mode (write to MSR `0xC0000080`)
4. Set `CR0.PG` (bit 31) = 1 to enable paging
5. Perform far jump to 64-bit code segment

After the far jump, the CPU is in **64-bit long mode**!

### 6. Exception Handlers in COM File Code Area

Exception handler code exists in the COM file's normal code area in low memory. An IDT (Interrupt Descriptor Table) is created pointing to these handlers. Both the handlers and IDT are later copied to the worker code area in high memory (see section 8) to prevent them from being overwritten by other DOS programs.

#### Fixed 10-byte Exception Stubs

The exception handler stubs are fixed at exactly 10 bytes each. This keeps the math simple for later patching operations. Without this constraint, the assembler might optimize some stubs to 7-10 bytes, making patching unnecessarily complicated.

#### USE_16BYTE_EXCEPTION_IDT

This option creates 16-byte IDT entries compatible with both 32-bit and 64-bit modes, providing backwards compatibility. In 64-bit mode, IDT entries are 16 bytes; in 32-bit mode, they're 8 bytes. Using 16-byte entries allows the same IDT structure to work in both modes.

#### SEL_CODE64 Patching

The 64-bit code segment selector (`SEL_CODE64`) in the IDT entries is patched just before entering 64-bit long mode. This ensures the interrupt handlers use the correct code segment when transitioning to 64-bit mode.

#### Optional Exception Testing

The code includes multiple optional exception test points (all disabled by default) that can be enabled for debugging. One example is `USE_INTENTIONAL_EXCEPTION_IN_WORKER`, which when defined causes the AP to intentionally trigger a division by zero exception (INT 0) to verify:
- The IDT is correctly installed
- Exception handlers work in 64-bit mode
- The stack is properly set up

The exception handler increments a counter and returns (`IRET`), allowing the AP to continue execution. Similar test points exist at various stages of initialization (BSP, AP immediate, after CR4/CR3/CR0 changes, after page table setup, after GDT setup, after moving to worker area), but all are commented out by default.

### 7. Intermediate Stack Setup

The AP's stack is initially set up in the trampoline area (top half of the 4KB-aligned block). This temporary stack is used during early initialization.

The stack is then moved directly to its permanent location within the worker code area before the worker loop begins. This ensures the stack doesn't get overwritten by other DOS programs using low memory.

### 8. Moving Setups to Worker Code Position

This is a critical step: All the intermediate structures (page tables, GDT, IDT, exception handlers, stack) are initially set up in low memory or temporary locations. We must move them to the final worker code position to prevent them from being overwritten.

#### What Gets Moved

- **Page tables**: Copied from `0x180000` (intermediate location) to worker code area in high memory
- **GDT**: Copied from COM file area to worker code area
- **IDT**: Copied from COM file area to worker code area
- **Exception handlers**: Copied from COM file's code area to worker code area; `SEL_CODE64` selectors in IDT entries are patched before entering 64-bit mode
- **Stack**: Moved to worker code area offset by stack size

#### Updating Pointers

After moving these structures, we must update all registers:
- `CR3`: Reload with new page table address
- `GDTR`: Reload with new GDT address
- `IDTR`: Reload with new IDT address
- `RSP/ESP`: Update stack pointer to new stack location

This ensures the AP is completely self-contained and doesn't rely on any memory that DOS or other programs might overwrite.

---

## Worker Code (The AP's Main Loop)

After initialization, the AP enters its main worker loop. This code runs continuously in the background, making its presence visible through VGA output and responding to commands from the BSP.

### 1. Visual Indicators

To demonstrate that the AP is running, the worker code modifies VGA text mode and graphics output:

#### Text Mode - Color Changes (Second Text Line)

The worker code randomly changes the foreground color of characters in the second line of VGA text mode (row 1, 80 columns). It:
- Reads the current character and attribute byte
- Generates a random foreground color (0-15)
- Ensures foreground doesn't match background (visibility check)
- Writes the new attribute byte back to VGA memory at `0xB8000`

This creates a "twinkling" effect where text colors change randomly, proving the AP is actively running.

#### VGA Graphics - Center Pixel Block

The worker code also writes to VGA graphics memory to create a visible 4x4 pixel block in the center of the screen. This works with VGA Mode Y (planar mode, 320x200, 256 colors) as used by games like DOOM, or other graphics modes.

**Mode Y planar addressing** (used by the code):

```
Physical offset = (y * 80) + (x / 4)
```

Plane selection is handled via VGA sequencer register. This differs from Mode 13h's linear addressing but provides the same visual result.

The 4x4 pixel block is drawn at screen coordinates (158, 98) - roughly center screen. Each pixel is written with a random color from the AP's RNG.

#### Pixel Counter and Wrapping

The worker uses a pixel counter (0-15) that cycles through the 4x4 grid:
- `Counter / 4` = row (0-3)
- `Counter % 4` = column (0-3)

Each iteration, it draws one pixel and increments the counter, wrapping at 16.

### 2. Command Observation (0xFF Mailbox)

The worker code continuously polls the command byte at `PSP+0xFF`. Commands:

- **0 = IDLE**: Worker continues normal operation (color changes, pixel drawing)

- **1/0 = ACKNOWLEDGMENT**: Written BY the AP to signal command completion status
  - `1` = command completed successfully
  - `0` = command failed
  - The BSP waits for this acknowledgment

- **2 = JUMP TO ADDRESS**: Jump to address provided in mailbox at `PSP+0x80-0x87` (most applications will use only `PSP+0x84-0x87` for 32-bit addresses). The AP will execute code at this address.

- **3 = PROVOKE DIV BY 0 EXCEPTION**: Intentionally trigger division by zero in AP
  - AP will acknowledge with 1
  - BSP leaves command byte as-is
  - AP becomes unusable after this (exception handler may not recover)

- **4 = PROVIDE SAFE REENTRY ADDRESS**: Store a safe reentry address in `PSP+0x80-0x87` that the AP can jump to for recovery
  - AP reads the address from the mailbox and stores it for future use
  - AP acknowledges with 1
  - BSP should reset command byte to 0
  - This provides a known-good entry point if the AP needs to recover from an error or reset its execution state

- **32/64 = RETURN 32/64-BIT CAPABILITY**: Query AP's current mode
  - AP acknowledges with 0 (32-bit mode) or 1 (64-bit mode)
  - BSP should reset command byte to 0 after reading response

- **255 = HALT**: The AP should halt itself. When this command is received:
  - AP stops the worker loop
  - Writes 1 to `PSP+0xFF` (acknowledgment)
  - BSP leaves command byte as-is
  - AP executes `HLT` instruction (low power state)
  - AP becomes unusable until system reset

The mailbox protocol is simple but effective for demonstrating inter-processor communication without complex synchronization primitives.

---

## Final Notes

This program is a technical demonstration of x86-64 assembly, DOS internals, APIC programming, and multiprocessor initialization. It serves no practical purpose in modern computing but offers a lot of potential:

### Practical Applications

- **SoundBlaster emulation** on the second core, observing reserved memory and acting completely transparent for the BSP core via DMA, just like real hardware would do
- **Providing a secondary CPU** that can safely perform complex calculations, such as 3Dfx Voodoo emulation, without interfering with the main DOS process
- **Preserving the current DOS state** in high memory and restoring previous states in games (save state functionality at the hardware level)
- **Academic/research**: Hiding from old virus scanners not expecting anything outside of the single-core 32-bit universe (rather academic than practical)

### Technical Showcase

- Deep understanding of x86-64 architecture (real, protected, long mode)
- APIC and IPI programming
- Memory management (GDT, IDT, page tables)
- DOS internals (PSP, TSR, memory "allocation")
- VGA programming (text mode and Mode Y graphics)
- Timing and synchronization challenges
- Creative abuse of ancient technology

**It should not be existing, but here it is. Enjoy responsibly!**

---

## License

### DOS64SMP - x86-64 DOS Extender with SMP Support
**Copyright (c) 2025 Moritz Strickhausen**

This program is dual-licensed:

### Primary License: GNU General Public License v3.0 (GPL-3.0)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but **WITHOUT ANY WARRANTY**; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

### Mailbox Protocol Exception

**Programs that communicate with DOS64SMP solely through the documented mailbox protocol (PSP+0x80-0xFF command/data interface) are NOT considered derivative works and are NOT subject to GPL requirements.** Such programs may be licensed under any terms chosen by their authors.

This exception allows you to:
- Write programs that use the DOS64SMP TSR without GPL contamination
- Use the mailbox protocol in proprietary or closed-source software
- Distribute your programs under any license you choose

The exception does **NOT** apply to:
- Modifications to the DOS64SMP source code itself
- Derivative works based on DOS64SMP code
- Redistribution of DOS64SMP with modifications

### Commercial License

For commercial use that requires incorporation of DOS64SMP code without GPL obligations, alternative commercial licenses are available.

**Contact**: moritz.strickhausen at gmail(.com) for inquiries regarding commercial licensing.

dos64smp

dos64smp Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

dos64smp

dos64smp Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README