Allocating Memory (NDIS 5.1)
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.
During initialization, a miniport driver generally allocates any buffers, packet descriptors and buffer descriptors that it requires to send and receive data. The type and amount of memory that must be allocated depends on the type of NIC, as well as on the type of receive paradigm supported by the miniport driver.
Memory can be shared or unshared. A driver allocates shared memory only when that memory will be accessed by a bus-master DMA NIC. Miniport drivers for bus-master DMA NICs must allocate shared memory for any buffers that will be accessed by both the miniport driver and the NIC. Shared memory is a scarce system resource and is therefore harder to allocate.
A miniport driver that manages a bus-master DMA NIC must ensure that any cached memory it uses is coherent before reading received data from the buffer or before sending data from the buffer. Such a miniport driver must flush its buffers to ensure cache coherency on sends and receives.
A miniport driver that manages a subordinate DMA NIC or a non-DMA NIC does not have to maintain cache coherency. The NdisXxx functions called by a miniport driver for subordinate DMA NIC perform memory flushes on behalf of the miniport driver. A miniport driver for a non-DMA NIC does not allocate cached memory.
The following functions can be called to allocate memory.
NdisAllocateMemoryWithTag allocates, from resident (nonpaged) system-space memory, a buffer whose length is specified by the caller. The memory is not shared, but it can be cached or noncached, depending on the caller's request. The memory can be contiguous and within a particular physical address boundary.
NdisMAllocateSharedMemory allocates shared memory, which can be cached or noncached. This call returns both a physical address pointer that the NIC uses and a virtual address pointer that the miniport driver uses. NdisMAllocateSharedMemory must be called after NdisMSetAttributesEx and after NdisMAllocateMapRegisters or NdisMInitializeScatterGatherDma.
NdisAllocatePacketPool or NdisAllocatePacketPoolEx allocates and initializes a block of nonpaged system memory from which packet descriptors are allocated.
NdisAllocatePacket allocates a packet descriptor from the packet pool allocated by calling NdisAllocatePacketPool(Ex).
NdisAllocateBufferPool returns a handle that the caller can use to allocate buffer descriptors with NdisAllocateBuffer.
NdisAllocateBuffer allocates a buffer descriptor from the buffer pool allocated with NdisAllocateBufferPool.