Funzione NdisMAllocateNetBufferSGList (ndis.h)

Articolo
02/07/2025

Cautela

Per i processori ARM e ARM64, è consigliabile che i writer di driver NDIS usino DMA WDF o DMA WDM anziché NDIS Scatter/Gather DMA.

Per altre informazioni su DMA di WDF, vedere Gestione delle operazioni DMA nei driver KMDF.

Per altre informazioni su WDM DMA, vedere gli argomenti figlio correlati a DMA di Gestione dell'input/output per i driver.

I driver miniport master del bus chiamano la funzione NdisMAllocateNetBufferSGList per ottenere un elenco a dispersione/raccolta per i dati di rete associati a una struttura NET_BUFFER.

Sintassi

NDIS_STATUS NdisMAllocateNetBufferSGList(
  [in]           NDIS_HANDLE NdisMiniportDmaHandle,
  [in]           PNET_BUFFER NetBuffer,
  [in]           PVOID       Context,
  [in]           ULONG       Flags,
  [in, optional] PVOID       ScatterGatherListBuffer,
  [in]           ULONG       ScatterGatherListBufferSize
);

Parametri

[in] NdisMiniportDmaHandle

Handle per un'area di contesto NDIS usata per gestire una risorsa DMA. Il chiamante ha ottenuto questo handle chiamando il funzione NdisMRegisterScatterGatherDma.

[in] NetBuffer

Puntatore a una struttura NET_BUFFER. NdisMAllocateNetBufferSGList alloca un elenco a dispersione/raccolta per i dati di rete associati a questa struttura di NET_BUFFER. L'elenco a dispersione/raccolta viene generato dai dati a partire dall'inizio del file MDL specificato nella CurrentMdl membro della struttura di NET_BUFFER_DATA associata.

[in] Context

Puntatore a un'area di contesto creata dal chiamante. HAL passa questo puntatore a miniportProcessSGList dopo che HAL crea l'elenco a dispersione/raccolta. Il chiamante può usare questa area di contesto per scopi propri.

[in] Flags

Flag NDIS che possono essere combinati con un'operazione OR. Per cancellare tutti i flag, impostare questo membro su zero. Questa funzione supporta il flag NDIS_SG_LIST_WRITE_TO_DEVICE che; se impostato, indica la direzione del trasferimento DMA dal NET_BUFFER al dispositivo. Se NDIS_SG_LIST_WRITE_TO_DEVICE è chiaro, il trasferimento viene eseguito dal dispositivo. I driver Miniport devono impostare questo flag nel percorso di invio quando l'operazione DMA trasferisce i dati da un NET_BUFFER al dispositivo. I driver Miniport che eseguono operazioni DMA dal dispositivo a un NET_BUFFER preallocato, ad esempio le schede di interfaccia di rete con supporto per il camino durante le operazioni di ricezione, devono cancellare questo flag.

[in, optional] ScatterGatherListBuffer

Se non NULL, ScatterGatherListBuffer specifica un puntatore all'archiviazione allocato dal chiamante per contenere l'elenco a dispersione/raccolta. Se NULL, NDIS alloca l'archiviazione per l'elenco a dispersione/raccolta.

[in] ScatterGatherListBufferSize

Se il parametro ScatterGatherListBuffer non è NULL, ScatterGatherListBufferSize specifica le dimensioni del buffer che contiene l'elenco a dispersione/raccolta. Se questa dimensione è troppo piccola, NDIS alloca l'archiviazione per l'elenco a dispersione/raccolta. Se il parametro scatterGatherListBuffer è NULL, questo parametro non viene usato.

Valore restituito

NdisMAllocateNetBufferSGList restituisce una delle opzioni seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList compilato correttamente l'elenco a dispersione/raccolta per la struttura di NET_BUFFER specificata.
NDIS_STATUS_RESOURCES	NdisMAllocateNetBufferSGList non è riuscito a causa di risorse insufficienti.

Osservazioni

Un driver miniport master del bus NDIS chiama NdisMAllocateNetBufferSGList dal relativo funzione MiniportSendNetBufferLists. Il driver miniport chiama NdisMAllocateNetBufferSGList una volta per ogni struttura NET_BUFFER per cui deve ottenere un elenco a dispersione/raccolta.

Quando un driver miniport chiama NdisMAllocateNetBufferSGList, NDIS chiama HAL per compilare l'elenco a dispersione/raccolta. Dopo che HAL compila l'elenco a dispersione/raccolta, chiama la funzione MiniportProcessSGList registrata dal driver miniport NdisMRegisterScatterGatherDma.

HAL può chiamare MiniportProcessSGList prima o dopo la restituzione di NDIS da NdisMAllocateNetBufferSGList. I driver Miniport non devono tentare di accedere all'elenco a dispersione/raccolta fino a quando HAL non chiama MiniportProcessSGList.

Per migliorare le prestazioni del sistema, i driver miniport devono preallocare i buffer per l'uso nel parametro ScatterGatherListBuffer di NdisMAllocateNetBufferSGList. NDIS fornisce le dimensioni consigliate per i buffer nel membro ScatterGatherListSize del parametro DmaDescription quando il driver miniport chiama NdisMRegisterScatterGatherDma. I driver Miniport specificano le dimensioni del buffer nel parametro ScatterGatherListBufferSize quando chiamano NdisMAllocateNetBufferSGList.

NDIS potrebbe allocare un buffer anche se il driver miniport specifica un buffer nel parametro ScatterGatherListBuffer. Ciò può verificarsi se il buffer specificato è troppo piccolo per contenere l'elenco a dispersione/raccolta. Pertanto, i writer di driver non devono presupporre che il buffer specificato nell'parametro ScatterGatherListBuffer contenga l'elenco a dispersione/raccolta. HAL passa il puntatore di elenco a dispersione/raccolta corretto alla funzione di del driver miniport MiniportProcessSGList.

Per migliorare le prestazioni del sistema, l'elenco a dispersione/raccolta viene generato dai dati di rete a partire dall'inizio del file MDL specificato nella membro currentMdl della struttura di NET_BUFFER_DATA associata. L'inizio dei dati di rete nell'elenco SG viene scostato dall'inizio dell'elenco SG in base al valore specificato nel CurrentMdlOffset membro della struttura di NET_BUFFER_DATA associata.

I driver Miniport devono chiamare la funzione NdisMFreeNetBufferSGList per liberare un elenco a dispersione/raccolta.

Fabbisogno

Requisito	Valore
client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
piattaforma di destinazione	Universale
intestazione	ndis.h (include Ndis.h)
libreria	Ndis.lib
IRQL	DISPATCH_LEVEL
regole di conformità DDI	Irql_Gather_DMA_Function(ndis)