2.3.2.9 Packet and Buffer Functions

Miniport NIC drivers have a need to allocate buffers for receiving incoming data. The driver of a busmaster DMA device that indicates the entire incoming packet up to interested protocols must allocate and manage packets for this purpose. A NIC driver might need to allocate buffer space to stage data on a send if the packet it receives from an upper layer is small and fragmented. On a send, all miniport NIC drivers receive a complete packet and must call NDIS functions to manipulate those packets and extract the data to be sent. A miniport that transfers incoming data to an upper layer driver receives a packet from the upper layer and must manipulate the packet structure to fill it with received data. NDIS provides functions that miniport drivers can call to allocate, construct, and inspect packets.

NDIS defines a packet as a packet descriptor with a chain of one or more buffers containing the network packet data. The NDIS library describes a packet descriptor by defining the NDIS_PACKET structure. The descriptor consists of two parts: a public component that a miniport driver can see, and a private component that is invisible to the driver. The public component allows a miniport driver to maintain context information about the packet. A miniport driver can use this component to link packets into data transfer queues.

Function	Definition
NdisAllocatePacketPool	Allocates and initializes a block of nonpaged packet pool. The caller supplies the requested number of packet descriptors and the size in bytes of each fixed-size packet.
NdisAllocatePacket	Allocates a fixed-size packet descriptor from the packet pool returned by NdisAllocatePacketPool.
NdisAllocateBufferPool	Returns a handle with which the caller can allocate buffer descriptors with NdisAllocateBuffer.
NdisAllocateBuffer	Creates a buffer descriptor mapping a specified virtual range within an already allocated, nonpaged memory block, given a handle returned by NdisAllocateBufferPool.
NdisAdjustBufferLength	Modifies the length of the range specified in a given buffer descriptor.
NdisCopyBuffer	Creates a buffer descriptor for a specified range, given a handle for a block of already allocated memory and a pointer to the buffer descriptor for the block.
NdisCopyFromPacketToPacket	Copies a specified number of bytes from one packet to another, given a specified source packet and a destination packet and specified offsets in each.
NdisCreateLookaheadBufferFromSharedMemory	Returns the virtual address of a buffer within a block of memory shared with a busmaster DMA NIC. Allows a driver to map a portion of received data to indicate up to interested protocols as a read-only lookahead buffer.
NdisDestroyLookaheadBufferFromSharedMemory	Releases a buffer acquired by calling NdisCreateLookaheadBufferFromSharedMemory.
NdisQueryPacket	Returns a set of information that describes a packet and a pointer to the initial buffer in the chain.
NdisQueryBuffer	Returns the base virtual address and size of a buffer that is mapped by a given buffer descriptor.
NdisQueryBufferOffset	Returns the base virtual address of the range specified in a given buffer descriptor.
NdisGetFirstBufferFromPacket	Returns pointers to the buffer descriptor and base virtual address for the initial buffer chained to a given packet, along with the size of the initial buffer and full buffer, in case the buffer is fragmented.
NdisGetNextBuffer	Returns the next buffer descriptor in a chain, given the current buffer descriptor.
NdisGetPacketFlags	Returns the flags, if any, set by a protocol driver in a given packet.
NdisFreePacketPool	Releases a block of nonpaged pool allocated by calling NdisAllocatePacketPool.
NdisFreePacket	Releases a packet allocated by calling NdisAllocatePacket.
NdisFreeBufferPool	Releases a handle obtained by calling NdisAllocateBufferPool.
NdisFreeBuffer	Releases a buffer descriptor allocated by calling NdisAllocateBuffer.
NdisChainBufferAtFront	Links a given buffer descriptor at the front of a chain of buffer descriptors for a given packet.
NdisChainBufferAtBack	Links a given buffer descriptor at the end of a chain of buffer descriptors for a given packet.
NdisUnchainBufferAtFront	Removes a given buffer descriptor from the front of a chain of buffer descriptors for a given packet and returns a pointer to that buffer descriptor.
NdisUnchainBufferAtBack	Removes a given buffer descriptor from the back of a chain of buffer descriptors for a given packet and returns a pointer to that buffer descriptor.
NdisReinitializePacket	Removes any chained buffers from a given packet and reinitializes it for reuse.
NdisRecalculatePacketCounts	Resets the valid count for a given packet so that the next call to NdisQueryPacket recalculates the counts.