NdisMAllocateMapRegisters

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

At a Glance

Header file:	Ndis.h
Windows CE versions:	2.0 and later

Syntax

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 MiniportInitialize function.
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 MiniportInitialize called the NdisMSetAttributesEx function 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 MiniportInitialize functions.

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

The specified 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 subsequently to the NdisMStartBufferPhysicalMapping function.
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 NdisQueryMapRegisterCount function 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. MiniportInitialize should pass the minimum of the following values for PhysicalMapRegistersNeeded to this function:

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 the NdisQueryMapRegisterCount function

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

The driver of a busmaster DMA NIC must call this function before it calls the NdisMAllocateSharedMemory function.

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

A driver that calls this function runs at IRQL PASSIVE_LEVEL.