NdisMAllocateNetBufferSGList (Compact 2013)

3/26/2014

Bus-master miniport drivers call this function to obtain a scatter/gather list for the network data that is associated with a NET_BUFFER structure.

Syntax

NDIS_STATUS
  NdisMAllocateNetBufferSGList(
    IN NDIS_HANDLE  NdisMiniportDmaHandle,
    IN PNET_BUFFER  NetBuffer,
    IN PVOID  Context,
    IN ULONG  Flags,
    IN PVOID  ScatterGatherListBuffer OPTIONAL,
    IN ULONG  ScatterGatherListBufferSize OPTIONAL
    ); 

Parameters

• NdisMiniportDmaHandle
  A handle to a context area that NDIS uses to manage a DMA resource. The caller obtained this handle by calling the NdisMRegisterScatterGatherDma function.

• NetBuffer
  A pointer to a NET_BUFFER structure. NdisMAllocateNetBufferSGList allocates a scatter/gather list for the network data that is associated with this NET_BUFFER structure. The scatter/gather list is generated from the data starting at the beginning of the MDL that is specified at the CurrentMdl member of the associated NET_BUFFER_DATA structure.

• Context
  A pointer to a context area that the caller created. HAL passes this pointer to MiniportProcessSGList after HAL creates the scatter/gather list. The caller can use this context area for its own purposes.

• Flags
  NDIS flags that can be combined with an OR operation. To clear all the flags, set this member to zero. This function supports the NDIS_SG_LIST_WRITE_TO_DEVICE flag which; if set, indicates the direction of the DMA transfer is from the NET_BUFFER to the device. If NDIS_SG_LIST_WRITE_TO_DEVICE is clear, the transfer is from the device. Miniport drivers should set this flag on the send path when DMA operation transfers data from a NET_BUFFER to the device. Miniport drivers that perform DMA operations from the device to a pre-allocated NET_BUFFER, for example chimney offload capable NICs during receive operations, should clear this flag.

• ScatterGatherListBuffer
  If not NULL, ScatterGatherListBuffer specifies a pointer to storage that the caller allocates to hold the scatter/gather list. If NULL, NDIS allocates storage for the scatter/gather list.

• ScatterGatherListBufferSize
  If the ScatterGatherListBuffer parameter is not NULL, ScatterGatherListBufferSize specifies the size of the buffer that contains the scatter/gather list. If this size is too small, NDIS allocates storage for the scatter/gather list. If the ScatterGatherListBuffer parameter is NULL, this parameter is not used.

Return Value

NdisMAllocateNetBufferSGList returns one of the following:

Remarks

An NDIS bus-master miniport driver calls NdisMAllocateNetBufferSGList from its MiniportSendNetBufferLists function. The miniport driver calls NdisMAllocateNetBufferSGList one time for each NET_BUFFER structure for which it must obtain a scatter/gather list.

When a miniport driver calls NdisMAllocateNetBufferSGList, NDIS calls HAL to build the scatter/gather list. After HAL builds the scatter/gather list, it calls the MiniportProcessSGList function that the miniport driver registered by calling NdisMRegisterScatterGatherDma.

HAL can call MiniportProcessSGList before or after NDIS returns from NdisMAllocateNetBufferSGList. Miniport drivers must not try to access the scatter/gather list until after HAL calls MiniportProcessSGList.

To improve system performance, miniport drivers should preallocate buffers for the use in the ScatterGatherListBuffer parameter of NdisMAllocateNetBufferSGList. NDIS provides the recommended size for the buffers in the ScatterGatherListSize member of the DmaDescription parameter when the miniport driver calls NdisMRegisterScatterGatherDma. Miniport drivers specify the size of the buffer in the ScatterGatherListBufferSize parameter when they call NdisMAllocateNetBufferSGList.

NDIS might allocate a buffer even if the miniport driver specifies a buffer in the ScatterGatherListBuffer parameter. This can occur if the specified buffer is too small to hold the scatter/gather list. Therefore, driver writers must not assume that the buffer specified in the ScatterGatherListBuffer parameter contains the scatter/gather list. HAL passes the correct scatter/gather list pointer to the miniport driver's MiniportProcessSGList function.

To improve system performance, the scatter/gather list is generated from the network data starting at the beginning of the MDL that is specified at the CurrentMdl member of the associated NET_BUFFER_DATA structure. The start of the network data in the SG list is offset from the beginning of the SG list by the value specified in the CurrentMdlOffset member of the associated NET_BUFFER_DATA structure.

Miniport drivers must call the NdisMFreeNetBufferSGList function to free a scatter/gather list.

Requirements

See Also

Reference

NDIS Scatter/Gather DMA Functions
NET_BUFFER
NET_BUFFER_DATA
NdisMFreeNetBufferSGList
NdisMRegisterScatterGatherDma