Bus-master miniport drivers call the NdisMAllocateNetBufferSGList function to obtain a scatter/gather list for the network data that is associated with a NET_BUFFER structure.
NDIS_STATUS NdisMAllocateNetBufferSGList( _In_ NDIS_HANDLE NdisMiniportDmaHandle, _In_ PNET_BUFFER NetBuffer, _In_ PVOID Context, _In_ ULONG Flags, _In_opt_ PVOID ScatterGatherListBuffer, _In_ ULONG ScatterGatherListBufferSize );
- NdisMiniportDmaHandle [in]
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 [in]
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 [in]
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 [in]
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 [in, optional]
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 [in]
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.
NdisMAllocateNetBufferSGList returns one of the following:
NdisMAllocateNetBufferSGList successfully built the scatter/gather list for the specified NET_BUFFER structure.
NdisMAllocateNetBufferSGList failed due to insufficient resources.
An NDIS bus-master miniport driver calls NdisMAllocateNetBufferSGList from its MiniportSendNetBufferLists function. The miniport driver calls NdisMAllocateNetBufferSGList once 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 attempt 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 happen 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.
|Supported in NDIS 6.0 and later.|
DDI compliance rules
- Allocating and Freeing Scatter/Gather Lists
- Miniport Driver Scatter/Gather DMA
- NDIS Scatter/Gather DMA
- Registering and Deregistering DMA Channels