BASIC-DOS

A PCjs Retro-Programming Project

Project maintained by jeffpar

BASIC-DOS Technical Reference

Protected Mode and Memory Management

BASIC-DOS manages all memory, on every processor, through a built-in driver, CPU$, which is also the only part of BASIC-DOS that knows about descriptors, selectors, and physical memory. CPU$ loads first and determines the processor type, and on a processor that can use protected mode, it manages a table of physical memory blocks covering conventional and extended memory, along with the GDT, the IDT, and the LDTs that sessions use (see The CPU$ Drivers).

On an 80286 or later, unless real mode is requested (by a CPU=8088 line in CONFIG.SYS, or R at the boot message), BASIC-DOS switches to protected mode while its drivers initialize, and stays there (see Protected-Mode Initialization): CPU$, the drivers, and the kernel run at ring 0, and COMMAND.COM, its BASIC programs, and the programs it runs run at ring 3, with each console’s sessions’ memory in an LDT of their own (see Running Programs at Ring 3), and DOS allocates memory from anywhere in conventional or extended memory. Otherwise, as on an 8086 or 8088, the same binaries run in real mode, BASIC-DOS’s most compatible mode, where CPU$ manages memory with a chain of MCBs, as DOS always has, and uses no extra memory (see Mode-Independent Code).

Every demo runs in protected mode on a PC AT, and on a COMPAQ DeskPro 386 with the 80386’s features, except Wolfenstein 3D, an MZ EXE file; the Extended Memory demos also give DOS extended memory to allocate. What doesn’t work in protected mode yet (most notably, MZ EXE files) is listed under Limitations.

Supported Machines

Protected mode needs an 80286 or later, at least 256K of conventional memory (after any MEMSIZE= line), and A20 control through the 8042 keyboard controller, as on a PC AT; otherwise (or when real mode is requested; see CPU), BASIC-DOS runs in real mode. Extended memory is a bonus: it adds to the memory that DOS can allocate.

Protected mode is built and tested for the IBM PC AT (80286, with IBM’s revision 3 BIOS), typically with 2Mb of memory: 640K of conventional memory and 1408K of extended memory. On an 80386, CPU$ also uses some of the 80386’s features (see The CPU$ Drivers), which are tested on a COMPAQ DeskPro 386 with 2Mb. Protected mode is the default on those machines, so every demo that boots on one runs in protected mode, except Wolfenstein 3D, whose diskette has a CPU=8088 line, and tools/tests/mmutest.sh runs the protected-mode tests on six machines: a PC XT, a PC AT in real mode, and a PC AT and a DeskPro 386 in protected mode, each both with RING=0 and without it.

The CPU$ Drivers

BASDEV.COM starts with two CPU$ drivers, of which exactly one stays loaded: the 80386 driver (which also supports the 80286), followed by the 8086 driver. The 80386 driver, which is initialized first, determines the processor type:

  1. An 8086 or 80186 decrements SP before PUSH SP stores it, whereas an 80286 or later stores the original value.
  2. An 80186 masks shift counts to 5 bits, so shifting 1 left 33 times leaves 2 (instead of 0 on an 8086).
  3. In real mode, an 80286 always clears FLAGS bits 12-15, whereas an 80386 lets software set bits 12-14 (IOPL and NT).

It stores the result in CPU_HWTYPE (0:513h) and CPU_TYPE (0:512h), as one of the CPUTYPE_* values in cpu.inc (0 = 8086/8088, 1 = 80186/80188, 2 = 80286, 3 = 80386 or later). A request for real mode (a CPU=8088 line in CONFIG.SYS, which P at the boot message overrides, or R at the boot message), or less than 256K of conventional memory (after any MEMSIZE= line, which the 80386 driver applies by lowering the BIOS’s memory size), makes CPU$ store 0 in CPU_TYPE and act as it does on an 8088, without enabling A20, and so does any later reason not to stay (no A20 control, or a failed test of protected mode); CPU_HWTYPE is still the processor’s own type, for software that must know how the processor runs instructions (eg, DEBUG.COM’s disassembler).

  • The 80386 driver stays if the processor is an 80286 or later, with the memory and A20 control that protected mode needs (see Supported Machines), and a switch to protected mode and back succeeds. It enables A20 permanently, and builds its arena (a table of PMBs) and descriptor tables in the 64K system area. On an 80386 or later, it uses the 80386’s features, unless CONFIG.SYS has a CPU=80286 line, and stores 3 in CPU_TYPE (otherwise, 2): an 80386 TSS (with an I/O permission bitmap that allows no ports, so every I/O instruction at ring 3 still faults, except a V86 machine’s use of the video ports; see V86 Machines), selectors that can cover more than 64K (see CPU_SETLIM), and paging. Either way, an 80386 returns to real mode by clearing PE.
  • The 8086 driver stays otherwise. It manages memory with a chain of MCBs, as DOS always has, so every block that’s allocated after it (eg, the other drivers, the kernel, and programs) has an MCB in the paragraph before it, which programs that walk the MCB chain can see.

Neither can be skipped (devinit ignores SKIP=CPU$), and whichever stays is at 0970h. It provides its functions through DDINT_CPU (0050:0030h), a far jump in low memory like the other DDINT entry points, which fails (with carry set) until CPU$ initializes. It also provides DDINT_GETVEC and DDINT_SETVEC (see Device Drivers), which read and write the real-mode vector table, or in protected mode, CPU$’s IDT.

Functions

Call DDINT_CPU with a function number in AH. Physical addresses and lengths are 32-bit byte values: addresses in DX:CX and lengths in SI:DI (high:low). Every function runs with interrupts disabled, preserves BX, SI, DI, BP, DS, and ES, and returns carry clear on success, or carry set with an error code in AX.

AH Function Inputs Outputs
00h CPU_GETINFO   AL = CPU type, AH = CPUF_* flags (bits 6-7 = CPU_HWTYPE), DX:CX = length of largest free block
01h CPU_ALLOC AL = MEMF_* flags, BX = owner (see Owner IDs), SI:DI = length AX = first selector (0 if MEMF_NONE), DX:CX = address
02h CPU_FREE DX:CX = block  
03h CPU_MAP AL = MEMF_* flags, DX:CX = address, SI:DI = length (with MEMF_REMAP, BX = selector ID) AX = first selector, CX = number of selectors, and with MEMF_LDT, DX = the selector’s ID (see Selector IDs)
04h CPU_UNMAP BX = first selector, CX = number of selectors (0 = 1), or BX = selector ID  
05h CPU_QUERY BX = PMB number (0 = first), or -1 for block DX:CX; ES:DI -> 32-byte buffer PMB copied to ES:DI
06h CPU_ALIAS AL = MEMF_* flags, BX = selector AX = new selector, DX:CX = base address
07h CPU_PMODE (none) Protected mode, for good: CS, DS, ES, and SS are now selectors for the same memory, and AX = a data selector for the caller’s CS (see Protected-Mode Initialization)
08h CPU_REALLOC DX:CX = block, SI:DI = new length  
09h CPU_MOVE ES:BX -> MOVEPKT (source address, destination address, and length, all dwords)  
0Ah CPU_SETBLK DX:CX = block, AL = MCBTYPE_*, BX = owner (non-zero), ES:SI -> 8-character name (SI = 0 for none)  
0Bh CPU_FREEALL BX = owner (see Owner IDs)  
0Ch CPU_SETLIM BX = selector, SI:DI = new length (1 to 64K, or on an 80386, any non-zero length)  
0Dh CPU_SEGINFO AL = ADDR_* flags, BX = selector (or segment) DX:CX = base address, AX = limit (or with ADDR_RIGHTS, AL = access rights, AH = extended byte)
0Eh CPU_RWMEM AL = ADDR_* flags, BX:SI = address, CX = length, ES:DI -> buffer  
0Fh CPU_SYSREGS ES:DI -> 16-byte buffer GDTR, IDTR, and a V86 machine’s interrupt return address (offset, selector) stored at ES:DI; AX = MSW, CX = LDTR, DX = TR
10h CPU_SETFAULT DX:CX = fault handler (0:0 for none) DX:CX = previous handler
11h CPU_SETSTACK DX:CX = ring 0 stack (SS:SP) DX:CX = previous ring 0 stack
12h CPU_SETLDT AL = LDT number  
13h CPU_V86 AL = 0: BX = owner, SI:DI = length, DX = video memory’s selector (or 0); AL = 1: BX = machine, ES:DI -> V86REGS; AL = 2 or 3: ES:DI -> V86REGS; AL = 4 or 5: BX = machine, CX = first port, DX = # of ports AL = 0: AX = machine (its memory’s first selector), DX = its video memory’s segment (or 0); AL = 1: AL = V86X_* exit; AL = 2: the last machine’s registers stored at ES:DI; AL = 3: its registers set from ES:DI; AL = 4: the ports lent to the machine; AL = 5: taken back (see V86 Machines)

