Função NdisMAllocateNetBufferSGList (ndis.h)

Artigo
08/07/2023

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 Manipulando 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 master de 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 NET_BUFFER. A lista de dispersão/coleta é gerada a partir dos dados que começam no início do MDL especificado no membro CurrentMdl da estrutura de 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 miniport devem definir esse sinalizador no caminho de envio quando a operação de 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é durante as operações de recebimento, devem limpar esse sinalizador.

[in, optional] ScatterGatherListBuffer

Se não for 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.

Retornar valor

NdisMAllocateNetBufferSGList retorna um dos seguintes:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList criou com êxito a lista de dispersão/coleta para a estrutura de NET_BUFFER especificada.
NDIS_STATUS_RESOURCES	Falha no NdisMAllocateNetBufferSGList devido a recursos insuficientes.

Comentários

Um driver de miniporte master de barramento NDIS chama NdisMAllocateNetBufferSGList de seu 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 o 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 depois que o NDIS retornar de NdisMAllocateNetBufferSGList. Os drivers de miniporte 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 miniport especificam o tamanho do buffer no parâmetro ScatterGatherListBufferSize quando chamam NdisMAllocateNetBufferSGList.

O NDIS pode alocar um buffer mesmo se o driver de miniporto especificar 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 membro CurrentMdl 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 membro CurrentMdlOffset 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
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
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)