======================================================================
  Microsoft(R) Product Support Services Application Note (Text File)
                  PW0519: Virtual DMA Services (VDS)
======================================================================
                                                   Revision Date: 9/92
                                                      No Disk Included

The following information applies to Microsoft Windows(TM) Software
Development Kit versions 3.0 and 3.1.

 --------------------------------------------------------------------
| INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY    |
| ACCOMPANY THIS DOCUMENT (collectively referred to as an            |
| Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY      |
| KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO    |
| THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A     |
| PARTICULAR PURPOSE. The user assumes the entire risk as to the     |
| accuracy and the use of this Application Note. This Application    |
| Note may be copied and distributed subject to the following        |
| conditions: 1) All text must be copied without modification and    |
| all pages must be included; 2) If software is included, all files  |
| on the disk(s) must be copied without modification [the MS-DOS(R)  |
| utility DISKCOPY is appropriate for this purpose]; 3) All          |
| components of this Application Note must be distributed together;  |
| and 4) This Application Note may not be distributed for profit.    |
|                                                                    |
| Copyright 1990-1992 Microsoft Corporation. All Rights Reserved.    |
| Microsoft and MS-DOS are registered trademarks and Windows         |
| is a trademark of Microsoft Corporation.                           |
| IBM and AT are registered trademarks and XT is a trademark of      |
| International Business Machines Corporation.                       |
 --------------------------------------------------------------------

                             INTRODUCTION
                             ============

An MS-DOS device driver that performs direct memory access (DMA)
programs a hardware controller with the address of a buffer region.
The DMA controller places the following restrictions on an acceptable
DMA buffer region:

   -  The DMA buffer region must be in contiguous physical memory.
   
   -  On IBM(R) PC/XT(TM)-compatible machines, the DMA buffer region
      must be in the first 1 megabyte (MB) of memory.
   
   -  On IBM PC/XTs, IBM PC/AT(R)s, and compatibles, the DMA buffer
      region must not cross a 64-kilobyte (K) or 128K alignment
      boundary.

However, software running in a protected mode environment, whether
running in virtual 8086 mode under Windows or in protected mode under
an MS-DOS extender, usually cannot determine the physical address of
the appropriate DMA buffer region. To compensate for this limitation,
the Virtual DMA Services (VDS) enable a device driver or application
program to obtain the information required to program a DMA transfer
using either the on-board DMA controller or a bus master DMA
controller.

The VDS are provided through Interrupt 4Bh. The VDS provider software
sets a bit in the BIOS data area to indicate the availability of the
VDS. Before using the VDS, an application or driver must load the byte
at address 0040:007Bh. If bit 5 of this byte is set, VDS provider
software is present, and the VDS can be used. If bit 5 is clear, the
VDS are not available.

  NOTE: If bit 5 of the byte at 0040:007Bh is clear, the processor is
  probably running in real mode, where all memory is mapped with its
  physical address equal to its linear address, and the application or
  driver can directly program the DMA device without modification.
  However, the processor may actually be running in virtual 8086 mode
  under protected mode software that does not support the VDS. Under
  these circumstances, there is no way to determine if the physical
  and linear address are the same.

An implementation of the VDS on a 386 or faster processor must do one
of the following:

   -  Automatically remap pages to force regions of memory to be
      physically contiguous
   -  Support a DMA buffer of at least 16K, if paging is enabled by
      the system software

On a 386 processor, neither of these characteristics is required.

With the exception of the AX register and Carry flag, all registers
and flags are preserved across VDS calls unless otherwise specified.
If the Carry flag is set upon return from a VDS call, the AL register
contains an error code. Otherwise, the contents of the AX register are
undefined upon return.


                 NOTES FOR WRITING DMA DEVICE DRIVERS
                 ====================================

Applications and device drivers that use the VDS must verify that bit
5 of the byte at 0040:007Bh is set before programming DMA. The VDS
provider software may initialize or terminate DMA services at any
time. For example, when an application first uses simulated expanded
memory, a limulator places the processor into virtual 8086 mode and
enables the VDS. (A limulator is an application that emulates expanded
memory using the Lotus/Intel/Microsoft [LIM] Expanded Memory
Specification [EMS].) When all memory provided by the limulator is
freed, the limulator typically returns the processor to real mode and
terminates the VDS.

Note also that the type of DMA support provided may change
dynamically. For example, the user may run one protected mode
environment, close it, and then run a second protected mode
environment. In this example, the VDS are provided by two separate
implementations.

Device drivers can provide various levels of support for DMA. The
options are listed below and are ordered from most desirable to least
desirable:

   -  Scatter/gather operations are supported by the hardware DMA
      adapter.
   -  The VDS provider software parcels the DMA requests, eliminating
      the need for a buffer.
   -  The VDS provider software parcels the DMA requests into 16K or
      smaller pieces, using the default buffer.
   -  The user is required to override the default buffer size.

For all practical purposes, the final option listed above is
unacceptable. At the very least, the VDS provider software should
parcel DMA transfers into pieces no larger than 16K. For example, the
VDS provider software could break transfers to a hard disk at a track
boundary. For most hard disks, one track fits into a 16K buffer.

However, for devices that are less sensitive to timing than a hard
drive, the VDS provider software can parcel each DMA transfer into
larger pieces. Ideally, all DMA hardware adapters would include
support for scatter/gather operations.

In some situations, a device driver has a real physical address to
specify in a DMA transfer. This address may be for a block of memory
allocated from extended memory or through Interrupt 15h before the VDS
was enabled, for memory on an adapter card, and so forth. In these
situations, the application must not call the Lock DMA Buffer Region
service because the VDS functions interpret region addresses as linear
addresses. If the standard DMA controller performs the transfer, the
application must still call the Disable DMA Translation and Enable DMA
Translation services.

By convention, the buffer identifier 0 in a DMA descriptor data
structure (DDS) indicates that no buffer has been allocated. The
device driver can check this field to determine if a buffer was
allocated.


                  NOTES FOR IMPLEMENTING DMA SERVICES
                  ===================================

On a machine with an 80386 processor, the recommended method of
supporting the VDS is to use a DMA buffer. A buffer has been found to
be faster than remapping memory on these machines. On a machine
equipped with an 80286 processor, the VDS can be implemented without
implementing a buffer. On these machines, the software calling the
services must parcel out transfers to avoid crossing alignment
boundaries. Implementations that do not include any buffers must
return the "No buffer available" error (code 04h) in response to the
Request DMA Buffer service (service 07h).

Each implementation of the VDS should provide a mechanism for
overriding the size of the DMA buffer or remap region. Each
implementation should also provide a mechanism for forcing the buffer
or remap region to reside in the first megabyte of physical memory.
These mechanisms are implementation dependent. For example, one VDS
implementation may use a configuration file while another may use a
set of command-line switches.

Lock DMA Buffer Region calls for the following types of memory must
not fail:

   -  Memory that is not "owned" by the VDS provider software
   -  Memory allocated before the VDS provider software started
      running (including low memory)
   -  The EBIOS data area
   -  Extended memory allocated through Interrupt 15h or the Extended
      Memory Specification (XMS)

If a VDS implementation supports auto-remapping, pages must be
remapped to create contiguous regions. If auto-remapping is not
supported, the VDS provider software must keep these memory areas
contiguous. Also, some environments include device drivers that
attempt long-term DMA transfers. In these environments, the user must
be able to configure the software to enable DMA transfers to take
place. One solution is to install long-term DMA device drivers only
after the VDS provider software. The other solution is to keep all
"unowned" memory mapped to its original location to keep its linear
memory address equal to its physical memory address. Mapping memory in
this way allows DMA transfers started prior to the VDS to continue as
normal.

