[Front] [Prev Chapter] [Next Chapter]

Chapter 2 - Multitasker API

Contents of this chapter

General Information
Installation Check
Functions

General Information

 Real mode applications call the multitasker's native API via the general-purpose INT 2F Multiplex Interrupt, with the multitasker being specified by the value 2780H (hex) in register AX.

NOTE: For brevity, the value AX=2780H is not listed in the entry parameters for each function.

The value in register CX identifies the individual functions, with CL being the module number (see Table 2-1) and CH the function within a module. The first call you make must be the Installation Check (see "Installation Check" on page 2-14), to verify that the multitasker is present.

Many of the INT 2F / AX=2780H calls take parameters in other registers. Some of these use the 32-bit general purpose registers. This should cause you no difficulty so long as you direct the assembler to accept 32-bit registers and operands. Parameters that are pointers are sometimes passed as 32-bit linear addresses, not segment:offset pairs. You can convert a segment:offset pair to a linear address by calculating segment*16+offset.

All functions return with the carry flag (CF) clear and CX=0 if successful, otherwise with CF set and the error code in CX. Values returned in EBX are copied into EAX, so you may use either register. All functions preserve the values in all other registers and flags. Where DS:EDX is used to point to a parameter block, we use [EDX] to mean "the memory pointed to by EDX."

The function names are equated to their values in the supplied assembly language include file FUNCTION.DEF, summarized in the following tables.

Error codes are equated in ERR.DEF and listed in Table A-1 on page A-1. INT 2FH with AX=2780H and an illegal module number or function number in CX will return an error code of E_BadModule or E_NotImplemented respectively.

The following tables list all the functions within each module, ordered by module number and function group. Within each table, functions are ordered alphabetically.
Table 2-1
Multitasker Module Numbers
CL Hex

 Module

01

 Supervisor (SUP)

02

 Real Time Monitor (RTM)

03

 Memory (MEM)

04

 Domains (DOM)

05

 Virtual Machines (VM)

Table 2-2
SUP Functions
CX Hex

 Function Name

 What it does

 Page

1101

 Installation check

 Check if multitasker installed

 2-14

0201

 Z_ModuleReg

 Register OS Module

 2-112

0501

 Z_MoveReal

 Move from real memory to extended memory

 2-114

0601

 Z_Reboot

 Reboot

 2-198

Table 2-3
RTM Process Functions
CX Hex

 Function

 What it does

 Page

2502

 X_CritEnter

 Enter Critical Region

 2-15

2602

 X_CritExit

 Exit Critical Region

 2-17

0102

 Z_PCountGet

 Get count of dispatches

 2-125

0E02

 X_PCreate

 Create a new process

 2-126

0B02

 X_PDelay

 Go to sleep for some clock ticks

 2-130

0C02

 X_PDispatch

 Force a dispatch

 2-131

1002

 X_PHandleGet

 Get my process handle

 2-132

2802

 Z_PHandleListGet

 Get list of process handles

 2-133

2902

 Z_PNameGet

 Get a process' name

 2-135

2C02

 Z_PPriorGet

 Get this process' priority

 2-136

0F02

 Z_PPriorSet

 Set this process' priority

 2-132

2A02

 Z_PStatusGet

 Get a process' status

 2-138

2302

 X_PSuspend

 Suspend a process

 2-140

1102

 X_PTerm

 Terminate a process

 2-141

1702

 X_PTermOff

 Disable terminating

 2-143

1802

 X_PTermOK

 Reenable terminating

 2-144

2402

 X_PUnsuspend

 Release a process

 2-145

3D02

 X_TickGet

 Get clock tick period

 2-213

3C02

 Z_TicksSet

 Set foreground slices

 2-214

Table 2-4
RTM Queue Functions
CX Hex

 Function

 What it does

 Page

3F02

 X_QClose

 Close a queue

 2-172

0402

 X_QCreate

 Create a new queue

 2-173

0602

 X_QDelete

 Delete a queue

 2-176

3402

 Z_QFlagsGet

 Get a queue's flags

 2-179

4502

 Z_QFlagsSet

 Set a queue's flags

 2-179

2D02

 Z_QHandleListGet

 Get a list of queue handles

 2-180

2F02

 X_QMsgLenGet

 Get a queue's message length

 2-182

3002

 X_QMsgMaxGet

 Get a queue's message capacity

 2-183

3302

 X_QMsgNumGet

 Get the number of messages in a queue

 2-184

2E02

 Z_QNameGet

 Get a queue's name

 2-133

0502

 X_QOpen

 Open a queue for read/write

 2-188

0702

 X_QRead

 Read a message from a queue

 2-189

0802

 X_QReadC

 Read a message if there is one

 2-191

1F02

 X_QReadNDC

 Peek at a message if there is one

 2-192

3202

 Z_QReaderGet

 Get handle of process waiting to read

 2-193

0902

 X_QWrite

 Write a message to a queue

 2-194

0A02

 X_QWriteC

 Write a message if there is space

 2-196

3102

 Z_QWriterGet

 Get handle of process waiting to write

 2-197

Table 2-5
RTM Mutex Functions
CX Hex

 Function

 What it does

 Page

3702

 X_MXCreate

 Create a new mutex

 2-92

3802

 X_MXDelete

 Delete a mutex

 2-94

3902

 X_MXEnter

 Enter a mutex zone

 2-95

3A02

 X_MXEnterC

 Enter a mutex zone if it is free

 2-97

3B02

 X_MXExit

 Exit from a mutex zone

 2-98

Table 2-6
RTM Flag Functions
CX Hex

 Function

 What it does

 Page

1C02

 Z_FlagAlloc

 Allocate a flag

 2-40

1D02

 Z_FlagFree

 Free a flag

 2-41

0302

 Z_FlagSet

 Set a flag

 2-42

1902

 Z_FlagStatusGet

 Return status of a flag

 2-43

0202

 Z_FlagWait

 Wait on a flag

 2-44

2002

 Z_FlagWWTO

 Wait with a timeout

 2-45

1E02

 X_FlagsMaxGet

 Return number of flags supported

 2-46

Table 2-7
MEM Functions
CX Hex

 Function

 What it does

 Page

1003

 Z_DescAlloc

 Allocate a descriptor

 2-18

1103

 Z_DescFree

 Release a descriptor

 2-21

1203

 Z_DescGet

 Get a descriptor's details

 2-22

1303

 Z_DescSet

 Set a descriptor

 2-23

2F03

 Z_GateAlloc

 Allocate a gate

 2-50

3003

 Z_GateFree

 Release a gate

 2-52

0C03

 Z_MemAlloc

 Allocate a memory block

 2-99

1403

 Z_MemDescAlloc

 Allocate a memory block and its descriptor

 2-101

1503

 Z_MemDescFree

 Release a memory block and its descriptor

 2-103

1703

 Z_MemDescResize

 Resize a block

 2-104

1603

 Z_MemDescSizeGet

 Get size of a block

 2-105

0D03

 Z_MemFree

 Release a memory block

 2-106

3103

 X_MemFreeGet

 Get total free memory

 2-107

0F03

 Z_MemResize

 Resize a block

 2-108

0E03

 Z_MemSizeGet

 Get size of a block

 2-109

3203

 X_MemTopGet

 Get top memory address

 2-110

3303

 X_MemTotalGet

 Get total memory size

 2-111

0303

 Z_PageAlloc

 Allocate a given page

 2-146

2903

 Z_PageDomLock

 Lock a page in a specified domain, with existing contents

 2-147

2B03

 Z_PageDomLockAny

 Lock a page in a specified domain, with undefined contents

 2-148

2D03

 Z_PageDomLockNone

 Lock a page in a specified domain, with no physical memory

 2-149

2A03

 Z_PageDomUnlock

 Unlock a page in a specified domain

 2-150

2E03

 Z_PageDomUnlockNone

 Unlock a page in a specified domain, physical memory not reused

 2-151

2C03

 Z_PageDomUnlockReuse

 Unlock a page in a specified domain, physical memory reused

 2-152

0B03

 Z_PageFree

 Free a page of memory

 2-153

1803

 Z_PageLock

 Lock a page, with existing contents

 2-154

1A03

 Z_PageLockAny

 Lock a page, with undefined contents

 2-155

1C03

 Z_PageLockNone

 Lock a page, with no physical memory

 2-156

1903

 Z_PageUnlock

 Unlock a page

 2-157

1D03

 Z_PageUnlockNone

 Unlock a page, physical memory not reused

 2-158

1B03

 Z_PageUnlockReuse

 Unlock a page, physical memory reused

 2-159

0A03

 Z_PagesAlloc

 Allocate memory pages

 2-160

0803

 Z_PtblGet

 Read page table

 2-170

0903

 Z_PtblSet

 Write page table

 2-171

Table 2-8
DOM Functions
CX Hex

 Function

 What it does

 Page

1504

 Z_DomFork

 Copy this domain

 2-24

2B02

 Z_DomHandleGet

 Get a process' domain

 2-25

0204

 X_DomHandleGetMy

 Get current domain handle

 2-26

2604

 X_DomMemFreeGet

 Get a domain's free memory

 2-27

2804

 Z_DomMemMaxGet

 Get per-domain memory limit

 2-28

2904

 Z_DomMemMaxSet

 Set per-domain memory limit

 2-29

0D04

 Z_DomMemRead

 Read memory in another domain

 2-30

2704

 X_DomMemUsedGet

 Get memory used by this domain

 2-32

0E04

 Z_DomMemWrite

 Write to memory in another domain

 2-33

1204

 X_DomNProcessesGet

 Get number of processes in domain

 2-34

2104

 Z_DomRootProcessGet

 Get handle of domain's root process

 2-35

1304

 Z_DomSuspend

 Suspend a domain

 2-36

1604

 Z_DomTerm

 Terminate all processes in a domain

 2-37

1404

 Z_DomUnsuspend

 Resume process execution in a domain

 2-38

1D04

 Z_EndOfInterrupt

 Signal EOI

 2-39

0801

 X_ForeCheck

 Check if domain is in foreground

 2-47

0B05

 X_ForeGet

 Get foreground domain

 2-49

0704

 Z_HandlerGenEx

 Install general exception handler

 2-53

0804

 Z_HandlerHWInt

 Install HW int handler

 2-59

1804

 Z_HandlerHWIntDflt

 Install default HW int handler

 2-61

0604

 Z_HandlerIOEx

 Install I/O exception handler

 2-62

1F04

 Z_HandlerPCreate

 Install process create handler

 2-65

2004

 Z_HandlerPTerm

 Install process terminate handler

 2-68

0504

 Z_HandlerPageFault

 Install page fault handler

 2-70

0404

 Z_HandlerSWInt

 Install SW int handler

 2-72

1B04

 Z_HandlerSwapIn

 Install swap in handler

 2-74

1C04

 Z_HandlerSwapOut

 Install swap out handler

 2-76

1704

 Z_HandlerUnlink

 Uninstall a handler

 2-78

1904

 Z_HandlerVHWInt

 Install virtual HW int handler

 2-79

1A04

 Z_HandlerVHWIntDflt

 Install default virtual HW int handler

 2-81

0B04

 Z_IOBitmapDomGet

 Get a domain's I/O Bitmap entry

 2-83

0C04

 Z_IOBitmapDomSet

 Set a domain's I/O Bitmap entry

 2-85

0904

 Z_IOBitmapGet

 Get the current domain's I/O Bitmap entry

 2-87

0A04

 Z_IOBitmapSet

 Set the current domain's I/O Bitmap entry

 2-88

1104

 Z_InstanceSet

 Register instanced addresses

 2-89

0F04

 Z_PtblDomGet

 Read a domain's Page Table

 2-167

1004

 Z_PtblDomSet

 Write a domain's Page Table

 2-169

Table 2-9
VM Functions
CX Hex

 Function

 What it does

 Page

1505

 X_MsgDomEnter

 Enter Domain Message Mode

 2-115

1605

 X_MsgDomDisplay

 Display message

 2-117

1705

 X_MsgDomExit

 Exit mode

 2-119

1805

 Z_MsgFatalDisplay

 Display message

 2-120

1205

 X_MsgGlobalEnter

 Enter Global Message Mode

 2-123

1305

 X_MsgGlobalDisplay

 Display message

 2-121

1405

 X_MsgGlobalExit

 Exit mode

 2-124

1A05

 Z_ParallelBaseSet

 Set port address

 2-161

1C05

 Z_ParallelIRQSet

 Set port IRQ

 2-162

2305

 Z_ParallelOwnerGet

 Get port owner

 2-163

2405

 Z_ParallelTimeoutGet

 Get port timeout

 2-164

0F05

 Z_ParallelTimeoutSet

 Set port timeout

 2-165

1905

 Z_SerialBaseSet

 Set port address

 2-199

1B05

 Z_SerialIRQSet

 Set port IRQ

 2-200

2105

 Z_SerialOwnerGet

 Get port owner

 2-201

2205

 Z_SerialTimeoutGet

 Get port timeout

 2-202

0E05

 Z_SerialTimeoutSet

 Set port timeout

 2-203

0A05

 Z_TMHotKeyDisable

 Stop scanning

 2-205

0905

 Z_TMHotKeyEnable

 Restart scanning

 2-206

0805

 Z_TMHotKeyGet

 Get task manager key

 2-207

0705

 Z_TMInit

 Initialize task manager

 2-209

0105

 Z_TMLoad

 Load task manager

 2-211

0205

 Z_TMUnload

 Unload task manager

 2-212

0305

 Z_VMBackSet

 Send VM to back

 2-215

0405

 Z_VMForeSet

 Send VM to front

 2-216

0605

 Z_VMSaveDisable

 Disable saving VM

 2-217

0505

 Z_VMSaveEnable

 Enable saving VM

 2-218

Table 2-10
Other INT 2FH Functions
AX Hex

 Function

 What it does

 Page

1680

 Release Time Slice

 Same as X_PDispatch

 2-131

1681

 Enter Critical Region

 Enter Critical Section Mutex

 2-15

1682

 Exit Critical Region

 Exit Critical Section Mutex

 2-17

1683

Get VM ID

1684

Get VxD API entry point

1685

Call a function in a different VM

2700

 Task Manager Install Check

 Task manager

 1-26

2701

 Task Manager Status

 Task manager

 1-26

2702

 Get EMS limit per task

 Task manager

 1-26

2703

 Set EMS limit per task

 Task manager

 1-26

2705

 Enable/disable direct switching

 Task manager

 1-26

2706

 Switch Tasks

 Task manager

 1-26

2707

 Create Task

 Task manager

 1-26

2708

 Delete Task

 Task manager

 1-26

270A

 Get Task ID

 Task manager

 1-26

270B

 Get Task Index

 Task manager

 1-26

4B02

 Switcher Install Check

 Return entry point of Switcher Service Function

4B03

Allocate a switcher ID

4B04

Free a switcher ID

Table 2-11
Switcher Service Functions (called through Switcher Service Functions entry point)
AX Hex

 Function

 What it does

0000

 Get version

 Return version information

0001

 Test memory

 Return local/global information

0002

 Suspend

 Refuse to suspend

0003

 Resume

 Nothing

0004

 Hook Notification Chain

 Ask switcher to inform it of session switches

0005

 Unhook

 Reverse of above

0006

 Query API Support

 Find who else is out there

Table 2-12
INT 2FH Functions called by the Task Manager
AX Hex

 Function

 What it does

4B01

 Build Notification Chain

 Ask global programs to identify themselves. Tells them the entry point of the Switcher Service Function

4B05

 Identify Instance Data

 Ask global programs to identify their instance data

Table 2-13
Notification Functions called by the Task Manager
EAX Hex

 Function

 What it does

0000

 Initialize switcher

 Warn of, and ask if OK to, start task switcher

0003

 Activate session

 Warn of session switch (interrupts off)

0004

 Session active

 Warn of session switch (interrupts on)

0005

 Create session

 Ask if OK to create a session

0006

 Destroy session

 Warn that a session is being deleted

0007

 Terminate switcher

 Warn that switcher terminating

Installation Check

Function

 Check whether the multitasker is resident.

Entry Parameters
Register

 Value

AX

 2780H

CX

 1101H

Returned Values
Register

 Value

CX

 00H - Multitasker resident
1101H - Multitasker not resident

EBX

 Version (if CX=0)

Explanation

 The Installation Check call must be the first one you make, because other Multitasker functions can only be accessed if the multitasker is resident.

If the multitasker is present, its version number is returned in BX. The initial release is version 1.00, corresponding to the value 0100H in BX.

X_CritEnter (2502H)

Function

 Enter a critical region.

Entry Parameters
Register

 Value

CX

 2502H

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
3EH - E_CritOverrun

>255 CritEnters

Explanation

 X_CritEnter disables the dispatcher, so no other process can run until you make a corresponding X_CritExit call. Interrupt service routines can run, however.

You can call X_CritEnter again while inside a critical region. If you do, you must call X_CritExit the same number of times you called X_CritEnter. The system maintains a count of the number of times you have entered, and only allows other processes to run when it reaches zero again.

The only error possible is that the count may overflow and generate the E_CritOverrun error.

Critical regions are similar to mutexes, but should be used only for truly time-critical operations, because they completely disable all other processes. While your process is in a critical region, it can call other system functions, but it cannot suspend or terminate itself. If it calls functions to do either of these they will not take effect until after the X_CritExit call.

See Also: X_CritExit, X_MXCreate

NOTE: The industry-standard call INT 2FH / AX=1681H is also supported by the multitasker, and is the preferred method.

X_CritExit (2602H)

Function

 Exit from a critical region.

Entry Parameters
Register

 Value

CX

 2602H

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
3DH - E_CritUnderrun

No CritEnter

Explanation

 X_CritExit re-enables the dispatcher if called the same number of times as X_CritEnter. Call X_CritExit after completing the operation protected by X_CritEnter. If the clock has ticked since you called X_CritEnter, the dispatcher will be called immediately.

If you were not in a critical region when you called X_CritExit, it returns an E_CritUnderrun error.

See Also: X_CritEnter

NOTE: The industry-standard call INT 2FH / AX=1682H is also supported by the multitasker, and is the preferred method.

Z_DescAlloc (1003H)

Function

 Allocate a descriptor.

Entry Parameters
Register

 Value

