WdfInterruptTryToAcquireLock 函式（wdfinterrupt.h）

發行項
03/22/2025

[適用於 KMDF 和 UMDF]

WdfInterruptTryToAcquireLock 方法會嘗試取得中斷對象的被動鎖定。

語法

BOOLEAN WdfInterruptTryToAcquireLock(
  [in] WDFINTERRUPT Interrupt
);

參數

[in] Interrupt

架構中斷物件的句柄。

返回值

WdfInterruptTryToAcquireLock 如果成功取得中斷的鎖定，則會傳回 TRUE。否則，方法會傳回 FALSE。

備註

使用被動層級中斷處理的驅動程式呼叫 WdfInterruptTryToAcquireLock ，以啟動在 IRQL = PASSIVE_LEVEL 執行的程式代碼序列，同時保留驅動程式在中斷物件 WDF_INTERRUPT_CONFIG 結構中設定的被動層級中斷鎖定。

WdfInterruptTryToAcquireLock 嘗試取得鎖定，然後立即傳回，無論是否已取得鎖定。如果 WdfInterruptTryToAcquireLock 成功取得鎖定，則架構會在傳回之前先呼叫 KeEnterCriticalRegion，讓一般核心 APC 停用。

對於被動層級中斷對象，驅動程式必須在任意線程中執行時呼叫 WdfInterruptTryToAcquireLock，而不是在任意線程中執行時呼叫 WdfInterruptAcquireLock，例如佇列物件回呼函式。例如，驅動程式可能會從 EvtIoRead呼叫 WdfInterruptTryToAcquireLock。這樣做可避免死結的可能性，如 WdfInterruptAcquireLock的一節所述。

在非任意線程中執行時，例如工作專案，驅動程式應該使用 WdfInterruptAcquireLock。

當驅動程式呼叫 WdfInterruptReleaseLock時，架構會釋放中斷鎖定。

範例

下列程式代碼範例示範如何在任意內容中執行 EvtIoRead 回呼函式，在執行中斷相關工作之前，先呼叫 WdfInterruptTryToAcquireLock。如果方法傳回 FALSE，驅動程式會將工作專案排入佇列，以在非任意線程中執行工作。驅動程式也會提供 EvtWorkItem 回呼函式，在 WdfInterruptAcquireLock 執行工作之前，先呼叫 WdfInterruptAcquireLock。

在此範例中，驅動程式已指定佇列的循序分派。如果指定的驅動程式 佇列的任何其他分派方法，驅動程式應該使用額外的手動佇列來保留要求來處理工作專案。程序代碼批註描述新增這類支援的位置。


VOID EvtIoRead(
  __in  WDFQUEUE Queue,
  __in  WDFREQUEST Request,
  __in  size_t Length
    )
{
    DEVICE_CONTEXT    devCtx;
    devCtx = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    
    //
    // Do any pre-acquiring interrupt lock work here.
    //
   

    //
    // Check if we can acquire the lock.
    //
    if (WdfInterruptTryToAcquireLock(devCtx->InterruptObject) {
        ReadFunctionLocked(Request);
        WdfInterruptReleaseLock(devCtx->InterruptObject);
        //
        // Do any post-releasing interrupt lock work here.
        // For example: complete the request, and so on.
        //
        ReadFunctionFinish(Request); 
    }
    else {
        WORK_ITEM_CONTEXT ctx;

        ctx = GetWorkItemContext(ReadWorkItem);
        ctx->Request = Request;

        // If previous queue is non-sequential, call WdfRequestForwardToIoQueue 
        // to store request in an additional manual queue.

        WdfWorkItemEnqueue(ReadWorkItem);
    }
}


VOID
EvtReadWorkItemCallback(
    WDFWORKITEM WorkItem
    )
{
    WORK_ITEM_CONTEXT wiCtx;
    DEVICE_CONTEXT    devCtx;

    wiCtx = GetWorkItemContext(ReadWorkItem);
    devCtx = GetDeviceContext(WdfWorkItemGetParentObject(WorkItem));

    // If delivery queue is non-sequential, call WdfIoQueueRetrieveNextRequest 
    // to retrieve request that we stored in EvtIoRead.

    //
    // Acquire interrupt lock.
    //
    WdfInterruptAcquireLock(devCtx->InterruptObject);
    ReadFunctionLocked(wiCtx->Request);
    WdfInterruptReleaseLock(devCtx->InterruptObject);

    //
    // Do any post-releasing interrupt lock work here.
    // For example: complete the request, and so on.
    //
    ReadFunctionFinish(wiCtx->Request); 
}

需求

要求	價值
目標平臺	普遍
最低 KMDF 版本	1.11
最低 UMDF 版本	2.0
標題	wdfinterrupt.h （包括 Wdf.h）
程式庫	Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate（kmdf）