Because other hardware and software services can be provided on the
Interrupt 4Bh chain, the VDS provider software must determine if it
should chain interrupts when AH is not 81h. On Micro Channel
Architecture (MCA) machines, this information is available in bit 3 of
the byte at 0040:007Bh. The following table provides the
interpretation for the contents of this bit:

   Interrupt 4Bh Intercepted Indicator (MCA Only)
   ----------------------------------------------
   
   Bit 3 Set    Interrupt vector intercepted. Chaining is required.
   Bit 3 Clear  Interrupt vector not intercepted. Action depends on
                the contents of the interrupt vector. If the vector
                contains 0:0, or if the vector's segment value is
                E000h or F000h, chaining is not permitted.

On other architectures, examining the value of the interrupt vector
may be the only method of determining if interrupts should be chained.

If the VDS provider software does not chain interrupts, it should
execute an IRET instruction to ignore the interrupt without modifying
any registers or flags.

DETERMINING WHICH ERROR CODES TO RETURN
=======================================

An application should implement the following pseudocode to access the
Lock DMA Buffer Region service (service 8103h):

   IF region contiguous THEN
      IF region does not cross alignment boundary THEN
         BEGIN
         Lock region
         Set Buffer_ID field to 0
         Return with Carry flag clear
         END
      ELSE
         PERFORM Buffer/Remap
      ENDIF
   ELSE
      PERFORM Buffer/Remap
   ENDIF


BUFFER/REMAP Function
---------------------

   IF buffer supported THEN
      IF Buffer Disable flag clear THEN
         PERFORM Buffer
      ELSE
         Return with Carry flag set and AL=1, 2, or 3
      ENDIF
   ELSE
      IF remap supported THEN
         IF Remap Disable flag clear THEN
            PERFORM Remap
         ELSE
            Return with Carry flag set and AL=1, 2, or 3
         ENDIF
      ELSE
         Return with Carry flag set and AL=1, 2, or 3
      ENDIF
   ENDIF


BUFFER Function
---------------

   IF buffer available THEN
      IF region size <= buffer size THEN
         BEGIN
         Allocate buffer
         IF Copy flag set THEN
            Copy data from linear region to buffer
         ENDIF
         Set Buffer_ID field (nonzero)
         Set Physical_Address field to buffer physical address
         Return with Carry flag clear
        END
      ELSE
         Return with Carry flag set and AL=05h
      ENDIF
   ELSE
      Return with Carry flag set and AL=06h
   ENDIF


REMAP Function
--------------

   IF region can be forced contiguous THEN
      IF region will not cross specified boundary THEN
         BEGIN
         Force region contiguous
         Set Physical_Address field
         Set Buffer_ID field to 0
         Return with Carry flag clear
         END
      ELSE
         Return with Carry flag set and AL=02h
      ENDIF
   ELSE
      Return with Carry flag set and AL=01h
   ENDIF


                               SERVICES
                               ========

Most services require a pointer to a DMA DDS as one parameter. The DDS
is defined as follows:

   DDS                   STRUCT
     Region_Size         DWORD     ?    ; offset 0
     Offset              DWORD     ?    ; offset 4
     Seg_or_Select       WORD      ?    ; offset 8
     Buffer_ID           WORD      ?    ; offset A
     Physical_Address    DWORD     ?    ; offset C
   DDS                   ENDS

Region_Size is a double word (DWORD, or 32-bit quantity) at offset 0.
It specifies the size of the DMA buffer region in bytes.

Offset and Seg_or_Select (segment/selector) are a far word (FWORD, or
48-bit quantity) pair at offset 04h. They specify a segment:offset
pointer in virtual 8086 mode, or a selector:offset pointer in
protected mode.

  NOTE: If the linear address has been determined, the application can
  set the Seg_or_Select field to 0 and place the linear address in the
  Offset field. An application can specify a 32-bit value in the
  Offset field even with a real mode segment value. This eases the
  process of parceling a DMA transfer in a device driver; the driver
  can modify the Offset value without changing the Seg_or_Select
  value.

