Função NdisMRegisterScatterGatherDma (ndis.h)

Artigo
08/07/2023

Cuidado

Para processadores ARM e ARM64, é altamente recomendável que os gravadores de driver NDIS usem dma WDF ou DMA WDM em vez de DMA de dispersão/coleta de NDIS.

Para obter mais informações sobre o AMD WDF, consulte Manipulando operações de DMA em drivers KMDF.

Para obter mais informações sobre o AMD do WDM, consulte os tópicos filho relacionados ao DMA de Gerenciamento de entrada/saída para drivers.

Os drivers de microporte master de barramento chamam a função NdisMRegisterScatterGatherDma de MiniportInitializeEx para inicializar um canal DMA de dispersão/coleta.

Sintaxe

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

Parâmetros

[in] MiniportAdapterHandle

O identificador de miniporta que o NDIS passou para MiniportInitializeEx.

[in, out] DmaDescription

Um ponteiro para uma estrutura NDIS_SG_DMA_DESCRIPTION. Essa estrutura descreve as propriedades de DMA de dispersão/coleta do driver de miniporta. A estrutura é definida da seguinte maneira:

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;

Essa estrutura inclui os seguintes membros:

A estrutura NDIS_OBJECT_HEADER para a estrutura de NDIS_SG_DMA_DESCRIPTION. Defina o membro Type da estrutura especificada por Header como NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, o membro Revision como NDIS_SG_DMA_DESCRIPTION_REVISION_1 e o membro Size como NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.

Flags

Um conjunto de sinalizadores de bits que definem características de dispersão/coleta. Defina esse membro como OR bit a bit de todos os sinalizadores necessários.

O sinalizador NDIS_SG_DMA_64_BIT_ADDRESS especifica que a NIC pode usar endereçamento de 64 bits para operações de DMA. Caso contrário, a NIC usará endereçamento de 32 bits.

Defina esse membro como zero se o endereçamento de 64 bits não for necessário.

MaximumPhysicalMapping

O número máximo de bytes que a NIC pode transferir em uma única operação de DMA. O NDIS fornece esse valor para a HAL (camada de abstração de hardware) ao alocar um canal DMA, e HAL usa esse valor para determinar o número máximo de registros de mapa a serem reservados para a NIC.

ProcessSGListHandler

A função MiniportProcessSGList que o NDIS chama quando HAL termina de criar a lista de dispersão/coleta.

SharedMemAllocateCompleteHandler

O Função MiniportSharedMemoryAllocateComplete para drivers de miniport que chamam NdisMAllocateSharedMemoryAsyncEx. Esse campo é opcional e deverá ser NULL se o driver de miniporto não chamar NdisMAllocateSharedMemoryAsyncEx.

ScatterGatherListSize

O tamanho, em bytes, da memória necessária para manter uma lista de dispersão/coleta. O NDIS define esse valor antes de retornar de NdisMRegisterScatterGatherDma. Os drivers de miniport devem usar esse tamanho para pré-alocar memória para cada lista de dispersão/coleta.

[out] NdisMiniportDmaHandle

Um ponteiro para uma variável que o chamador fornece e que o NDIS preenche com um identificador. O identificador identifica uma área de contexto que o NDIS usa para gerenciar esse recurso de AMD. O driver de miniporta passa esse identificador para o NDIS em chamadas subsequentes para o NDIS que envolvem esse recurso de DMA.

Retornar valor

NdisMRegisterScatterGatherDma retorna um dos seguintes:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	NdisMRegisterScatterGatherDma alocou com êxito recursos para operações de DMA master barramento.
NDIS_STATUS_RESOURCES	NdisMRegisterScatterGatherDma falhou devido a recursos insuficientes.
NDIS_STATUS_NOT_SUPPORTED	NdisMRegisterScatterGatherDma falhou porque o miniporto não especificou que ele dá suporte ao NDIS 6.0 ou versões posteriores ou porque o driver de miniporto não especificou que sua NIC é um dispositivo DMA master barramento. Um driver de miniporta especifica sua versão do NDIS quando ele chama NdisMRegisterMiniportDriver. Um driver de miniporta especifica que ele dá suporte a dispositivos DMA master barramento quando chama NdisMSetMiniportAttributes.
NDIS_STATUS_BAD_VERSION	A versão atual do NDIS não dá suporte à versão especificada no membro Revision da estrutura Header de DmaDescription .

Comentários

Um driver de microporte master de barramento NDIS chama NdisMRegisterScatterGatherDma dentro de sua função MiniportInitializeEx para inicializar recursos para operações de DMA de dispersão/coleta. O parâmetro DmaDescription que o driver de miniporto passa para NdisMRegisterScatterGatherDma contém as informações que o NDIS usa para inicializar os recursos de DMA de dispersão/coleta. Depois que NdisMRegisterScatterGatherDma retorna, o membro ScatterGatherListSize de DmaDescription contém um tamanho de buffer que deve ser suficiente para manter uma lista de dispersão/coleta. Os drivers de miniport devem usar esse tamanho para pré-alocar a memória para listas de dispersão/coleta.

O membro ProcessSGListHandler no parâmetro DmaDescription define o ponto de entrada no driver de miniport para a função MiniportProcessSGList . Quando um driver de miniporta chama NdisMAllocateNetBufferSGList, o NDIS chama HAL para fornecer a lista de dispersão/coleta para o driver de miniporta. HAL chama MiniportProcessSGList depois que HAL conclui a criação da lista de dispersão/coleta. O NDIS pode chamar MiniportProcessSGList fora do contexto da chamada para NdisMAllocateNetBufferSGList.

NdisMRegisterScatterGatherDma retorna um ponteiro para uma área de contexto opaca para o driver de miniporto. O driver de miniporta deve usar esse identificador em chamadas subsequentes para funções de DMA de dispersão/coleta de NDIS.

Chamada de motoristas de miniporta master ônibus NdisMAllocateSharedMemoryAsyncEx para alocar dinamicamente a memória compartilhada para operações de transferência de dados. Essa chamada é necessária quando o tráfego de rede alto faz com que o driver de miniporto seja executado com pouco espaço de memória compartilhado que o driver alocou durante a inicialização. Se NdisMAllocateSharedMemoryAsyncEx retornar NDIS_STATUS_PENDING, o NDIS chamará o Função MiniportSharedMemoryAllocateComplete para concluir a operação posteriormente. Os drivers de miniport especificam o ponto de entrada para a função MiniportSharedMemoryAllocateComplete no membro SharedMemAllocateCompleteHandler do parâmetro DmaDescription .

Miniportores chamam o Função NdisMDeregisterScatterGatherDma para desalocar os recursos de DMA alocados por NdisMRegisterScatterGatherDma .

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	PASSIVE_LEVEL
Regras de conformidade da DDI	Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis)