DOS/32 Advanced DOS Extender

https://github.com/yetmorecode/dos32a-ng
Admin
DOS/32 Advanced DOS Extender is a next-generation DOS extender that enables running advanced DOS...
Tokens:16,170
Snippets:57
Trust Score:6.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build DOS/32A with TASM

Source: https://github.com/yetmorecode/dos32a-ng/blob/main/README.md

Assemble and link the kernel and extender using TASM 4+ and tlink. Ensure TASM is installed and configured.

```assembly
tasm32 /dEXEC_TYPE=0 /m /ml /c /la kernel.asm
tasm32 /dEXEC_TYPE=0 /m /ml /c /la dos32a.asm
tlink /3 dos32a kernel,DOS4GW.exe
```

--------------------------------

### DPMI Get Vendor-Specific API Entry Point (INT 31h, 0A00h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Use INT 31h, AX=0A00h with DS:ESI pointing to a null-terminated vendor ID string (e.g., "SUNSYS DOS/32A") to get the entry point for host-specific DPMI extensions. On success, ES:EDI will contain the code selector and offset, and other registers provide system information. Check the carry flag (CF) for failure (AX=8001h if not found).

```asm
; Obtain the DOS/32A vendor-specific DPMI extension entry point

dos32a_id   DB  "SUNSYS DOS/32A", 0   ; null-terminated vendor ID string

        lea     esi, [dos32a_id]
        push    ds
        pop     ds                  ; DS:ESI -> vendor ID string
        mov     ax, 0A00h           ; Get Vendor-Specific API Entry Point
        int     31h
        jc      no_ext              ; AX=8001h if extension not found

        ; CF clear on success:
        ; ES:EDI  = code selector:offset of DOS/32A DPMI extension entry point
        ; AX  = version (AH=major, AL=minor)
        ; BH  = system type (00=Clean,01=XMS,02=VCPI,03=DPMI)
        ; BL  = DPMI kernel config bits
        ; CL  = CPU type (03=386,04=486,05=Pentium,06=P-Pro)
        ; CH  = FPU type (00=none,01=8087,...,06=Pentium Pro)
        ; DX  = PIC values (unrelocated)
        mov     [ext_entry_sel], es
        mov     [ext_entry_off], edi
        movzx   eax, ah
        mov     [dos32a_ver_major], al
        movzx   eax, al
        mov     [dos32a_ver_minor], al

        ; Call an ADPMI extension via FAR CALL to ES:EDI
        ; (AL = sub-function code, parameters per ADPMI spec)
        push    cs
        call    far ptr [ext_entry_sel]

no_ext:

```

--------------------------------

### Get ADPMI Configuration Info (INT 21h, 0FF8Ah)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Queries the CPU type, system software environment (Clean, XMS, VCPI, DPMI), ADPMI configuration bits, and the ADPMI configuration header pointer. Useful for runtime capability detection.

```asm
; Query CPU type and system software environment

        mov     ax, 0FF8Ah      ; DOS/32A: Get ADPMI Configuration Info
        int     21h

        ; EAX = 49443332h ('ID32') if supported
        cmp     eax, 49443332h
        jne     no_adpmi

        ; EBX = version (AH=major, AL=minor)
        ; CL  = CPU type: 03h=386, 04h=486, 05h=Pentium, 06h=P-Pro/PII
        movzx   eax, cl
        mov     [cpu_type], al      ; e.g., 05h for Pentium

        ; CH  = System software type:
        ;   00h = Clean (INT 15h raw)
        ;   01h = XMS
        ;   02h = VCPI
        ;   03h = DPMI
        movzx   eax, ch
        mov     [sys_type], al

        ; DL  = ADPMI kernel configuration bits
        ; ESI = pointer to ADPMI configuration header
        ; FS  = selector to access ADPMI configuration header
        mov     [adpmi_cfg_bits], dl
        mov     [adpmi_hdr_ptr],  esi

no_adpmi:

```

--------------------------------

### Get DOS/32A Configuration Info (INT 21h, 0FF89h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Detects the presence of DOS/32A and retrieves its version, DOS Transfer Buffer size, and configuration details. Use this function to check for DOS/32A at runtime.

```asm
; Detect DOS/32A and read its version and transfer buffer size

        mov     ax, 0FF89h      ; DOS/32A: Get Configuration Info
        int     21h

        ; If EAX = 49443332h ('ID32'), DOS/32A is active
        cmp     eax, 49443332h
        jne     not_dos32a

        ; EBX = version: AH=major, AL=minor (e.g., EBX=00000912h -> v9.1.2)
        movzx   eax, bh         ; major version
        movzx   ecx, bl         ; minor version
        mov     [ver_major], al
        mov     [ver_minor], cl

        ; ECX = DOS Transfer Buffer size in bytes (e.g., 8192 = 8 KB default)
        mov     [dtb_size], ecx

        ; EDX = configuration bits (see Technical Reference for bit definitions)
        ; ESI = linear pointer to "ID32" configuration header
        ; FS  = selector to access configuration header
        mov     [config_ptr], esi
        mov     [config_sel], fs

        jmp     detect_done
not_dos32a:
        ; Running under a different DOS extender or no extender
detect_done:

```