Every function works the same way in either driver and in either mode, so callers needn’t check which is which: in real mode, CPU_ALLOC, CPU_MAP, and CPU_ALIAS return the memory’s segment instead of a selector (CPU_ALLOC returns 0 for a block above 1Mb, and CPU_MAP needs memory below 1Mb that’s paragraph-aligned), a segment is its own alias, and CPU_UNMAP has nothing to do. Errors are ERR_INVALID (eg, a bad function, a zero length, or a selector that isn’t in use), ERR_NOMEMORY (no block big enough, with DX:CX = the length of the largest free block; or no free PMB or descriptors), and ERR_BADADDR (a block that CPU_ALLOC didn’t return).

  • Blocks: a block (DX:CX) is the address that CPU_ALLOC returned, or DX = -1 and CX = the selector (or segment) that it returned, which is what DOS has (eg, in ES for DOS_MEM_FREE). CPU_ALLOC rounds lengths up to a multiple of 16, so every block starts on a paragraph boundary, and a block of more than 64K gets one selector for every 64K (each 8 more than the last). CPU_REALLOC shrinks a block, or grows it into the free block after it; its first selector and code alias stay the same, but its selectors always fit its new length (it gets or loses one for every 64K, so growing past a multiple of 64K needs free descriptors after its last selector). In protected mode, a block that can’t grow where it is (the block after it isn’t free, or isn’t long enough) moves to the first free block that’s long enough (below 1Mb, if that’s where it was), as long as it has selectors and isn’t a V86 machine’s memory: its contents are copied, and every code or data descriptor that maps its memory, in the GDT and in every LDT, gets the new address, so its selectors and aliases stay the same, and only its address changes (so that DOS_MEM_REALLOC can grow a program’s block that another block follows). CPU_MOVE copies memory between any two physical addresses (below 1Mb, in real mode), even if they overlap. CPU_SETBLK records a block’s owner, type, and name for DOS (as an MCB does), which MEM and DEBUG’s DM show, and CPU_FREEALL frees every block an owner has (DOS uses it when a program ends).
  • Owner IDs: an owner is a PSP (or a driver’s segment, or MCBOWNER_SYSTEM), which the 80386 driver stores as an owner ID (PMB_OWNER). In protected mode, a ring 3 program’s PSP is an LDT selector, which a program with another LDT can share (see Ring 3), so its ID is 80h plus its LDT number in the high byte and its LDT index in the low byte (eg, 8000h for session 0’s COMMAND.COM, whose PSP is selector 0007h, and 8100h for session 1’s, if session 1 has LDT 1), which is unique, and above MCBOWNER_SYSTEM, like a PSP segment; any other owner is its own ID. CPU_QUERY returns the IDs (eg, to MEM and DEBUG’s DM, which display them), and CPU_FREEALL takes an owner, as CPU_ALLOC and CPU_SETBLK do. DOS compares a block’s owner with a program’s ID, which it gets from the program’s own block (every PSP block owns itself), when it needs to know whether the program owns the block (eg, for a fault in the program’s code, or FRE(-1); see DOS_UTL_QRYMEM).
  • Memory flags: MEMF_LDT (01h) requests LDT selectors instead of GDT selectors, MEMF_CODE (02h) code segments instead of data segments, MEMF_NONE (04h) a block without any selectors (for CPU_MAP and CPU_ALIAS, the same bit is MEMF_CONFORM, which makes conforming code, which code at any ring can call, and which runs at the caller’s ring, as FPU$’s functions do), MEMF_RDONLY (08h) read-only data (or execute-only code), and MEMF_USER (10h) DPL 3 selectors, for programs at ring 3. CPU_MAP also takes MEMF_REMAP (80h; see Selector IDs), and CPU_ALIAS takes MEMF_SHARE (20h; see Code Aliases). CPU_ALLOC also takes MEMF_LOW (20h) to allocate below 1Mb, MEMF_HIGH (40h) to allocate from the top of the last free block that’s big enough, and MEMF_AT (80h) to allocate the memory at DX:CX; otherwise, it allocates from the first free block that’s big enough, conventional or extended.
  • Selectors: CPU_MAP maps existing memory, CPU_ALIAS creates another selector for the same memory as an existing one, with different access rights (see Code Aliases), CPU_UNMAP frees either, and CPU_SETLIM changes the length that a selector covers, keeping the selector. When CPU_TYPE is 3 (an 80386), CPU_SETLIM (and CPU_MAP with MEMF_REMAP) also accepts lengths beyond 64K, so one selector can cover all of a large block (eg, for code with 32-bit offsets); beyond 1Mb, the limit has 4K granularity, and the length is rounded down to a multiple of 4K, so the selector never reaches past it. CPU_SEGINFO then reports a limit of FFFFh (with ADDR_RIGHTS, AH has limit bits 19-16 and the granularity bit), as a 16-bit LSL reports only bits 15-0, and CPU_REALLOC refits the block’s selectors to 64K each.
  • Selector IDs: CPU_MAP with MEMF_LDT returns its selector’s ID in DX, in the same form as an owner ID (80h plus the LDT number, and the LDT index), which names the selector in any LDT, so that a driver can change what it maps later, from any session: CPU_MAP with MEMF_REMAP and BX = the ID gives it a new address and length (64K or less), or with a length of zero, makes it not present, and CPU_UNMAP with BX = the ID frees it. A program that loads a not-present selector (or that DOS resumes with one in DS or ES) waits, as if for DOS_UTL_WAIT with wait ID SELID_WAIT (FFFFh):ID, so the driver ends that wait with DOS_UTL_ENDWAIT (once for each waiting session, until it returns carry) when the selector is present again, and the program retries the instruction. A segment register that already holds the selector keeps what it had until it’s loaded again, so a driver changes a selector only while the sessions that use it aren’t running (eg, during another session’s DOS call); VKD$ uses these for video memory (see Video Memory).
  • Debuggers: CPU_SEGINFO, CPU_RWMEM, and CPU_SYSREGS never change CPU$’s state, so they work even when CPU$ itself was interrupted. An address is in real-mode form unless ADDR_SEL (01h) says its segment is a protected-mode selector (in either mode) or ADDR_PHYS (04h) says it’s a physical address (its “segment” holds bits 16-31), or in protected mode, ADDR_LDT (10h) says that its “segment” is an LDT number, and the segment is that LDT (so that DEBUG’s DL command can find any session’s, although the GDT describes only the active one), or ADDR_V86 (20h) says that it’s a real-mode address in the V86 machine whose memory’s first selector is in the active LDT (an error if there’s none), where the limit ends where the machine’s memory, or the ROMs, do (CPU_RWMEM also accepts an offset that reaches beyond its segment’s 64K, or wraps at 1Mb), or ADDR_LIN (40h) says that it’s a linear address (its “segment” holds bits 16-31, and SI holds the offset, for CPU_SEGINFO, too), which is a physical address unless paging is on, when CPU$ translates it through the current page directory (CR3), so the limit ends with its page, and a page that isn’t present is an error; with ADDR_SEL, CPU_SEGINFO returns a selector’s base as a linear address. CPU_SEGINFO returns a segment’s base address and limit, or with ADDR_RIGHTS (08h), its descriptor’s access rights and extended byte. CPU_RWMEM copies CX bytes from the address to ES:DI, or with ADDR_WRITE (02h), from ES:DI to the address, which must be within the segment’s limit; it can write to a code segment (eg, to store a breakpoint). CPU_SYSREGS stores the GDTR and IDTR (as SGDT and SIDT do), followed by the address that the handler of a hardware interrupt from a V86 machine returns to, and returns the MSW, LDTR, and TR; the 8086 driver returns ERR_INVALID, which tells a debugger that the processor has only one mode. A debugger that stops where an interrupt frame returns to that address has interrupted the handler itself, so the machine was running, and CPU_V86 with AL = 2 gets the machine’s registers, and AL = 3 changes them before the handler returns (see V86 Machines).
  • Faults: CPU_SETFAULT gives a fatal protected-mode exception to a handler (eg, the kernel’s, or a debugger’s), before CPU$ reports it and stops the machine. The handler is entered with the registers as they were, interrupts disabled, and SS:SP pointing to a far return address, the vector, the error code, and an interrupt frame for the faulting instruction. A handler that can’t handle the exception declines it by returning (RETF) with the registers and stack as they were. Before stopping the machine, CPU$ offers the halt to the handler, as the same exception with FAULT_HALTED (80h) in the vector’s high byte: a debugger can accept it by never returning, and any other handler declines it. See Faults.
  • Ring 3 support: CPU_SETSTACK sets the ring 0 stack that the processor switches to when an interrupt or exception takes ring 3 code to ring 0, and CPU_SETLDT makes one of its 32 LDTs the active one, so that the selectors that the other functions allocate, free, and resolve are in that LDT, which DOS assigns to one or more sessions (see Running Programs at Ring 3). In real mode, CPU_SETSTACK returns ERR_INVALID, and CPU_SETLDT does nothing.

CPU_GETINFO’s flags are CPUF_PM (01h), set when the processor is in protected mode, CPUF_PMOK (02h), set when the 80386 driver stayed (so CPU_PMODE is available), and CPUF_HWTYPE (C0h), the processor’s own type (CPU_HWTYPE), which AL (CPU_TYPE) understates in real mode.

DDINT_CPU is the entry point in either mode, since a far call through segment 50h has the same address in protected mode (see Mode-Independent Code), and it doesn’t use up an interrupt vector. In protected mode, segment 50h is a DPL 0 code segment, so only ring 0 code (the drivers, the kernel, and programs run with RING=0) can call CPU$; programs at ring 3 use DOS functions instead (eg, DOS_MEM_ALLOC, DOS_UTL_ALIAS, and DOS_UTL_MAPSEG).

Memory Map

Physical memory on a 2Mb PC AT:

Address Length PMB type Contents
000000h 1K USED Real-mode interrupt vector table
000400h 256 USED ROM BIOS data area (segment 40h)
000500h 1136 USED BASIC-DOS low memory (also segment 40h, from offset 100h): CPU_TYPE (512h), CPU_HWTYPE (513h), CPU_ARENA (514h), the diskette parameter table (522h), the DDINT entry points (530h, called through segment 50h, starting with DDINT_CPU at 0050:0030h), and two disk buffers
000970h   USED Drivers: CPU$ (first), NUL, VKD$, …, then BASDOS.COM and its tables
    FREE The rest of conventional memory, except for:
08E000h 8K SYS On an 80386, the page directory and a page table for every 4Mb (see Paging), in the same block as:
090000h 64K SYS CPU$ system area (see below)
0A0000h 384K RSVD Video memory, adapter ROMs, and the system ROM (not RAM)
100000h 1408K FREE Extended memory, if any
260000h     End of memory

On a COMPAQ 80386 machine (eg, a DeskPro 386), the part of its first 1Mb of RAM that isn’t conventional memory (eg, 384K) ends at 16Mb. The ROM BIOS keeps the last 128K (FE0000h), where it copies the ROMs, and describes the rest (COMPAQ Built-in Memory; eg, 256K at FA0000h) with a table in segment F000h, at the offset in F000:FFE0h: unless its first word is FFFFh, its third word is the number of free paragraphs, and its fourth is the paragraph (in F0000h) where they end. CPU$ adds that memory as one more FREE block (with an RSVD block for the addresses between it and extended memory), usable in protected mode like extended memory, and on an 80386, it then needs page tables for all 16Mb (16K more). It leaves the table alone, since nothing that reads it (eg, COMPAQ’s CEMM) runs on BASIC-DOS, and the ROM BIOS rebuilds it on every reset.

The PMB types (PMBTYPE_* in cpu.inc) are FREE (0), USED (1, allocated by CPU_ALLOC), SYS (2), and RSVD (3). The end of conventional memory comes from the BIOS, so a machine with less than 640K (or a MEMSIZE= line) has a larger RSVD block.

The System Area

CPU$ keeps its data in the last whole 64K of conventional memory (090000h-09FFFFh, with 640K), which is addressable in real mode with a segment (9000h, with 640K), and in protected mode with a selector for the same memory (see Paging), so the same offsets work in both modes:

Offset Contents
0000h Unused (except by the protected-mode test)
0020h CPU$’s variables
00E0h GDT: 256 descriptors (the fixed ones first)
08E0h The protected-mode IDT (256 gates; see Protected-Mode Interrupts)
10E0h TSS (104 bytes: 80386 format on an 80386, otherwise 80286 format), only for its ring 0 stack
114Eh PMB table (32 bytes per entry), growing up, and below A0DEh, LDTs, growing down (see Table Growth)
A0E0h GDT: identity selectors A000h-F800h, every 800h (see below), through offset F8E7h

A PSP’s CALL 5 uses PSP_FCSEG, which in protected mode is SEL_CALL5, a DPL 3 call gate to the far jump at 0:00C0h (a far call through a gate ignores its offset, so PSP_SIZE keeps the value that CP/M programs read as their memory size).

Paging

On an 80386 (unless CONFIG.SYS has CPU=80286), protected mode also turns on paging, and maps all of physical memory (the first 4Mb for every page table) at linear address C0000000h, which leaves the lower linear addresses free for other mappings (eg, for V86 machines). The page directory and the page tables are just below the system area, and every page is user-accessible, since segment limits are what protect memory.

Every selector’s base is C0000000h plus the physical address it maps, so selectors for any memory (eg, the identity selectors for video memory and the ROMs) work as before, and the CPU$ functions still take and return physical addresses: CPU_SEGINFO and CPU_ALIAS subtract C0000000h from a base, and DEBUG.COM at ring 3, which reads descriptors directly, uses only bits 0-23 of a base. CPU$ builds the tables during its initialization, and adds C0000000h to the bases of the descriptors that it made until then, after the protected-mode test (which doesn’t use paging); CPU_PMODE then turns on paging along with protected mode, while the low linear addresses still map physical memory, and as soon as every register uses the new mapping, removes the low mapping, so any code that uses a physical address as a linear address faults.

Table Growth

The PMB table and the LDTs share the 36,752 bytes between the TSS and the identity selectors. The PMB table starts at the bottom and is only as long as the blocks it describes, and the LDTs are packed down from the top, with LDT 0 first. Each LDT starts empty, and grows 32 descriptors at a time, up to 256 (all that fits in an owner ID). Moving an LDT doesn’t change any selectors, since they’re indexes. Allocating fails with ERR_NOMEMORY only when the PMB table and the LDTs would meet, or an LDT has all 256 descriptors. An LDT keeps its largest size until the system restarts.

So that long tables don’t delay interrupts, the CPU$ functions that walk or change them (CPU_GETINFO, CPU_ALLOC, CPU_FREE, CPU_MAP, CPU_QUERY, CPU_ALIAS, CPU_REALLOC, CPU_SETBLK, and CPU_FREEALL) run with interrupts on if the caller had them on, holding a session lock (through DDINT_UTIL), so no other session can call CPU$ until they’re done. Interrupts are off only while moving a piece of the PMB table (64 words at a time), while copying a piece of a block that CPU_REALLOC moves (1K at a time), and while moving the active LDT and reloading the LDTR, which is never more than 1K words. Interrupt handlers must not call those functions.

Fixed GDT Selectors

Selector Base Use
00h   Null selector
08h System area Data: the system area (so offsets match its real-mode segment)
10h   The active LDT
18h 000970h Code: CPU$
20h 000000h Data: the first 64K (interrupt vectors, BIOS data, BASIC-DOS low memory)
28h   Data: the caller’s stack, while switching modes
30h, 48h   Data: scratch
38h   Call gate (DPL 0) to CPU$’s functions (unused, since DDINT_CPU works in either mode)
40h 000400h Data: the BIOS segment (40h), so code that uses segment 40h works in either mode
50h 000500h Code: the DDINT segment (50h), so the DDINT entry points have the same addresses in either mode
58h 000000h Code: just the CALL 5 jump at 0:00C0h
60h   SEL_CALL5: call gate (DPL 3) for a PSP’s CALL 5
68h System area + 10E0h The TSS
A000h-B800h A0000h-B8000h Data: identity selectors for video memory, every 800h, for the BIOS and the drivers (a ring 3 program gets its own selector from VKD$; see Video Memory)
C000h-F800h C0000h-F8000h Code: identity selectors for the adapter and system ROMs, every 800h, so the ROM BIOS can run at ring 0 with its own segments (eg, F000h)

Selectors 70h-7F8h (GDT) and 04h-7FCh (the active LDT) are allocated by CPU_ALLOC, CPU_MAP, and CPU_ALIAS. All descriptors are 80286-format (the 80386 fields are zero, except bits 31-24 of the base, for blocks above 16Mb or with paging, and on an 80386, the limit bits that CPU_SETLIM sets) and DPL 0 (unless MEMF_USER is set). The GDT’s limit extends through the identity selectors, so the processor can also read the rest of the system area as descriptors, through selectors 0800h to 9FF8h. So the PMB table and LDTs start at an offset of 6 mod 8, which puts each of those selectors’ access bytes on a byte that never has its present bit set (bits 31-24 of a descriptor’s base, or in a PMB, the top of PMB_ADDR, the high byte of PMB_NSEL, a reserved byte, or the last byte of PMB_NAME, whose bit 7 CPU_SETBLK clears). That way, loading one of those selectors (eg, a real-mode segment by mistake) always faults, and a ring 3 program can’t reach another LDT’s descriptors through the GDT.

Physical Memory Arena

The 80386 driver’s arena is a table of Physical Memory Blocks (PMBs) in address order, covering all memory from 0 to the end of extended memory, with the last PMB marked PMBSIG_LAST (‘Z’), like the last MCB:

Field Size Contents
PMB_SIG byte ‘M’, or ‘Z’ for the last PMB
PMB_TYPE byte PMBTYPE_*
PMB_OWNER word Owner ID (see Owner IDs), or zero
PMB_ADDR dword Physical address
PMB_LEN dword Length, in bytes
PMB_SEL word First selector (if any)
PMB_NSEL word Number of selectors
PMB_MCBTYPE byte Block type (MCBTYPE_*, as in an MCB), or zero
(reserved) byte  
PMB_CODE word The block’s code alias (see Code Aliases), or zero
PMB_V86 word A V86 machine’s page number, or zero
PMB_SHARE word The block whose memory its code alias maps (see MEMF_SHARE), or zero
PMB_NAME 8 bytes Name of the process (as in an MCB), or zero

Unlike MCBs, PMBs aren’t stored in front of the memory they describe:

  • the arena has to describe memory that isn’t RAM (eg, 640K-1Mb), where no header could be stored;
  • headers in extended memory couldn’t be read or written in real mode;
  • blocks need no header, so they stay aligned, and a block can be mapped by a selector with no offset; and
  • a program that writes past the end of its block can’t damage the arena.

The cost is the room that the table takes in the system area (see Table Growth). The 8086 driver’s arena is the MCB chain itself: programs on an 8086 expect to see MCBs, and conventional memory is all there is. With the 8086 driver, CPU_QUERY describes each MCB with a PMB (whose PMB_SEL is the block’s segment).

For debuggers that can’t call CPU$ (eg, the PCjs Debugger, whose d dos command lists the arena the way DEBUG’s DM does), whichever driver stays stores the real-mode address of its arena in CPU_ARENA (0:514h): the 8086 driver’s first MCB, or the 80386 driver’s PMB table (in the system area, at offset 114Eh); a nonzero offset means it’s the table, since an MCB’s offset is always zero.

Memory and DOS

From the moment CPU$ initializes, everything that runs during the boot (devinit, each driver, and sysinit) claims the memory it uses from CPU$, and moves memory only with CPU_MOVE, so neither devinit nor sysinit computes a segment from an address. After the boot, DOS’s memory functions are calls to CPU$: DOS_MEM_ALLOC calls CPU_ALLOC (so in protected mode, a block can be anywhere in conventional or extended memory) and CPU_SETBLK, DOS_MEM_FREE calls CPU_FREE, DOS_MEM_REALLOC calls CPU_REALLOC, a program’s blocks are freed with CPU_FREEALL when it ends, and DOS_UTL_QRYMEM (for MEM) uses CPU_QUERY. There’s no MCB chain for programs to walk, other than the 8086 driver’s, and MEM’s total memory (SI_MEMSIZE in SYSINFO) includes extended memory.

Switching Modes

To test protected mode, CPU$ switches to it and back. An 80386 returns to real mode by clearing PE. An 80286 can’t, so before switching, CPU$ sets the CMOS shutdown code to 0Ah and stores its return address in 40:67h, and to return, it resets the processor through the 8042, as the BIOS’s own block move (INT 15h function 87h) does; the BIOS sees the shutdown code and jumps through 40:67h without initializing anything else. Because the shutdown code is set before switching, a “triple fault” (which resets the processor) also returns to CPU$, and until the test passes, every gate in the IDT returns to real mode (without a reset, on an 80386), so a bug in protected mode makes the test fail instead of hanging the machine. The test writes and reads back a word at the start of the system area, through its selector; CPU$ stays loaded only if that works; otherwise, it turns A20 back off, and the 8086 driver stays instead.

CPU_PMODE switches to protected mode the same way, but for good: it never returns to real mode.

Protected-Mode Initialization

On an 80286 or later, when the 80386 CPU$ stays loaded, BASIC-DOS switches to protected mode during devinit, right after CPU$ initializes, and never switches back:

  1. CPU$ initializes in real mode, as the first driver, and devinit loads BASDOS.COM (the kernel) while it can still use the boot code. It also moves itself up, since FDC$’s buffer is larger in protected mode (up to 9K), and the drivers after FDC$ will move up to make room.
  2. devinit calls CPU_PMODE, which turns its segment registers into selectors for the same memory, points DDINT_CPU, DDINT_GETVEC, and DDINT_SETVEC at CPU$’s protected-mode code, moves the master PIC’s interrupts to 78h-7Fh, and loads the protected-mode IDT and the TSS.
  3. Each driver gets a code selector and a data selector (CPU_MAP and CPU_ALIAS) before its initialization: devinit stores the data selector in DDH_DATA, calls the driver through its code selector, and links it into the chain with its code selector. When the driver’s initialization returns, devinit fits both selectors to what the driver keeps (CPU_SETLIM). Drivers install their interrupt handlers in the IDT with DDINT_SETVEC.
  4. devinit moves the kernel after the drivers, with a code selector and a data selector for it, and starts the kernel’s initialization (sysinit).
  5. sysinit runs in protected mode: it points the DOS vectors at the kernel’s code selector, gives CPU$ the kernel’s fault handler (CPU_SETFAULT), builds its tables, gets a selector for each disk buffer, loads any DEVICE= drivers (calling each one through a code alias of its block), and loads the SHELLs.
  6. The first session starts, at ring 3 unless CONFIG.SYS has RING=0, with CS set to the code alias of its program’s block (see Code Aliases).

The kernel’s protected-mode-only code (its fault handler, NE loader, and ring 3 support) comes after the rest of its resident code, so in real mode, it costs no memory.

Protected-Mode Interrupts

After CPU_PMODE, every interrupt goes through CPU$’s IDT, and the master PIC is moved from 08h to 78h, next to the slave PIC (70h-77h), so that IRQs 0-7 no longer share vectors with processor exceptions. Its default gates “reflect” each interrupt to the handler in the real-mode vector table, if that’s in the ROM (whose segments are identity selectors, eg, F000h), at ring 0, on the interrupted code’s stack (or for an interrupt from ring 3, its ring 0 stack), so a BIOS call never costs a mode switch:

IDT entries DPL Default handling
00h 3 Divide errors (DPL 3, since ring 3 code may issue INT 0, as FPU$ does)
01h-02h, 05h-0Fh 0 Exceptions: fatal, except the cases below
03h-04h, 10h-6Fh, 80h-FFh 3 Software interrupts: the vector’s handler, if it’s in the ROM; otherwise fatal
70h-77h 0 IRQs 8-15: vectors 70h-77h’s handlers, if in the ROM; otherwise an EOI
78h-7Fh 0 IRQs 0-7: vectors 08h-0Fh’s handlers, if in the ROM; otherwise an EOI

Ring 3 code can issue software interrupts (eg, INT 21h, or INT 10h, which is reflected to the ROM at ring 0), but an INT at ring 3 for any other exception or an IRQ is a general protection fault.

  • Drivers’ handlers: in protected mode, DDINT_GETVEC and DDINT_SETVEC read and write the IDT: setting a vector replaces its gate’s selector and offset (for vectors 08h-0Fh, the gates for IRQs 0-7), keeping the gate’s DPL, so the driver’s handler is called directly, and getting a vector returns its gate, or if the gate is a default one, its real-mode vector if that’s in the ROM (eg, F000:FEA5h for INT 08h, which CLOCK$ chains to), or 0:0 if not.
  • INT 13h: the BIOS’s disk functions assume that ES:BX is a real-mode address, so FDC$, which makes every disk transfer, gives the BIOS an address that works in both modes: for the diskette BIOS, which turns ES:BX into a DMA address, an offset from segment 40h (or, for a buffer more than 64K above it, a buffer of its own, large enough for a track of the largest diskette drive, so that reading a track still takes one BIOS call), and for the fixed disk BIOS, a selector of the buffer’s own, with a zero offset.
  • Vectors 05h and 08h-0Fh are also software interrupts sometimes (INT 05h is the BIOS’s print screen, which its keyboard handler issues, and eg, the AT BIOS’s IRQ 9 handler does INT 0Ah), so an exception at ring 0 whose return address follows an INT for its vector is treated as one. Ring 3 code can’t issue those INTs, so at ring 3, vector 05h is always a BOUND fault.
  • Null selectors in the ROM: the BIOS loads DS with 0 to address the vectors (eg, LDS SI,[78h] with DS = 0), so a general protection fault with a zero error code, in the ROM, while DS or ES holds a null selector, is retried with a selector for the first 64K. BASIC-DOS’s own code gets no such fix.

Faults

