Funzione NdisMAllocateNetBufferSGList (ndis.h)
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 |
|---|---|
|
NdisMAllocateNetBufferSGList ha compilato correttamente l'elenco a dispersione/raccolta per la struttura di NET_BUFFER specificata. |
|
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) |