Função NdisMRegisterScatterGatherDma (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 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 miniporto 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 miniporto. 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:
Cabeçalho
A estrutura NDIS_OBJECT_HEADER para a estrutura NDIS_SG_DMA_DESCRIPTION. Defina o membro tipo da estrutura que de Cabeçalho especifica para NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, o membro de Revisão de para NDIS_SG_DMA_DESCRIPTION_REVISION_1 e o membro tamanho do para NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.
Sinalizadores
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 o endereçamento de 64 bits para operações de DMA. Caso contrário, a NIC usará o 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 camada de abstração de hardware (HAL) 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 terminar de criar a lista de dispersão/coleta.
SharedMemAllocateCompleteHandler
O função MiniportSharedMemoryAllocateComplete para drivers de miniporto que chamam NdisMAllocateSharedMemoryAsyncEx. Esse campo é opcional e deve 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 DMA. O driver de miniporto passa esse identificador para o NDIS em chamadas subsequentes para o NDIS que envolvem esse recurso de DMA.
Valor de retorno
NdisMRegisterScatterGatherDma retorna um dos seguintes:
| Código de retorno | Descrição |
|---|---|
|
NdisMRegisterScatterGatherDma recursos alocados com êxito para operações de DMA mestre de barramento. |
|
NdisMRegisterScatterGatherDma falhou devido a recursos insuficientes. |
|
NdisMRegisterScatterGatherDma falha 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 mestre de ônibus. Um driver de miniporto especifica sua versão do NDIS quando ele chama NdisMRegisterMiniportDriver. Um driver de miniporto especifica que ele dá suporte a dispositivos DMA mestres de barramento quando ele chama NdisMSetMiniportAttributes. |
|
A versão atual do NDIS não dá suporte à versão especificada no membro de Revisão da estrutura de Cabeçalho do DmaDescription. |
Observações
Um driver de miniporto mestre de ônibus do 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 dispersão/coleta de DMA. Depois que NdisMRegisterScatterGatherDma retorna, o ScatterGatherListSize membro do 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 miniporto chama NdisMAllocateNetBufferSGList, o NDIS chama HAL para fornecer a lista de dispersão/coleta para o driver de miniporto. HAL chama miniportProcessSGList depois que HAL terminar de compilar a 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 miniporto deve usar esse identificador em chamadas subsequentes para funções de DMA de dispersão/coleta de NDIS.
Chamada de motoristas de miniporto mestre do barramento 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 miniporto especificam o ponto de entrada para a função MiniportSharedMemoryAllocateComplete no SharedMemAllocateCompleteHandler membro do parâmetro DmaDescription.
Os drivers de miniporto chamam o função NdisMDeregisterScatterGatherDma para desalocar os recursos de DMA que NdisMRegisterScatterGatherDma alocados.
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 | PASSIVE_LEVEL |
| regras de conformidade de DDI | Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis) |
Consulte também
MiniportSharedMemoryAllocateCompletede dispersão/coleta de DMA do NDIS
NdisMAllocateSharedMemoryAsyncEx NdisMDeregisterScatterGatherDma