NdisMAllocateMapRegisters

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

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

Parameters

MiniportAdapterHandle: Specifies the handle input to MiniportInitialize.
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 zero.
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. Together 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 Value

NdisMAllocateMapRegisters can return one of the following:

NDIS_STATUS_SUCCESS: The requested number of map registers has been allocated for the NIC and, if DmaChannel was nonzero, the specified channel has been reserved.
NDIS_STATUS_RESOURCES: Either the caller specified incompatible parameters when MiniportInitialize called NdisMSetAttributesEx or the requested number of map registers could not be allocated due to system resource constraints.

Comments

Drivers of busmaster DMA NICs call NdisMAllocateMapRegisters from their MiniportInitialize functions.

Such a driver’s MiniportInitialize function must call NdisMSetAttributes or NdisMSetAttributesEx before it calls NdisMAllocateMapRegisters. It should call NdisQueryMapRegisterCount before calling NdisMAllocateMapRegisters as well.

The given PhysicalMapRegistersNeeded is 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 MaximumPhysicalMapping and the memory PAGE_SIZE of the current platform
For a busmaster NIC, MaximumPhysicalMapping is the largest number of bytes in any virtual range described by an NDIS_BUFFER-type descriptor that can be passed to NdisMStartBufferPhysicalMapping subsequently.
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. NdisQueryMapRegisterCount returns the maximum number of map registers that can be allocated on the current platform for the type of I/O bus the NIC uses. MiniportInitialize should pass the minimum of the following values for PhysicalMapRegistersNeeded to NdisMAllocateMapRegisters:

The result of (MaximumBytesPerTransferOfNIC / PAGE_SIZE + 1)
The number of physical discontiguites per virtual transfer range that the NIC can handle in any DMA transfer operation
The value returned by NdisQueryMapRegisterCount

The map registers allocated with NdisMAllocateMapRegisters are implicitly numbered from zero through (PhysicalMapRegistersNeeded - 1). When calling NdisMStartBufferPhysicalMapping, the driver of a busmaster NIC specifies which map register to use in each call by specifying that map register’s zero-based index.

The driver of a busmaster DMA NIC must call NdisMAllocateMapRegisters before it calls NdisMAllocateSharedMemory.

Drivers of NICs that use PIO or the host DMA controller as slave devices do not call NdisMAllocateMapRegisters during initialization.

Callers of NdisMAllocateMapRegisters run at IRQL PASSIVE_LEVEL.