A.2.3.4.1  Buffers

Both NIC and transport drivers allocate and manage virtual memory buffers in the host. The NDIS interface library provides functions that allow the drivers to allocate, construct, and inspect such buffers. These buffers are listed in Table A.2.6.

NDIS 3.0 (ndis.h) uses an NDIS_BUFFER structure to define a variable-length buffer descriptor for a buffer. A buffer descriptor is an MDL that contains virtual and physical addressing information for the buffer, the buffer length, and a pointer to the next buffer descriptor in the chain of buffer descriptors that make up a packet descriptor.

For bus-mastering transfers, a NIC driver needs to send the physical addresses of virtual memory buffers to its network interface card. Under NDIS 3.0, the driver can obtain these addresses by calling NdisStartBufferPhysicalMapping. A portable NIC driver has limited use of physical addresses and sometimes only has knowledge of a virtual address when the network interface card requires a physical address. The operating system must then map the virtual address to an appropriate physical address. The resultant mapping is temporary and the NIC driver must manage it using map registers.

Table A.2.6    Buffer Functions

Function Definition
NdisAdjustBufferLength Modifies the length field in an allocated buffer descriptor.
NdisAllocateBuffer Allocates and initializes a buffer descriptor for virtual memory.
NdisAllocateBufferPool Allocates and initializes a block of storage for a pool of buffer descriptors.
NDIS_BUFFER_LINKAGE Retrieves the internal buffer linkage from a buffer descriptor for use by a transport driver.
NdisChainBufferAtBack Appends a buffer descriptor to a chain of buffer descriptors for a packet descriptor.
NdisChainBufferAtFront Adds a buffer descriptor at the front of a chain of buffer descriptors for a packet descriptor.
NdisCompleteBufferPhysicalMapping Indicates to the operating system that a physical address mapping is no longer needed.
NdisCopyBuffer Creates a buffer descriptor for a specific memory descriptor that a higher network layer passes to the transport driver.
NdisCreateLookaheadBufferFrom SharedMemory Provides a lookahead buffer, which is a virtual memory copy of shared memory on the network interface card.
NdisDestroyLookaheadBufferFrom SharedMemory Disassociates a lookahead buffer from shared memory on the network card.
NdisFreeBuffer Frees a buffer descriptor.
NdisFreeBufferPool Terminates the use of a buffer descriptor pool.
NdisGetBufferPhysicalAddress Obtains the physical segments that make up a single buffer. This function is obsolete, and NdisStartBufferPhysicalMapping replaces it.
NdisGetBufferPhysicalArraySize Determines the maximum number of physical segments in a buffer.
NdisGetNextBuffer Finds the next buffer descriptor in a buffer descriptor chain.
NdisGetPhysicalAddressHigh Queries the high 32 bits of a physical address.
NdisGetPhysicalAddressLow Returns the low 32 bits of a physical address.
NdisQueryBuffer Queries a specified buffer descriptor.
NdisSetPhysicalAddressHigh Sets the high 32 bits of a physical address.
NdisSetPhysicalAddressLow Sets the low 32 bits of a physical address.
NdisStartBufferPhysicalMapping Starts a mapping that the NDIS interface library uses to associate the virtual address of a buffer with the addresses of its physical segments. Replaces function NdisGetBufferPhysicalAddress that is no longer supported.
NdisUnchainBufferAtBack Removes the last buffer descriptor from a buffer descriptor chain.
NdisUnchainBufferAtFront Removes the first buffer descriptor from a buffer descriptor chain.