Funzione NdisMAllocateNetBufferSGList (ndis.h)

Articolo
02/26/2024

Attenzione

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

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

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

I driver miniport master del bus chiamano la funzione NdisMAllocateNetBufferSGList per ottenere un elenco di 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 Funzione NdisMRegisterScatterGatherDma .

[in] NetBuffer

Puntatore a una struttura NET_BUFFER. NdisMAllocateNetBufferSGList alloca un elenco di dispersione/raccolta per i dati di rete associati a questa struttura NET_BUFFER. L'elenco a dispersione/raccolta viene generato dai dati a partire dall'inizio del file MDL specificato nel membro CurrentMdl 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 specifici.

[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 proviene 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 in grado di offload del camino durante le operazioni di ricezione, devono cancellare questo flag.

[in, optional] ScatterGatherListBuffer

Se non è NULL, ScatterGatherListBuffer specifica un puntatore alla risorsa di archiviazione allocata dal chiamante per contenere l'elenco a dispersione/raccolta. Se NULL, NDIS alloca lo spazio di 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 lo spazio di archiviazione per l'elenco a dispersione/raccolta. Se il parametro ScatterGatherListBuffer è NULL, questo parametro non viene usato.

Valore restituito

NdisMAllocateNetBufferSGList restituisce uno dei valori seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList ha 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.

Commenti

Un driver miniport bus-master 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 di dispersione/raccolta. Dopo che HAL compila l'elenco a dispersione/raccolta, chiama la funzione MiniportProcessSGList registrata dal driver miniport chiamando 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 nel parametro ScatterGatherListBuffer contenga l'elenco di dispersione/raccolta. HAL passa il puntatore di elenco a dispersione/raccolta corretto alla funzione MiniportProcessSGList del driver miniport .

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 nel membro CurrentMdl della struttura di NET_BUFFER_DATA associata. L'inizio dei dati di rete nell'elenco SG è offset dall'inizio dell'elenco SG in base al valore specificato nel membro CurrentMdlOffset della struttura di NET_BUFFER_DATA associata.

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

Requisiti

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)