Application Program Interface Specification for HIGHUMM.SYS of THE LAST BYTE MEMORY MANAGER (tm) Version 2.52 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 ...... 6 1.3.3 Function 2: Request a Bank-Switch memory block 6 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 7 1.3.7 Function 6: Put a Word to a Bank-Switch block. 7 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 ... 8 1.3.11 Function 10: Assign a name to a UMB or....... 8 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.3.14 Function 13: Resize a UMB block ........... 9 1.4 Final Notes ................................. 9 Oct 09, 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 Oct 09, 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 ; Resize a UMB memory block mov bx,new_size_in_paragraphs Copyright (C) 1990-94, Key Software Products. All Rights Reserved Oct 09, 1994 Programmer's Interface to HIGHUMM.SYS 3 mov dx,paragraph_address_of_umb_block call [XMSControl] ; a FAR call! cmp ax,1 jne Request_Failed ; If request was successful: ; -------------------------- ; AX = 1 ; BX = Segment address of reallocated 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 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 Copyright (C) 1990-94, Key Software Products. All Rights Reserved Oct 09, 1994 Programmer's Interface to HIGHUMM.SYS 4 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 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 Copyright (C) 1990-94, Key Software Products. All Rights Reserved Oct 09, 1994 Programmer's Interface to HIGHUMM.SYS 5 AH = C Locate a BSW block by name EXTRA AH = D Resize a UMB memory block STANDARD 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � 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: 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 (same as XMS function AH=10h) DX = Size of requested block in paragraphs Returns: AX = Status BX = Segment Number or Error Code DX = Size of requested block/largest block Copyright (C) 1990-94, Key Software Products. All Rights Reserved Oct 09, 1994 Programmer's Interface to HIGHUMM.SYS 6 Description: Identical to XMS function 10h 1.3.2 Function 1: Release a UMB memory block Parameters: AH = 1 (same as XMS function AH=11h) 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 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 Copyright (C) 1990-94, Key Software Products. All Rights Reserved Oct 09, 1994 Programmer's Interface to HIGHUMM.SYS 7 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. 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 Copyright (C) 1990-94, Key Software Products. All Rights Reserved Oct 09, 1994 Programmer's Interface to HIGHUMM.SYS 8 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. 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 Copyright (C) 1990-94, Key Software Products. All Rights Reserved Oct 09, 1994 Programmer's Interface to HIGHUMM.SYS 9 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. 1.3.14 Function 13: Resize a UMB block Parameters: AH = 0Dh (same as XMS function AH=12h) BX = new size of UMB block in paragraphs DX = segment number of memory block to resize Returns: AX = Status BX = Segment Number or Error Code Description: Attempts to change the size of a previously allocated UMB memory block. 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 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