Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 25 additions & 7 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ name: CI
# programs the examples and tests, built for i686-dos-musl through openkal-platform with this
# repository's openkal-dos, run under DOSBox Staging with CWSDPMI beside them (dirun),
# unoptimised and optimised: hello's arguments, exception, environment and status 7;
# files' FAT operations and status 9; a page fault's status 139.
# files' FAT operations and status 9; a page fault's status 139; the default stack
# (1 MiB) holding sixty-four frames of 8 KiB, and a stack of 64 KiB stopped by the
# guard page with status 139.

on:
push:
Expand All @@ -20,7 +22,7 @@ on:
env:
XLINGS_VERSION: v2026.10.26.1
XLINGS_NON_INTERACTIVE: '1'
MCPP_VERSION: 2026.11.14.1
MCPP_VERSION: 2026.11.16.1
LLVM: llvm@23.1.3

jobs:
Expand Down Expand Up @@ -96,12 +98,13 @@ jobs:
xlings install "mcpp@$MCPP_VERSION" -y -g
mcpp self config --mirror GLOBAL
mcpp toolchain install llvm 23.1.3
# Each program is built with this repository's openkal-dos in place of the indexed one.
- name: This repository's openkal-dos
# Each program is built with this repository's openkal-dos and seal in place of the indexed
# ones: the stub and the runtime agree on the hand-over's version.
- name: This repository's openkal-dos and okdos
run: |
for p in examples/hello examples/files tests/fault; do
printf '\n[target.i686-dos-musl.dependencies]\nmcpplibs.openkal-dos = { path = "%s", override = true }\n' \
"$GITHUB_WORKSPACE" >> "$p/mcpp.toml"
for p in examples/hello examples/files tests/fault tests/stack tests/stack-small; do
printf '\n[target.i686-dos-musl.dependencies]\nmcpplibs.openkal-dos = { path = "%s", override = true }\nmcpplibs.openkal-dos-tools = { path = "%s/tools", override = true }\n' \
"$GITHUB_WORKSPACE" "$GITHUB_WORKSPACE" >> "$p/mcpp.toml"
done
- name: hello (status 7), unoptimised and optimised
working-directory: examples/hello
Expand Down Expand Up @@ -131,3 +134,18 @@ jobs:
[ "$rc" = 139 ] || { echo "::error::the faulting program ended with $rc, not 139"; exit 1; }
tr -d '\r' < out.txt | grep -qx 'before the fault'
! tr -d '\r' < out.txt | grep -q 'after the fault'
- name: the default stack holds sixty-four frames of 8 KiB (status 0)
working-directory: tests/stack
run: |
set +e; mcpp run --target i686-dos-musl > out.txt; rc=$?; set -e
cat out.txt
[ "$rc" = 0 ] || { echo "::error::the recursion ended with $rc, not 0"; exit 1; }
tr -d '\r' < out.txt | grep -qx 'sum 2080'
- name: a stack of 64 KiB stops at the guard page (status 139)
working-directory: tests/stack-small
run: |
set +e; mcpp run --target i686-dos-musl > out.txt; rc=$?; set -e
cat out.txt
[ "$rc" = 139 ] || { echo "::error::the overflowing recursion ended with $rc, not 139"; exit 1; }
tr -d '\r' < out.txt | grep -qx 'before the recursion'
! tr -d '\r' < out.txt | grep -q '^sum '
47 changes: 38 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,13 @@ A DOS program of this arrangement is two parts in one file:

| part | what it is |
|---|---|
| the stub (`stub/stub.S`, 2544 bytes) | an MZ program in 16-bit code |
| the stub (`stub/stub.S`, 2656 bytes) | an MZ program in 16-bit code |
| the executable | ELF32, i386, linked at its address (`ET_EXEC`, base 0x1000), at most 16 program headers |

The stub finds a 32-bit DPMI host (int 2Fh, 1687h), and where there is none it
runs `CWSDPMI.EXE` from the program's own directory and asks again. It enters
protected mode as a 32-bit client, allocates one block for the executable's
loadable segments, its first stack (64 KiB) and the hand-over record, makes a
loadable segments, the hand-over record, a guard page and the stack, makes a
code and a data descriptor whose base is the block and whose limit is 4 GiB,
reads each loadable segment from its own file through a 16 KiB transfer buffer
in conventional memory, and enters the executable at `e_entry` with EBX naming
Expand All @@ -51,14 +51,40 @@ stub before an executable, in place; `okdos check <file>` reports whether a file
is such a program. The stub applies no relocation, which is why the executable
is linked at its address.

## The stack

