Função NdisMAllocateNetBufferSGList (ndis.h)
Cuidado
Para processadores ARM e ARM64, é altamente recomendável que os gravadores de driver NDIS usem DMA do WDF ou DMA do WDM em vez de DMA de Dispersão/Coleta de NDIS.
Para obter mais informações sobre o DMA do WDF, consulte tratando operações de DMA em drivers KMDF.
Para obter mais informações sobre o DMA do WDM, consulte os tópicos filho relacionados ao DMA de gerenciamento de entrada/saída para drivers.
Os drivers de miniporto mestre do barramento chamam a função NdisMAllocateNetBufferSGList para obter uma lista de dispersão/coleta para os dados de rede associados a uma estrutura de NET_BUFFER.
Sintaxe
NDIS_STATUS NdisMAllocateNetBufferSGList(
[in] NDIS_HANDLE NdisMiniportDmaHandle,
[in] PNET_BUFFER NetBuffer,
[in] PVOID Context,
[in] ULONG Flags,
[in, optional] PVOID ScatterGatherListBuffer,
[in] ULONG ScatterGatherListBufferSize
);
Parâmetros
[in] NdisMiniportDmaHandle
Um identificador para uma área de contexto que o NDIS usa para gerenciar um recurso de DMA. O chamador obteve esse identificador chamando o função NdisMRegisterScatterGatherDma.
[in] NetBuffer
Um ponteiro para uma estrutura NET_BUFFER. NdisMAllocateNetBufferSGList aloca uma lista de dispersão/coleta para os dados de rede associados a essa estrutura de NET_BUFFER. A lista de dispersão/coleta é gerada a partir dos dados que começam no início do MDL especificado no currentMdl membro da estrutura NET_BUFFER_DATA associada.
[in] Context
Um ponteiro para uma área de contexto que o chamador criou. HAL passa esse ponteiro para MiniportProcessSGList depois que HAL cria a lista de dispersão/coleta. O chamador pode usar essa área de contexto para suas próprias finalidades.
[in] Flags
Sinalizadores NDIS que podem ser combinados com uma operação OR. Para limpar todos os sinalizadores, defina esse membro como zero. Essa função dá suporte ao sinalizador NDIS_SG_LIST_WRITE_TO_DEVICE que; se definido, indica que a direção da transferência de DMA é do NET_BUFFER para o dispositivo. Se NDIS_SG_LIST_WRITE_TO_DEVICE estiver claro, a transferência será do dispositivo. Os drivers de miniporto devem definir esse sinalizador no caminho de envio quando a operação DMA transferir dados de um NET_BUFFER para o dispositivo. Os drivers de miniport que executam operações de DMA do dispositivo para uma NET_BUFFER pré-alocada, por exemplo, NICs compatíveis com descarregamento de chaminés durante operações de recebimento, devem limpar esse sinalizador.
[in, optional] ScatterGatherListBuffer
Se não NULL, ScatterGatherListBuffer especificar um ponteiro para o armazenamento que o chamador aloca para manter a lista de dispersão/coleta. Se NULL, o NDIS alocará armazenamento para a lista de dispersão/coleta.
[in] ScatterGatherListBufferSize
Se o parâmetro ScatterGatherListBuffer não for NULL, ScatterGatherListBufferSize especificará o tamanho do buffer que contém a lista de dispersão/coleta. Se esse tamanho for muito pequeno, o NDIS alocará armazenamento para a lista de dispersão/coleta. Se o parâmetro ScatterGatherListBuffer for NULL, esse parâmetro não será usado.
Valor de retorno
NdisMAllocateNetBufferSGList retorna um dos seguintes:
| Código de retorno | Descrição |
|---|---|
|
NdisMAllocateNetBufferSGList criou com êxito a lista de dispersão/coleta para a estrutura de NET_BUFFER especificada. |
|
falha no NdisMAllocateNetBufferSGList devido a recursos insuficientes. |
Observações
Um motorista de miniporto mestre de ônibus do NDIS chama NdisMAllocateNetBufferSGList de sua função MiniportSendNetBufferLists. O driver de miniporto chama NdisMAllocateNetBufferSGList uma vez para cada estrutura NET_BUFFER para a qual deve obter uma lista de dispersão/coleta.
Quando um driver de miniporto chama NdisMAllocateNetBufferSGList, o NDIS chama HAL para criar a lista de dispersão/coleta. Depois que HAL compila a lista de dispersão/coleta, ele chama a função MiniportProcessSGList que o driver de miniporto registrou chamando NdisMRegisterScatterGatherDma.
HAL pode chamar MiniportProcessSGList antes ou após o retorno do NDIS de NdisMAllocateNetBufferSGList. Os drivers de miniporto não devem tentar acessar a lista de dispersão/coleta até que HAL chame miniportProcessSGList.
Para melhorar o desempenho do sistema, os drivers de miniport devem pré-alocar buffers para uso no parâmetro ScatterGatherListBuffer de NdisMAllocateNetBufferSGList. O NDIS fornece o tamanho recomendado para os buffers no membro ScatterGatherListSize do parâmetro DmaDescription quando o driver de miniporto chama NdisMRegisterScatterGatherDma. Os drivers de miniporto especificam o tamanho do buffer no parâmetro ScatterGatherListBufferSize quando chamam NdisMAllocateNetBufferSGList.
O NDIS pode alocar um buffer mesmo que o driver de miniporto especifique um buffer no parâmetro ScatterGatherListBuffer. Isso pode acontecer se o buffer especificado for muito pequeno para manter a lista de dispersão/coleta. Portanto, os gravadores de driver não devem assumir que o buffer especificado no parâmetro ScatterGatherListBuffer contém a lista de dispersão/coleta. HAL passa o ponteiro de lista de dispersão/coleta correto para a função MiniportProcessSGList do driver de miniport.
Para melhorar o desempenho do sistema, a lista de dispersão/coleta é gerada a partir dos dados de rede começando no início do MDL especificado no currentMdl membro da estrutura de NET_BUFFER_DATA associada. O início dos dados de rede na lista SG é deslocado do início da lista SG pelo valor especificado no CurrentMdlOffset membro da estrutura de NET_BUFFER_DATA associada.
Os drivers de miniport devem chamar a função NdisMFreeNetBufferSGList para liberar uma lista de dispersão/coleta.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Com suporte no NDIS 6.0 e posterior. |
| da Plataforma de Destino | Universal |
| cabeçalho | ndis.h (inclua Ndis.h) |
| biblioteca | Ndis.lib |
| IRQL | DISPATCH_LEVEL |
| regras de conformidade de DDI | Irql_Gather_DMA_Function(ndis) |
Consulte também
de dispersão/coleta de DMA do NDIS
NdisMRegisterScatterGatherDma