NdisMAllocateMapRegisters function

Article
06/19/2017

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisMAllocateMapRegisters reserves system resources during miniport driver initialization for subsequent bus-master DMA operations.

Syntax

NDIS_STATUS NdisMAllocateMapRegisters(
  _In_ NDIS_HANDLE   MiniportAdapterHandle,
  _In_ UINT          DmaChannel,
  _In_ NDIS_DMA_SIZE DmaSize,
  _In_ ULONG         BaseMapRegistersNeeded,
  _In_ ULONG         MaximumBufferSize
);

Parameters

MiniportAdapterHandle [in]
Specifies the handle input to MiniportInitialize.
DmaChannel [in]
Specifies the bus-relative DMA channel for an ISA bus-master NIC. If the NIC is on another type of I/O bus, this parameter must be zero.
DmaSize [in]
Specifies the address size that the NIC uses for DMA operations as one of the following:
- NDIS_DMA_24BITS
  24-bit DMA address
- NDIS_DMA_32BITS
  32-bit DMA address
- NDIS_DMA_64BITS
  64-bit DMA address
When NDIS_DMA_64BITS is specified on a system that is running the Microsoft Windows 2000 and later DataCenter Server operating system with Physical Address Extension (PAE) enabled, the physical addresses of mapped buffers can be greater than 32 bits.
BaseMapRegistersNeeded [in]
Specifies the number of base map registers required by the driver. The driver should request one base map register for each DMA send buffer that it requires. For each requested base map register, NDIS allocates one or more map registers, each of which maps a page of physical memory. NDIS allocates a sufficient number of map registers per requested base register to create a send buffer large enough to contain the specified MaximumBufferSize. NDIS imposes a limit of 64 map registers per miniport driver. If the total number of map registers that NDIS would have to allocate would exceed 64, NdisMAllocateMapRegisters returns NDIS_STATUS_RESOURCES. For more information about specifying BaseMapRegistersNeeded, see the Remarks below.
MaximumBufferSize [in]
Specifies the size, in bytes, of the largest send buffer required by the driver for a DMA transfer.

Return value

NdisMAllocateMapRegisters can return one of the following:

Return code	Description
NDIS_STATUS_SUCCESS	NDIS allocated enough map registers per requested base map register to accommodate the specified MaximumBufferSize. If DmaChannel was nonzero, the specified channel has been reserved.
NDIS_STATUS_RESOURCES	One of the following occurred: NDIS could not allocate enough map registers because of system resource constraints. The total number of map registers that NDIS would have to allocate for the requested number of base map registers exceeds 64.

NDIS_STATUS_SUCCESS

NDIS allocated enough map registers per requested base map register to accommodate the specified MaximumBufferSize. If DmaChannel was nonzero, the specified channel has been reserved.

NDIS_STATUS_RESOURCES

One of the following occurred:

NDIS could not allocate enough map registers because of system resource constraints.
The total number of map registers that NDIS would have to allocate for the requested number of base map registers exceeds 64.

Remarks

A driver of a bus-master DMA NIC calls NdisMAllocateMapRegisters from its MiniportInitialize function. The driver's MiniportInitialize function must call NdisMSetAttributes or NdisMSetAttributesEx before it calls NdisMAllocateMapRegisters.

If its NIC can use 32-bit or 64-bit addressing for DMA operations, a miniport driver should not set DmaSize to NDIS_DMA_24BITS. A PCI NIC, for example, should always set DmaSize to NDIS_DMA_32BITS or NDIS_DMA_64BITS. System memory below 16MB is a scarce resource. Setting DmaSize to NDIS_DMA_24BITS could therefore cause NdisMAllocateMapRegisters to return NDIS_STATUS_RESOURCES.

To determine how many BaseMapRegistersNeeded the miniport driver should request, consider the following:

The number of map registers that NDIS will allocate per requested base map register, based on the MaximumBufferSize
The number of send buffers required by the miniport driver for optimum performance
The NDIS-imposed limit of 64 map registers per miniport driver

If, for example, a miniport driver for an Ethernet NIC has a maximum send-packet size of 1512 bytes, it should specify a MaximumBufferSize of 1512. Given a page size of 4 Kbytes, a buffer of 1512 bytes can span two physical pages. NDIS therefore allocates two map registers per requested base register. To stay within the limit of 64 map registers, in this case, the miniport driver must request no more than 32 base map registers.

If the miniport driver's MaximumBufferSize is large enough so that NDIS would have to allocate numerous map registers per requested base map register, the miniport driver should call NdisMInitializeScatterGatherDma instead of NdisMAllocateMapRegisters to allocate DMA resources. Otherwise, the miniport driver may not be able to allocate enough send buffers to perform well. For example, a miniport driver that specifies a MaximumBufferSize of 64 Kbytes can request no more than three base registers because NDIS, in this case, will allocate 17 map registers per base register. (With a page size of 4 Kbytes, a 64-Kbyte buffer can span 17 physical pages.) Requesting more than three base registers would cause NdisMAllocateMapRegisters to return NDIS_STATUS_RESOURCES because NDIS would enforce the limit of 64 map registers per miniport driver.

Note that, on systems enabled for Physical Address Extension (PAE), requesting too many base map registers can cause the system to stop responding because not enough map registers are available to satisfy the request. PAE-enabled systems that have more than one NIC are even more likely to stop responding in this situation.

The map registers allocated with NdisMAllocateMapRegisters are implicitly numbered from zero. When calling NdisMStartBufferPhysicalMapping, the driver of a bus-master NIC specifies which map register to use in each call by specifying that map register's zero-based index.

The driver of a bus-master DMA NIC must call NdisMAllocateMapRegisters before it calls NdisMAllocateSharedMemory.

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

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL

Share via