The block is `[loadable segments][the record's page][the guard page][the
stack]`, and the stack's top is the block's end. The stack's size is a property
of the executable, fixed at its link: the program header `PT_GNU_STACK`'s
`p_memsz` (lld's `-z stack-size=N`), rounded up to a page. Where the header is
absent or states zero, the stub's default applies, 1 MiB. A program states
another size with its own link flags; the row links with `ld.lld` itself, so
the flag is the linker's:

```toml
[build]
ldflags = ["-z stack-size=4194304"]
```

The runtime makes the guard page uncommitted through DPMI 1.0's 0507h (set page
attributes), so a stack that grows past its size is a page fault, reported as
every fault is (status 139). CWSDPMI r7 under DOSBox Staging grants 0507h
(measured: the record's page below the guard page reads, the guard page
faults). A host that refuses it leaves the page committed: the runtime fills it
with a canary, says on standard error at the start that the guard is absent, and
checks the canary at the program's end, where an overwritten canary ends the
program with a sentence and status 139.

## The hand-over

The record (`src/dos.h`, version 1, 168 bytes) states the block's linear base,
The record (`src/dos.h`, version 2, 176 bytes) states the block's linear base,
its size and DPMI handle, the segment prefix's selector and segment, the
environment's segment, the transfer buffer's segment, size and selector, the
code and data selectors, the program's file (left open), and the name DOS
started the program by. `okdos_entry` (`src/start.S`) aligns the stack and calls
`okdos_start`, which refuses a record of another version with status 127.
code and data selectors, the program's file (left open), the name DOS started
the program by, the guard page's offset and the stack's size. `okdos_entry`
(`src/start.S`) aligns the stack and calls `okdos_start`, which accepts versions
1 and 2 and refuses any other with status 127. A record of version 1 (the 0.1.0
stub) has no guard page, and its program keeps the 64 KiB stack of that stub.

## Two arrangements

Expand Down Expand Up @@ -133,9 +159,12 @@ call, as an i386 ok image's is. The link is `ld.lld -static
CI (`.github/workflows/ci.yml`) asserts that `stub/stub.S` assembles to the
committed `tools/src/stub_bytes.h`; that `okdos` builds on Linux, macOS and
Windows and refuses a file that is no ELF32 i386 executable; and that the
examples and `tests/fault`, built for `i686-dos-musl` with this repository's
openkal-dos and run under DOSBox Staging, unoptimised and optimised, print what
they state and end with 7, 9 and 139.
examples and the tests, built for `i686-dos-musl` with this repository's
openkal-dos and seal and run under DOSBox Staging, print what they state and end
with their statuses: `examples/hello` 7 (unoptimised and optimised),
`examples/files` 9, `tests/fault` 139, `tests/stack` 0 (sixty-four frames of
8 KiB within the default stack) and `tests/stack-small` 139 (the same recursion
with a stack of 64 KiB, stopped by the guard page).

## CWSDPMI

Expand Down
2 changes: 1 addition & 1 deletion mcpp.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-dos"
version = "0.1.0"
version = "0.1.1"
description = "An implementation of openkal on DOS through DPMI (technical experiment only)"
license = "Apache-2.0"
provides = ["mcpp:kernel-abi=openkal"]
Expand Down
18 changes: 15 additions & 3 deletions src/dos.h
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
// What the stub hands over, and the two ways this implementation reaches DOS.
//
// THE HAND-OVER (stub/stub.S writes it, version 1). The program is entered in 32-bit protected
// THE HAND-OVER (stub/stub.S writes it, version 2). The program is entered in 32-bit protected
// mode with CS, DS, ES and SS descriptors whose base is the block the stub allocated and whose
// limit spans 4 GiB, so an address of the program is an offset from the block's base and any
// linear address L is reached at L - base. EBX holds the record's offset.
//
// THE BLOCK is [loadable segments][the record's page][the guard page][the stack]; the stack's top
// is the block's end.
#pragma once

namespace okdos {
Expand All @@ -12,7 +15,7 @@ using u8 = unsigned char; using u16 = unsigned short; using u32 = unsigned int;

struct handoff {
u32 magic; // "OKDS"
u32 version; // 1
u32 version; // 2
u32 base; // the block's linear address
u32 size; // its size
u32 block; // its DPMI handle
Expand All @@ -24,8 +27,13 @@ struct handoff {
u16 code_selector, data_selector, tb_selector;
u16 exe_handle; // the program's own file, opened by the stub
char name[128]; // the program's name as DOS gave it
// Version 2 (0.1.1). A record of version 1 (the 0.1.0 stub) ends here; its program has the
// stack of 64 KiB above the record and no guard page.
u32 guard; // the guard page's offset in the block
u32 stack_size; // the stack's size: PT_GNU_STACK's, or the stub's default (1 MiB)
};
static_assert(sizeof(handoff) == 168);
static_assert(sizeof(handoff) == 176);
constexpr u32 kVersion = 2;
constexpr u32 kMagic = 0x53444b4fu;

// DPMI's real-mode call structure (int 31h, 0300h).
Expand Down Expand Up @@ -65,6 +73,10 @@ bool append_handle(u16 handle);
// The handlers of the processor's faults (fault.S, fault.cpp): a fault is reported on standard
// error and ends the program with 128 and the signal's number.
void install_faults();
// The guard page below the stack (stack.cpp): uncommitted through DPMI 1.0 (int 31h, 0507h), so an
// overflow is a page fault; where the host refuses, a canary checked at the program's end.
void guard_stack();
void check_stack();

// Days from 1970-01-01 to a civil date (H. Hinnant's algorithm).
inline long long days_from_civil(long long y, unsigned m, unsigned d) {
Expand Down
1 change: 1 addition & 0 deletions src/kal.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ bool is_console(u16 handle) {
extern "C" {

KAL_NORETURN void kal_exit(int code) {
check_stack();
__asm__ volatile("int $0x21" ::"a"(0x4c00 | (code & 0xff)));
for (;;) {}
}
Expand Down
59 changes: 59 additions & 0 deletions src/stack.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
// The guard page below the stack (openkal-dos 0.1.1).
//
// The stub reserves one page between the hand-over record's page and the stack (src/dos.h). Made
// uncommitted through DPMI 1.0's 0507h (set page attributes), it turns a stack that grows past its
// size into a page fault, which fault.cpp reports with status 139. A host without 0507h leaves the
// page committed: the page is then filled with a canary, a sentence on standard error says at the
// start that the guard is absent, and the program's end checks the canary.
#include "dos.h"

namespace okdos {
namespace {

constexpr u32 kPage = 4096;
constexpr u32 kCanary = 0x4b415453u; // "STAK"
bool canary_set = false;

u32* guard_words() {
return reinterpret_cast<u32*>(static_cast<unsigned long>(self().h->guard));
}

void say(const char* s) {
u32 n = 0;
while (s[n]) ++n;
write_handle(2, reinterpret_cast<const u8*>(s), n);
}

} // namespace

void guard_stack() {
const handoff* h = self().h;
if (h->version < 2) return; // the 0.1.0 stub reserves no guard page
u16 attribute = 0; // uncommitted
u32 ax = 0x0507, pages = 1; // ECX returns the pages set on a refusal
int carry;
__asm__ volatile("int $0x31\n\tsbb %2, %2"
: "+a"(ax), "+c"(pages), "=r"(carry)
: "S"(h->block), "b"(h->guard), "d"(&attribute)
: "memory", "cc");
if (carry == 0) return;
u32* w = guard_words();
for (u32 i = 0; i < kPage / 4; ++i) w[i] = kCanary;
canary_set = true;
say("openkal-dos: the DPMI host has no 0507h: no guard page below the stack; an overflow is "
"reported at the program's end\r\n");
}

void check_stack() {
if (!canary_set) return;
const u32* w = guard_words();
for (u32 i = 0; i < kPage / 4; ++i)
if (w[i] != kCanary) {
canary_set = false;
say("openkal-dos: the stack overflowed its size\r\n");
__asm__ volatile("int $0x21" ::"a"(0x4c00 | (128 + 11)));
for (;;) {}
}
}

} // namespace okdos
3 changes: 2 additions & 1 deletion src/start.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,13 @@ void record_arguments(const handoff* h) {
} // namespace

extern "C" [[noreturn]] void okdos_start(const handoff* h) {
if (h->magic != kMagic || h->version != 1) {
if (h->magic != kMagic || h->version < 1 || h->version > kVersion) {
// A stub of another version: nothing here can be trusted to say so but the status.
kal_exit(127);
}
self().h = h;
install_faults();
guard_stack();
record_arguments(h);
#ifdef OKDOS_STANDALONE
__libc_start_main(main, 0, nullptr, nullptr, nullptr, nullptr);
Expand Down
40 changes: 32 additions & 8 deletions stub/stub.S
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,17 @@
// at the end of its environment and opens it; reads the executable's ELF header and program
// headers; asks for a DPMI host (int 2Fh, 1687h), and where there is none runs CWSDPMI.EXE from
// the program's directory and asks again; enters protected mode as a 32-bit client; allocates
// one block of memory for the executable's segments, its first stack and the hand-over record;
// one block of memory for the executable's segments, the hand-over record, a guard page and the
// stack, in this order;
// makes a code and a data descriptor whose base is the block and whose limit spans 4 GiB; reads
// each loadable segment into the block through a transfer buffer in conventional memory (int 21h
// simulated by DPMI 0300h), zeroes what the file does not hold, and enters the executable at its
// ELF entry with EBX the hand-over record's offset (src/dos.h, okdos::handoff).
//
// THE STACK'S SIZE is the executable's PT_GNU_STACK p_memsz (lld's `-z stack-size=N'), rounded up
// to a page; where the program header is absent or states zero, DEFAULT_STACK. The runtime makes
// the guard page uncommitted (src/stack.cpp); the stub only reserves it.
//
// Built by stub/build.sh into tools/src/stub_bytes.h, which the seal (tools/) writes before the
// executable. Apache-2.0, as the rest of openkal-dos; nothing of DJGPP's stub is used.
.code16
Expand All @@ -41,7 +46,8 @@ _okdos_stub:
.set STACK, 0x800
.set PHMAX, 16
.set TB_PARAS, 0x400 // the transfer buffer: 16 KiB
.set FIRST_STACK, 0x10000 // the executable's first stack: 64 KiB
.set DEFAULT_STACK, 0x100000 // the stack where the executable states none: 1 MiB
.set PT_GNU_STACK, 0x6474e551

start:
movw %es, %ax
Expand Down Expand Up @@ -125,12 +131,22 @@ start:
call read
jc fail_read

// The span: the highest end of a loadable segment.
// The span: the highest end of a loadable segment. The stack: PT_GNU_STACK's size.
movl $DEFAULT_STACK, stack_size
xorl %eax, %eax
movw phnum, %cx
movw $phdrs, %si
6: jcxz 7f
cmpl $1, (%si) // PT_LOAD
cmpl $PT_GNU_STACK, (%si)
jne 14f
movl 20(%si), %edx // p_memsz; zero states nothing
testl %edx, %edx
jz 8f
addl $0xfff, %edx
andl $0xfffff000, %edx
movl %edx, stack_size
jmp 8f
14: cmpl $1, (%si) // PT_LOAD
jne 8f
movl 8(%si), %edx // p_vaddr
addl 20(%si), %edx // p_memsz
Expand All @@ -143,7 +159,9 @@ start:
7: addl $0xfff, %eax
andl $0xfffff000, %eax
movl %eax, span
addl $(FIRST_STACK + 0x1000), %eax
addl $0x2000, %eax // the record's page and the guard page
addl stack_size, %eax
jc fail_format
movl %eax, block_size

// A DPMI host, or CWSDPMI from the program's directory.
Expand Down Expand Up @@ -239,7 +257,7 @@ have_dpmi:
movw data_sel, %es
movl span, %edi
movl $0x53444b4f, %es:(%edi) // "OKDS"
movl $1, %es:4(%edi) // version
movl $2, %es:4(%edi) // version
movl base, %eax
movl %eax, %es:8(%edi)
movl block_size, %eax
Expand All @@ -263,6 +281,11 @@ have_dpmi:
movw %ax, %es:36(%edi)
movw handle, %ax // the program's file, left open: closing it here hangs
movw %ax, %es:38(%edi) // under DOSBox Staging, and DOS closes it at the end
movl span, %eax // the guard page, after the record's page
addl $0x1000, %eax
movl %eax, %es:168(%edi)
movl stack_size, %eax
movl %eax, %es:172(%edi)
// The name the program was started by, as DOS gave it.
leal 40(%edi), %edi
movw $path, %si
Expand All @@ -273,7 +296,7 @@ have_dpmi:
testb %al, %al
jnz 13b

// Enter: DS, ES and SS the data descriptor, the first stack at the block's end.
// Enter: DS, ES and SS the data descriptor, the stack's top at the block's end.
movl span, %ebx
movl ehdr + 24, %edx // e_entry
movw code_sel, %cx
Expand Down Expand Up @@ -518,7 +541,7 @@ fail_pm:
m_memory: .asciz "okdos: not enough memory\r\n"
m_open: .asciz "okdos: the program cannot open itself\r\n"
m_read: .asciz "okdos: the program's executable cannot be read\r\n"
m_format: .asciz "okdos: the appended executable is not ELF32 i386 with at most 16 program headers\r\n"
m_format: .asciz "okdos: the appended executable is not ELF32 i386 with at most 16 program headers and a block below 4 GiB\r\n"
m_dpmi: .asciz "okdos: no 32-bit DPMI host, and none from CWSDPMI.EXE beside the program\r\n"
m_switch: .asciz "okdos: the DPMI host refused protected mode\r\n"
m_block: .asciz "okdos: the DPMI host has no block of the executable's size\r\n"
Expand All @@ -545,6 +568,7 @@ tb_sel: .word 0
.balign 4
span: .long 0
block_size: .long 0
stack_size: .long 0
base: .long 0
block_handle: .long 0
exec_block: .word 0
Expand Down
Loading
Loading