home *** CD-ROM | disk | FTP | other *** search
/ Shareware 1 2 the Maxx / sw_1.zip / sw_1 / MEM_MAN / TLB_V202.ZIP / HIGHUMM.DOC < prev    next >
Text File  |  1992-07-01  |  22KB  |  662 lines
  1.  
  2.  
  3.         
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.                                    HIGHUMM.SYS
  12.  
  13.  
  14.                        Application Program Interface (API)
  15.                                        to
  16.                         THE LAST BYTE MEMORY MANAGER (tm)
  17.  
  18.  
  19.                                   Version 2.02
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                               Copyright (C) 1990-92
  28.                                All Rights Reserved
  29.  
  30.  
  31.  
  32.  
  33.                                        by
  34.  
  35.  
  36.                               KEY SOFTWARE PRODUCTS
  37.                                 440 Ninth Avenue
  38.                           Menlo Park, California 94025
  39.                                  (415) 364-9847
  40.  
  41.  
  42.         The Last Byte Memory Manager is a trademark of Key Software Products
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.                          Prodigy E-Mail Address: VGDC59A
  54.                E-Mail on Internet, Bitnet, etc: DLEWIS@SCU.BITNET
  55.              CompuServe E-Mail Address: >Internet:DLEWIS@SCU.BITNET
  56.  
  57.  
  58.  
  59.  
  60.         
  61.  
  62.  
  63.         Jul 01, 1992      HIGHUMM.SYS API Specification                 1
  64.  
  65.  
  66.         HIGHUMM.SYS  is a device driver that lets application programmers
  67.         access  upper  memory  between  640k  and 1Meg.  It requires that
  68.         LASTBYTE  be installed first, and automatically loads itself into
  69.         upper  memory  without the need to use either HIGHDRVR or the DOS
  70.         5 DEVICEHIGH command.  
  71.  
  72.         HIGHUMM provides two methods of accessing high memory: 
  73.  
  74.         1. XMS Upper Memory Blocks      
  75.  
  76.         If  an  Extended  Memory  Specification  (XMS)  driver  (such  as
  77.         HIMEM.SYS)  has  already  been loaded, HIGHUMM will link into it,
  78.         providing   an  implementation  of  the  two  XMS  functions  for
  79.         accessing  what  the XMS specification refers to as "Upper Memory
  80.         Blocks"  (UMB's).   Although  described in the XMS specification,
  81.         the  UMB functions have not been implemented in the current (June
  82.         1990) and previous versions of HIMEM.SYS.  
  83.  
  84.         If  an XMS driver has not been loaded, then HIGHUMM will become a
  85.         UMB-Only  XMS  device driver, providing support for XMS functions
  86.         00h   (Get   Version  Number),  10h  (Allocate  UMB  Block),  11h
  87.         (Deallocate  UMB  Block).   All  other  XMS functions will return
  88.         failure, indicating that the function is not implemented.  
  89.  
  90.  
  91.                                 Important!       
  92.  
  93.                 If  another  XMS  device driver is used (e.g., to
  94.                 provide  management  of  Extended  Memory  or the
  95.                 High  Memory  Area),  it  must  be  loaded before
  96.                 HIGHUMM.SYS.  
  97.  
  98.  
  99.         Upper  Memory  Blocks  (UMBs)  are  blocks of memory available on
  100.         some  80x86  based  machines which are located between DOS's 640K
  101.         limit  and  the  1MB  address  boundary.   The  number, size, and
  102.         location  of these blocks vary widely depending upon the types of
  103.         hardware  adapter cards installed in the machine.  By definition,
  104.         this   memory   is  DOS-accessible,  but  does  NOT  include  the
  105.         Bank-Switch memory supported by LASTBYTE.  
  106.  
  107.         On  80286  and  80386  based machines, XMS allows DOS programs to
  108.         utilize  Extended  Memory  in  a  consistent, machine independent
  109.         manner.   With some restrictions, XMS adds almost 64K of Extended
  110.         Memory  to  the  640K  which  DOS  programs  can access directly.
  111.         Depending  on  available  hardware,  XMS  may  provide  even more
  112.         memory  (UMB's)  to DOS programs.  XMS also provides DOS programs
  113.         with a standard method of storing data in Extended Memory.  
  114.  
  115.         The   XMS  Specification  version  2.0  for  MS-DOS  was  jointly
  116.         developed  by  Lotus,  Intel,  Microsoft,  and AST Research.  The
  117.  
  118.  
  119.  
  120.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  121.  
  122.  
  123.         Jul 01, 1992      HIGHUMM.SYS API Specification                 2
  124.  
  125.  
  126.         specification  was published on July 19, 1988 and released to the
  127.         public  domain  and  is  not confidential or proprietary, but the
  128.         specification  is  still  the  copyright  and  property  of these
  129.         companies.   You  may  obtain  a copy from Microsoft Corporation,
  130.         16011  NE  36th  Way, Box 97017, Redmond, WA 98073, or by calling
  131.         Microsoft at (800) 426-9400.  
  132.  
  133.         Access to the UMB's through XMS is a four step process: 
  134.  
  135.                 1.  Test for the existence of the XMS driver.  
  136.                 2.  Obtain the address of the XMS control function.  
  137.                 3.  Invoke the Request UMB or Release UMB function.  
  138.                 4.  Check for success or failure.  
  139.  
  140.         This is best explained by an example: 
  141.  
  142.                 ...  
  143.                 mov     ax,4300h        ; XMS driver installed? 
  144.                 int     2Fh 
  145.                 cmp     al,80h 
  146.                 jne     NoXMSDriver 
  147.                 ...  
  148.                 mov     ax,4310h        ; Get adrs of XMS Ctl Func 
  149.                 int     2Fh 
  150.                 mov     WORD PTR [XMSControl],bx 
  151.                 mov     WORD PTR [XMSControl+2],es 
  152.                 ...  
  153.                 mov     ah,10h          ; Request a UMB memory block 
  154.                 mov     dx,size_in_paragraphs 
  155.                 call    [XMSControl]    ; a FAR call! 
  156.                 cmp     ax,1 
  157.                 jne     Request_Failed 
  158.  
  159.                 ; If request was successful: 
  160.                 ; -------------------------- 
  161.                 ; AX = 1 
  162.                 ; BX = Segment address of allocated block 
  163.                 ; DX = Actual size of block (same as requested size) 
  164.  
  165.                 ; If request failed: 
  166.                 ; ------------------ 
  167.                 ; AX = 0 
  168.                 ; DX = size of largest available in paragraphs 
  169.                 ; Error Codes:  BL = 80h (Not implemented/installed) 
  170.                 ;               BL = B0h (Smaller UMB available) 
  171.                 ;               BL = B1h (No UMB available) 
  172.  
  173.                 mov     ah,11h          ; Release a UMB memory block 
  174.                 mov     dx,segment_address_of_umb 
  175.                 call    [XMSControl]    ; a FAR call! 
  176.                 cmp     ax,1 
  177.  
  178.  
  179.  
  180.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  181.  
  182.  
  183.         Jul 01, 1992      HIGHUMM.SYS API Specification                 3
  184.  
  185.  
  186.                 jne     Release_Failed 
  187.  
  188.                 ; If request was successful: 
  189.                 ; -------------------------- 
  190.                 ; AX = 1 
  191.  
  192.                 ; If request failed: 
  193.                 ; ------------------ 
  194.                 ; AX = 0 
  195.                 ; Error Codes:  BL = 80h (Not implemented/installed) 
  196.                 ;               BL = B2h (invalid segment number) 
  197.  
  198.  
  199.         HIGHMEM lists such UMB memory blocks as "MS-DOS XMS UMB".  
  200.  
  201.  
  202.         2. Bank-Switch Memory        
  203.  
  204.         The  second  method  of  accessing  high memory is by opening the
  205.         device  "KSP$UMM"  and  performing  an  IOCTL Read of four bytes.
  206.         This  obtains  the  offset and segment address of an extended UMB
  207.         control  function  that  provides access to Bank-Switch memory as
  208.         well  as  normal  UMB  blocks.   Using HIGHUMM.SYS in this manner
  209.         does  not  require  that  an  XMS  driver  such  as  HIMEM.SYS be
  210.         loaded.  For example: 
  211.  
  212.  
  213.         Device_Name     db     'KSP$UMM',0   ;  HIGHUMM.SYS  device  name
  214.         HIGHUMM_Ctl   dw   0,0         ; far ptr to ctl func 
  215.  
  216.                 ...  
  217.                 mov     ax,3D00h        ; open file or device 
  218.                 mov     dx,OFFSET Device_Name   ; DS:DX => device name 
  219.                 int     21h 
  220.                 jc      Open_Failed     ; (HIGHUMM.SYS not installed) 
  221.                 mov     handle,ax       ; save handle 
  222.  
  223.                 mov     ax,4400h        ; ioctl: get device attributes 
  224.                 mov     bx,handle 
  225.                 int     21h 
  226.                 jc      Attb_Failed     ; (HIGHUMM.SYS not functioning) 
  227.                 test    dl,80h          ; is this a device or a filename 
  228.                 jz      Not_Device      ; File called "KSP$UMM" exists! 
  229.  
  230.                 mov     ax,4402h        ; IOCTL Read (BX = handle) 
  231.                 mov     bx,handle 
  232.                 mov     dx,OFFSET HIGHUMM_Ctl   ; DS:DX => read buffer 
  233.                 mov     cx,4            ; read *EXACTLY* four bytes 
  234.                 int     21h 
  235.  
  236.                 pushf 
  237.  
  238.  
  239.  
  240.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  241.  
  242.  
  243.         Jul 01, 1992      HIGHUMM.SYS API Specification                 4
  244.  
  245.  
  246.                 mov     ah,3Eh          ; Close device (BX = handle) 
  247.                 mov     bx,handle 
  248.                 int     21h 
  249.                 popf 
  250.  
  251.                 jc      IOCTL_Error     ; (HIGHUMM.SYS not functioning) 
  252.  
  253.                 ; Offset of control function is in "HIGHUMM_Ctl" 
  254.                 ; Segment of control function is in "HIGHUMM_Ctl+2" 
  255.  
  256.  
  257.         Once  you  have the address of the extended control function from
  258.         HIGHUMM.SYS, you can invoke any of the following 13 functions: 
  259.  
  260.                 Function        Description                     Class 
  261.                 --------        -----------                     -------- 
  262.  
  263.                 AH = 0  Request a UMB memory block              STANDARD 
  264.                 AH = 1  Release a UMB memory block              STANDARD 
  265.  
  266.                 AH = 2  Request a Bank-Switch memory block      EXTRA 
  267.                 AH = 3  Release a Bank-Switch memory block      EXTRA 
  268.                 AH = 4  Transfer data to/from high memory       EXTRA 
  269.                 AH = 5  Get a Word from a Bank-Switch block     EXTRA 
  270.                 AH = 6  Put a Word to a Bank-Switch block       EXTRA 
  271.                 AH = 7  Put a Byte to a Bank-Switch block       EXTRA 
  272.                 AH = 8  Enable Bank-Switch Memory               EXTRA 
  273.                 AH = 9  Disable Bank-Switch Memory              EXTRA 
  274.                 AH = A  Assign a name to a UMB or BSW block     EXTRA 
  275.                 AH = B  Locate a UMB block by name              EXTRA 
  276.                 AH = C  Locate a BSW block by name              EXTRA 
  277.  
  278.  
  279.  
  280.         Support  for  the  "EXTRA" class of functions requires use of the
  281.         "/EXTRA" option on the HIGHUMM.SYS command line: 
  282.  
  283.                             DEVICE=HIGHUMM.SYS /EXTRA
  284.  
  285.                   ("/EXTRA" may be abbreviated as simply "/E".)
  286.  
  287.         These  function  numbers  are  different  than  those  used  with
  288.         XMSControl  even though the first two are otherwise equivalent to
  289.         XMS  functions 10h and 11h!  Calling one of the HIGHUMM functions
  290.         is  similar  to  calling  the  XMS  functions.   For  example, to
  291.         request  a  Bank-Switch memory block, the following code would be
  292.         used:  
  293.  
  294.                 mov     ah,2                    ; Request a BSW block 
  295.                 mov     dx,paragraphs 
  296.                 call    [HIGHUMM_Control]       ; a FAR call! 
  297.  
  298.  
  299.  
  300.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  301.  
  302.  
  303.         Jul 01, 1992      HIGHUMM.SYS API Specification                 5
  304.  
  305.  
  306.                 cmp     ax,1 
  307.                 jne     Request_Failed          ; BL contains error code 
  308.                                                 ; DX = largest available 
  309.  
  310.                 ; Success: BX contains segment number 
  311.  
  312.         For  all  HIGHUMM.SYS  functions, the error codes are the same as
  313.         returned by the XMS driver: 
  314.  
  315.                 AX = 0001h      Function successful 
  316.                      0000h      Function failed; error code in BL 
  317.  
  318.                 BL = 80h        Function not implemented 
  319.                      B0h        Insuf. memory; smaller block available 
  320.                      B1h        Insuf. memory; no block available 
  321.                      B2h        Invalid block segment number 
  322.  
  323.  
  324.         3. Summary of HIGHUMM.SYS Functions      
  325.  
  326.  
  327.         3.1 Function 0: Request a UMB memory block  
  328.  
  329.              Parameters:     AH = 0
  330.                              DX = Size of requested block in paragraphs
  331.  
  332.              Returns:        AX = Status
  333.                              BX = Segment Number or Error Code
  334.                              DX = Size of requested block/largest block
  335.  
  336.              Description:    Identical to XMS function 10h
  337.  
  338.  
  339.         3.2 Function 1: Release a UMB memory block  
  340.  
  341.              Parameters:     AH = 1
  342.                              DX = Segment number of memory block
  343.  
  344.              Returns:        AX = Status
  345.                              BL = Error Code
  346.  
  347.              Description:    Identical to XMS function 11h
  348.  
  349.  
  350.         3.3 Function 2: Request a Bank-Switch memory block  
  351.  
  352.              Parameters:     AH = 2
  353.                              DX = Size of requested block in paragraphs
  354.  
  355.              Returns:        AX = Status
  356.                              BX = Segment Number or Error Code
  357.  
  358.  
  359.  
  360.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  361.  
  362.  
  363.         Jul 01, 1992      HIGHUMM.SYS API Specification                 6
  364.  
  365.  
  366.                              DX = Size of requested block/largest block
  367.  
  368.              Description:    Similar to function 0 for regular UMB blocks,
  369.                              except that HIGHMEM lists these blocks as
  370.                              "Bank-Switch UMB".
  371.  
  372.  
  373.         3.4 Function 3: Release a Bank-Switch memory block  
  374.  
  375.              Parameters:     AH = 3
  376.                              DX = Segment number of memory block
  377.  
  378.              Returns:        AX = Status
  379.                              BL = Error Code
  380.  
  381.              Description:    Similar to function 1 for regular UMB blocks.
  382.  
  383.  
  384.         3.5 Function 4: Transfer data to/from high memory  
  385.  
  386.              Parameters:     AH = 4
  387.                              DS:SI = Segment:Offset of source
  388.                              ES:DI = Segment:Offset of destination
  389.                              CX = byte count
  390.  
  391.              Returns:        AX = Status (Never returns failure)
  392.  
  393.              Description:    Enables Bank-Switch Memory, copies data between
  394.                              the specified source and destination, then
  395.                              disables Bank-Switch memory.
  396.  
  397.  
  398.         3.6 Function 5: Get a Word from a Bank-Switch block
  399.  
  400.              Parameters:     AH = 5
  401.                              ES:DI = Segment:Offset of word to read
  402.  
  403.              Returns:        AX = Status (Never returns failure)
  404.                              DX = WORD from BSW Block
  405.  
  406.              Description:    Enables Bank-Switch Memory, loads DX from the
  407.                              specified location, then disables Bank-Switch
  408.                              memory.
  409.  
  410.  
  411.         3.7 Function 6: Put a Word to a Bank-Switch block
  412.  
  413.              Parameters:     AH = 6
  414.                              DX = Word to put into BSW Block
  415.                              ES:DI = Segment:Offset of word to write
  416.  
  417.  
  418.  
  419.  
  420.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  421.  
  422.  
  423.         Jul 01, 1992      HIGHUMM.SYS API Specification                 7
  424.  
  425.  
  426.              Returns:        AX = Status (Never returns failure)
  427.  
  428.              Description:    Enables Bank-Switch Memory, stores DX into the
  429.                              specified location, then disables Bank-Switch
  430.                              memory.
  431.  
  432.  
  433.         3.8 Function 7: Put a Byte to a Bank-Switch block
  434.  
  435.              Parameters:     AH = 7
  436.                              DL = Byte to put into BSW Block
  437.                              ES:DI = Segment:Offset of byte to write
  438.  
  439.              Returns:        AX = Status (Never returns failure)
  440.  
  441.              Description:    Enables Bank-Switch Memory, stores DL into the
  442.                              specified location, then disables Bank-Switch
  443.                              memory.
  444.  
  445.  
  446.         3.9 Function 8: Enable Bank-Switch Memory    
  447.  
  448.              Parameters:     AH = 8
  449.                              DS:SI = Segment:Offset of 6-byte save area
  450.  
  451.              Returns:        AX = Status (Never returns failure)
  452.  
  453.              Description:    Disables interrupts, saves the memory controller
  454.                              state in a 6-byte save area within the 
  455.                              application program, and enables Bank-Switch
  456.                              memory so that data within it may be accessed.
  457.  
  458.  
  459.         3.10 Function 9: Disable Bank-Switch Memory    
  460.  
  461.              Parameters:     AH = 9
  462.                              DS:SI = Segment:Offset of 6-byte save area
  463.  
  464.              Returns:        AX = Status (Never returns failure)
  465.  
  466.              Description:    Reloads the state of the memory controller from a
  467.                              6-byte save area in the application program and
  468.                              restores the previous interrupt enable status.
  469.  
  470.  
  471.         3.11 Function 10: Assign a name to a UMB or
  472.  
  473.              Parameters:     AH = 0Ah
  474.                              DX = Segment number of memory block
  475.                              DS:SI = Segment:Offset of 8-byte blank-padded
  476.                                      name
  477.  
  478.  
  479.  
  480.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  481.  
  482.  
  483.         Jul 01, 1992      HIGHUMM.SYS API Specification                 8
  484.  
  485.  
  486.  
  487.              Returns:        AX = Status
  488.                              BX = Error Code
  489.  
  490.              Description:    Copies 8 bytes to the name field of the
  491.                              allocated UMB or BSW memory block.
  492.  
  493.  
  494.         3.12 Function 11: Locate a UMB block by name 
  495.  
  496.              Parameters:     AH = 0Bh
  497.                              DS:SI = Segment:Offset of 8-byte blank-padded
  498.                                      name
  499.  
  500.              Returns:        AX = Status
  501.                              BX = Segment Number or Error Code
  502.                              DX = Size of block
  503.  
  504.              Description:    Locates a UMB memory block by its 1-8 character
  505.                              name.  All 8 bytes of name are compared; letter
  506.                              with different case do not match.
  507.  
  508.  
  509.         3.13 Function 12: Locate a BSW block by name 
  510.  
  511.              Parameters:     AH = 0Bh
  512.                              DS:SI = Segment:Offset of 8-byte blank-padded
  513.                                      name
  514.  
  515.              Returns:        AX = Status
  516.                              BX = Segment Number or Error Code
  517.                              DX = Size of block
  518.  
  519.              Description:    Locates a BSW memory block by its 1-8 character
  520.                              name.  All 8 bytes of name are compared; letter
  521.                              with different case do not match.
  522.  
  523.         IMPORTANT!  A  call  to  function 8 must be followed by a call to
  524.         function  9, and without enabling interrupts in between.  This is
  525.         because  while  Bank-Switch  memory  is enabled, all adapter RAMs
  526.         (including  display  buffers) and any ROMs which are not shadowed
  527.         are  disabled;  thus  any  code (either your own program or a TSR
  528.         activated  by  the  timer  tick)  that  attempts  to access these
  529.         resources  will fail.  Also, it is important to execute this code
  530.         quickly  to  minimize  the  amount  of  time  that interrupts are
  531.         disabled.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  541.  
  542.  
  543.         Jul 01, 1992      HIGHUMM.SYS API Specification                 9
  544.  
  545.  
  546.         4. Final Notes        
  547.  
  548.         The  only valid use of Bank-Switch memory is to store data! Never
  549.         load  a program into Bank-Switch memory and then reference it via
  550.         a  JMP  or  CALL  -  it won't be there!  For example, you may NOT
  551.         load   a  TSR  into  Bank-Switch  memory  and  expect  it  to  be
  552.         accessible when it's activating interrupt occurs.  
  553.  
  554.         UMB's  (regular  and  Bank-Switched) are NOT automatically free'd
  555.         at  program  termination  like  regular  memory allocated by your
  556.         program  using  DOS  function  72 (48 hex).  For example, if your
  557.         program  uses  a  UMB for a temporary buffer, you must be sure to
  558.         release the UMB before terminating the program.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  601.  
  602.  
  603.                           HIGHUMM.SYS API Specification
  604.  
  605.  
  606.                                 Table of Contents
  607.  
  608.  
  609.         1. XMS Upper Memory Blocks     ............................    1
  610.  
  611.         2. Bank-Switch Memory       ...............................    3
  612.  
  613.         3. Summary of HIGHUMM.SYS Functions     ...................    5
  614.            3.1  Function 0: Request a UMB memory block  ...........    5
  615.            3.2  Function 1: Release a UMB memory block  ...........    5
  616.            3.3  Function 2: Request a Bank-Switch memory block  ...    5
  617.            3.4  Function 3: Release a Bank-Switch memory block  ...    6
  618.            3.5  Function 4: Transfer data to/from high memory  ....    6
  619.            3.6  Function 5: Get a Word from a Bank-Switch block....    6
  620.            3.7  Function 6: Put a Word to a Bank-Switch block......    6
  621.            3.8  Function 7: Put a Byte to a Bank-Switch block......    7
  622.            3.9  Function 8: Enable Bank-Switch Memory    ..........    7
  623.            3.10  Function 9: Disable Bank-Switch Memory    ........    7
  624.            3.11  Function 10: Assign a name to a UMB or............    7
  625.            3.12  Function 11: Locate a UMB block by name ..........    8
  626.            3.13  Function 12: Locate a BSW block by name ..........    8
  627.  
  628.         4. Final Notes       ......................................    8
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.         Copyright (C) 1990-92, Key Software Products. All Rights Reserved
  661.  
  662.