WdfDmaEnablerGetFragmentLength function (wdfdmaenabler.h)
[Applies to KMDF only]
The WdfDmaEnablerGetFragmentLength method returns the maximum transfer length that the operating system supports for a single DMA transfer.
Syntax
size_t WdfDmaEnablerGetFragmentLength(
[in] WDFDMAENABLER DmaEnabler,
[in] WDF_DMA_DIRECTION DmaDirection
);
Parameters
[in] DmaEnabler
A handle to a DMA enabler object that the driver obtained from a previous call to WdfDmaEnablerCreate.
[in] DmaDirection
A WDF_DMA_DIRECTION-typed value that specifies the direction of the DMA transfer operation. For more information, see the following Remarks section.
Return value
WdfDmaEnablerGetFragmentLength returns the maximum length of a DMA transfer, in bytes, that the operating system can support, or zero if the DmaDirection parameter's value is invalid.
A bug check occurs if the driver supplies an invalid object handle.
Remarks
The maximum DMA transfer length that the operating system can support depends on the number of map registers that are available. If enough map registers are available, WdfDmaEnablerGetFragmentLength returns the same value that WdfDmaEnablerGetMaximumLength returns. Otherwise, the value that WdfDmaEnablerGetFragmentLength returns will be less than the value that WdfDmaEnablerGetMaximumLength returns.
Your driver can determine the number of map registers that are available by using the BYTE_TO_PAGES macro, as follows:
BYTE_TO_PAGES(WdfDmaEnablerGetFragmentLength()) + 1
If your driver specified a duplex profile when it called WdfDmaEnablerCreate, the DmaDirection parameter's value must be WdfDmaDirectionReadFromDevice to obtain the maximum transfer length for read operations and WdfDmaDirectionWriteToDevice to obtain the maximum transfer length for write operations. If your driver did not specify a duplex profile, the driver can specify either WdfDmaDirectionReadFromDevice or WdfDmaDirectionWriteToDevice for DmaDirection.
Note that if your driver's device supports duplex operation, WdfDmaEnablerGetFragmentLength can return different values for the read and write directions that the DmaDirection parameter specifies. This difference is because the framework creates a separate adapter object for each direction, and the operating system might provide a different number of map registers to each adapter object.
Examples
The following code example determines the minimum number of map registers that are necessary to handle a NIC device's read operations, calculates the number of map registers that are available, and reports an error if the number of allocated map registers is insufficient.
ULONG minimumMapRegisters;
ULONG maxLengthSupported;
ULONG mapRegistersAllocated;
miniMapRegisters = BYTES_TO_PAGES(NIC_MAX_PACKET_SIZE) + 1;
maxLengthSupported =
(ULONG) WdfDmaEnablerGetFragmentLength(
FdoData->WdfDmaEnabler,
WdfDmaDirectionReadFromDevice
);
mapRegistersAllocated = BYTES_TO_PAGES(maxLengthSupported) + 1;
if (mapRegistersAllocated < minimumMapRegisters) {
status = STATUS_INSUFFICIENT_RESOURCES;
return status;
}
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.1 |
| Header | wdfdmaenabler.h (include Wdf.h) |
| Library | Wdf01000.sys (see Framework Library Versioning.) |
| IRQL | <=DISPATCH_LEVEL |
| DDI compliance rules | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |