Função NdisAcquireRWLockRead (ndis.h)

Artigo
02/07/2025

A função NdisAcquireRWLockRead obtém um bloqueio de leitura que o chamador usa para acesso de leitura aos recursos compartilhados entre threads de driver.

Sintaxe

void NdisAcquireRWLockRead(
  [in]  PNDIS_RW_LOCK_EX Lock,
  [out] PLOCK_STATE_EX   LockState,
  [in]  UCHAR            Flags
);

Parâmetros

[in] Lock

Um ponteiro para uma variável de NDIS_RW_LOCK_EX opaca que representa um bloqueio. O chamador pode usar esse bloqueio para obter acesso de gravação ou leitura a recursos compartilhados entre threads de driver não ISR.

[out] LockState

Um ponteiro para uma variável de LOCK_STATE_EX opaca que rastreia o estado do bloqueio. Essa variável existe no intervalo entre as vezes que o chamador obtém e libera o bloqueio. O chamador deve usar uma variável diferente do tipo LOCK_STATE_EX para cada tentativa que ele faz para obter o bloqueio do mesmo thread de driver não ISR.

[in] Flags

Um valor ULONG que contém sinalizadores de bloqueio. Defina esse parâmetro para NDIS_RWL_AT_DISPATCH_LEVEL se o IRQL atual do chamador for DISPATCH_LEVEL. Caso contrário, defina esse parâmetro como zero. Para obter mais informações sobre o acompanhamento do IRQL de expedição, consulte de Acompanhamento de IRQL de Expedição.

Observação Se o chamador souber que o IRQL atual está DISPATCH_LEVEL, defina esse parâmetro como NDIS_RWL_AT_DISPATCH_LEVEL. Esse sinalizador torna o bloqueio ainda mais eficiente, fazendo com que ele omita uma verificação do IRQL atual. Se o IRQL atual for desconhecido, não teste o IRQL atual com KeGetCurrentIrql apenas para determinar se esse sinalizador deve ser definido, pois é mais eficiente permitir que a função NdisAcquireRWLockRead teste o próprio IRQL.

Valor de retorno

Nenhum

Observações

Os drivers NDIS chamam a função NdisAcquireRWLockRead para obter acesso somente leitura aos recursos compartilhados entre threads de driver.

O driver deve alocar uma variável de tipo NDIS_RW_LOCK_EX com a função NdisAllocateRWLock antes que o driver chame a função de NdisAcquireRWLockRead.

Depois que o driver chama NdisAllocateRWLock, ele pode chamar NdisAcquireRWLockWrite ou NdisAcquireRWLockRead para obter acesso de gravação ou leitura ao recurso. Somente um thread de driver não ISR por vez pode obter acesso de gravação ao recurso. Quando um thread não ISR tem acesso de gravação, todos os acessos de leitura e gravação por outros threads não ISR devem aguardar até que o titular do acesso de gravação libere o bloqueio. No entanto, se um thread não ISR tiver acesso de leitura, outros threads não ISR poderão obter simultaneamente acesso de leitura.

O bloqueio NDIS_RW_LOCK_EX não dá suporte à promoção de leitura para gravação. Depois que um processador tiver adquirido um NDIS_RW_LOCK_EX para acesso de leitura (chamando NdisAcquireRWLockRead), o mesmo processador não deve tentar adquirir acesso de gravação (chamando NdisAcquireRWLockWrite) até que o acesso de leitura anterior seja liberado.

Um NDIS_RW_LOCK_EX bloqueio de leitura pode ser adquirido recursivamente no mesmo processador. Para cada chamada para NdisAcquireRWLockRead, deve haver uma chamada correspondente para NdisReleaseRWLock. O bloqueio só é liberado após a última chamada para NdisReleaseRWLock.

O driver não pode usar um bloqueio para proteger os recursos contra acesso de leitura ou gravação que suas outras funções compartilham com o MiniportInterrupt ou função MiniportDisableInterruptEx ou ambas. Em vez disso, o driver deve chamar NdisMSynchronizeWithInterruptEx para que sua função MiniportSynchronizeInterrupt acessa tais recursos compartilhados no mesmo DIRQL que seu MiniportInterrupt ou funções de MiniportDisableInterruptEx ou ambas.

NdisAcquireRWLockRead sempre eleva o IRQL para IRQL = DISPATCH_LEVEL.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Com suporte no NDIS 6.20 e posterior.
da Plataforma de Destino	Universal
cabeçalho	ndis.h (inclua Ndis.h)
biblioteca	Ndis.lib
IRQL	<= DISPATCH_LEVEL