Использование __sdv_save_request и __sdv_retrieve_request для отложенных вызовов процедур

Отложенные вызовы процедур (DPCs) представляют собой проблемы для статического средства проверки драйверов (SDV), так как трудно отслеживать объект запроса платформы. Одна из трудностей заключается в том, что запрос должен быть получен из глобального указателя, как правило, из контекста очереди или из рабочего элемента. Чтобы преодолеть эту трудность, средство проверки статических драйверов предоставляет две функции: __sdv_save_request и __sdv_retrieve_request. Эти функции сопоставляют отложенный запрос с запросом, который sdv может отслеживать.

Функции __sdv_save_request и __sdv_retrieve_request имеют следующий синтаксис:

__sdv_save_request( request ) 

__sdv_retrieve_request( request ) 

Где запрос может быть дескриптором для любого объекта запроса платформы.

Эти функции используются только средствами статического анализа. Функции игнорируются компилятором.

В следующем примере кода показано, как функции __sdv_save_request и __sdv_retrieve_request используются для управления SDV, чтобы SDV могли сопоставить отложенный запрос. SDV может использовать это сопоставление для проверки правила DeferredRequestCompleted . Правило DeferredRequestCompleted требует, чтобы в коде отображались __sdv_save_request и __sdv_retrieve_request . Существует два правила свойств драйвера (AliasWithinDispatch, AliasWithinTimerDpc), которые ищут существование функций __sdv_save_request и __sdv_retrieve_request .

В следующем примере кода функция EchoEvtIoRead является функцией обратного вызова события EvtIoRead , которая сохраняет дескриптор в объект запроса платформы в области контекста очереди. Функция EchoEvtTimerFunc является функцией обратного вызова события EvtTimerFunc , которая извлекает ее.

VOID
EchoEvtIoRead(
 )in WDFQUEUE   Queue,
 __in WDFREQUEST Request,
 __in size_t      Length
    )
{
/* ..................... */
    // Mark the request as cancelable
    WdfRequestMarkCancelable(Request, EchoEvtRequestCancel);
 
 
    // Defer the completion to another thread from the timer DPC and save the handle to the framework request object by using the __sdv_save_request function. 
    queueContext->CurrentRequest = Request;    
 __sdv_save_request(Request);

    queueContext->CurrentStatus  = Status;

    return;
}

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

VOID
EchoEvtTimerFunc(
    IN WDFTIMER     Timer
    )
{...................................................
    queue = WdfTimerGetParentObject(Timer);
    queueContext = QueueGetContext(queue);

    //
    // The DPC is automatically synchronized to the queue lock,
    // so this prevents race conditions from occurring without explicit driver-managed locking. The __sdv_retrieve_request function is used so that SDV can restore the deferred request in the timer DPC. Because we know that this deferred request is valid (because it has been previously saved), the __analysis_assume function is used to suppress false defects that might otherwise result in this code path.

    //
 __sdv_retrieve_request(queueContext->CurrentRequest);
    Request = queueContext->CurrentRequest;
 __analysis_assume(Request != NULL);
    if( Request != NULL ) {

        //
        // Try to remove cancel status from the request.
        //
        // The request is not completed if it is already canceled
        // because the EchoEvtIoCancel function has run, or is about to run,
        // and we are racing with it. 

        Status = WdfRequestUnmarkCancelable(Request);
// Because we know that the request is not NULL in this code path and that the request is no longer marked cancelable, we can use the __analysis_assume function to suppress the reporting of a false defect. 

 __analysis_assume(Status != STATUS_CANCELLED);
        if( Status != STATUS_CANCELLED ) {

            queueContext->CurrentRequest = NULL;
            Status = queueContext->CurrentStatus;

            KdPrint(("CustomTimerDPC Completing request 0x%p, Status 0x%x \n", Request,Status));

            WdfRequestComplete(Request, Status);
        }
        else {
            KdPrint(("CustomTimerDPC Request 0x%p is STATUS_CANCELLED, not completing\n",
                                Request));
        }
    }

    return;
}