Buffer_ID is a word (16-bit quantity) at offset 0Ah. This field is set
by the Request DMA Buffer service. (It might also be set by the Lock
DMA Buffer Region service.)

Physical_Address is a double word at offset 0Ch. This field is set by
the Lock DMA Buffer Region and Request DMA Buffer services.


RESERVED SUBFUNCTIONS
=====================

Functions 00h, 01h, and 0Dh through 0FFh are reserved. Any of these
functions returns with the Carry flag set and the AL register set to
0Fh ("Function not supported").

Notes
   
None.

GET VERSION
-----------

This service returns the VDS version number, information about the
hardware and buffer size, and whether automatic memory remapping is
supported.

To Call
   
   AH = 81h
   AL = 02h
   DX = Flags
   All bits are reserved and must be 0.

Returns
   
   If function was successful:
   
      Carry flag is clear.
      AH = Major specification version number (binary, currently 1)
      AL = Minor specification version number (binary, currently 0)
      BX = Product number
      CX = Product revision number
      SI:DI = Maximum DMA buffer size supported (size in bytes)
      DX = Flags
          Bit 0 = 1 If PC/XT bus architecture (DMA in first megabyte
                    only)
          Bit 1 = 1 If physical buffer/remap region is in first
                    megabyte
          Bit 2 = 1 If automatic remap supported
          Bit 3 = 1 If all memory physically contiguous
          Other flags are reserved and must be 0.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
          10h = Reserved flag bits set in DX

Notes
   
   -  The version numbers returned in the AH and AL registers
      determine the functionality supported by a VDS implementation.
      Drivers that support the functionality described in this
      document return AX=0100h.
   
   -  Bit 3 of the flag word is set only in an environment that runs
      in protected mode but does not perform paging. One example of
      such an environment is an 80286 MS-DOS extender. When bit 3 is
      set, the VDS services only convert selector:offset linear
      address pairs into physical addresses.

LOCK DMA BUFFER REGION
----------------------

An application calls this service to determine if a target DMA buffer 
region is in contiguous physical memory. If so, this service returns 
the physical address of the region that the VDS provider software can 
use to program the DMA channel. A locked DMA buffer region must be 
unlocked once DMA is complete.

If the DMA controller has memory-placement restrictions (for example,
if the memory must be addressed in the first megabyte), the device
driver can examine the returned physical address. If the address is
unsuitable, the driver must unlock the region and request a DMA
buffer.

Some implementations of the VDS attempt to remap memory pages to force
the region to be contiguous physical memory. The calling application
can disable this behavior by setting bit 3 in the DX register. Under
most circumstances, a device can parcel transfers or use a DMA buffer
more quickly than the VDS can remap pages.

This service has an automatic buffer-allocation option that is often
very convenient to use. When an application specifies this option, if
the DMA buffer region cannot be locked for any reason, the VDS will
attempt to allocate a DMA buffer. The VDS can automatically copy the
data in the DMA buffer region into the allocated buffer.

To Call
   
   AH = 81h
   AL = 03h
   DX = Flags
      Bit 1 = 1  If data should be copied into buffer (ignored if bit 2
                 = 1)
      Bit 2 = 1  Disable buffer allocation if DMA buffer region not
                 contiguous or crosses a physical alignment boundary
                 specified by bits 4 and 5
      Bit 3 = 1  Disable automatic remap attempt
      Bit 4 = 1  If region must not cross a 64K physical alignment
                 boundary
      Bit 5 = 1  If region must not cross a 128K physical alignment
                 boundary
      All other bits are reserved and must be 0.
      
   ES:DI = Pointer to DDS
      The caller must complete the Region_Size, Offset, and
      Seg_or_Select fields in the data structure before calling this
      service.

Returns
   
   If function was successful:
   
      Carry flag is clear.
      Memory is locked.
      The Physical_Address field of DDS contains the starting physical
      address of the region.
      The Buffer_ID field will contain the ID of the allocated buffer
      or 0 if no buffer was allocated.
   
   If function was not successful:
   
      Carry flag is set.
      Memory is NOT locked.
      Region_Size field of DDS contains the maximum contiguous length
      in bytes.
      AL = Error code
         01h = Region not in contiguous memory
         02h = Region crossed a physical alignment boundary
         03h = Unable to lock pages (virtual memory systems only)
         05h = Region too large for buffer
         06h = Buffer currently in use
         07h = Invalid memory region
         10h = Reserved flag bits set in DX

Notes
   
   -  The VDS locks memory on a page-by-page basis. A page can be
      locked more than once, which allows two DMA buffer regions to
      overlap on a page. The VDS maintains page locking as a count.
      Some systems need not maintain a count because memory is never
      discarded or moved. In these systems, the Unlock DMA Buffer
      Region service will never fail.
   
   -  If an application selects the automatic buffer-allocation option
      by clearing bit 2 of the flags in the DX register, the VDS will
      automatically allocate a DMA buffer if the region cannot be
      locked. An application sets bit 1 to indicate that the data
      should be copied into the buffer for a memory-read operation.
      When the Lock DMA Buffer Region Service fails and bit 2 is clear
      but no buffer is supported, VDS reports the actual cause of the
      error, rather than returning a "No buffer error available" error
      (error code 04h).
   
   -  If an application receives a "Buffer currently in use" error
      (error code 06h), it can wait in a loop to allow another device
      time to release the buffer. For more details, refer to the
      documentation for the Request DMA Buffer service below in this
      document.
   
   -  An application should use the buffer-alignment mask with devices
      that have physical memory boundary constraints. For example,
      with the PC/AT architecture, the standard DMA controllers "wrap"
      memory address calculations at 64K or 128K physical boundaries.
      If the programmed DMA controller has an alignment constraint,
      set the applicable bit in the DX register.

UNLOCK DMA BUFFER REGION
------------------------

This service unlocks a previously locked DMA buffer region.

To Call
   
   AH = 81h
   AL = 04h
   DX = Flags
      Bit 1 = 1  If data should be copied out of buffer
      All other bits are reserved and must be 0.
      
   ES:DI = Pointer to DDS
      The caller must complete the Region_Size, Physical_Address, and
      Buffer_ID fields before calling this service. (Usually the
      caller specifies the data structure completed by a call to the
      Lock DMA Buffer Region service.)

Returns
   
   If function was successful:
   
      Carry flag is clear.
      Memory is unlocked or no count is maintained.

   If function was not successful:
   
      Carry flag is set.
      All memory remains locked.
      AL = Error code
         08h = Region was not locked
         0Ah = Invalid Buffer_ID
         10h = Reserved flag bits set in DX

Notes
   
If the Buffer_ID field of the DDS data structure is nonzero, this
service releases the DMA buffer allocated by the Lock DMA Buffer
Region service. Any data in the buffer is lost. If the DMA transfer
was a memory-write operation and bit 1 in the DX register is set, this
service will copy the data from the DMA buffer before the buffer is
released.

SCATTER/GATHER LOCK REGION
--------------------------

This service allows a hardware device that supports automatic
scatter/gather operations to determine the physical regions of a
linear address range and to lock the linear address range in one
service. A device driver that parcels DMA requests can use this
service instead of repeatedly calling Lock DMA Buffer Region.

