NDIS-Supplied Packet and Buffer Handling Functions (NDIS 5.1)

  • Article

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.

Miniport drivers must allocate buffers to receive incoming data. The driver of a bus-master 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 operation if the packet it receives from an upper layer is small and fragmented. On a send, all miniport drivers receive a complete packet and must call NDIS functions to manipulate those packets and extract the data to be sent. A miniport driver 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.

The following functions are supplied by NDIS to handle packets and buffers:

  • NdisAllocatePacketPool
    Allocates and initializes a block of nonpaged packet pool. The caller supplies the requested number of packet descriptors and the length of the protocol reserved space for each packet.
  • NdisAllocatePacketPoolEx
    Allocates and initializes a block of nonpaged packet pool. In addition to supplying the requested number of packet descriptors and protocol reserved length, the caller supplies the number of packet descriptors reserved for an overflow situation.
  • NdisAllocatePacket
    Allocates a fixed-size packet descriptor from the packet pool returned by NdisAllocatePacketPool.
  • NdisAllocateBufferPool
    Returns a handle that the caller can use to allocate buffer descriptors with NdisAllocateBuffer.
  • NdisAllocateBuffer
    Creates a buffer descriptor that maps a specified virtual range within an allocated, nonpaged memory block, given a handle returned by NdisAllocateBufferPool.

  • NdisBufferVirtualAddress(Safe)
    Returns the base virtual address for the buffer mapped by a given buffer descriptor and maps the physical pages described by the given buffer descriptor onto system space if these pages are not already mapped to system space.

    Drivers should call NdisBufferVirtualAddressSafe instead of NdisBufferVirtualAddress. NDIS 5.1 miniport drivers must call NdisBufferVirtualAddressSafe instead of NdisBufferVirtualAddress.

  • 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(Safe)
    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.

    Drivers should call NdisCopyFromPacketToPacketSafe instead of NdisCopyFromPacketToPacket. NDIS 5.1 miniport drivers must call NdisCopyFromPacketToPacketSafe instead of NdisCopyFromPacketToPacket.

  • NdisCreateLookaheadBufferFromSharedMemory
    Returns the virtual address of a buffer within a block of memory shared with a bus-master DMA NIC. Allows a driver to map a portion of received data to indicate up to interested protocols as a read-only lookahead buffer.
  • NdisQueryPacket
    Returns a set of information that describes a packet and a pointer to the initial buffer in the chain.

  • NdisQueryBuffer(Safe)
    Returns the base virtual address and size of a buffer that is mapped by a given buffer descriptor.

    Drivers should call NdisQueryBufferSafe instead of NdisQueryBuffer. NDIS 5.1 miniport drivers must call NdisQueryBufferSafe instead of NdisQueryBuffer.

  • NdisQueryBufferOffset
    Returns the offset of a virtual address within a page at which a given buffer begins.

  • NdisGetFirstBufferFromPacket(Safe)
    Returns pointers to the buffer descriptor and base virtual address, for the first buffer chained to a given packet, along with the sizes of the first buffer and the total buffer.

    Drivers should call NdisGetFirstBufferFromPacketSafe instead of NdisGetFirstBufferFromPacket. NDIS 5.1 miniport drivers must call NdisGetFirstBufferFromPacketSafe instead of NdisGetFirstBufferFromPacket.

  • NdisGetNextBuffer
    Returns the next buffer descriptor in a chain, given the current buffer descriptor.
  • NdisGetBufferPhysicalArraySize
    Returns the number of discontiguous physical blocks backing a buffer, given the buffer descriptor. The driver of a bus-master DMA NIC might call this function to determine how many NDIS_PHYSICAL_ADDRESS structures to allocate and fill in before calling NdisMStartBufferPhysicalMapping.
  • 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.
  • NdisPacketPoolUsage
    Returns the number of packet descriptors currently allocated from a packet pool.
  • NdisFreePacket
    Releases a packet allocated by calling NdisAllocatePacket.
  • 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.
  • NdisRecalculatePacketCounts
    Resets the valid count for a given packet so that the next call to NdisQueryPacket recalculates the counts.

 

 

Send comments about this topic to Microsoft