Função NdisMAllocateSharedMemoryAsyncEx (ndis.h)

Artigo
02/26/2024

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 miniport chamam a função NdisMAllocateSharedMemoryAsyncEx para alocar memória adicional compartilhada entre o driver e sua NIC de DMA master barramento, geralmente quando o driver de miniport está ficando sem buffers de recebimento nic disponíveis.

Sintaxe

NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
  [in] NDIS_HANDLE MiniportDmaHandle,
  [in] ULONG       Length,
  [in] BOOLEAN     Cached,
  [in] PVOID       Context
);

Parâmetros

[in] MiniportDmaHandle

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] Length

O número de bytes a serem alocados.

[in] Cached

Esse parâmetro é ignorado (a memória armazenada em cache sempre é usada em sistemas x86 e x64).

[in] Context

Um ponteiro para o contexto determinado pelo driver a ser passado para a função MiniportSharedMemoryAllocateComplete quando ela é chamada.

Retornar valor

NdisMAllocateSharedMemoryAsyncEx pode retornar um dos seguintes:

Código de retorno	Descrição
NDIS_STATUS_PENDING	O NDIS chamará a função MiniportSharedMemoryAllocateComplete e fornecerá informações que descrevem a memória compartilhada alocada. Se a tentativa de alocar memória compartilhada falhar, o NDIS chamará MiniportSharedMemoryAllocateComplete e passará ponteiros NULL .
NDIS_STATUS_FAILURE	A memória solicitada não pôde ser alocada no momento. Se NdisMAllocateSharedMemoryAsyncEx retornar esse status, uma chamada subsequente com os mesmos parâmetros poderá ser bem-sucedida, dependendo se os recursos do sistema se tornaram disponíveis.

Comentários

Nota Um driver de miniporte já deve ter chamado NdisMRegisterScatterGatherDma ou NdisMRegisterDmaChannel para inicializar um canal DMA de dispersão/coleta antes de chamar NdisMAllocateSharedMemoryAsyncEx.

Os drivers de NICs de DMA master de barramento chamam NdisMAllocateSharedMemoryAsyncEx para alocar dinamicamente a memória compartilhada. Esses drivers também alocam espaço de memória compartilhado durante a inicialização. Esses drivers usam a memória compartilhada alocada dinamicamente para operações de transferência quando o alto tráfego de rede coloca demandas excessivas no espaço de memória compartilhado existente.

Esse driver de miniporto geralmente mantém uma ou mais variáveis de estado para acompanhar o número de buffers de memória compartilhados disponíveis para transferências de entrada. Quando o número de buffers disponíveis atinge uma baixa determinada pelo driver, o driver de miniport chama NdisMAllocateSharedMemoryAsyncEx para alocar mais espaço de buffer na memória compartilhada. Quando o número de buffers disponíveis sobe para um alto determinado pelo driver, o driver de miniport chama NdisMFreeSharedMemory uma ou mais vezes para liberar suas alocações dinâmicas anteriores.

Normalmente, esse driver de miniporto retém o bloco de memória compartilhada que sua função MiniportInitializeEx alocada com NdisMAllocateSharedMemory até que uma NIC seja removida. Quando a NIC é removida, o NDIS chama a função MiniportHaltEx do driver de miniport. Essa alocação é suficiente para lidar com uma demanda média por transferências por meio da NIC.

Um driver de miniporte deve definir um limite sobre a quantidade de memória compartilhada que ele pode alocar. Esse limite é específico do driver e deve ser alto o suficiente para que o driver não fique sem buffers. Não et um limite excessivamente alto, pois isso pode resultar em um consumo desperdiçado de memória compartilhada que poderia reduzir o desempenho do sistema.

Qualquer driver de miniporto que chame NdisMAllocateSharedMemoryAsyncEx ou NdisMAllocateSharedMemory deve liberar todas as alocações pendentes com uma ou mais chamadas para NdisMFreeSharedMemory quando sua NIC for removida.

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)
IRQL	<= DISPATCH_LEVEL
Regras de conformidade de DDI	Irql_Gather_DMA_Function(ndis)