Microsoft Windows CE 3.0  

NdisMAllocateMapRegisters

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function reserves system resources during NIC driver initialization for subsequent busmaster DMA operations.

NDIS_STATUS NdisMAllocateMapRegisters(
IN NDIS_HANDLE
MiniportAdapterHandle
,
IN UINT
DmaChannel
,
IN BOOLEAN
Dma32BitAddresses
,
IN ULONG
PhysicalMapRegistersNeeded
,
IN ULONG
MaximumPhysicalMapping
);

Parameters

MiniportAdapterHandle
Handle input to the MiniportInitializefunction.
DmaChannel
Specifies the bus-relative DMA channel for an ISA busmaster NIC. If the NIC is on another type of I/O bus, this parameter must be 0.
Dma32BitAddresses
Specifies TRUE if the NIC is capable of using 32-bit addressing for DMA operations.
PhysicalMapRegistersNeeded
Specifies the maximum number of map registers, each mapping a discrete physical page or contiguous range within a physical page, that the NIC can use in a DMA operation. With MaximumPhysicalMapping, this parameter describes the DMA-transfer capabilities of the NIC.
MaximumPhysicalMapping
Specifies the maximum number of bytes that the NIC can transfer as a single DMA operation.

Return Values

NDIS_STATUS_SUCCESS indicates success. NDIS_STATUS_RESOURCES indicates that either the caller specified incompatible parameters when MiniportInitializecalled the NdisMSetAttributesExfunction or the requested number of map registers could not be allocated due to system resource constraints.

Remarks

Drivers of busmaster DMA NICs call this function from their MiniportInitializefunctions.

Such a driver's MiniportInitializefunction must call NdisMSetAttributesor NdisMSetAttributesExbefore it calls this function. It should call the NdisQueryMapRegisterCountfunction before calling this function as well.

The specified PhysicalMapRegistersNeededis constrained by one of the following:

  • The number of physical discontiguities backing any specified virtual range for a DMA transfer that the NIC can handle.
  • The relative sizes of the NIC's MaximumPhysicalMappingand the memory PAGE_SIZE of the current platform.
  • For a busmaster NIC, MaximumPhysicalMappingis the largest number of bytes in any virtual range described by an NDIS_BUFFER-type descriptor that can be passed subsequently to the NdisMStartBufferPhysicalMappingfunction.
  • The number of available map registers for the NIC's I/O bus in the current platform.

    Map registers are a limited system resource, so a miniport should never allocate more map registers than its NIC can use in a DMA transfer operation. The NdisQueryMapRegisterCountfunction returns the maximum number of map registers that can be allocated on the current platform for the type of I/O bus that the NIC uses. MiniportInitializeshould pass the minimum of the following values for PhysicalMapRegistersNeededto this function: