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. |