To Call
   
   AH = 81h
   AL = 05h
   DX = Flags
      Bit 6 = 1 If an extended data descriptor structure (EDDS) should
                be returned with page-table entries.
      Bit 7 = 1 If only present pages should be locked. Not-present
                pages are identified with a page-table entry of 0 (if
                bit 6 = 0, bit 7 is ignored).
      All other bits are reserved and must be 0.
   
   ES:DI = Pointer to one of the following extended EDDS's:
      
      If bit 6 of the DX register is 0, this service returns an EDDS
      with a table of physical regions (address and size pairs), as
      follows:
      
         EDDS                 STRUCT
           Region_Size        DWORD     ?    ; offset  0h
           Offset             DWORD     ?    ; offset  4h
           Seg_or_Select      WORD      ?    ; offset  8h
           Reserved           WORD      0    ; offset  Ah
           Number_Avail       WORD      ?    ; offset  Ch
           Number_Used        WORD      ?    ; offset  Eh
           R0_Physical_Addr   DWORD     ?    ; offset 10h
           R0_Size            DWORD     ?    ; offset 14h
           R1_Physical_Addr   DWORD     ?    ; offset 18h
           R1_Size            DWORD     ?    ; offset 1Ch
           ...
           Rn_Physical_Addr   DWORD     ?    ; offset 10h + n*8
           Rn_Size            DWORD     ?    ; offset 14h + n*8
         EDDS                 ENDS
      
      If bit 6 of the DX register is 1, this service returns an EDDS
      with a table of page-table entries (one entry per 4K page, the
      same format as 80386 page-table entries), as follows:
      
         EDDS                 STRUCT
           Region_Size        DWORD     ?    ; offset  0h
           Linear_Offset      DWORD     ?    ; offset  4h
           Seg_or_Select      WORD           ?   ; offset  8h
           Reserved           WORD           0   ; offset  Ah
           Number_Avail       WORD           ?   ; offset  Ch
           Number_Used        WORD           ?   ; offset  Eh
           Page_Table_Ent0    DWORD     ?    ; offset 10h
           Page_Table_Ent1    DWORD     ?    ; offset 14h
           ...
           Page_Table_Entn    DWORD     ?    ; offset 10h + n*4
         EDDS                 ENDS
            
           Each page-table entry contains the physical page number in
           the upper 20 bits; the lower 12 bits are flag bits, as
           follows:
            
               Bit 0 = 1 If the page is present and locked
               Bits 1 through 11 are reserved and set to 0

           If option bit 7 is 1, then pages in the region that do not
           have a physical page assigned will have a page-table entry
           of 0 and are not locked by this service.

      The caller must complete the Region_Size, Offset (or
      Linear_Offset), Seg_or_Select, and Number_Avail fields. The
      Number_Avail field specifies the number of physical regions
      (page-table entries) in the EDDS.

Returns
   
   If function was successful:
   
      Carry flag is clear.
      The Number_Used field contains the number of table entries
      filled in with information about physical regions.
      If bit 6 of the DX register was set (page-table copy), bits 0
      through 11 of the BX register are set to the offset in the first
      page to the start of the DMA buffer region. Bits 12 through 15
      are 0.

   If function was not successful:
   
      Carry flag is set.
      Memory is NOT locked.
      The Region_Size field contains the maximum number of bytes that
      can be locked and described in the DDS table.
      The physical regions (table entry) fields are undefined.
      AL = Error code
          03h = Unable to lock pages
          07h = Invalid memory region
          09h = Number of physical pages was greater than table
                length. (The Number_Used field will contain the number
                of table entries required to describe the DMA buffer
                region.)
          10h = Reserved flag bits set in DX

Notes
   
Given a linear address and the size of the DMA buffer region, the
maximum number of physical regions required to describe a DMA buffer
region is computed as follows:

   (Linear Address AND 0FFFh) + Region Size + 0FFFh
   ------------------------------------------------
                          1000h

SCATTER/GATHER UNLOCK REGION
----------------------------

This service unlocks a DMA buffer region locked by the Scatter/Gather
Lock Region service.

To Call
   
   AH = 81h
   AL = 06h
   DX = Flags
      Bit 6 = 1 If the EDDS contains page-table entries.
      Bit 7 = 1 If the EDDS may contain not-present pages. Not-present
                pages are identified with a page-table entry of 0 (if
                bit 6 = 0, bit 7 is ignored).
      All other bits are reserved and must be 0.
      
   ES:DI = Pointer to the EDDS specified in a call to the
   Scatter/Gather Lock Region service.

Returns
   
   If function was successful:
   
      Carry flag is clear.
      Memory is unlocked.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
         08h = Region was not locked
         10h = Reserved flag bits set in DX

Notes

This service uses only the Region_Size, Offset (or Linear_Offset), and
Seg_or_Select fields of the EDDS. Therefore, the application need not
maintain the physical address (page-table) entries unless bits 6 and 7
in the DX register are set in the corresponding call to the
Scatter/Gather Lock Region service. If an application uses this
special form of region locking, the table is required to unlock the
correct pages.

REQUEST DMA BUFFER
------------------

To perform buffered DMA, a device driver must perform the following
steps:

   -  Request a DMA buffer
   -  Copy data into the buffer (when a memory-read operation is
      performed)
   -  Program the DMA channel and initiate the transfer
   -  Copy data from the buffer (when a memory-write operation is
      performed)
   -  Release the DMA buffer

The driver must copy the data from the buffer before the buffer is
released. The physical address of the buffer is not valid after the
buffer is released.

To Call
   
   AH = 81h
   AL = 07h
   DX = Flags
      Bit 1 = 1 If data should be copied into the buffer
      All other bits are reserved and must be 0.
   ES:DI = Pointer to DDS
      The caller must complete the Region_Size field. If automatic
      copy is selected (flag bit 1 is set), the caller must also
      complete the Seg_or_Select and Offset fields.

Returns
   
   If function was successful:
   
      Carry flag is clear.
      The Physical_Address field of the DDS contains the starting
      physical address of the buffer.
      The Region_Size field specifies the size of the buffer.
      The Buffer_ID field contains the identifier of the allocated
      buffer.
      If automatic copy was selected, then data was copied into the
      buffer.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
         04h = No buffer available
         05h = Region too large for buffer
         06h = Buffer currently in use
         07h = Invalid memory region
         10h = Reserved flag bits set in DX

Notes
   
   -  Under the 386 enhanced mode of Windows, a device should enter a
      Windows critical section to prevent another virtual machine from
      running while a DMA buffer is in use.
   
   -  If the buffer is currently in use (error code 06h), the
      application can loop with interrupts enabled repeatedly,
      attempting to allocate the buffer. Doing so gives another device
      time to complete its DMA transfer.
   
   -  A device driver must either poll for the DMA operation to
      complete or receive a hardware interrupt. Once DMA is complete,
      the driver releases ownership of the DMA buffer. If ownership is
      released in response to a hardware interrupt, other devices can
      wait for the buffer as described above.

RELEASE DMA BUFFER
------------------

This service releases a DMA buffer that was previously requested. The
buffer's physical address is invalidated by this service.

To Call
   
   AH = 81h
   AL = 08h
   DX = Flags
      Bit 1 = 1 If data should be copied out of buffer
      All other bits are reserved and must be 0.
   
   ES:DI = Pointer to DDS
      The caller must complete the Buffer_ID field of the DDS before
      calling this service.

Returns
   
   If function was successful:
   
      Carry flag is clear.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
         0Ah = Invalid Buffer_ID
         10h = Reserved flag bits set in DX

Notes
   
None.

COPY INTO DMA BUFFER
--------------------

Copy data from a user-specified buffer into the DMA buffer to prepare
for a memory-read DMA transfer.

To Call
   
   AH = 81h
   AL = 09h
   DX = Flags
      All bits are reserved and must be 0.
      
   ES:DI = Pointer to DDS
      The caller must complete the Buffer_ID, Offset, Seg_or_Select,
      and Region_Size fields. The Offset and Seg_or_Select fields
      specify the source address for the copy operation.
      
   BX:CX = Starting offset in DMA buffer to copy
      The Region_Size field of the DDS determines the number of bytes
      to copy.

Returns
   
   If function was successful:
   
      Carry flag is clear.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
         0Ah = Invalid Buffer_ID
         0Bh = Buffer boundary violated
         10h = Reserved flag bits set in DX

Notes
   
None.

COPY OUT OF DMA BUFFER
----------------------

Copy data from a DMA buffer into a user-specified buffer after a
memory-write DMA transfer.

To Call
   
   AH = 81h
   AL = 0Ah
   DX = Flags
      All bits are reserved and must be 0.
      
   ES:DI = Pointer to DDS
      The caller must complete the Buffer_ID, Offset, Seg_or_Select,
      and Region_Size fields. The Offset and Seg_or_Select fields
      specify the destination address for the copy operation.
      
   BX:CX = Starting offset in DMA buffer to copy
      The Region_Size field of the DDS determines the number of bytes
      to copy.

Returns
   
   If function was successful:
   
      Carry flag is clear.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
         0Ah = Invalid Buffer_ID
         0Bh = Buffer boundary violated
         10h = Reserved flag bits set in DX

Notes
   
None.

DISABLE DMA TRANSLATION
-----------------------

Environments that support the VDS trap the standard DMA I/O ports and
attempt to remap the addresses provided by the client application
(assumed to be linear addresses) into appropriate physical addresses.
However, an application that uses the VDS to determine the physical
address of its DMA buffer region must call this service to disable the
remapping of standard DMA ports.

This service maintains a disable count. Therefore, one call to Enable
DMA Translation must be made for each call to the Disable DMA
Translation service before automatic DMA translation is enabled.

To Call
   
   AH = 81h
   AL = 0Bh
   BX = DMA channel number
   DX = Flags
      All bits are reserved and must be 0.

Returns
   
   If function was successful:
   
      Carry flag is clear.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
         0Ch = Invalid DMA channel number
         0Dh = Disable count overflow
         10h = Reserved flag bits set in DX

Notes
   
None.

ENABLE DMA TRANSLATION
----------------------

An application calls this service to reenable automatic DMA buffer
remapping that was disabled by the Disable DMA Translation service.

This service maintains a disable count. Therefore, one call to Enable
DMA Translation must be made for each call to the Disable DMA
Translation service before automatic DMA translation is enabled.

To Call
   
   AH = 81h
   AL = 0Ch
   BX = DMA channel number
   DX = Flags
      All bits are reserved and must be 0.

Returns
   
   If function was successful:
   
      Carry flag is clear.
      If disable count is decremented to 0, the Zero flag is set.

   If function was not successful:
   
      Carry flag is set.
      AL = Error code
         0Ch = Invalid DMA channel number
         0Eh = Disable count underflow (was not previously disabled; 
               count not changed)
         10h = Reserved flag bits set in DX

Notes
   
None.
                                   
                SUMMARY OF ERROR CODES AND OPTION FLAGS
                =======================================

ERROR CODES
===========

   01h = Region not in contiguous memory
   02h = Region crossed a physical alignment boundary
   03h = Unable to lock pages
   04h = No buffer available
   05h = Region too large for buffer
   06h = Buffer currently in use
   07h = Invalid memory region
   08h = Region was not locked
   09h = Number of physical pages was greater than table length
   0Ah = Invalid Buffer_ID
   0Bh = Buffer boundary violated
   0Ch = Invalid DMA channel number
   0Dh = Disable count overflow
   0Eh = Disable count underflow
   0Fh = Function not supported
   10h = Reserved flag bits set in DX

OPTION FLAGS
============

   Bit 1 = Automatically copy to/from buffer
   Bit 2 = Disable automatic buffer allocation
   Bit 3 = Disable automatic remap feature
   Bit 4 = Region must not cross 64K physical alignment boundary
   Bit 5 = Region must not cross 128K physical alignment boundary
   Bit 6 = Copy page-table for scatter/gather remap
   Bit 7 = Allow non-present pages for scatter/gather remap


