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:

  • 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 NdisQueryMapRegisterCountfunction

    The map registers allocated with this function are implicitly numbered from 0 through ( PhysicalMapRegistersNeeded1). When calling the NdisMStartBufferPhysicalMappingfunction, 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 NdisMAllocateSharedMemoryfunction.

    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.

    Requirements

    Runs on	Versions	Defined in	Include	Link to
    Windows CE OS	2.0 and later	Ndis.h

    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

    NdisMFreeMapRegisters, NdisMSetAttributes, NdisMSetAttributesEx, NdisQueryMapRegisterCount

    
    

    ---

     Last updated on Tuesday, July 13, 2004

    © 2004 Microsoft Corporation. All rights reserved.