Функция NdisAcquireRWLockRead (ndis.h)

Статья
02/07/2025

Функция NdisAcquireRWLockRead получает блокировку чтения, которую вызывающий объект использует для доступа на чтение к ресурсам, общим для потоков драйверов.

Синтаксис

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

Параметры

[in] Lock

Указатель на непрозрачную переменную NDIS_RW_LOCK_EX, представляющую блокировку. Вызывающий объект может использовать эту блокировку для получения доступа на запись или чтение к ресурсам, которыми предоставляется общий доступ между потоками драйверов, отличных от ISR.

[out] LockState

Указатель на непрозрачную переменную LOCK_STATE_EX, которая отслеживает состояние блокировки. Эта переменная существует в интервале между временем, когда вызывающий объект получает и освобождает блокировку. Вызывающий объект должен использовать другую переменную типа LOCK_STATE_EX для каждой попытки получить блокировку из одного потока драйвера, отличного от ISR.

[in] Flags

Значение ULONG, содержащее флаги блокировки. Задайте для этого параметра значение NDIS_RWL_AT_DISPATCH_LEVEL, если текущий IRQL вызывающего объекта DISPATCH_LEVEL. В противном случае задайте для этого параметра нулевое значение. Дополнительные сведения об отслеживании IRQL см. в разделе Dispatch IRQL Tracking.

Примечание Если вызывающий объект знает, что текущий IRQL DISPATCH_LEVEL, задайте для этого параметра значение NDIS_RWL_AT_DISPATCH_LEVEL. Этот флаг делает блокировку еще более эффективной, вызвав ее пропустить проверку текущего IRQL. Если текущий IRQL неизвестен, не проверяйте текущий IRQL с помощью KeGetCurrentIrql исключительно, чтобы определить, следует ли задать этот флаг, так как это эффективнее, чтобы позволить функции NdisAcquireRWLockRead для проверки самого IRQL.

Возвращаемое значение

Никакой

Замечания

Драйверы NDIS вызывают функцию NdisAcquireRWLockRead для получения доступа только для чтения к ресурсам, которыми предоставляется общий доступ между потоками драйверов.

Драйвер должен выделить переменную типа NDIS_RW_LOCK_EX с функцией NdisAllocateRWLock, прежде чем драйвер вызывает функцию NdisAcquireRWLockRead.

После вызова драйвера NdisAllocateRWLockон может вызывать NdisAcquireRWLockWrite или NdisAcquireRWLockRead, чтобы получить доступ на запись или чтение к ресурсу. Только один поток драйвера, отличный от ISR, может получить доступ на запись к ресурсу. Если один поток, отличный от ISR, имеет доступ на запись, все доступы для чтения и записи другими потоками, не являющихся ISR, должны ждать, пока владелец доступа на запись не освобождает блокировку. Однако если поток, отличный от ISR, имеет доступ на чтение, другие потоки, отличные от ISR, могут одновременно получить доступ на чтение.

Блокировка NDIS_RW_LOCK_EX не поддерживает повышение уровня чтения на запись. Когда процессор приобрел NDIS_RW_LOCK_EX для доступа на чтение (вызывая NdisAcquireRWLockRead), тот же процессор не должен пытаться получить доступ на запись (вызывая NdisAcquireRWLockWrite), пока не будет выпущен предыдущий доступ на чтение.

Блокировка чтения NDIS_RW_LOCK_EX может быть получена рекурсивно на одном процессоре. Для каждого вызова NdisAcquireRWLockReadдолжен быть соответствующий вызов NdisReleaseRWLock. Блокировка освобождается только после последнего вызова NdisReleaseRWLock.

Драйвер не может использовать блокировку для защиты ресурсов от доступа на чтение или запись, к которым используются другие функции с помощью MiniportInterrupt или функции MiniportDisableInterruptEx или обоих. Вместо этого драйвер должен вызвать NdisMSynchronizeWithInterruptEx, чтобы его Функция MiniportSynchronizeInterrupt обращается к таким общим ресурсам в том же DIRQL, что его MiniportInterrupt или функции MiniportDisableInterruptEx или оба выполняются.

NdisAcquireRWLockRead всегда вызывает IRQL до IRQL = DISPATCH_LEVEL.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Поддерживается в NDIS 6.20 и более поздних версиях.
целевая платформа	Всеобщий
заголовка	ndis.h (include Ndis.h)
библиотеки	Ndis.lib
IRQL	<= DISPATCH_LEVEL