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