CX

 1003H

DS:EDX

 Pointer to a Descriptor Parameter Block; see "Explanation"

Returned Values
Register

 Value

 Meaning

EBX

 =DESC_PB_SEL

 Selector

ECX

 Error code:
00H - No error
31H - E_BadDesc
32H - E_NoDesc

Invalid DESC_PB_SINFO
No free descriptors

DS:[EDX]

 DESC_PB_SEL

 Selector

Explanation

 Z_DescAlloc allocates a protected mode memory descriptor and returns its selector. Applications and device drivers should normally allocate their descriptors through a higher level interface: XMS or DPMS.

The parameter block is defined in STRUCS.DEF as follows:.
DESC_PBLK

 struc

DESC_PB_BASE

 dd

 ?

DESC_PB_LIMIT

 dd

 ?

DESC_PB_SEL

 dw

 ?

DESC_PB_MINFO

 db

 ?

DESC_PB_SINFO

 db

 ?

DESC_PBLK

 ends

Before you call Z_DescAlloc, you must initialize all fields in DESC_PBLK except DESC_PB_MINFO and DESC_PB_SEL, which will be filled with the selector of the allocated descriptor when the function returns successfully. If the size exceeds 1 MB, the granularity will be set to 4 KB, otherwise the segment will have byte granularity. In either case, the DESC_PB_LIMIT you supply must be the limit (size-1) in bytes.

DESC_PB_MINFO is a packed flag byte. It is not used by Z_DescAlloc, but is used by related calls which share the same DESC_PBLK parameter block. The bits have the following meanings. Bits 6 and 7 should be reset.
Bit

 Reset

 Set

0

 Not 4 KB aligned

 4 KB aligned

1

 Not 64 KB aligned

 64 KB aligned

2

 Pageable to disk

 Locked

3

 Domain local

 Global

4

 User access

 System access only

5

 Memory present

 Empty address space required

DESC_PB_SINFO is also a packed flag byte. The bits have the following meanings. Other bits must be reset.
Bit

 Reset

 Set

0

 16-bit code or data

 32-bit code or data

1

 Data segment

 Code segment

4

 Allocate from LDT

 Allocate from LDT

5,6

 Privilege level

 Privilege level

Note that data segments are assumed to be writable and expand-up, and code segments to be non-conforming and readable. Call Z_DescFree to deallocate the descriptor when it is no longer needed.

See Also: Z_DescFree, Z_DescGet, Z_MemDescAlloc, Z_DescSet

Z_DescFree (1103H)

Function

 Release a descriptor.

Entry Parameters
Register

 Value

CX

 1103H

DS:EDX

 Pointer to a Descriptor Parameter Block; see "Z_DescAlloc (1003H)" on page 2-18

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
31H - E_BadDesc

Invalid selector

Explanation

 Z_DescFree releases a protected mode memory descriptor previously allocated by Z_DescAlloc or Z_MemDescAlloc. The parameter block is as described under Z_DescAlloc. Only the DESC_PB_SEL field need be filled in when you call Z_DescFree.

Note that freeing a descriptor renders its selector invalid. The selector must not be loaded into a segment register while the descriptor is freed, or reloaded at a later date.

See Also: Z_DescAlloc, Z_DescGet, Z_MemDescAlloc, Z_DescSet

Z_DescGet (1203H)

Function

 Get a descriptor's base, limit and flags.

Entry Parameters
Register

 Value

CX

 1203H

DS:EDX

 Pointer to a Descriptor Parameter Block; see "Z_DescAlloc (1003H)" on page 2-18

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
31H - E_BadDesc

Invalid selector

Explanation

 Z_DescGet returns a descriptor's base, limit and flags in the DESC_PBLK supplied by the caller. The parameter block is as described under Z_DescAlloc. Only the DESC_PB_SEL field need be filled in when you call Z_DescGet. The other fields will be filled in on return.

See Also: Z_DescAlloc, Z_MemDescAlloc, Z_DescSet

Z_DescSet (1303H)

Function

 Set a descriptor's base, limit and flags.

Entry Parameters
Register

 Value

CX

 1303H

DS:EDX

 Pointer to a Descriptor Parameter Block; see "Z_DescAlloc (1003H)" on page 2-18

Returned Values
Register

 Value

 Meaning

EBX

 Selector

ECX

 Error code:
00H - No error
31H - E_BadDesc

Invalid selector or DESC_PB_SINFO

Explanation

 Z_DescSet changes a descriptor's base, limit and flags to the values in the DESC_PBLK supplied by the caller. The parameter block is as described under Z_DescAlloc. You must fill in all its fields when you call Z_DescSet. The selector is unaffected by this call.

See Also: Z_DescAlloc, Z_DescGet, Z_MemDescAlloc

Z_DomFork (1504H)

Function

 Fork the current domain.

Entry Parameters
Register

 Value

CX

 1504H

DS:EDX

 Pointer to a PCREATE_PBLK parameter block; see "X_PCreate (0E02H)" on page 2-126

Returned Values
Register

 Value

 Meaning

EBX

 Handle

 Child domain's handle

CX

 Error code:
00H - No error
xxH - Error codes

See Table A-1 on page A-1

Explanation

 Z_DomFork creates an exact copy of the current domain, then creates a process in it and starts the process executing. The process is specified in the PCREATE_PBLK which is identical to that used in the X_PCreate call described on page 2-126.

Z_DomFork may fail at any stage, which requires a limited resource to be allocated. See Table A-1 on page A-1 for a full list of error codes.

See Also: Z_DomTerm, X_PCreate

Z_DomHandleGet (2B02H)

Function

 Get the domain of a specified process.

Entry Parameters
Register

 Value

CX

 2B02H

EDX

 Process handle

Returned Values
Register

 Value

 Meaning

EBX

 Domain handle

ECX

 Error code:
00H - No error
0BH - E_BadPHandle

Process handle is invalid

Explanation

 Z_DomHandleGet returns the handle of the domain that a specified process is in, given the process handle. The domain handle can be used in subsequent calls to the Domain Manager.

See Also: X_PCreate, X_PHandleGet, Z_PHandleListGet, Z_PNameGet, X_DomHandleGetMy