Any other exception (including a software interrupt with no handler that CPU$ can call; an INT 3 goes to its handler, so a failed DEBUG assertion is handled as in real mode, see Interrupt Vectors) goes to the fault handler (see CPU_SETFAULT), which is the kernel’s unless a debugger has replaced it:

  • In the current program’s own code (or any block that the program owns, such as one of COMMAND’s BASIC code blocks), DOS displays CPU fault vv (EC=xxxx) at cccc:iiii and ends the program with exit code 255 and EXTYPE_FAULT, as it does for a divide error, and the system continues.
  • A not-present LDT selector (#NP), which a driver took away (see Selector IDs), isn’t fatal: in a program, or in the kernel resuming one, the session waits for the selector, as if the faulting instruction were a DOS call, and then the instruction runs again. In a hardware interrupt, or while the session is locked, it’s treated like any other fault.
  • In the kernel, working for a ring 3 program: a protection fault (#TS, #NP, #SS, or #GP) in the kernel, usually from a bad pointer that a program gave it, ends that program the same way, since the kernel can abandon what it was doing: it resets its session lock and INDOS count, returns to the top of the program’s ring 0 stack, and ends the program as if the program had asked to end. A fault in a hardware interrupt isn’t working for a program, and a fault while already ending one could repeat forever, so both are fatal.
  • Anywhere else (eg, in a driver or the ROM, or in the kernel with RING=0), the exception is fatal: CPU$ prints the same CPU fault line, followed by System halted, offers the halt to the fault handler, and unless a debugger takes it, stops the machine.
  • With DEBUG.COM loaded as a driver, DEBUG.COM passes each exception on to the kernel unless its VT command traps the vector, and stops for any that the kernel declines, so that G can retry it (eg, after a fix); it then accepts CPU$’s halt, so that it never gives up control (see Exceptions and Faults).

The processor’s exceptions differ in where the saved CS:IP points: a fault (eg, #BR, #UD, #NP, #SS, #GP, #PF, and on an 80286 or later, a divide error) is reported before its instruction completes, with CS:IP at that instruction, so that it can run again once the cause is fixed; a trap (eg, #BP, #OF, a single-step, or any INT n) is reported after its instruction, with CS:IP at the next one; and an abort (a double fault, or a coprocessor overrun) leaves no reliable place to resume. Despite its name, CPU fault reports any exception that CPU$ can’t give to a handler, not just faults: an NMI or an abort, too, and a software interrupt with no handler that CPU$ can call, whose CS:IP is the INT and whose EC is the caller’s AX (eg, its function number). Only after a fault does a retry (eg, DEBUG.COM’s G after a fix) run the instruction that failed.

Mode-Independent Code

The drivers and the kernel (everything that runs at ring 0) are the same code in either mode, so they follow these rules:

  1. Low memory through segment 40h: the ROM BIOS data area and BASIC-DOS’s low memory (CPU_TYPE, the DDINT entry points, and the diskette parameter table) are addressed through segment 40h, which in protected mode is a selector with the same base.
  2. Interrupt vectors through DDINT_GETVEC and DDINT_SETVEC, which pass vectors in DX:CX rather than in segment registers (see Device Drivers), since segment 0 is the null selector in protected mode. Only the boot code and devinit, which run first, use segment 0.
  3. DDINT entry points through segment 50h (eg, DDINT_SETVEC is 0050:003Ah), which in protected mode is a code selector with the same base, so the addresses are the same in either mode.
  4. No writes through CS: a protected-mode code segment can’t be written, so code that writes to its own memory uses DS, ES, or SS holding its own data segment (or selector); a driver gets its own from DDH_DATA (see Device Drivers), whose code selector (CS) and data selector are separate selectors for the same memory in protected mode.
  5. No unnecessary null selectors: segment registers are never loaded with 0 just to have a value, and an empty chain’s far pointer (eg, CLOCK$’s list of waiting packets) has an offset of FFFFh and a segment of 0, rather than -1:-1, so that loading the whole pointer before checking the offset is safe.
  6. A new program’s FLAGS are 0202h, not F202h (as an 8086 pushes FLAGS), so that an IRET in protected mode doesn’t set IOPL 3 and NT (and the next IRET with NT set doesn’t switch tasks), which also gives every program IOPL 0, so ring 3 code can’t use IN, OUT, CLI, or STI.

COMMAND.COM

COMMAND.COM runs at ring 3, so it uses only selectors that the kernel gives it, and asks the kernel or a driver for anything it can’t reach itself:

  • Video memory comes from VKD$ (IOCTL_GETMODE with CL = 1 returns the context’s video memory in DX, which in protected mode is an LDT selector of the context’s own; see Video Memory).
  • The tick count (for RANDOMIZE, SOUND, and PLAY) comes from DOS_UTL_GETTIME with AL = 1, MEM’s totals from DOS_UTL_QRYSCB with CL = -1 (see SYSINFO), and START’s session list from DOS_UTL_QRYSCB.
  • Sounds start and stop through CLOCK$ (DOS_UTL_SOUND), rather than with IN and OUT.
  • BASIC code runs from code blocks through their code aliases (see Code Aliases), and DEF SEG gets a selector from the kernel (see DEF SEG).
  • Blocks (for code, text, variables, and strings) come from DOS_MEM_ALLOC with MCBTYPE_HIGH, so in protected mode, they come from the top of memory.

Code Aliases

A protected-mode segment is either code (executable, and at most readable) or data (readable, and perhaps writable), so memory that’s both written and executed needs two selectors. CPU_ALIAS creates the second one: given a selector, it returns a new selector for the same base and limit, with the access rights selected by MEMF_CODE, MEMF_RDONLY, and MEMF_USER, and CPU_UNMAP frees it.

A block’s own code alias (CPU_ALIAS with just MEMF_CODE, for the selector that CPU_ALLOC returned for the block) is created only once, with the block’s DPL, and is freed with the block, so nothing else has to keep track of it (and it must never be freed with CPU_UNMAP). Programs get it from DOS_UTL_ALIAS (27h; see Utility Functions), since ring 3 code can’t call CPU$, and with AL = 1, the same function does the reverse, returning the block’s own selector for its code alias, since a code selector isn’t writable (eg, so that a debugger can store a breakpoint in a program’s code); in real mode, a block’s code alias is its segment.

With MEMF_SHARE as well, and a second block’s own selector in DX, the block’s code alias maps the second block’s memory instead of its own, which PMB_SHARE records; the alias is still freed with the block, and when the last block that shares the second block is freed, CPU$ frees the second block, too. That’s how ring 3 programs share code (see Loading Programs), since the alias can execute and read the code, but not write it.

COMMAND.COM compiles BASIC into code blocks that it allocates as data, and runs them (and transfers from one to another) through their code aliases. Generated code that writes to its own block (eg, a double’s result) gets the block’s data selector from the block itself, rather than from CS.

Loading Programs

In protected mode, the DOS_PSP_EXEC functions run COM and NE programs, and on an 80386, LE programs, but not “MZ” EXE files:

  • COM programs: a COM program’s code and data are in one block (its PSP block). CS comes from the block’s code alias, and DS, ES, and SS come from the block’s data selector. A program that sets a vector with DS:DX, as COM programs often do, would give it a data selector, so when DS is the program’s PSP block, DOS_MSC_SETVEC uses the block’s code alias instead, which in real mode is the same segment.
  • Shared code: a COM program with shared code (see COMDATA) normally runs the code in the first copy’s block, which also holds that copy’s data. Ring 3 programs can’t, since each session has an LDT of its own, and a program’s memory is its own, so the loader copies the first copy’s image to a code block: a block that owns itself (so no program’s exit frees it), named for the program, at the top of memory, whose own selector is for the kernel alone. Every copy, including the first, gets a code alias of it in its own LDT (CPU_ALIAS with MEMF_SHARE), which becomes its CS, and keeps only its data and heap; no copy can write the code, and CPU$ frees the code block with the last copy. A program loaded with DOS_PSP_EXEC1 keeps its own code instead (eg, a program that DEBUG.COM loads, whose breakpoints are written in its code), and so does any program when there’s no memory for a code block.
  • MZ EXE files: an EXE file’s relocations are paragraph arithmetic, which doesn’t work with selectors, so in protected mode, the DOS_PSP_EXEC functions refuse a file with no NE or LE header with ERR_BADMODE (any other file they can’t load is ERR_BADFORMAT), which COMMAND reports as “Unable to load X”, followed on an 80386 by “Run START V86 first”, since a V86 machine can run it.
  • NE programs: an NE (“new executable”) file lists each segment’s type and size, and its relocations refer to segments by number, so each segment gets a block of its own, owned by the program’s PSP, and a selector whose limit fits the segment exactly (for a code segment, the block’s code alias). The program must be marked PROTMODE (or be an OS/2 program; see below), with FIXED segments; it starts with DS and ES addressing its PSP, as an MZ program does. In real mode, an NE file runs its MS-DOS stub, like any MZ EXE file.
  • NE libraries: an NE program’s relocations can also refer to functions in libraries, each by a module name and an ordinal. A module named X is the file X.DLL in the EXT\DLL directory of the system drive (the drive that DOS_MSC_GETPCH returns), or in the directory that a LIBPATH line in CONFIG.SYS names: an NE file marked as a library and PROTMODE, with FIXED segments, whose entry table lists the function as an exported entry. The loader gives the program its own copy of each library’s segments, in blocks that the program’s PSP owns, loads each library once per program (however many modules refer to it, and libraries can refer to each other), and stores each function’s address (a code alias and an offset) wherever the program refers to it. A library’s entry point isn’t called, references by name aren’t supported, and a missing or unsuitable library fails the load with ERR_NOMEMORY. DOSCALLS.DLL is the first library: it provides OS/2’s DOSCALLS functions, at OS/2’s ordinals, as far calls (in the Pascal convention) that it turns into DOS calls, and it has the functions that LINK386 and CL386 (the linker and C compiler for 32-bit programs, which are OS/2 1.x programs) import, and the three that search directories; TESTS\REGRESS\DLLTESTS.EXE calls 24 of them (those in the table without a note that they’re for LINK386 1.01 or CL386, except DosExecPgm):
Ordinal Function Notes
5 DosExit DOS_PSP_RETURN
14 DosSetSigHandler CTRL-C signals only: end the program (the default), ignore the signal, or call a handler
33 DosGetDateTime (CL386) DOS_MSC_GETTIME and DOS_MSC_GETDATE; there’s no time zone
34, 38, 39 DosAllocSeg, DosReallocSeg, DosFreeSeg DOS_MEM_ALLOC, DOS_MEM_REALLOC, and DOS_MEM_FREE; a selector that isn’t a writable segment is refused
43 DosCreateCSAlias (CL386) Always fails: a code alias is the kernel’s to make
49 DosGetMachineMode Always 1 (OS/2’s value for protected mode), so that a program uses these functions instead of DOS calls and real-mode habits (eg, LINK386 otherwise frees segments it never allocated when it ends early, which faults)
52 DosDevConfig (CL386) Every item is 0 (eg, no math coprocessor, so a program leaves floating point to the system)
53 DosDevIOCtl Always fails: OS/2’s device control functions aren’t supported
58, 59, 60 DosChgFilePtr, DosClose, DosDelete DOS_HDL_SEEK, DOS_HDL_CLOSE, and DOS_DSK_DELETE
61 DosDupHandle (CL386) Always fails: BASIC-DOS doesn’t duplicate handles
63, 64, 65 DosFindClose, DosFindFirst, DosFindNext DOS_DSK_FFIRST and DOS_DSK_FNEXT, with a find block for each directory handle, so a program can have several searches: the system’s handle (1), or a new one (the selector of a small segment, which DosFindClose frees); each call finds one file, whatever number is asked for, a file’s allocated size is its size, and when there are no files (or no more), the error is OS/2’s ERROR_NO_MORE_FILES (18)
68 DosNewSize A zero-length write at the new size; the file’s position doesn’t change
70 DosOpen Opens, creates, or replaces a file, as the open flags say; only the open mode’s access bits are used, and opening a drive is refused
71 DosQCurDir (LINK386 1.01) DOS_DSK_GETCWD: a drive’s current directory, with no drive or leading backslash
72, 75, 77 DosQCurDisk, DosQFileMode, DosQHandType The current drive and a bit for each drive, a file’s attributes, and whether a handle is a file or a device
74, 83 DosQFileInfo, DosSetFileInfo (CL386) A handle’s date and time of last write (DOS_HDL_GETTIME and DOS_HDL_SETTIME) and, for DosQFileInfo, its size
81 DosSelectDisk (LINK386 1.01) DOS_DSK_SETDRV
85 DosSetMaxFH Succeeds for up to 20 handles (a PSP’s), which can’t be increased
89 DosSetVec Gets and sets an exception’s interrupt vector
91 DosGetEnv (LINK386 1.01) The environment’s selector and the command line’s offset that the program started with
92, 94 DosGetVersion, DosGetPid The DOS version, and the program’s PSP as its process ID
120 DosError (CL386) Does nothing
136 DosHugeIncr (LINK386 1.01) Not a function: an entry whose offset (8) is the difference between the selectors of a huge object’s segments, which there are none of
137, 138 DosRead, DosWrite DOS_HDL_READ and DOS_HDL_WRITE
144 DosExecPgm Runs a program and waits for it (DOS_PSP_EXEC), with a copy of the environment it’s given (CL386 passes each pass its options there), or the caller’s if there’s none

A function returns 0 or a DOS error code (which OS/2’s error codes extend), and preserves every other register. os2.inc has OS/2’s values and structures for these functions, and PCALL, a macro that calls one: it pushes the parameters in the order they’re documented, and for ADDR,name, a far pointer to that variable in the program’s automatic data segment (eg, PCALL DOSWRITE,bx,<ds,dx>,cx,ADDR,written). KBDCALLS.DLL, MSG.DLL, and NLS.DLL each have the one function that LINK386 imports from those modules: KbdFlushBuffer (13) discards type-ahead, DosTrueGetMessage (2) never finds a message (BASIC-DOS has no message files), and DosGetDBCSEv (4) reports no double-byte character ranges.

  • OS/2 programs: an NE file whose header says it’s for OS/2 (NE_OS is NEOS_OS2) needn’t be marked PROTMODE, and it starts as OS/2 would start it, not with DS and ES addressing its PSP. So does a file that isn’t marked PROTMODE and whose header names no operating system (NE_OS is 0), which is what every OS/2 1.0 program is, and what LINK4 makes of a module definitions file without PROTMODE. In an OS/2 program, the header’s self-loading flag means that the program is “bound” (its stub runs it on DOS, too), so it’s ignored, and relocation records that are operating system fixups (which mark floating-point instructions) are skipped. The loader makes the entry point of the program’s copy of DOSCALLS.DLL (which it must import from) the starting address, with the program’s own starting address on its stack; that code, running as part of the program, allocates a new environment block, copies the PSP’s environment strings to it, and adds the command line after them (two strings: the program’s name, which is always “C”, and the command tail), and then starts the program with DS and ES = its automatic data segment (which holds its stack), AX = the new block’s selector, BX = the command line’s offset there, and CX = the data segment’s size. LINK386, the linker for LE programs, is such a program, and runs unmodified (in real mode, an OS/2 program’s file runs its MS-DOS stub, and LINK386’s can’t find its own file on BASIC-DOS). CL386 and its passes are, too (C1_386 and CL386 with their one import by name changed to an ordinal). SRC\SDK’s FIND16 is another, built on BASIC-DOS: a version of FIND.COM that calls only DOSCALLS functions, so the same file runs on OS/2 1.x.

  • LE programs: on an 80386 with the 80386’s features (CPU_TYPE 3), with programs at ring 3, an LE (“linear executable”) file, which is 32-bit code and data for a flat address space, runs in a flat machine; otherwise, the DOS_PSP_EXEC functions refuse it with ERR_NOMEMORY, like an MZ EXE file (and in real mode, it runs its MS-DOS stub).

TESTS\MISC\PRIMES.EXE is an NE program, linked by LINK4 (see tests/misc/PRIMES.DEF and the build tools), with the real-mode program as its MS-DOS stub, so it runs in either mode. LINK4 makes a segment code only if its class is CODE, and requires a DGROUP.

DEF SEG, PEEK, and POKE

DEF SEG accepts any segment, which in protected mode isn’t a selector, so COMMAND.COM gets a selector for the segment’s 64K from the kernel (DOS_UTL_MAPSEG; see Utility Functions), which each session keeps one of. The selector is writable for video memory (A000h through BFFFh), and read-only everywhere else, including low memory and the ROMs, so PEEK works, but POKE is an “Illegal function call”. DEF SEG with no segment (BASIC’s own data) is readable and writable, as before. In real mode, none of these restrictions apply.

Video Memory

In protected mode, the identity selectors for video memory are DPL 0, for the BIOS and the drivers, so a ring 3 program that draws directly (eg, COMMAND.COM’s graphics statements) gets a selector from the console’s driver instead: IOCTL_GETMODE with CL = 1 returns VKD$’s LDT selector for the context, which maps the adapter’s video memory (16K for a CGA, or 4K for an MDA), starting at the context’s own page in a text mode, so that offset 0 is the context’s page, as it would be on page 0 (a context on a virtual page gets the adapter’s first page instead). VKD$ creates it with CPU_MAP the first time a program asks, in the LDT of the sessions on that console, and frees it when the context closes, and in between, it decides what the selector maps (see Selector IDs):

  • While another context on the same adapter is in a mode other than its original one (eg, after SCREEN 1), the context is blocked, and its selector maps the copy of the adapter’s video memory that VKD$ made (see VKD$), so a program that uses it keeps running, as the context’s output does; if there’s no copy (eg, there wasn’t enough memory for one), the selector is not present, so a program that loads the selector waits until the other context returns to its original mode, as the context’s output does.
  • Otherwise, the selector maps the adapter’s video memory, where the context has a region (or a page) of its own, so it stays present when the context loses focus.

The copy starts on a page boundary, so a V86 machine’s pages can follow the selector there, too. In real mode, IOCTL_GETMODE returns the video memory’s segment, and so it does in a V86 machine that V86.COM created with its console’s selector, where the machine’s pages follow the selector. DEF SEG’s selectors (DOS_UTL_MAPSEG) don’t go through the driver, so POKE can still change any console’s video memory.

Running Programs at Ring 3

In protected mode, unless CONFIG.SYS has RING=0 (see CONFIG.SYS), every session’s first program (eg, COMMAND.COM) and every program that the DOS_PSP_EXEC functions start runs at ring 3, with CPU$, the drivers, and the kernel at ring 0, so that a program can use only the memory it’s given, and can’t use privileged instructions.

  • Selectors: the blocks that DOS_MEM_ALLOC allocates for a ring 3 program (including the blocks that a program is loaded into) have DPL 3 selectors (MEMF_USER) in its session’s LDT (MEMF_LDT), and a program’s CS has RPL 3, which is how DOS knows to start it at ring 3.
  • LDTs: each session that sysinit loads (eg, each SHELL), or that a program loads with DOS_UTL_LOAD’s AL = 1 (eg, START), has an LDT of its own, whose number is the session’s number, and any other session that a program loads (eg, the next program of a pipeline) shares that program’s LDT, so the sessions on a console share one, and a program can’t name the memory of a session with another LDT; the kernel makes a session’s LDT the active one (CPU_SETLDT) whenever it switches sessions. Selectors repeat from one LDT to the next, so a ring 3 program’s PSP doesn’t identify it on its own, and CPU$ stores the owner of each of its blocks as an owner ID that includes the LDT number, which is what CPU_FREEALL frees by. A program can also reach the memory of the other sessions that share its LDT.
  • Ring 0 stacks: the TSS is used only for its ring 0 stack (CPU_SETSTACK), which the processor switches to when an interrupt takes ring 3 code to ring 0. A program’s ring 0 stack is its parent’s stack, where the parent waits for it to end, so nested programs need no stacks of their own; a session’s first program, which has no parent, uses a 1K ring 0 stack that the kernel allocates for each session.
  • DOS calls: a DOS call’s parameters on the caller’s stack (eg, for DOS_UTL_PRINTF and DOS_UTL_SPRINTF) are read through a ring 0 alias of the caller’s stack, and a CALL 5 works at ring 3, too, since SEL_CALL5 is a DPL 3 gate.
  • Memory blocks: a ring 3 program can free or resize only a block that it owns, so any other selector with the same base address (eg, a DOS_UTL_MAPSEG selector for low memory) gets ERR_BADADDR, and it can’t free its PSP’s block, or shrink it below the PSP, since the kernel needs the PSP until the program ends. If it frees or shrinks the memory that it’s running in, it ends with a CPU fault, as it would have at its next instruction. A DS or ES selector that’s gone becomes 0.
  • The kernel’s checks: a fault in the kernel stops the system, so before the kernel uses a ring 3 program’s stack, or returns to an address that the program supplied, it checks that it won’t fault (with VERW, LSL, and LAR). If it would, the program ends with a CPU fault (a handler that can’t be entered gets the default CTRL-C or ABORT response, and an interrupt that can’t be reflected goes to the previous handler). INT 22h’s gate must be DPL 3, for the ring 3 stub described below, so issuing it for any other reason ends the program, too, with the error code of a fault on that gate. Disk and device transfers are checked first, too (DOS_HDL_READ, DOS_HDL_WRITE, and the FCB functions), since a transfer’s physical address ignores the buffer selector’s limit, and a fault in a driver is fatal, and so is the data for each IOCTL that uses DS:SI (the program ends with a CPU fault if it isn’t all in the program’s memory). Any other bad pointer faults in the kernel, which ends the program (see Faults).
  • The PSP: a program can write its own PSP, and its parent’s, so the kernel keeps what it depends on where a program can’t reach it: a record at the top of each program’s ring 0 stack holds its parent’s PSP, ring 0 stack, CTRL-C and critical error handlers, and DTA, and SCB_SP0 points to the record. When a program ends, the kernel rewrites PSP_PARENT, PSP_SCB, PSP_CTRLC, PSP_ERROR, and PSP_DTAPREV in its PSP, and PSP_STACK and PSP_SCB in its parent’s, from what it knows, and it returns to PSP_EXIT only if that’s a usable ring 3 address. A handler that isn’t at ring 3 is always the kernel’s default. DOS_PSP_SET accepts only a PSP in the same LDT, and DOS_PSP_COPY and DOS_PSP_CREATE only a block that the program owns.
  • Selectors in memory: the processor checks a selector that a program loads into a segment register, but not one that it leaves in memory or a general register, which the kernel could then load at ring 0. So each far pointer in an EPB, or an SPB’s command line, gets RPL 3 before the kernel uses it, which makes the processor fault on a ring 0 selector, as it would at ring 3.
  • CTRL-C and critical error handlers (INT 23h and INT 24h) run at ring 3, on the stack of the program that called DOS, and return to the kernel through a ring 3 stub. A critical error handler gets a copy of the device header (since it can’t read the driver’s memory), and a CTRL-C handler can continue the DOS call (with any registers it changed) or end the program, as at ring 0; either way, the kernel makes sure the program stays at ring 3, with IOPL 0.
  • BIOS and other interrupts: ring 3 code can issue only INT 00h, 03h, 04h, DOS’s vectors (INT 20h-2Fh), INT 33h (the mouse), and INT 60h-67h; any other INT ends the program with a CPU fault. A BIOS function would run at ring 0, trusting what it was given (eg, disk functions compute a DMA address from a segment value), and a fault in the ROM stops the system. Programs use DOS and the drivers’ IOCTLs instead, and programs that need the BIOS (eg, DISKREAD and DISKWRIT in TOOLS) need RING=0.
  • Functions for drivers and the kernel: DOS_UTL_HPRINTF, DOS_UTL_WAIT, DOS_UTL_ENDWAIT, DOS_UTL_HOTKEY, DOS_UTL_LOCK, and DOS_UTL_UNLOCK return ERR_ACCDENIED to a ring 3 caller, since a lock stops every other session, and the others can affect other sessions.
  • Selectors for blocks: DOS_UTL_ALIAS returns a code alias only for the selector of a block that the program owns (otherwise, ERR_BADADDR), since those are the aliases that the kernel frees, and a program could otherwise use up the GDT.
  • File handles: a program can write anything in its PSP_PFT, so the kernel keeps a table that only it can reach, of which sessions opened each open SFB. A handle’s SFB must be one that its session opened, or one of the session’s standard SFBs, or the DOS function returns ERR_BADHANDLE; any other entry is removed from PSP_PFT before the kernel copies or closes them, and an SPB’s SFHs are checked the same way.
  • Chains of programs: a program’s ring 0 stack is its parent’s, so DOS_PSP_EXEC returns ERR_NOMEMORY when less than 512 bytes of the session’s 1K ring 0 stack would remain, which is about 8 programs.
  • Interrupt vectors: a ring 3 program can hook only the vectors on a short list: the exceptions that a program can handle (INT 00h, 01h, 03h, and 04h), DOS (INT 21h), and the vectors free for programs to use (INT 60h-67h). Any other DOS_MSC_SETVEC returns ERR_ACCDENIED, and any other DOS_MSC_GETVEC returns 0:0, so a program can’t take over an IRQ, whose handler would stop that interrupt for every session if it didn’t chain. The IDT is shared by every session and by ring 0 code, so a ring 3 program’s handler can’t go in a gate. Instead, when a ring 3 program sets a vector (other than INT 22h-24h, which each session has its own of), the kernel puts a gate of its own there, which reflects the interrupts that ring 3 code in the program’s session issues to the program’s handler, at ring 3, and passes all others to the previous handler. A ring 3 program that gets a vector (eg, to chain to it) gets the address of a ring 3 stub that passes the interrupt to the previous handler. The kernel removes the program’s handlers when it ends. So, for example, an INT 21h hook sees the DOS calls of the programs it runs, but not the kernel’s own. A single-step trap goes to the previous handler, too, while a debugger steps the session (SCSTAT_STEP in its SCB, which the DEBUG.COM driver sets whenever it resumes with TF set), so a ring 3 program’s INT 01h handler (eg, DEBUG’s, run as a program) doesn’t take the driver’s steps; the driver’s breakpoints in ring 3 code are HLT instructions, whose faults reach it before any ring 3 INT 03h handler could.
  • FPU$: its functions are mapped with conforming code selectors, so the kernel and programs at ring 3 call them through the same FPUTBL, and they run at the caller’s ring (see Floating-Point Interface).
  • DEBUG.COM as a driver (at ring 0) can stop and resume ring 3 programs with every command. As a program at ring 3, it can’t call CPU$, so it uses DOS functions and the 80286’s unprivileged instructions instead (see Installable Drivers), and it can write only the memory that ring 3 can (eg, the program’s own, not DOS’s, the drivers’, or the BIOS data area), although it can read memory below 1Mb, by finding a selector’s base in the GDT (see DOS_UTL_MAPSEG); it has no LN command, no &, #, or % addresses, and no system registers, and T steps over an INT, as P does.

V86 Machines

On an 80386 with the 80386’s features (CPU_TYPE 3), CPU_V86 provides V86 machines, which run real-mode code in virtual-8086 mode, at ring 3, for a host program that provides whatever services that code needs; ring 3 programs reach it through DOS_UTL_MAPSEG with AL = 2 (create a machine of BX paragraphs, owned by the current program) and AL = 3 (run machine BX, with ES:DI -> its V86REGS). V86.COM is the host for real-mode DOS programs. The interface is in v86.inc.

  • Memory: a machine’s memory (up to 640K, a multiple of 4K, from the top of memory, starting on a 64K boundary, so that its 64K boundaries are where its programs think they are, as a DMA controller’s are) starts at linear address 0, followed by the ROMs (C0000h-FFFFFh, read-only), and the 64K above 1Mb wraps to the first 64K, as on an 8086. If DX (DOS_UTL_MAPSEG’s REG_DX) is a console’s video memory selector (from IOCTL_GETMODE with CL = 1), which must be an LDT selector for whole pages from A0000h to C0000h, the machine also gets that memory at the start of its frame (eg, a console’s text page at B8000h, as page 0 would be, whatever page the console is on), and DX returns that segment (otherwise, DX is zero, and nothing else is mapped). Each time the machine resumes, its page table gets the selector’s memory if the selector is present and its memory starts on a page (see Video Memory), or else pages that aren’t present, and a page fault there waits for the selector (wait ID SELID_WAIT:ID, as a program that loads it does) and then runs the instruction again, or if the wait ends early (eg, for a CTRLC), exits as V86X_TICK, so that DOS can act on it; once the selector is freed, the machine faults there (V86X_FAULT). Each machine has its own page directory and page table (8K, also from the top of memory), whose page directory has the system’s PDEs (see Paging), so the kernel’s selectors work while it’s loaded. The memory’s selectors (DPL 3, in the creator’s LDT) start every 32K, and each covers the 64K there (or what remains), so its host can reach anything smaller than 32K through a single selector; the first one names the machine, and freeing the memory, or its owner ending, frees the machine too.
  • Running: CPU_V86 with AL = 1 runs the machine, with interrupts on (it’s the only function that doesn’t keep them off), until it exits: V86X_INT for an INT (or one of the exceptions that real mode delivers through the vectors: 00h, 01h, 05h, 06h, and 07h) whose vector’s handler starts with a HLT, V86X_IO for an IN or OUT of a byte or a word (with VR_EIP past it, and the port and opcode in VR_ERR), so that its host can do it, V86X_FAULT for anything else that real mode would allow but the machine doesn’t (eg, string I/O, HLT, or a page fault), and V86X_TICK after each hardware interrupt (with VR_VEC = the interrupt’s real-mode vector, eg, 08h for a timer tick), so that DOS can switch (or end) the session, and its host can give the machine interrupts of its own (eg, a tick, or one that a driver counted for it; see SND$). Its registers are in a V86REGS, whose IF is the machine’s own (CPU_V86 with AL = 2 and 3 copies the registers of the machine that ran last from and to its context, as an exit and AL = 1 do, for a debugger that interrupted its hardware interrupt’s handler; see Debuggers), and at each exit, VR_DSSEL and VR_ESSEL are selectors for 64K at its DS and ES (less anything beyond its memory), so that the host can pass its pointers to DOS.
  • The monitor: a machine’s IOPL is 0, so CLI, STI, PUSHF, POPF, INT, INT3, INTO, and IRET (with or without an operand-size prefix) fault, and CPU$ does what real mode would, using the machine’s IF, which never stops interrupts (without leaving the machine’s IDT, page directory, and ports, unless the instruction exits to the host); an INT goes to the machine’s own vector (pushing FLAGS, CS, and IP, and clearing IF and TF), unless the handler starts with a HLT, which is how a host marks its default handlers (one HLT for each vector). The TSS’s I/O permission bitmap allows no ports, so I/O instructions fault, too, and an IN or OUT exits to the host, except at the interrupt controller’s ports (20h and 21h), where the machine has no interrupts of its own, so CPU$ itself ignores an OUT (eg, an end of interrupt) and reads zero, without an exit, and the game port (201h), which no driver owns, so CPU$ ignores an OUT and reads FFh (no game adapter: programs that poll it, eg, for joystick buttons, don’t exit every time), and except at ports that a driver has lent the machine (CPU_V86 with AL = 4, which only a driver that owns the device should use, eg, SND$, and which can also give CPU$ a far function of the driver’s (ES:DI) to call, with interrupts off, when the machine is suspended (AL = 0) or resumes (AL = 1); AL = 5 takes them back), whose bits are clear in the machine’s own copy of the bitmap (in its context), which CPU$ copies into the TSS while the machine runs, and (below B0000h, which VKD$ maps for a console only in one of their graphics modes, 0Dh-13h, when it has the screen to itself): then the bitmap’s bits for the video ports (3C0h-3DFh) are clear while the machine runs, too, so its code uses them directly (CPU$ sets them all again whenever the machine stops). The bitmap follows the GDT’s last identity selector, where no selector can reach it, and ends with the byte after the video ports’ (so every port above them faults, and ports can be lent only below them, 8 at a time). The machine’s direction flag is still set when CPU$ is entered (eg, after its STD), so CPU$ clears it first (the machine’s own is in its FLAGS).
  • Suspending: a machine that has the video ports (ie, its console is in one of an EGA or VGA’s graphics modes) is suspended while its video memory selector isn’t present, which VKD$ arranges while its console is hidden and its state is saved elsewhere (see Device Drivers): each time the machine would resume, CPU$ waits for the selector instead (SELID_WAIT:ID, as a page fault there does), so the machine doesn’t run at all, and once the selector is present, it resumes where it was. A wait that ends early (eg, for a CTRLC or KILL) exits as V86X_TICK with VR_VEC = 0Eh, so that DOS can act on it. The first time, and when it resumes, CPU$ calls the function of the driver that lent it ports, if any.
  • Interrupts: an interrupt from virtual-8086 mode needs an 80386 gate, and pushes a 32-bit frame (with the machine’s segment registers), so while a machine runs, its own IDT is loaded (built the first time a machine is created), whose gates (for the exceptions, 00h-11h, and the IRQs, 70h-7Fh) all go to CPU$, and the TSS’s ring 0 stack is the machine’s register context, so that’s where the processor stores its registers. CPU$ then loads the system’s IDT and the TSS’s previous ring 0 stack, and goes back to the stack of the call that ran the machine, where it runs the system’s handler for a hardware interrupt, as if the interrupt had come from there, so the drivers’ handlers (and session switches) work as they always have. The machine gets no hardware interrupts of its own, other than those that its host gives it.

  • V86.COM: the host for DOS programs creates a 640K machine (or one of the size its /M switch gives, in K, which is also the memory size in the machine’s copy of the BIOS data), keeps the machine’s memory blocks (MCBs from 710h up, after the 256 bytes at 500h that DOS and programs like BASIC use, and its default handlers at 600h), PSPs, DTA, and vectors itself, loads COM and EXE files (with COMDATA, as BASIC-DOS does), and passes the rest of the DOS and DOSUTIL functions to BASIC-DOS, with selectors for the machine’s DS and ES and the current PSP’s handles in its own PSP_PFT (which BASIC-DOS uses), keeping a count of each SFH’s references, since DOS has no DUP for a new PSP’s copies. The PRINTF functions are rebuilt, since their format strings follow the INT (and %s is a near pointer), as are TOKID and STRSTR, whose data is in the caller’s CS, and LOAD (eg, for a pipeline’s next program, which runs as an ordinary BASIC-DOS program). IOCTL_GETFPU gets a copy of FPU$’s functions in the machine (see fpu.inc), which its programs call directly, and IOCTL_GETMODE with CL = 1 gets the segment of its console’s video memory in the machine (V86.COM gets the selector itself before it creates the machine, and passes it to DOS_UTL_MAPSEG), or an error for another console’s selector, and a CTRLC goes to the machine’s INT 23h vector, which restarts the interrupted call when its handler returns, as DOS does. A far call to DDINT_CPU, DDINT_GETVEC, or DDINT_SETVEC (which are HLTs in the machine, as its default handlers are) gets what the 8086 driver would do for a debugger: the machine’s vectors, CPU_GETINFO (with no free memory), CPU_MAP, CPU_UNMAP, CPU_SEGINFO, CPU_RWMEM, and CPU_QUERY, which describes the machine’s memory below its first MCB (named V86) and then its MCBs, for DEBUG’s DM; every other CPU$ function is invalid. V86.COM combines free blocks when it frees one (as BASIC-DOS does), so MEM reports the same free memory after a program ends as before it ran, and when a program ends, any vector still pointing into its memory gets its default handler again (as BASIC-DOS does; eg, DEBUG’s INT 01h and 03h, if a CTRLC ends it). An INT 10h, 16h, or 17h that reaches a default handler gets the common BIOS video, keyboard, and printer functions (and INT 10h AX = 1A00h, get display combination, when the machine’s BIOS data says that there’s a VGA), done with the console driver’s IOCTLs and DOS’s console and printer functions (so they work on a terminal, too), an INT 11h or 12h gets the equipment or memory size in the machine’s BIOS data, an INT 1Ah gets the system’s tick count (function 00h; the others return with carry set), and DOS_PSP_COPY copies the machine’s current PSP. V86.COM gives its console the machine’s first selector with IOCTL_SETKEYS (CL bit 1), so that VKD$ keeps the keyboard data in the machine’s copy of the BIOS data current, for programs that look there before they call INT 16h (eg, MSBASIC). After a V86X_TICK exit for a timer tick, the tick count in the machine’s BIOS data becomes the system’s (so it stays right, though the machine misses ticks), and the machine is owed as many ticks as its timer would have made since the last one (one, unless a program has set counter 0’s divisor, through ports 40h and 43h, down to 400h; at most 64 are owed). After any V86X_TICK exit, unless the machine’s IF is clear (in which case they wait for the next exit), V86.COM gives the machine the interrupts it’s due, in this order: an INT 09h for the next scan code in its console’s queue, if the program has hooked INT 09h (one scan code per exit, after any E0h/E1h prefixes, so a release never immediately follows its press), the interrupts from a borrowed sound card that SND$ counted (up to 2 at a time), and an INT 08h for each tick it’s owed (up to 16 at a time). It pushes the interrupted frame, and then a frame for each handler after the first, from the last to the second (with IF and TF clear), and runs the machine at the first handler, so each handler’s IRET goes straight into the next one, as if its interrupt had arrived just then, and the last one returns to where the machine was, with no exits in between (at 700 ticks a second, an exit for each would leave little time for the program); only a scan code prefix with another code after it returns to a HLT at STUB_SEG:STUB_VIRQ instead, which exits so that V86.COM can give the next code. VKD$ adds each scan code to the queue (KQ_HEAD, in bios.inc, just below 600h in the machine) while the console that has the machine’s BIOS data (IOCTL_SETKEYS CL bit 1) has focus, and port 60h reads the code of the last INT 09h; a handler that passes the interrupt on to the default vector (a HLT) lets the system’s keys stay readable, while one that keeps it makes V86.COM discard the console’s keys (DOS_TTY_FLUSH) on the next tick, so the system’s keyboard buffer doesn’t fill. The default INT 08h and 1Ch handlers are code in the machine, next to its default-vector HLTs (an INT 1Ch and an IRET, and an IRET; INT 33h’s default is that IRET, too, so programs see no mouse), so that a tick never needs another exit. A machine gets ticks only while its code runs, not during a DOS call that waits (eg, for a key). A V86X_IO exit goes to the handler for its port, from a table of port ranges (a word is two bytes, at that port and the next): the timer (40h-43h, as above), the keyboard (60h-64h), the DMA controller (00h-0Fh and its page registers, 80h-8Fh), which go to SND$ (IOCTL_SNDDMA) if the machine borrowed a sound card, and ports with nothing behind them, which read as FFh (sound cards at 210h-26Fh, the parallel ports, an FM sound card’s, 388h-389h, and without a sound card, the DMA controller’s); a port with no handler ends the program with a CPU fault, as before. When it starts, V86.COM opens SND$, if it’s installed, and borrows its card for the machine (IOCTL_SNDLEND); its handle for SND$ is the last of its 20 (the machine’s programs get the other 19, and closing handle 19 fails), so that DOS closes it when V86.COM ends, however it ends, which gives the card back.

Flat Machines and LE Programs

A flat machine (CPU_V86 with AL = 6-8; see v86.inc) runs 32-bit code at ring 3, in protected mode, in a linear address space of its own: every address below C0000000h (where the system’s addresses begin; see Paging), of which only the memory that the machine has been given is mapped. Like a V86 machine, it has its own page directory, it runs with the machines’ IDT (whose gates are 80386 gates) and its own ring 0 stack (its register context), and every interrupt takes it back to the call that ran it (CPU_V86 with AL = 1), so the system’s 16-bit interrupt gates, which would lose the upper halves of a 32-bit program’s EIP and ESP, never see 32-bit code, and everything else in the system works as it always has.

  • Memory: the machine’s memory starts at linear address 10000h (so the first 64K isn’t mapped, and a null pointer faults) and is contiguous in its address space, but not in physical memory: it’s made of blocks from the top of memory, each a multiple of 4K, which the machine’s owner owns, so they’re all freed when it ends. More memory goes at the end (CPU_V86 with AL = 8), with another page table (4K, for every 4Mb of addresses) when it’s needed.
  • Selectors: a machine is five LDT selectors: one for its context (DPL 0, which names the machine), its code and data selectors (32-bit, with base 0 and a limit just below C0000000h), which are the only CS and SS that it ever runs with (whatever its V86REGS says), and two 16-bit selectors for its host, which CPU_V86 with AL = 7 points at any linear address in the machine: each covers as many of the bytes there as are in consecutive physical pages, at most 64K, because DOS and the drivers use them with the system’s page tables, where a transfer goes to the physical address of a selector’s base (see Running Programs at Ring 3).
  • Exits: a flat machine has nothing to emulate: an INT exits (V86X_INT, with VR_EIP past it), a hardware interrupt runs the system’s handler and then exits (V86X_TICK, so that DOS can switch sessions), and anything else is a fault (V86X_FAULT): it has IOPL 0 and no ports. An INT 3 doesn’t exit: it goes to the system’s INT 03h handler, as a 16-bit program’s does (DOS’s, which ignores it, or a debugger’s), and so does a single-step trap while a debugger is stepping the machine (CPU_V86 with AL = 2 and 3 give a debugger the machine’s registers, as they do a V86 machine’s), and then the machine runs again. A fault goes to that handler first, too, with its vector and error code in the machine’s registers, so that a debugger can stop for it: if the debugger gives the machine its registers back (AL = 3), the machine runs again, and otherwise it exits with the fault; an INT 3 that follows a NOP (a failed assertion) is treated the same way, so without a debugger, it ends the program as a fault with vector 03h. Its DS, ES, FS, and GS can be any selectors that ring 3 could load (any other becomes zero).

LE programs: the kernel loads an LE file (see Loading Programs) into a flat machine whose memory is as large as the file’s objects need, or if there’s more to spare, half of the largest free block, up to 256K. The objects are loaded one after another from 10000h, each starting on a page, whatever addresses the linker gave them (LINK386 1.01 puts each at a multiple of 64K, which would cost 64K of memory apiece): each object’s pages are read (or left zeroed), and each page’s fixup records are applied, which must all be 32-bit offsets to the program’s own objects (what LINK386 makes for a program whose segments are in a group named FLAT), and which are the only references to an object’s address; at most 16 objects, with 4K pages. The program starts at the entry point and stack pointer in its LE header, with DS = SS = its data selector, ES = its PSP’s (16-bit) selector (eg, for its command tail), EDX = its first object’s address, EBX = the address after its last object, and ECX = how much memory follows that.

The program has a PSP, handles, and a parent, like any other, because as far as DOS can tell, it’s a small 16-bit program: its PSP’s block holds the PSP, a little data, and a stack, and its code is a piece of the kernel (mapped by a ring 3 code selector of its own), which runs the machine until the 32-bit code issues an INT 21h, makes that DOS call itself, at ring 3, and runs the machine again. So the kernel needs no 32-bit entry points, and the translation can’t do anything that the program couldn’t. A 32-bit program’s DOS calls work like this:

  • Registers are passed and returned as their low 16 bits (EAX’s upper half returns zero), and a pointer (which must be in the program’s data segment) becomes one of the machine’s two host selectors with a zero offset: DS:EDX for the functions that take a string or a small buffer (DOS_TTY_PRINT, DOS_TTY_INPUT, DOS_DSK_MKDIR through DOS_HDL_OPEN, DOS_DSK_DELETE, the attribute functions, and DOS_DSK_FFIRST), DS:ESI for DOS_DSK_GETCWD, and ES:EDI as well for DOS_DSK_RENAME.
  • DOS_HDL_READ and DOS_HDL_WRITE take a 32-bit count in ECX and return one in EAX: the transfer is made a piece at a time (as much as one selector covers, at most 32K), until it’s done or a piece transfers less than it was asked to.
  • DOS_MEM_ALLOC takes a number of bytes in EBX, adds that much zeroed memory (rounded up to 4K) to the end of the machine’s memory, and returns its address in EAX; there’s no DOS_MEM_FREE or DOS_MEM_REALLOC.
  • DOS_DSK_FFIRST and DOS_DSK_FNEXT use the PSP’s default DTA (at 80h in the PSP, which the program reaches through the selector it started with in ES), since the program can’t set another: a program with more than one search copies each find block from there, and back before the next DOS_DSK_FNEXT (as SRC\SDK’s CRT32.ASM does for C programs).
  • The functions with no pointers (console, date and time, drive, DOS_HDL_CLOSE, DOS_HDL_SEEK, DOS_HDL_GETTIME, DOS_PSP_RETURN, and so on) are passed as they are, and every other function (eg, those that use FCBs, set the DTA or vectors, or DOS_PSP_EXEC) returns carry set and ERR_INVALID.
  • A fault in the 32-bit code (or an INT other than INT 21h) displays CPU fault vv (EC=xxxx) at cccc:iiiiiiii and ends the program with exit code 255 and EXTYPE_FAULT, as a fault in any other program does.

A CTRLC ends the program at its next exit (every timer tick is one). DOS_UTL_MAPSEG with AL = 4 and 5 gives the kernel’s code those two CPU$ functions at ring 3 (see Utility Functions).

The Extended Memory Demos

The Extended Memory (2Mb) demo is a 2Mb PC AT with a Color Display and three full-screen consoles, one on each page of video memory. The Extended Memory (VT100 Debugger) demo runs the same sessions, with a DEC VT100 on COM2 for DEBUG.COM, and its Debugger page is the same machine with the PCjs Debugger. Each also runs on a 2Mb COMPAQ DeskPro 386 with a VGA (2Mb and VT100), from the same diskette, where CPU$ also uses the 80386’s features (see The CPU$ Drivers). Pressing R at the boot message boots the diskette in real mode instead. Everything after CPU$ initializes runs in protected mode, and COMMAND.COM runs at ring 3, with C: as the default drive. Commands, BASIC programs, and NE programs work (eg, PRIMES.BAS in the third session), but MZ EXE files don’t (see Loading Programs).

In the VT100 demo, DEBUG.COM, loaded as a driver, shows each fault on the VT100, with the registers at the faulting instruction (adding /H to its line in CONFIG.SYS stops it as soon as it’s loaded, so that you can set breakpoints before booting continues). The B: drive has the BASIC-DOS Tests diskette, so B:\TESTS\MISC\FAULT n causes exception n (0, 1, 3-6, 12, or 13), or with -1, a fault in the kernel (a null pointer to a filename), to see how BASIC-DOS responds: DOS reports a divide error (0) or an overflow (4) and ends the program, a single-step trap (1) or a breakpoint (3) resumes (unless DEBUG.COM stops there), and DOS ends the program for the rest (eg, CPU fault 0D), unless DEBUG.COM’s VT command traps the vector.

Debugging

  • DEBUG.COM works in either mode, and as a driver, in a 32-bit program’s flat machine, where addresses are linear addresses: an address can start with & (real mode), # (protected mode), % (a linear address), or %% (a physical address), DS selector displays a selector’s descriptor, R also shows the MSW, GDTR, and IDTR (and in protected mode, the LDTR, TR, and each segment register’s base and limit), and LN [address] shows the name of the memory an address is in (see DEBUG.COM).
  • The PCjs Debugger’s r shows each segment register’s selector with its base and limit in protected mode (eg, CS=0018[000970,FFFF] in CPU$), along with the GDTR, IDTR, LDTR, and TR, and its d dos command lists CPU$’s arena, in either mode (see Physical Memory Arena).

Limitations

  • MZ EXE files don’t run in protected mode (see Loading Programs). On an 80386, V86.COM runs them (and COMMAND.COM, and the programs it runs) in a V86 machine, with the common BIOS video, keyboard, and printer functions, and its console’s video memory. On an 80286, they could run with the processor switched back to real mode (as in OS/2’s DOS session, with other sessions waiting), which isn’t implemented.
  • The 80386 gets an 80386 TSS, selectors beyond 64K, paging that maps physical memory at C0000000h, V86 machines, and flat machines for LE programs, and only IBM’s PC AT BIOS and the COMPAQ DeskPro 386’s are tested in protected mode.
  • LE programs get only the DOS functions listed in Flat Machines and LE Programs (no FCBs, vectors, EXEC, or DOSUTIL functions, and only the PSP’s DTA), can’t free memory, and can’t be loaded by DEBUG.COM run as a program; loaded as a driver, DEBUG.COM stops in one’s 32-bit code (at an INT 3, a breakpoint, or a CTRL-C), with 32-bit registers, disassembly and assembly, stepping, breakpoints at linear addresses, and the faults that VT traps. LINK386’s default MS-DOS stub isn’t a valid program, so an LE file needs a STUB of its own to say anything useful in real mode.
  • BIOS functions: the ones that the drivers use work in protected mode, but the rest haven’t been tried, and a few (eg, INT 15h functions 87h and 89h, which switch modes themselves) would need CPU$ replacements.
  • Interrupt hooks at ring 3: a ring 3 program’s handler sees only the interrupts that ring 3 code in its own session issues, so a hook of an interrupt that ring 0 code issues (eg, INT 1Ch, from the BIOS’s timer handler, or INT 13h, from FDC$) never runs. And there are only 8 reflected vectors for all sessions; with none free, DOS_MSC_SETVEC returns ERR_NOMEMORY, and DOS_MSC_GETVEC returns 0:0.
  • CPU$ from ring 3: ring 3 code can’t call CPU$, so programs that do (eg, CPUTESTS) need RING=0, and DEBUG.COM run as a program has fewer commands at ring 3 (see Running Programs at Ring 3).
  • I/O at ring 3: programs run with IOPL 0, so a program that uses IN, OUT, CLI, or STI needs RING=0.
  • Table sizes: the GDT (256 entries) and the number of LDTs (32) are fixed, and the PMB table and LDTs share a fixed amount of space (see Table Growth).
  • Faults in drivers are still fatal, since only the driver knows what it was doing. DOS checks the buffers that it gives them.
  • Sharing an SFB: a session that shares an SFB (eg, a pipe, or a file that two sessions opened) can close more references to it than it has, by repeating its SFH in its PSP_PFT, which can affect the other session. It still can’t reach an SFB that it never had.
  • What DOS allows: there’s no privilege model for programs, so any program can do what COMMAND.COM can with DOS functions: restart the system (DOS_UTL_RESTART), end another session (DOS_UTL_END), and change any file, or write any volume (eg, with FORMAT’s IOCTLs). It can also use all of memory, up to the table limits, and through DEF SEG (DOS_UTL_MAPSEG), draw on any console’s video memory.
  • Reading kernel memory: a %ls parameter to DOS_UTL_PRINTF can still point to a ring 0 selector, so a ring 3 program can read kernel memory that way (but not write it).
  • Identity selectors exist only every 800h from A000h to F800h, so a ROM segment that isn’t a multiple of 800h (eg, F600h, the PC’s ROM BASIC) can’t be reflected to.
  • A20 stays enabled, so programs that depend on addresses wrapping at 1Mb could break (eg, EXEPACK-compressed programs loaded in the first 64K report “Packed file is corrupt”).
  • COMMAND.COM’s transient portion can’t be set aside at ring 3, where every copy runs the code in a code block that none of them owns (see Loading Programs), so the first copy keeps all of its code in memory while a program runs, even when it’s the only copy (at ring 0 and in real mode, a lone copy sets its transient portion aside).
  • DEF SEG makes only video memory and BASIC’s own data writable, even for blocks that belong to the session.

« Data StructuresBASIC-DOS vs. DOS Extenders »

Copyright (c) 2020-2026 Jeff Parsons Released under MIT License