WdfInterruptTryToAcquireLock 函式 (wdfinterrupt.h)

發行項
02/29/2024

[適用於 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); 
}

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.11
最低UMDF版本	2.0
標頭	wdfinterrupt.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate (kmdf)