X_DomHandleGetMy (0204H)

Function

Get the current domain's handle.

Entry Parameters
Register

 Value

CX

 0204H

Returned Values
Register

 Value

 Meaning

EBX

 Handle

 Handle of calling process' domain

ECX

 Error code:
00H - No error

Explanation

 X_DomHandleGetMy returns the handle of the calling process' domain. This can then be used to call other functions in the Domain Module, although you can always pass a null handle (0) to imply "the current domain."

You can get the domain handle of another process, if you know its process handle, by calling Z_DomHandleGet.

See Also: Z_DomHandleGet

X_DomMemFreeGet (2604H)

Function

 Get free memory size for a specified domain.

Entry Parameters
Register

 Value

CX

 2604H

EDX

 Domain handle (0=current domain)

Returned Values
Register

 Value

 Meaning

EBX

 Free memory

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid domain handle

Explanation

 X_DomMemFreeGet returns the number of bytes the specified domain could allocate. This is equal to the Domain Memory Limit (see Z_DomMemMaxSet) minus the amount already allocated to the domain, or the total of free memory if that is lower.

See Also: Z_DomMemMaxGet, Z_DomMemMaxSet, X_DomMemUsedGet

Z_DomMemMaxGet (2804H)

Function

 Get the domain memory limit.

Entry Parameters
Register

 Value

CX

 2804H

Returned Values
Register

 Value

EBX

 Domain Memory Limit

ECX

 Error code:
00H - No error

Explanation

 Z_DomMemMaxGet returns the Domain Memory Limit. This is the global limit on the memory that any domain may use. Initially, this limit is set to all memory, but the task manager may reduce it, typically to allow badly-behaved applications which allocate all available memory to coexist.

See Also: X_DomMemFreeGet, Z_DomMemMaxSet, X_DomMemUsedGet

Z_DomMemMaxSet (2904H)

Function

 Set the domain memory limit.

Entry Parameters
Register

 Value

CX

 2904H

EDX

 New value for the Domain Memory Limit

Returned Values
Register

 Value

EBX

 Old limit

ECX

 Error code:
00H - No error

Explanation

 Z_DomMemMaxSet sets a new value for the Domain Memory Limit. This is used to limit allocations, including VCPI allocations, so that no one application can allocate all the physical memory.

The previous value of the limit is returned in EBX.

See Also: X_DomMemFreeGet, Z_DomMemMaxGet, X_DomMemUsedGet

Z_DomMemRead (0D04H)

Function

 Read memory in another domain.

Entry Parameters
Register

 Value

CX

 0D04H

DS:EDX

 Pointer to a BANKMEM_PBLK parameter block; see "Explanation"

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid domain handle

Explanation

 Z_DomMemRead allows programs running in one domain to read the memory of another domain. The related function Z_DomMemWrite allows them to write the memory of another domain.

You must supply all fields in the parameter block, which is defined as follows:
BANKMEM_PBLK

 struc

BANKM_PB_DOMAIN

 dd

 ?

BANKM_PB_LENGTH

 dd

 ?

BANKM_PB_SOURCE

 dd

 ?

BANKM_PB_DEST

 dd

 ?

BANKMEM_PBLK

 ends

X_DomMemUsedGet (2704H)

Function

 Get size of memory allocated to a specified domain.

Entry Parameters
Register

 Value

CX

 2704H

EDX

 Domain handle (0=current domain)

Returned Values
Register

 Value

 Meaning

EBX

 Allocated memory

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid domain handle

Explanation

 X_DomMemUsedGet returns the number of bytes allocated to the specified domain, including VCPI allocations.

See Also: X_DomMemFreeGet, Z_DomMemMaxGet, Z_DomMemMaxSet

Z_DomMemWrite (0E04H)

Function

 Write to memory in another domain.

Entry Parameters
Register

 Value

CX

 0E04H

DS:EDX

 Pointer to a BANKMEM_PBLK parameter block; see "Z_DomMemRead (0D04H)" on page 2-30

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid domain handle

Explanation

 Z_DomMemWrite allows programs running in one domain to write to the memory of another domain. The related function Z_DomMemRead allows them to read from the memory of another domain.

You must supply all fields in the BANKMEM_PBLK parameter block which is defined under Z_DomMemRead.

See Also: Z_DomMemRead

X_DomNProcessesGet (1204H)

Function

 Get the number of processes in a specified domain.

Entry Parameters
Register

 Value

CX

 1204H

EDX

 Domain handle (0=current domain)

Returned Values
Register

 Value

 Meaning

EBX

 Number

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid handle

Explanation

 X_DomNProcessesGet returns the current number of processes in the specified domain. The number includes all processes in all states.

As with other functions, you can pass a null domain handle to imply "the current domain."

See Also: X_PTerm, X_PCreate, Z_PHandleListGet

Z_DomRootProcessGet (2104H)

Function

 Get the handle of the root process in a specified domain.

Entry Parameters
Register

 Value

CX

 2104H

EDX

 Domain handle (0=current domain)

Returned Values
Register

 Value

 Meaning

EBX

 Process Handle

Error code:
00H - No error
36H - E_BadDomain

ECX

Invalid handle

Explanation

 Z_DomRootProcessGet returns the process handle of the root process in the specified domain. The root process is the process that was created when the domain was first created. All other processes in the same domain are its children or their descendents.

As with other functions, you can pass a null domain handle to imply "the current domain."

See Also: X_PCreate, X_DomNProcessesGet

Z_DomSuspend (1304H)

Function

 Suspend all processes in a specified domain.

Entry Parameters
Register

 Value

CX

 1304H

EDX

 Domain handle

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid handle

Explanation

 Z_DomSuspend calls X_PSuspend for each process in the specified domain. See X_PSuspend on page 2-140 for details. You can unsuspend all the suspended processes in a domain by calling Z_DomUnsuspend.

See Also: X_PSuspend, Z_DomUnsuspend

Z_DomTerm (1604H)

Function

 Terminate all processes in the specified domain.

Entry Parameters
Register

 Value

CX

 1604H

EDX

 Domain handle

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid handle

Explanation

 Z_DomTerm calls X_PTerm for each process in the specified domain. This terminates the processes.

See Also: X_PTerm

Z_DomUnsuspend (1404H)

Function

 Resume execution of all processes in a specified domain.

Entry Parameters
Register

 Value

CX

 1404H

EDX

 Domain handle (0=current domain)

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
36H - E_BadDomain

Invalid handle

Explanation

 Z_DomUnsuspend resumes execution of all the suspended processes in a domain. The processes may have been suspended by calls to X_PSuspend or Z_DomSuspend.

See Also: Z_DomSuspend, X_PSuspend

Z_EndOfInterrupt (1D04H)

Function

 Signal end of interrupt.

Entry Parameters
Register

 Value

CX

 1D04H

EDX

 Interrupt being cleared (0 to 0FH)

Returned Values
Register

 Value

ECX

 Error code:
00H - No error

Explanation

 Z_EndOfInterrupt must be called from level 0 hardware interrupt handlers which clear the In-Service bit of the Programmable Interrupt Controller (PIC).

See Also: Z_HandlerHWInt

Z_FlagAlloc (1C02H)

Function

 Allocate a flag.

Entry Parameters
Register

 Value

CX

 1C02H

Returned Values
Register

 Value

 Meaning

EBX

 Flag number

ECX

 Error code:
00H - No error
2DH - E_NoFlag

All flags allocated

Explanation

 Z_FlagAlloc allocates a flag, sets its initial state to Off, and returns the flag number. Some system flags are preallocated, but other flags must all be allocated from the pool.

There is a very limited number of flags available (normally 256), so use them sparingly.

When you no longer need a flag, you can free it by calling Z_FlagFree.

See Also: Z_FlagFree, X_FlagsMaxGet, Z_FlagSet, Z_FlagStatusGet, Z_FlagWait

Z_FlagFree (1D02H)

Function

 Release a flag.

Entry Parameters
Register

 Value

CX

 1D02H

EDX

 Flag number

Returned Values
Register

 Value

 Meaning

EBX

 Flag number

ECX

 Error code:
00H - No error
04H - E_BadFlag
2EH - E_FlagBusy

No such flag
Flag in use

Explanation

 Z_FlagFree releases a flag, freeing it to be allocated to some other user.

Z_FlagFree will not free a flag that is set, or on which a process is waiting. You can call Z_FlagStatusGet to determine the flag's current status.

See Also: Z_FlagAlloc, X_FlagsMaxGet, Z_FlagSet, Z_FlagStatusGet, Z_FlagWait

Z_FlagSet (0302H)

Function

 Set a flag.

Entry Parameters
Register

 Value

CX

 0302H

EDX

 Flag number

Returned Values
Register

 Value

 Meaning

EBX

 Flag number

ECX

 Error code:
00H - No error
04H - E_BadFlag
05H - E_FlagOverrun

Invalid flag number
Overrun detected

Explanation

 Z_FlagSet sets a flag to indicate that a process waiting on the flag should immediately become ready to run.

If the flag was already set, the overrun counter is incremented and the error code E_FlagOverrun is returned to the ISR. The same code will be returned to the process that eventually calls Z_FlagWait.

See Also: Z_FlagStatusGet, Z_FlagWait, Z_FlagWWTO

Z_FlagStatusGet (1902H)

Function

 Return the status of a flag.

Entry Parameters
Register

 Value

CX

 1902H

EDX

 Flag number

Returned Values
Register

 Value

 Meaning

EBX

 Status:
00H - Unused
01H - Flag_Off
02H - Flag_On
>2 - Process handle
Unallocated
Unset
Set
Unset, process waiting

ECX

 Error code:
00H - No error
04H - E_BadFlag

Flag number too big

Explanation

 Z_FlagStatusGet returns the status of a specified flag. If the returned value is above 2 then there is a process waiting on the flag and the returned value is its handle.

See Also: Z_FlagAlloc, Z_FlagFree, X_FlagsMaxGet, Z_FlagSet, Z_FlagWait

Z_FlagWait (0202H)

Function

 Wait for a flag.

Entry Parameters
Register

 Value

CX

 0202H

EDX

 Flag number

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
04H - E_BadFlag
05H - E_FlagOverrun
06H - E_FlagUnderrun

Flag number too big
Flag has been set twice
Someone else is waiting

Explanation

 Z_FlagWait makes the calling process wait indefinitely until the specified flag has been set, unless it is already set, in which case the calling process can continue. Use the related function Z_FlagWWTO if you want to specify a timeout.

If, at the time of this call, the flag has been set two or more times, the error code E_FlagOverrun is returned. If another process is waiting on the flag, the code E_FlagUnderrun is returned.

The act of calling Z_FlagWait or Z_FlagWWTO resets the flag or decrements the overrun counter. If overrun has occurred, you must call Z_FlagWait or Z_FlagWWTO once for each Z_FlagSet there has been.

See Also: Z_FlagSet, Z_FlagWWTO

Z_FlagWWTO (2002H)

Function

 Wait, with a timeout, for a flag.

Entry Parameters
Register

 Value

EBX

 Timeout count in ticks

CX

 2002H

EDX

 Flag number

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
04H - E_BadFlag
05H - E_FlagOverrun
06H - E_FlagUnderrun
2FH - E_FlagTimeout

Flag number too big
Flag had been set twice
Someone else is waiting
Timeout. Flag not set

Explanation

 Z_FlagWWTO functions exactly as Z_FlagWait, except that if the flag remains unset after the specified number of clock ticks, then the process is restarted with the error code E_FlagTimeout. Timeouts from 0 to 65535 ticks may be specified.

If, at the time of this call, the flag has been set two or more times, the error code E_FlagOverrun is returned. If another process is waiting on the flag, the code E_FlagUnderrun is returned.

See Also: Z_FlagSet, Z_FlagWait

X_FlagsMaxGet (1E02H)

Function

 Return the number of flags in the system.

Entry Parameters
Register

 Value

CX

 1E02H

Returned Values
Register

 Value

 Meaning

EBX

 Number of flags

ECX

 Error code:
00H - No error
No error is possible

Explanation

 X_FlagsMaxGet returns the number of flags the system supports.

See Also: Z_FlagAlloc, Z_FlagFree, Z_FlagStatusGet

X_ForeCheck (0801H)

