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

Статья
08/07/2023

Функция 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. В противном случае задайте для этого параметра значение 0. Дополнительные сведения об отправке отслеживания IRQL см. в разделе Dispatch IRQL Tracking.

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

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

None

Remarks

Драйверы 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 (включая Ndis.h)
Библиотека	Ndis.lib
IRQL	<= DISPATCH_LEVEL