Freigeben über

IoSetCompletionRoutineEx is not a drop in replacement for IoSetCompletionRoutine

  • Artikel

Yesterday I wrote
about the evolution of work items. Work items evolved because there was a need
to have a reference on the device object until the work item's callback routine
returned. As I illustrated yesterday, there is a small piece of assembly in between the last line of code and returning to the caller. The solution was that the I/O manager would maintain this reference and release it after the function returned. Unfortunately this particular issue is not
limited to work items, it is also an issue for completion routines.

To solve this problem IoSetCompletionRoutineEx()
was introduced in Windows XP. You should use it if possible, but BE WARNED,
IoSetCompletionRoutineEx() is not a drop in
replacement for IoSetCompletionRoutine()!!! If
you look at the signature for IoSetCompletionRoutineEx() you have:

 
    NTKERNELAPI
    NTSTATUS
    IoSetCompletionRoutineEx(
        PDEVICE_OBJECT DeviceObject,
        PIRP Irp,
        PIO_COMPLETION_ROUTINE CompletionRoutine,
        PVOID Context,
        BOOLEAN InvokeOnSuccess,
        BOOLEAN InvokeOnError,
        BOOLEAN InvokeOnCancel
        );

Note that while IoSetCompletionRoutine() does not
have a return value, while IoSetCompletionRoutineEx()
does. It returns an NTSTATUS. This means that the
call can now fail, so you cannot just do a string replacement for the Ex() version, you
must also add code that captures the return value and reacts appropriately
when it returns !NT_SUCCESS().

Checking the return value is not enough though! Internally
IoSetCompletionRoutineEx() allocates memory
so that it can do its work and this memory is freed when the completion routine
is invoked. This means that your driver must call IoCallDriver() after successfully calling
IoSetCompletionRoutineEx() . Otherwise, your driver
will cause a memory leak (which is not detectable by driver verifier because the
allocation occurred in the kernel itself, not your driver). This requirement
might make your driver's PIRP management more complicated, it certainly had that
affect on KMDF when I discovered that this requirement existed.

Comments

  • Anonymous
    August 08, 2006
    Neat post.

    Maybe this is a candidate for a DV enhancement; you could always have a hook that matches a driver's calls to IoSetCompletionRoutineEx() with calls to the completion routine or something.
  • Anonymous
    August 08, 2006
    Great idea.  I was thinking of SDV, but DV would also be great tool to catch the issue.  I emailed the owner of DV and I will let you know what comes of the suggestion.

    d
  • Anonymous
    June 19, 2009
    PingBack from http://mydebtconsolidator.info/story.php?id=16228