Function

 Check if in the foreground.

Entry Parameters
Register

 Value

CX

 0801H

Returned Values
Register

 Value

 Meaning

EBX

 00H
xxH

 Background
Foreground

ECX

 Error code:
00H - No error
No error is possible

Explanation

 Call X_ForeCheck if your application needs to know if it is running in the foreground. Only one domain is in the foreground at any instant. It owns the physical screen and is attached to the keyboard and mouse.

The user tells the task manager which task to bring to the foreground. The task manager in turn commands the VM and DOM modules to switch the selected domain into the foreground.

While running in the background, applications can read and write video memory and controllers (up to VGA resolution only), but the user will see nothing until they switch your application into the foreground.

If you wait for a keypress or mouse activity while in background, your application will be suspended until it is in the foreground again.

If, while running in the background, you urgently need to display a message to the user, you can call VM functions to do so. You cannot force your domain to the foreground, but you could ask the user to do so by pressing the appropriate task manager hot key combination.

See Also: X_ForeGet

X_ForeGet (0B05H)

Function

 Get the console owner's domain handle.

Entry Parameters
Register

 Value

CX

 0B05H

Returned Values
Register

 Value

 Meaning

EBX

 Handle

 Domain handle of console owner

ECX

 Error code:
00H - No error

Explanation

 X_ForeGet gets the domain handle of the console owner, in other words the foreground domain. Just as ownership is switching, the console may have no owner, so the handle returned may be zero.

See Also: X_ForeCheck

Z_GateAlloc (2F03H)

Function

 Allocate a call gate.

Entry Parameters
Register

 Value

CX

 2F03H

DS:EDX

 Pointer to a Gate Parameter Block; see "Explanation"

Returned Values
Register

 Value

 Meaning

EBX

 =GATE_PB_GATE

 Gate selector

ECX

 Error code:
00H - No error
31H - E_BadDesc
32H - E_NoDesc

Invalid parameters
No free descriptors

DS:[EDX]

 GATE_PB_GATE

 Gate selector

Explanation

 Z_GateAlloc allocates a protected mode call gate and returns its selector.

The parameter block is defined in STRUCS.DEF as follows:
GATE_PBLK

 struc

GATE_PB_SEL

 dw

 ?

GATE_PB_COUNT

 dw

 ?

GATE_PB_OFFSET

 dd

 ?

GATE_PB_GATE

 dw

 ?

unused

 db

 ?

GATE_PB_SINFO

 db

 ?

GATE_PBLK

 ends

Before you call Z_GateAlloc, you must initialize all fields in GATE_PBLK except GATE_PB_GATE, which will be filled with the selector of the allocated gate when the function returns successfully.

GATE_PB_SEL and GATE_PB_OFFSET are the address of the destination procedure. GATE_PB_COUNT should be 0.

GATE_PB_SINFO is an image of the byte within the gate which holds its DPL. Only bits 5 and 6 are used:
Bit

 Reset

 Set

5, 6

 Privilege level

 Privilege level

Note that this function creates a call gate, not a task, interrupt or trap gate. Call Z_GateFree to deallocate the gate when it is no longer needed.

See Also: Z_GateFree

Z_GateFree (3003H)

Function

 Release a call gate.

Entry Parameters
Register

 Value

CX

 3003H

DS:EDX

 Pointer to a Gate Parameter Block; see "Z_GateAlloc (2F03H)" on page 2-50

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error
31H - E_BadDesc

Invalid selector

Explanation

 Z_GateFree releases a call gate. The parameter block is as described under Z_GateAlloc. Only the GATE_PB_GATE field need be filled in when you call Z_GateFree.

See Also: Z_GateAlloc

Z_HandlerGenEx (0704H)

Function

 Install a general exception handler.

Entry Parameters
Register

 Value

CX

 0704H

DS:EDX

 Pointer to Handler Parameter Block; see "Explanantion"

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error

DS:[EDX]

 Modified

 See "Explanation"

Explanation

 Z_HandlerGenEx installs a handler for General Exceptions. The following description applies in most respects also to the following functions:

Z_HandlerHWInt

Z_HandlerHWIntDflt

Z_HandlerIOEx

Z_HandlerPageFault

Z_HandlerSWInt

Z_HandlerVHWInt

Z_HandlerVHWIntDflt

Differences between the functions are explained in the individual function descriptions.

Handlers are themselves level zero protected mode code functions. Before you install a handler, you must obtain a code descriptor and selector for its code segment.

In each case, the function to install the handler takes as a parameter a pointer to the following Handler Parameter Block:
HPB

 struc

dw

 0FFFFH

 dw

 0

HPB_EIP

 dd

 ?

HPB_CS

 dd

 ?

 dd

 4 dup (?)

HPB

 ends

Before you call the function to install the handler, you must supply the HPB_EIP and HPB_CS fields, which should point to the handler itself.

The last handler in each chain is the default handler provided by the operating system. Handlers are installed just before this default handler, so the first installed handler always remains first on the chain. When an exception occurs, the handlers are called in order from the first on the chain to the last.

All exceptions and software interrupts (but not hardware interrupts) are considered to belong to the current domain. Each domain therefore has its own chains of handlers for exceptions and software interrupts.

You can uninstall any handler by calling Z_HandlerUnlink.

Handler Interface
All handlers are called with the same stack frame, and handler-specific information in the registers. This information is detailed in the sections describing each handler installation function.

In each case, DS:EBX contains the address of the Handler Parameter Block passed when this handler was installed, so it can find its data if it needs to. Note that the memory above or below this HPB can be used to store data that may be useful to the handler.

The stack frame on entry to the handler includes the following structure, defined in STRUCS.DEF, with SS:EBP pointing to its base:
EXCEP

 struc

EX_EDI

 dd

 ?

EX_ESI

 dd

 ?

EX_EBP

 dd

 ?

EX_OPCODE

 db

 ?,0,0,0

EX_EBX

 dd

 ?

EX_EDX

 dd

 ?

EX_ECX

 dd

 ?

EX_EAX

 dd

 ?

EX_ERROR

 dd

 ?

EX_EIP

 dd

 ?

EX_CS

 dw

 ?

EX_OSINFO

 dw

 ?

