Microsoft KB Archive/93469

{|
 * width="100%"|

Complete Text PW0519: Virtual DMA Services (VDS)

 * }

Q93469

-

The information in this article applies to:


 * Microsoft Windows Software Development Kit (SDK) versions 3.0, 3.1

-

SUMMARY
====================================================================== 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 &quot;AS IS&quot; 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.                      |
 * 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 &quot;No buffer available&quot; 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 &quot;owned&quot; 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 &quot;unowned&quot; 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 (&quot;Function not supported&quot;).

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 &quot;No buffer error available&quot; error (error code 04h).

- If an application receives a &quot;Buffer currently in use&quot; 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 &quot;wrap&quot; 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 Additional query words: no32bit 3.00 3.10 appnote PW0519

Keywords : kb16bitonly

Issue type :

Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK300 kbWinSDK310