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.