--------------------------------

### DPMI Function 0A00h — Get Vendor-Specific API Entry Point (INT 31h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Retrieves the entry point for host-specific DPMI extensions. This function is used to discover and call extended DPMI services provided by the environment, such as DOS/32A.

```APIDOC
## DPMI Function 0A00h — Get Vendor-Specific API Entry Point (INT 31h)

Returns the entry point for host-specific DPMI extensions. DOS/32A recognizes two ID strings: `"RATIONAL DOS/4G"` (for DOS/4G compatibility) and `"SUNSYS DOS/32A"` (for native DOS/32A extensions). Using the DOS/32A ID also returns CPU type, FPU type, system type, version, and PIC values in registers.

### Get Vendor-Specific API Entry Point

- **Function**: `AX = 0A00h`
- **Parameter**: `DS:ESI` points to a null-terminated vendor ID string (e.g., `"SUNSYS DOS/32A"`)
- **Call**: `INT 31h`
- **On Success (CF=0)**:
    - `ES:EDI` = code selector:offset of the vendor-specific API entry point
    - `AX` = version (major in `AH`, minor in `AL`)
    - `BH` = system type (00=Clean, 01=XMS, 02=VCPI, 03=DPMI)
    - `BL` = DPMI kernel config bits
    - `CL` = CPU type (03=386, 04=486, 05=Pentium, 06=P-Pro)
    - `CH` = FPU type (00=none, 01=8087, ..., 06=Pentium Pro)
    - `DX` = PIC values (unrelocated)
- **On Failure (CF=1)**: `AX = 8001h` if the extension is not found.

### Example Usage

```asm
; Obtain the DOS/32A vendor-specific DPMI extension entry point

dos32a_id   DB  "SUNSYS DOS/32A", 0   ; null-terminated vendor ID string

        lea     esi, [dos32a_id]
        push    ds
        pop     ds                  ; DS:ESI -> vendor ID string
        mov     ax, 0A00h           ; Get Vendor-Specific API Entry Point
        int     31h
        jc      no_ext              ; AX=8001h if extension not found

        ; CF clear on success:
        ; ES:EDI  = code selector:offset of DOS/32A DPMI extension entry point
        ; AX  = version (AH=major, AL=minor)
        ; BH  = system type (00=Clean,01=XMS,02=VCPI,03=DPMI)
        ; BL  = DPMI kernel config bits
        ; CL  = CPU type (03=386,04=486,05=Pentium,06=P-Pro)
        ; CH  = FPU type (00=none,01=8087,...,06=Pentium Pro)
        ; DX  = PIC values (unrelocated)
        mov     [ext_entry_sel], es
        mov     [ext_entry_off], edi
        movzx   eax, ah
        mov     [dos32a_ver_major], al
        movzx   eax, al
        mov     [dos32a_ver_minor], al

        ; Call an ADPMI extension via FAR CALL to ES:EDI
        ; (AL = sub-function code, parameters per ADPMI spec)
        push    cs
        call    far ptr [ext_entry_sel]

no_ext:
```
```

--------------------------------

### Get VBE 2.0 SuperVGA Information (INT 10h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Queries VESA BIOS Extension 2.0 adapter information. DOS/32A automatically converts real-mode pointers to flat 32-bit linear addresses for protected mode use. Ensure the VBE_INFO structure is correctly defined and the buffer is prepared.

```asm
; Query VESA VBE 2.0 adapter information from protected mode

VBE_INFO STRUC
  VbeSignature    DD ?        ; +00h "VESA" if valid
  VbeVersion      DW ?        ; +04h VBE version (e.g., 0200h = VBE 2.0)
  OemStringPtr    DD ?        ; +06h linear ptr to OEM string (fixed up by DOS/32A)
  Capabilities    DD ?        ; +0Ah capability flags
  VideoModePtr    DD ?        ; +0Eh linear ptr to mode list (fixed up by DOS/32A)
  TotalMemory     DW ?        ; +12h blocks of 64 KB
                  DB (512-20) DUP (?) ; remainder of 512-byte buffer
VBE_INFO ENDS

        ; Place "VBE2" signature to request VBE 2.0 info
        mov     dword ptr [vbe_buf.VbeSignature], 'VBE2'

        lea     edi, [vbe_buf]
        push    ds
        pop     es              ; ES:EDI -> 512-byte buffer
        mov     ax, 4F00h       ; VBE: Get SuperVGA Information
        int     10h

        cmp     al, 4Fh         ; AL=4Fh means function supported
        jne     no_vesa
        test    ah, ah          ; AH=00h means success
        jnz     vesa_fail

        ; VbeVersion = 0200h confirms VBE 2.0
        ; OemStringPtr and VideoModePtr are already flat linear addresses (DOS/32A fixup)
        mov     esi, [vbe_buf.OemStringPtr]  ; ESI -> OEM string (e.g., "NVIDIA ...")
        mov     edi, [vbe_buf.VideoModePtr]  ; EDI -> word array of mode numbers, ends with 0FFFFh

mode_loop:
        mov     ax, [edi]
        cmp     ax, 0FFFFh
        je      mode_list_end
        ; AX = VESA mode number (e.g., 0103h = 800x600x8bpp)
        add     edi, 2
        jmp     mode_loop

mode_list_end:
no_vesa:
vesa_fail:

```

--------------------------------

### DOS/32A Extended Function 0FF89h — Get Configuration Info (INT 21h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

A DOS/32A-specific function to retrieve extender version, DOS Transfer Buffer size, configuration bits, and a pointer to the internal configuration header. Useful for detecting DOS/32A presence and runtime configuration.

```APIDOC
## DOS/32A Extended Function 0FF89h — Get Configuration Info (INT 21h)

### Description
A DOS/32A-specific extended INT 21h function that returns the extender's version number, low-buffer (DOS Transfer Buffer) size, configuration bits, and a pointer to the internal configuration header "ID32". Use to detect whether DOS/32A is present and to read runtime configuration.

### Method
INT 21h

### Parameters
#### Input Registers
- **AX**: `0FF89h` (Function code)

#### Output Registers (if DOS/32A is active)
- **EAX**: `49443332h` ('ID32')
- **EBX**: Extender version (AH=major, AL=minor, e.g., `00000912h` -> v9.1.2)
- **ECX**: DOS Transfer Buffer size in bytes
- **EDX**: Configuration bits
- **ESI**: Linear pointer to the "ID32" configuration header
- **FS**: Selector to access the configuration header

#### Output Registers (if DOS/32A is not active)
- **EAX**: Not `49443332h`

### Request Example
```asm
        mov     ax, 0FF89h      ; DOS/32A: Get Configuration Info
        int     21h
```

### Response Example
```asm
        ; If EAX = 49443332h ('ID32'), DOS/32A is active
        cmp     eax, 49443332h
        jne     not_dos32a

        ; EBX = version: AH=major, AL=minor (e.g., EBX=00000912h -> v9.1.2)
        movzx   eax, bh         ; major version
        movzx   ecx, bl         ; minor version
        mov     [ver_major], al
        mov     [ver_minor], cl

        ; ECX = DOS Transfer Buffer size in bytes (e.g., 8192 = 8 KB default)
        mov     [dtb_size], ecx

        ; EDX = configuration bits (see Technical Reference for bit definitions)
        ; ESI = linear pointer to "ID32" configuration header
        ; FS  = selector to access configuration header
        mov     [config_ptr], esi
        mov     [config_sel], fs

        jmp     detect_done
not_dos32a:
        ; Running under a different DOS extender or no extender
detECT_DONE:
```
```

--------------------------------

### Get Free Memory Information (DPMI 0500h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Query extended memory information using DPMI function 0500h. The returned structure provides details on free memory, page allocation limits, and paging file size. Note that only the largest free block (offset 00h) is guaranteed to be valid in multitasking environments.

```assembly
; Query extended memory via DPMI 0500h and print largest free block

MEM_INFO STRUC
  mi_largest_free   DD ?   ; +00h  largest contiguous free block (bytes)
  mi_max_unlocked   DD ?   ; +04h  max unlocked page allocation (pages)
  mi_max_locked     DD ?   ; +08h  max locked page allocation (pages)
  mi_linear_size    DD ?   ; +0Ch  total linear address space (pages)
  mi_unlocked_pages DD ?   ; +10h  total unlocked pages
  mi_free_pages     DD ?   ; +14h  total free pages
  mi_physical_pages DD ?   ; +18h  total physical pages
  mi_free_linear    DD ?   ; +1Ch  free linear address space (pages)
  mi_paging_file    DD ?   ; +20h  paging file size (pages)
  mi_reserved       DB 0Ch DUP(?)  ; +24h  all 0FFh if unsupported
MEM_INFO ENDS

        lea     edi, [mem_info_buf]
        push    ds
        pop     es                  ; ES:EDI -> 48-byte buffer
        mov     ax, 0500h           ; Get Free Memory Information
        int     31h
        ; CF is always clear for this function

        ; Fields = 0FFFFFFFFh if not supported by DPMI host
        mov     eax, [mem_info_buf.mi_largest_free]
        ; EAX = largest free block in bytes (e.g., 0x03F00000 = ~63 MB)
        mov     [largest_block], eax

        mov     eax, [mem_info_buf.mi_free_pages]
        ; multiply by page size (usually 4096) for total free bytes
        shl     eax, 12
        mov     [total_free_bytes], eax
```

--------------------------------

### DPMI Function 0202h / 0203h — Get/Set Processor Exception Handler Vector

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

These functions manage protected-mode handlers for CPU exceptions (#0–#0Fh). Function 0202h retrieves the current handler, and 0203h installs a new one. The handler selector must be a valid protected-mode code selector. Note that exception #0Ch (Stack Fault) is not supported.

```APIDOC
## DPMI Function 0202h / 0203h — Get/Set Processor Exception Handler Vector (INT 31h)

Retrieves or installs a protected-mode handler for CPU exceptions (faults #0–#0Fh). The handler selector must be a valid protected-mode code selector. DOS/32A supports exceptions #0–#0Fh; exception #0Ch (Stack Fault) is not handled.

```asm
; Install a custom #0D General Protection Fault handler
        ; --- GET current #GP handler ---
        mov     ax, 0202h       ; Get Exception Handler Vector
        mov     bl, 0Dh         ; #GP fault
        int     31h
        jc      exc_get_fail    ; AX=8021h if BL out of range
        mov     [old_exc_sel], cx
        mov     [old_exc_off], edx

        ; --- SET new #GP handler ---
        mov     ax, 0203h       ; Set Exception Handler Vector
        mov     bl, 0Dh
        mov     cx, cs          ; selector of handler (must be a code selector)
        mov     edx, offset gp_handler
        int     31h
        jc      exc_set_fail    ; AX=8021h invalid BL | 8022h invalid selector
        jmp     exc_done

gp_handler:
        ; Handler is called with DPMI exception frame on stack
        ; Must return via IRET or chain to old handler
        jmp     far ptr [old_exc_sel]   ; chain to previous handler

exc_get_fail:
exc_set_fail:
exc_done:
```
```

--------------------------------

### DOS/32A Extended Function 0FF8Ah — Get ADPMI Configuration Info (INT 21h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Retrieves extender version, CPU type, system software type (Clean, XMS, VCPI, DPMI), ADPMI kernel configuration bits, and a pointer to the ADPMI configuration header. Useful for runtime capability detection.

```APIDOC
## DOS/32A Extended Function 0FF8Ah — Get ADPMI Configuration Info (INT 21h)

### Description
Returns the extender version, detected CPU type, system software type (Clean/XMS/VCPI/DPMI), ADPMI kernel configuration bits, and a pointer to the ADPMI configuration header. Useful for runtime capability detection and system introspection.

### Method
INT 21h

### Parameters
#### Input Registers
- **AX**: `0FF8Ah` (Function code)

#### Output Registers (if supported)
- **EAX**: `49443332h` ('ID32')
- **EBX**: Extender version (AH=major, AL=minor)
- **CL**: CPU type (e.g., `03h`=386, `04h`=486, `05h`=Pentium, `06h`=P-Pro/PII)
- **CH**: System software type (`00h`=Clean, `01h`=XMS, `02h`=VCPI, `03h`=DPMI)
- **DL**: ADPMI kernel configuration bits
- **ESI**: Linear pointer to the ADPMI configuration header
- **FS**: Selector to access the ADPMI configuration header

#### Output Registers (if not supported)
- **EAX**: Not `49443332h`

### Request Example
```asm
        mov     ax, 0FF8Ah      ; DOS/32A: Get ADPMI Configuration Info
        int     21h
```

### Response Example
```asm
        ; EAX = 49443332h ('ID32') if supported
        cmp     eax, 49443332h
        jne     no_adpmi

        ; EBX = version (AH=major, AL=minor)
        ; CL  = CPU type: 03h=386, 04h=486, 05h=Pentium, 06h=P-Pro/PII
        movzx   eax, cl
        mov     [cpu_type], al      ; e.g., 05h for Pentium

        ; CH  = System software type:
        ;   00h = Clean (INT 15h raw)
        ;   01h = XMS
        ;   02h = VCPI
        ;   03h = DPMI
        movzx   eax, ch
        mov     [sys_type], al

        ; DL  = ADPMI kernel configuration bits
        ; ESI = pointer to ADPMI configuration header
        ; FS  = selector to access ADPMI configuration header
        mov     [adpmi_cfg_bits], dl
        mov     [adpmi_hdr_ptr],  esi

no_adpmi:
```
```

--------------------------------

### DPMI Function 0500h — Get Free Memory Information

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

This function returns a structure describing available extended memory, including the largest free block, total free pages, and physical page count. Note that this information is advisory in multitasking environments, with only the largest free block guaranteed to be valid.

```APIDOC
## DPMI Function 0500h — Get Free Memory Information (INT 31h)

Returns a 48-byte structure describing available extended memory: largest free block, total free pages, physical page count, linear address space, and paging file size. Advisory only in multitasking environments; only offset 00h (largest free block) is guaranteed valid.

### Method
INT 31h with AX = 0500h

### Parameters

#### Input Registers
None specific to this function call, but the DPMI host provides the memory information.

#### Output Registers
- **CF**: Always clear for this function.

#### Response Structure (48 bytes, pointed to by ES:EDI)
- **mi_largest_free (DD)**: Offset +00h - Largest contiguous free block in bytes.
- **mi_max_unlocked (DD)**: Offset +04h - Maximum unlocked page allocation in pages.
- **mi_max_locked (DD)**: Offset +08h - Maximum locked page allocation in pages.
- **mi_linear_size (DD)**: Offset +0Ch - Total linear address space in pages.
- **mi_unlocked_pages (DD)**: Offset +10h - Total unlocked pages.
- **mi_free_pages (DD)**: Offset +14h - Total free pages.
- **mi_physical_pages (DD)**: Offset +18h - Total physical pages.
- **mi_free_linear (DD)**: Offset +1Ch - Free linear address space in pages.
- **mi_paging_file (DD)**: Offset +20h - Paging file size in pages.
- **mi_reserved (DB 0Ch)**: Offset +24h - Reserved, all 0FFh if unsupported.

### Request Example
```asm
; Query extended memory via DPMI 0500h and print largest free block

MEM_INFO STRUC
  mi_largest_free   DD ?   ; +00h  largest contiguous free block (bytes)
  mi_max_unlocked   DD ?   ; +04h  max unlocked page allocation (pages)
  mi_max_locked     DD ?   ; +08h  max locked page allocation (pages)
  mi_linear_size    DD ?   ; +0Ch  total linear address space (pages)
  mi_unlocked_pages DD ?   ; +10h  total unlocked pages
  mi_free_pages     DD ?   ; +14h  total free pages
  mi_physical_pages DD ?   ; +18h  total physical pages
  mi_free_linear    DD ?   ; +1Ch  free linear address space (pages)
  mi_paging_file    DD ?   ; +20h  paging file size (pages)
  mi_reserved       DB 0Ch DUP(?)  ; +24h  all 0FFh if unsupported
MEM_INFO ENDS

        lea     edi, [mem_info_buf]
        push    ds
        pop     es                  ; ES:EDI -> 48-byte buffer
        mov     ax, 0500h           ; Get Free Memory Information
        int     31h
        ; CF is always clear for this function

        ; Fields = 0FFFFFFFFh if not supported by DPMI host
        mov     eax, [mem_info_buf.mi_largest_free]
        ; EAX = largest free block in bytes (e.g., 0x03F00000 = ~63 MB)
        mov     [largest_block], eax

        mov     eax, [mem_info_buf.mi_free_pages]
        ; multiply by page size (usually 4096) for total free bytes
        shl     eax, 12
        mov     [total_free_bytes], eax
```

### Response Example
(See Response Structure above for details of the 48-byte buffer populated by this function.)

### Error Handling
- This function does not set the Carry Flag on error. However, fields within the response structure may be set to `0FFFFFFFFh` if they are not supported by the DPMI host.
```

--------------------------------

### Building DOS/32A with Docker

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Instructions for building DOS/32A using a Docker image with a headless DOSBox environment.

```APIDOC
## Building DOS/32A with Docker

### Description
This section provides instructions for building DOS/32A using Docker, which utilizes a headless DOSBox environment. This is useful for automated builds or environments without direct DOSBox installation.

### Build Docker Image

```bash
# Build the Docker image (Debian + dosbox + xauth)
docker build -t dos32a .
```

### Run Headless Build

```bash
# Run the headless build; output DOS32ANG.EXE appears in the current directory
docker run -it -v ${PWD}/:/app/ dos32a --rm dosbox.sh
```

### Expected Output File

- `./DOS32ANG.EXE`
```

--------------------------------

### Build DOS/32A with Docker

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Builds the DOS/32A extender using a Docker image containing DOSBox for headless execution. The output executable DOS32ANG.EXE will appear in the current directory.

```bash
# Build the Docker image (Debian + dosbox + xauth)
docker build -t dos32a .

# Run the headless build; output DOS32ANG.EXE appears in the current directory
docker run -it -v ${PWD}/:/app/ dos32a --rm dosbox.sh

# Expected output file after build:
#   ./DOS32ANG.EXE
```

--------------------------------

### Build DOS/32A with Docker

Source: https://github.com/yetmorecode/dos32a-ng/blob/main/README.md

Build the project using Docker for a consistent and isolated environment. This command builds the Docker image and then runs a container to perform the build process.

```bash
$ docker build -t dos32a .
$ docker run -it -v ${PWD}/:/app/ dos32a --rm dosbox.sh
```

--------------------------------

### Build DOS/32A Directly in DOSBox

Source: https://github.com/yetmorecode/dos32a-ng/blob/main/README.md

Build the project directly within a DOSBox environment by mounting the repository and running the make.bat script. This method is suitable for users with DOSBox set up.

```dosbatch
mount d ~/git/dos32a-ng
D:
make.bat
```

--------------------------------

### Building DOS/32A with TASM 4+

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Instructions and commands for building DOS/32A directly within DOSBox using TASM 4+ and TLINK.

```APIDOC
## Building DOS/32A with TASM 4+

### Description
This section details how to build the DOS/32A extender using TASM 4+ and TLINK within a DOSBox environment. It includes the necessary batch commands and the underlying TASM/TLINK invocations.

### Build Commands

```bat
; Mount and navigate to the repository root inside DOSBox
mount d ~/git/dos32a-ng
D:
make.bat
```

### Underlying TASM/TLINK Invocations

```bat
tasm32 /dEXEC_TYPE=0 /m /ml /c /la kernel.asm
tasm32 /dEXEC_TYPE=0 /m /ml /c /la dos32a.asm
tlink /3 dos32a kernel,DOS4GW.exe
```

### Output

- `DOS4GW.EXE` (drop-in DOS/4GW replacement) is generated in the repository root.
```

--------------------------------

### Build DOS/32A with TASM 4+ in DOSBox

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Builds the DOS/32A extender using TASM 4+ and TLINK within a DOSBox environment. Assumes the repository is mounted and make.bat is executed.

```bat
; Mount and navigate to the repository root inside DOSBox
mount d ~/git/dos32a-ng
D:
make.bat

; The underlying TASM/TLINK commands performed by make.bat:
tasm32 /dEXEC_TYPE=0 /m /ml /c /la kernel.asm
tasm32 /dEXEC_TYPE=0 /m /ml /c /la dos32a.asm
tlink /3 dos32a kernel,DOS4GW.exe

; Output: DOS4GW.EXE (drop-in DOS/4GW replacement) in the repository root
```

--------------------------------

### Execute Program (INT 21h AH=4Bh AL=00h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Loads and executes a child program with a command line from protected mode. DOS/32A handles environment copying and requires minimal DOS Transfer Buffer space. Check the carry flag (CF) for success or failure.

```asm
; Spawn CHILD.EXE with a command line from protected mode

; Parameter block for INT 21h AH=4Bh AL=00h (WATCOM/DPMI convention)
EXEC_PARM STRUC
  ep_env_sel  DW 0        ; 0 = inherit parent environment
  ep_env_off  DW 0
  ep_cmd_off  DD ?        ; offset of command-line string (length byte + text + CR)
  ep_cmd_sel  DW ?        ; selector of command-line string
  ep_fcb1_off DD 0
  ep_fcb1_sel DW 0
  ep_fcb2_off DD 0
  ep_fcb2_sel DW 0
EXEC_PARM ENDS

child_path  DB  "C:\CHILD.EXE", 0       ; ASCIIZ path
child_cmd   DB  05h, " arg1", 0Dh       ; length byte, args, CR

        lea     edx, [child_path]       ; DS:EDX -> ASCIIZ path
        lea     ebx, [exec_parm]
        mov     [exec_parm.ep_cmd_off], offset child_cmd
        push    ds
        pop     word ptr [exec_parm.ep_cmd_sel]

        push    ds
        pop     es                      ; ES:EBX -> parameter block
        mov     ah, 4Bh
        mov     al, 00h                 ; sub-function: load & execute
        int     21h
        jc      spawn_fail              ; EAX = DOS error code on failure
        ; CF clear: child ran and returned to DOS, parent resumes here
        jmp     spawn_done

spawn_fail:
        ; EAX = 0FFFFFFFFh if not enough DOS mem for environment
        ; EAX = standard DOS error code otherwise
spawn_done:

```

--------------------------------

### DOS/32A High Memory Allocation (INT 21h, 0FF90h-0FF92h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Demonstrates how to query the largest free high memory block, allocate a block of a specified size, and free a previously allocated block using DOS/32A extended functions.

```APIDOC
## DOS/32A Extended Functions 0FF90h–0FF92h — High Memory Alloc/Free (INT 21h)

Simplified extended-memory allocation functions that mirror DPMI 0500h/0501h/0502h but use 32-bit registers directly (no 16:16 register pairs). `0FF90h` returns the size of the largest free block; `0FF91h` allocates; `0FF92h` frees.

### Query Free Extended Memory

- **Function**: `AX = 0FF90h`
- **Call**: `INT 21h`
- **Returns**: `EAX` = size of largest free block in bytes

### Allocate High Memory Block

- **Function**: `AX = 0FF91h`
- **Parameter**: `EBX` = desired block size in bytes
- **Call**: `INT 21h`
- **On Success (CF=0)**: `EBX` = 32-bit linear address of allocated block, `ESI` = handle
- **On Failure (CF=1)**: No allocation occurs.

### Free High Memory Block

- **Function**: `AX = 0FF92h`
- **Parameter**: `ESI` = handle of the block to free
- **Call**: `INT 21h`
- **On Success (CF=0)**: Block is freed.

### Example Usage

```asm
; Check free memory, allocate 2 MB, use it, then free it

        ; --- Query free extended memory ---
        mov     ax, 0FF90h      ; DOS/32A: Get Free High Memory Info
        int     21h
        ; EAX = size of largest free block in bytes
        mov     [free_mem], eax

        ; --- Allocate 2 MB extended block ---
        mov     ax, 0FF91h      ; DOS/32A: Allocate High Memory Block
        mov     ebx, 200000h    ; 2 MB in bytes
        int     21h
        jc      hm_fail         ; CF set on failure

        ; CF clear:
        ; EBX = 32-bit linear address of allocated block
        ; ESI = handle (save for free)
        mov     [hm_linear], ebx
        mov     [hm_handle], esi

        ; Set up a selector to access the block (use DPMI 0000h/0007h/0008h)
        ; ... (see DPMI 0501h example above for selector setup) ...

        ; --- Free the block ---
        mov     ax, 0FF92h      ; DOS/32A: Free High Memory Block
        mov     esi, [hm_handle]
        int     21h             ; CF clear on success
        jmp     hm_done

hm_fail:
        ; Not enough extended memory available
hm_done:
```
```

--------------------------------

### Allocate Memory Block (DPMI 0501h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Allocates a block of linear extended memory and sets up a flat selector for it. Requires subsequent calls to DPMI 0000h, 0007h, and 0008h to configure the selector. The allocated block can be freed using DPMI 0502h.

```asm
; Allocate a 1 MB extended memory block and set up a flat selector for it

        ; Request 1 MB (00100000h bytes): BX:CX = high:low word
        mov     bx, 0010h       ; high word of size
        mov     cx, 0000h       ; low word of size  -> 0x00100000 bytes
        mov     ax, 0501h       ; DPMI: Allocate Memory Block
        int     31h
        jc      mem_fail        ; AX=8012h/8013h/8014h/8016h on error

        ; BX:CX = linear address (e.g., BX=0020h, CX=0000h -> 0x00200000)
        ; SI:DI = memory block handle (save for resize/free)
        shl     ebx, 16
        or      ebx, ecx        ; EBX = 32-bit linear address
        mov     [block_linear], ebx
        shl     esi, 16
        or      esi, edi
        mov     [block_handle], esi

        ; Allocate a selector and configure it to cover the block
        mov     ax, 0000h       ; Allocate Descriptor
        mov     cx, 1
        int     31h
        jc      mem_fail
        mov     [block_sel], ax

        mov     ax, 0007h       ; Set Segment Base Address
        mov     bx, [block_sel]
        mov     cx, word ptr [block_linear+2]   ; high word of base
        mov     dx, word ptr [block_linear]     ; low word of base
        int     31h

        mov     ax, 0008h       ; Set Segment Limit
        mov     bx, [block_sel]
        mov     cx, 000Fh       ; high word of limit (1 MB - 1 = 0x000FFFFF)
        mov     dx, 0FFFFh
        int     31h

        ; Free the block when done (DPMI 0502h)
        mov     ax, 0502h
        mov     si, word ptr [block_handle+2]
        mov     di, word ptr [block_handle]
        int     31h
        jmp     mem_done

mem_fail:
        ; AX = 8012h linear mem unavailable
        ;      8013h physical mem unavailable
        ;      8014h backing store unavailable
        ;      8016h handle unavailable
mem_done:

```

--------------------------------

### Allocate Real Mode Callback Address (DPMI 0303h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Use this function to create a real-mode thunk that calls a protected-mode procedure. Ensure a 32-byte real-mode register buffer is allocated in DOS memory. The resulting real-mode segment:offset is returned in CX:DX.

```assembly
; Register a protected-mode callback so a real-mode ISR can call into PM

        ; DS:ESI -> protected-mode callback procedure
        ; ES:EDI -> 32h-byte real-mode register buffer (allocated in DOS mem)
        lea     esi, [pm_callback_proc]
        push    ds
        pop     ds                      ; DS:ESI = our PM procedure

        ; Allocate a 50-byte DOS memory block for the register save area
        mov     ax, 0100h
        mov     bx, 4                   ; 4 paragraphs = 64 bytes
        int     31h
        jc      cb_fail
        mov     [rm_regs_sel], dx       ; PM selector for the buffer
        movzx   edi, ax
        shl     edi, 4                  ; linear address of buffer

        mov     ax, 0303h               ; Allocate Real Mode Callback Address
        push    ds
        pop     ds                      ; DS:ESI already set
        push    ds
        pop     es
        lea     edi, [rm_regs_buffer]   ; ES:EDI -> register save buffer
        int     31h
        jc      cb_fail                 ; AX=8015h if no callbacks available

        ; CX:DX = real-mode seg:off of the callback thunk
        ; Pass CX:DX to real-mode code (e.g., install as interrupt vector via 0201h)
        mov     [cb_seg], cx
        mov     [cb_off], dx

        ; Free callback when done (DPMI 0304h)
        mov     ax, 0304h
        mov     cx, [cb_seg]
        mov     dx, [cb_off]
        int     31h
        jmp     cb_done
cb_fail:
cb_done:
```

--------------------------------

### DOS/32A High Memory Allocation/Free (INT 21h)

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Use 0FF90h to query the largest free block, 0FF91h to allocate a block, and 0FF92h to free it. Allocation returns a linear address and a handle; freeing requires the handle. Ensure the carry flag (CF) is checked after allocation to detect failures.

```asm
; Check free memory, allocate 2 MB, use it, then free it

        ; --- Query free extended memory ---
        mov     ax, 0FF90h      ; DOS/32A: Get Free High Memory Info
        int     21h
        ; EAX = size of largest free block in bytes
        mov     [free_mem], eax

        ; --- Allocate 2 MB extended block ---
        mov     ax, 0FF91h      ; DOS/32A: Allocate High Memory Block
        mov     ebx, 200000h    ; 2 MB in bytes
        int     21h
        jc      hm_fail         ; CF set on failure

        ; CF clear:
        ; EBX = 32-bit linear address of allocated block
        ; ESI = handle (save for free)
        mov     [hm_linear], ebx
        mov     [hm_handle], esi

        ; Set up a selector to access the block (use DPMI 0000h/0007h/0008h)
        ; ... (see DPMI 0501h example above for selector setup) ...

        ; --- Free the block ---
        mov     ax, 0FF92h      ; DOS/32A: Free High Memory Block
        mov     esi, [hm_handle]
        int     21h             ; CF clear on success
        jmp     hm_done

hm_fail:
        ; Not enough extended memory available
hm_done:

```

--------------------------------

### DPMI Function 0000h — Allocate Descriptors

Source: https://context7.com/yetmorecode/dos32a-ng/llms.txt

Details on how to use DPMI Function 0000h via INT 31h to allocate one or more descriptors in the client's LDT.

```APIDOC
## DPMI Function 0000h — Allocate Descriptors (INT 31h)

### Description
Allocates one or more descriptors in the client's LDT. Each allocated descriptor is initialized as a data descriptor with base=0 and limit=0. Applications must configure these descriptors further using subsequent DPMI calls (e.g., 0007h Set Segment Base, 0008h Set Segment Limit).

### Method

`INT 31h` with `AX = 0000h`

### Parameters

#### Input

- `AX` (0000h): Function number for Allocate Descriptors.
- `CX`: Number of contiguous descriptors to allocate.

#### Output

- `CF` (Carry Flag):
  - Set on error. `AX` will contain `8011h` if no descriptors are available.
  - Clear on success.
- `AX`:
  - On success: Base selector of the first allocated descriptor.
  - On error: Error code (e.g., `8011h`).

### Notes

- The selector increment value (typically 8) can be obtained using DPMI function 0003h (Get Selector Increment Value).

### Request Example (Assembly)

```asm
; Allocate 2 descriptors via INT 31h AX=0000h

    mov     ax, 0000h       ; DPMI: Allocate Descriptors
    mov     cx, 2           ; request 2 contiguous descriptors
    int     31h
    jc      alloc_failed    ; CF set on error (AX = 8011h if none available)

    ; AX = base selector of first descriptor
    ; selector increment = value returned by DPMI fn 0003h (Get Selector Increment Value)
    mov     [sel1], ax      ; save first selector
    add     ax, 8           ; typical increment = 8 (RPL 0, GDT bit clear, index +1)
    mov     [sel2], ax      ; save second selector
    jmp     alloc_done

alloc_failed:
    ; AX = 8011h  descriptor unavailable
    mov     [error_code], ax

alloc_done:
```
```
Tokens:
Raw