EX_EFLAGS

 dd

 ?

EX_ESP

 dd

 ?

EX_SS

 dw

 ?,?

EX_ES

 dw

 ?,?

EX_DS

 dw

 ?,?

EX_FS

 dw

 ?,?

EX_GS

 dw

 ?,?

EXCEP

 ends

EX_OPCODE contains flags that will be set if the instruction had any prefixes, or if the address size or operand size is 32 bits. STRUCS.DEF provides equates for all the used bits.
Bit

 Equated name

 Use if set:

0

Not used

1

 EXOP_ADDR

 AddressSize=32
(override xor 32-bit CS)

2

 EXOP_SIZE

 OperandSize=32
(override xor 32-bit CS)

3

Not used

4-6

 EXOP_SEG
EXOP_CS
EXOP_SS
EXOP_DS
EXOP_ES
EXOP_FS
EXOP_GS

 Segment override. EXOP_SEG=70H,
CS=10H,
SS=20H,
DS=30H,
ES=40H,
FS=50H,
GS=60H

7

 EXOP_REP

 Repeat prefix (REP/REPE or REPNE)

EX_OSINFO contains the 386 exception number in its low byte, and flags in its high byte.
Bit

 Use if set:

0-7

 386 exception number

8

 Processor exception

9

 Hardware interrupt

10

 Software interrupt

The system disables interrupts before calling the handler and restores the previous interrupt state after the handler returns.

General Exception Handler Entry Parameters
General exception handlers are passed the following information in registers:
Register

 Value

DS:EBX

 Pointer to Handler Parameter Block

DL

 Exception number

Return from the Handler
Handlers must return to the address on the stack by executing a
32-bit RETF. If the handler's code segment is 16-bit, it can execute a 32-bit RETF by placing an operand override byte (66H) in front of the RETF instruction.

To indicate success in handling the exception or interrupt, all handlers must clear the carry flag (CF) and place their return code in AX. The system will not call any other handlers in the chain.

To indicate failure, set CF. The system will call the next handler in the chain.

DX must be preserved by some handlers, and set by others, as detailed in the descriptions that follow of each handler installation function.

General Exception Handler Exit Codes
General exception handlers must return the following in register AX if they have handled the exception (CF clear):
Register

 Value

 Meaning

AX

 0
0FFFEH
0FFFFH

 Success: return to user
Suspend user
Terminate user

The default General Exception handler reflects exceptions 0 to 5 and 7 to real mode, and terminates the user process for other exceptions.

See Also: Z_HandlerHWInt, Z_HandlerHWIntDflt, Z_HandlerIOEx, Z_HandlerPageFault, Z_HandlerSWInt, Z_HandlerUnlink, Z_HandlerVHWInt, Z_HandlerVHWIntDflt

Z_HandlerHWInt (0804H)

Function

 Install a level 0 hardware interrupt handler.

Entry Parameters
Register

 Value

CX

 0804H

DS:EDX

 Pointer to Handler Parameter Block; see "Z_HandlerGenEx (0704H)" on page 2-53

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error

DS:[EDX]

 Modified

 As for Z_HandlerGenEx

Explanation

 Z_HandlerHWInt installs a level 0 handler for hardware interrupts. Such handlers are called before the system itself processes the interrupt. You can also install a virtual interrupt handler by calling Z_HandlerVHWInt, or replace the default handler by calling Z_HandlerHWIntDflt. Virtual hardware interrupt handlers are invoked, after switching to a specified domain, if the level 0 interrupt handler chain indicates that the interrupt is to be reflected.

Most details are the same as for Z_HandlerGenEx (see page 2-53) except for the following details of the handler's entry and exit conditions.

Handler Entry Parameters
Register

 Value

DS:EBX

 Pointer to Handler Parameter Block

DL

 Interrupt number (must be preserved)

DH

 EX_OSINFO (Must be preserved)

EX_OSINFO is described under Z_HandlerGenEx.

Handler Exit
If the interrupt has not been handled, set the carry flag (CF) to pass the interrupt on, otherwise clear it and return the following:
Register

 Value

 Meaning

CF

 Clear

 Interrupt handled

AL

 0
1

 Return from interrupt
Reflect it

AH

 0 to 0FH
0FFH

 Interrupt level
Interrupt completed

EBX

 0
Domain handle
0FFFFFFFFH

 No domain switch
Domain to switch to
Switch to next domain

DX

 Unchanged

If a level 0 hardware interrupt handler needs to signal End of Interrupt (EOI) by clearing the PIC's In-Service bit, it must inform the system of this by calling Z_EndOfInterrupt.

See Also: Z_EndOfInterrupt, Z_HandlerGenEx, Z_HandlerUnlink

Z_HandlerHWIntDflt (1804H)

Function

 Install a substitute for the default level 0 hardware interrupt handler.

Entry Parameters
Register

 Value

ECX

 1804H

DS:[EDX]

 Pointer to Handler Parameter Block; see "Z_HandlerGenEx (0704H)" on page 2-53

Returned Values
Register

 Value

 Meaning

CX

 Error code:
00H - No error

[EDX]

 Modified

 As for Z_HandlerGenEx

Explanation

 Z_HandlerHWIntDflt installs a substitute for the default level 0 handler for hardware interrupts. The default handler is called only if no installable handler has handled the interrupt.

Details are the same as for Z_HandlerHWInt (see page 2-59), except that the last level 0 hardware interrupt handler must not pass the interrupt on; it must clear CF to return to the system.

See Also: Z_EndOfInterrupt, Z_HandlerGenEx, Z_HandlerHWInt, Z_HandlerUnlink

Z_HandlerIOEx (0604H)

Function

 Install an I/O exception handler.

Entry Parameters
Register

 Value

CX

 0604H

DS:EDX

 Pointer to Handler Parameter Block; see "Z_HandlerGenEx (0704H)" on page 2-53

Returned Values
Register

 Value

 Meaning

ECX

 Error code:
00H - No error

DS:[EDX]

 Modified

 As for Z_HandlerGenEx

Explanation

 Z_HandlerIOEx installs a handler for I/O Exceptions. When a General Exception occurs, the system decodes the offending instruction and calls the I/O exception handlers if the instruction is IN, INS, OUT or OU