home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #1
/
monster.zip
/
monster
/
UTILS2
/
TLB_A240.ZIP
/
HIGHUMM.DOC
< prev
next >
Wrap
Text File
|
1994-04-06
|
23KB
|
663 lines
Application Program Interface Specification
for
HIGHUMM.SYS
of
THE LAST BYTE MEMORY MANAGER (tm)
Version 2.40
Copyright (C) 1990-94
All Rights Reserved
by
KEY SOFTWARE PRODUCTS
440 Ninth Avenue
Menlo Park, California 94025-1802
415-364-9847
The Last Byte Memory Manager is a trademark of Key Software Products
TABLE OF CONTENTS
CHAPTER 1 - APPLICATION PROGRAM INTERFACE TO HIGHUMM.SYS 1
1.1 XMS Upper Memory Blocks ....................... 1
1.2 Bank-Switch Memory .......................... 3
1.3 Summary Of HIGHUMM.SYS Functions .............. 5
1.3.1 Function 0: Request a UMB memory block ...... 5
1.3.2 Function 1: Release a UMB memory block ...... 5
1.3.3 Function 2: Request a Bank-Switch memory block 5
1.3.4 Function 3: Release a Bank-Switch memory block 6
1.3.5 Function 4: Transfer data to/from high memory 6
1.3.6 Function 5: Get a Word from a Bank-Switch bloc 6
1.3.7 Function 6: Put a Word to a Bank-Switch block. 6
1.3.8 Function 7: Put a Byte to a Bank-Switch block. 7
1.3.9 Function 8: Enable Bank-Switch Memory ..... 7
1.3.10 Function 9: Disable Bank-Switch Memory ... 7
1.3.11 Function 10: Assign a name to a UMB or....... 7
1.3.12 Function 11: Locate a UMB block by name ..... 8
1.3.13 Function 12: Locate a BSW block by name ..... 8
1.4 Final Notes ................................. 9
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 1
CHAPTER 1 - APPLICATION PROGRAM INTERFACE TO HIGHUMM.SYS
HIGHUMM.SYS is a device driver that lets application programmers
access upper memory between 640k and 1Meg. It requires that
LASTBYTE be installed first, and automatically loads itself into
upper memory without the need to use either HIGHDRVR or the DOS
5 DEVICEHIGH command.
HIGHUMM provides two methods of accessing high memory:
1.1 XMS Upper Memory Blocks
If an Extended Memory Specification (XMS) driver (such as
HIMEM.SYS) has already been loaded, HIGHUMM will link into it,
providing an implementation of the two XMS functions for
accessing what the XMS specification refers to as "Upper Memory
Blocks" (UMB's). Although described in the XMS specification,
the UMB functions have not been implemented in the current (June
1990) and previous versions of HIMEM.SYS.
If an XMS driver has not been loaded, then HIGHUMM will become a
UMB-Only XMS device driver, providing support for XMS functions
00h (Get Version Number), 10h (Allocate UMB Block), 11h
(Deallocate UMB Block). All other XMS functions will return
failure, indicating that the function is not implemented.
┌─────────────────────────────────────────────────┐
│ If another XMS device driver is used (e.g., to │
│ provide management of Extended Memory or the │
│ High Memory Area), it must be loaded before │
│ HIGHUMM.SYS. │
└─────────────────────────────────────────────────┘
Upper Memory Blocks (UMBs) are blocks of memory available on
some 80x86 based machines which are located between DOS's 640K
limit and the 1MB address boundary. The number, size, and
location of these blocks vary widely depending upon the types of
hardware adapter cards installed in the machine. By definition,
this memory is DOS-accessible, but does NOT include the
Bank-Switch memory supported by LASTBYTE.
On 80286 and 80386 based machines, XMS allows DOS programs to
utilize Extended Memory in a consistent, machine independent
manner. With some restrictions, XMS adds almost 64K of Extended
Memory to the 640K which DOS programs can access directly.
Depending on available hardware, XMS may provide even more
memory (UMB's) to DOS programs. XMS also provides DOS programs
with a standard method of storing data in Extended Memory.
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 2
The XMS Specification for MS-DOS was jointly developed by Lotus,
Intel, Microsoft, and AST Research. The specification was
published on July 19, 1988 and released to the public domain and
is not confidential or proprietary, but the specification is
still the copyright and property of these companies. You may
obtain a copy from Microsoft Corporation, 16011 NE 36th Way, Box
97017, Redmond, WA 98073, or by calling Microsoft at (800)
426-9400.
Access to the UMB's through XMS is a four step process:
1. Test for the existence of the XMS driver.
2. Obtain the address of the XMS control function.
3. Invoke the Request UMB or Release UMB function.
4. Check for success or failure.
This is best explained by an example:
...
mov ax,4300h ; XMS driver installed?
int 2Fh
cmp al,80h
jne NoXMSDriver
...
mov ax,4310h ; Get adrs of XMS Ctl Func
int 2Fh
mov WORD PTR [XMSControl],bx
mov WORD PTR [XMSControl+2],es
...
mov ah,10h ; Request a UMB memory block
mov dx,size_in_paragraphs
call [XMSControl] ; a FAR call!
cmp ax,1
jne Request_Failed
; If request was successful:
; --------------------------
; AX = 1
; BX = Segment address of allocated block
; DX = Actual size of block (same as requested size)
; If request failed:
; ------------------
; AX = 0
; DX = size of largest available in paragraphs
; Error Codes: BL = 80h (Not implemented/installed)
; BL = B0h (Smaller UMB available)
; BL = B1h (No UMB available)
mov ah,11h ; Release a UMB memory block
mov dx,segment_address_of_umb
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 3
call [XMSControl] ; a FAR call!
cmp ax,1
jne Release_Failed
; If request was successful:
; --------------------------
; AX = 1
; If request failed:
; ------------------
; AX = 0
; Error Codes: BL = 80h (Not implemented/installed)
; BL = B2h (invalid segment number)
HIGHMEM lists such UMB memory blocks as "MS-DOS XMS UMB".
1.2 Bank-Switch Memory
The second method of accessing high memory is by opening the
device "KSP$UMM" and performing an IOCTL Read of four bytes.
This obtains the offset and segment address of an extended UMB
control function that provides access to Bank-Switch memory as
well as normal UMB blocks. Using HIGHUMM.SYS in this manner
does not require that an XMS driver such as HIMEM.SYS be
loaded. For example:
Device_Name db 'KSP$UMM',0 ; HIGHUMM.SYS device name
HIGHUMM_Ctl dw 0,0 ; far ptr to ctl func
...
mov ax,3D00h ; open file or device
mov dx,OFFSET Device_Name ; DS:DX => device name
int 21h
jc Open_Failed ; (HIGHUMM.SYS not installed)
mov handle,ax ; save handle
mov ax,4400h ; ioctl: get device attributes
mov bx,handle
int 21h
jc Attb_Failed ; (HIGHUMM.SYS not functioning)
test dl,80h ; is this a device or a filename
jz Not_Device ; File called "KSP$UMM" exists!
mov ax,4402h ; IOCTL Read (BX = handle)
mov bx,handle
mov dx,OFFSET HIGHUMM_Ctl ; DS:DX => read buffer
mov cx,4 ; read *EXACTLY* four bytes
int 21h
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 4
pushf
mov ah,3Eh ; Close device (BX = handle)
mov bx,handle
int 21h
popf
jc IOCTL_Error ; (HIGHUMM.SYS not functioning)
; Offset of control function is in "HIGHUMM_Ctl"
; Segment of control function is in "HIGHUMM_Ctl+2"
Once you have the address of the extended control function from
HIGHUMM.SYS, you can invoke any of the following 13 functions:
Function Description Class
-------- ----------- --------
AH = 0 Request a UMB memory block STANDARD
AH = 1 Release a UMB memory block STANDARD
AH = 2 Request a Bank-Switch memory block EXTRA
AH = 3 Release a Bank-Switch memory block EXTRA
AH = 4 Transfer data to/from high memory EXTRA
AH = 5 Get a Word from a Bank-Switch block EXTRA
AH = 6 Put a Word to a Bank-Switch block EXTRA
AH = 7 Put a Byte to a Bank-Switch block EXTRA
AH = 8 Enable Bank-Switch Memory EXTRA
AH = 9 Disable Bank-Switch Memory EXTRA
AH = A Assign a name to a UMB or BSW block EXTRA
AH = B Locate a UMB block by name EXTRA
AH = C Locate a BSW block by name EXTRA
┌─────────────────────────────────────────────────┐
│ Support for the "EXTRA" class of functions │
│ requires use of the "/EXTRA" option on the │
│ HIGHUMM.SYS command line: │
└─────────────────────────────────────────────────┘
DEVICE=C:\TLBMM\HIGHUMM.SYS /EXTRA
("/EXTRA" may be abbreviated as simply "/E".)
These function numbers are different than those used with
XMSControl even though three of them are otherwise equivalent to
XMS functions 10h and 11h! Calling one of the HIGHUMM functions
is similar to calling the XMS functions. For example, to
request a Bank-Switch memory block, the following code would be
used:
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 5
mov ah,2 ; Request a BSW block
mov dx,paragraphs
call [HIGHUMM_Control] ; a FAR call!
cmp ax,1
jne Request_Failed ; BL contains error code
; DX = largest available
; Success: BX contains segment number
For all HIGHUMM.SYS functions, the error codes are the same as
returned by the XMS driver:
AX = 0001h Function successful
0000h Function failed; error code in BL
BL = 80h Function not implemented
B0h Insuf. memory; smaller block available
B1h Insuf. memory; no block available
B2h Invalid block segment number
1.3 Summary Of HIGHUMM.SYS Functions
1.3.1 Function 0: Request a UMB memory block
Parameters: AH = 0
DX = Size of requested block in paragraphs
Returns: AX = Status
BX = Segment Number or Error Code
DX = Size of requested block/largest block
Description: Identical to XMS function 10h
1.3.2 Function 1: Release a UMB memory block
Parameters: AH = 1
DX = Segment number of memory block
Returns: AX = Status
BL = Error Code
Description: Identical to XMS function 11h
1.3.3 Function 2: Request a Bank-Switch memory block
Parameters: AH = 2
DX = Size of requested block in paragraphs
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 6
Returns: AX = Status
BX = Segment Number or Error Code
DX = Size of requested block/largest block
Description: Similar to function 0 for regular UMB blocks,
except that HIGHMEM lists these blocks as
"Bank-Switch UMB".
1.3.4 Function 3: Release a Bank-Switch memory block
Parameters: AH = 3
DX = Segment number of memory block
Returns: AX = Status
BL = Error Code
Description: Similar to function 1 for regular UMB blocks.
1.3.5 Function 4: Transfer data to/from high memory
Parameters: AH = 4
DS:SI = Segment:Offset of source
ES:DI = Segment:Offset of destination
CX = byte count
Returns: AX = Status (Never returns failure)
Description: Enables Bank-Switch Memory, copies data between
the specified source and destination, then
disables Bank-Switch memory.
1.3.6 Function 5: Get a Word from a Bank-Switch block
Parameters: AH = 5
ES:DI = Segment:Offset of word to read
Returns: AX = Status (Never returns failure)
DX = WORD from BSW Block
Description: Enables Bank-Switch Memory, loads DX from the
specified location, then disables Bank-Switch
memory.
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 7
1.3.7 Function 6: Put a Word to a Bank-Switch block
Parameters: AH = 6
DX = Word to put into BSW Block
ES:DI = Segment:Offset of word to write
Returns: AX = Status (Never returns failure)
Description: Enables Bank-Switch Memory, stores DX into the
specified location, then disables Bank-Switch
memory.
1.3.8 Function 7: Put a Byte to a Bank-Switch block
Parameters: AH = 7
DL = Byte to put into BSW Block
ES:DI = Segment:Offset of byte to write
Returns: AX = Status (Never returns failure)
Description: Enables Bank-Switch Memory, stores DL into the
specified location, then disables Bank-Switch
memory.
1.3.9 Function 8: Enable Bank-Switch Memory
Parameters: AH = 8
DS:SI = Segment:Offset of 6-byte save area
Returns: AX = Status (Never returns failure)
Description: Disables interrupts, saves the memory controller
state in a 6-byte save area within the
application program, and enables Bank-Switch
memory so that data within it may be accessed.
1.3.10 Function 9: Disable Bank-Switch Memory
Parameters: AH = 9
DS:SI = Segment:Offset of 6-byte save area
Returns: AX = Status (Never returns failure)
Description: Reloads the state of the memory controller from a
6-byte save area in the application program and
restores the previous interrupt enable status.
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 8
1.3.11 Function 10: Assign a name to a UMB or
Parameters: AH = 0Ah
DX = Segment number of memory block
DS:SI = Segment:Offset of 8-byte blank-padded
name
Returns: AX = Status
BX = Error Code
Description: Copies 8 bytes to the name field of the
allocated UMB or BSW memory block.
1.3.12 Function 11: Locate a UMB block by name
Parameters: AH = 0Bh
DS:SI = Segment:Offset of 8-byte blank-padded
name
Returns: AX = Status
BX = Segment Number or Error Code
DX = Size of block
Description: Locates a UMB memory block by its 1-8 character
name. All 8 bytes of name are compared; letter
with different case do not match.
1.3.13 Function 12: Locate a BSW block by name
Parameters: AH = 0Ch
DS:SI = Segment:Offset of 8-byte blank-padded
name
Returns: AX = Status
BX = Segment Number or Error Code
DX = Size of block
Description: Locates a BSW memory block by its 1-8 character
name. All 8 bytes of name are compared; letter
with different case do not match.
IMPORTANT! A call to function 8 must be followed by a call to
function 9, and without enabling interrupts in between. This is
because while Bank-Switch memory is enabled, all adapter RAMs
(including display buffers) and any ROMs which are not shadowed
are disabled; thus any code (either your own program or a TSR
activated by the timer tick) that attempts to access these
resources will fail. Also, it is important to execute this code
Copyright (C) 1990-94, Key Software Products. All Rights Reserved
Apr 06, 1994 Programmer's Interface to HIGHUMM.SYS 9
quickly to minimize the amount of time that interrupts are
disabled.
1.4 Final Notes
The only valid use of Bank-Switch memory is to store data! Never
load a program into Bank-Switch memory and then reference it via
a JMP or CALL - it won't be there! For example, you may NOT
load a TSR into Bank-Switch memory and expect it to be
accessible when it's activating interrupt occurs.
UMB's (regular and Bank-Switched) are NOT automatically free'd
at program termination like regular memory allocated by your
program using DOS function 72 (48 hex). For example, if your
program uses a UMB for a temporary buffer, you must be sure to
release the UMB before terminating the program.
Copyright (C) 1990-94, Key Software Products. All Rights Reserved