NdisMAllocateMapRegisters

This function reserves system resources during network adapter 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 MiniportInitialize function.
• DmaChannel
  Specifies the bus-relative DMA channel for an ISA busmaster network adapter. If the network adapter is on another type of I/O bus, this parameter must be 0.
• Dma32BitAddresses
  Specifies TRUE if the network adapter 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 network adapter can use in a DMA operation. With MaximumPhysicalMapping, this parameter describes the DMA-transfer capabilities of the network adapter.
• MaximumPhysicalMapping
  Specifies the maximum number of bytes that the network adapter 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 network adapters 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 network adapter can handle.
• The relative sizes of the network adapter's MaximumPhysicalMapping and the memory PAGE_SIZE of the current platform.
• For a busmaster network adapter, 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 network adapter'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 network adapter 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 network adapter 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 network adapter 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 network adapter specifies which map register to use in each call by specifying that map register's 0-based index.

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

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

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

MiniportInitialize, NdisMFreeMapRegisters, NdisMSetAttributes, NdisMSetAttributesEx, NdisQueryMapRegisterCount

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.