A Hole In My Head : Design Patterns

WDFREQUESTs are for sharing in KMDF v1.9

doronh — Fri, 06 Mar 2009 00:48:14 GMT

In my last post I described why a WDFREQUEST is unique to a particular WDFDEVICE. There is one particular programming pattern where this is not the behavior you want. This pattern is when you have each PDO accepting IO requests which it then forwards on to the parent WDFDEVICE for processing. One great in box example of this is usbhub.sys. Each usbhub PDO receives URBs which are then forwarded to the parent FDO and the FDO is where all IO processing occurs.

If you want to apply this pattern to a KMDF driver written to a v1.7 or earlier and take advantage of WDFQUEUEs you had to send the requests from the PDO to the FDO with WdfRequestSend so that they were represented to the FDO. The easiest way to do this is to create a WDFIOTARGET for the FDO itself and then have each PDO send IO to that WDFIOTARGET as shown in the following 3 code snippets.

EvtDriverDeviceAdd for the FDO

NTSTATUS EvtDriverDeviceAdd(WDFDRIVER Driver, PWDFDEVICE_INIT DeviceInit) 
{
   WDFDEVICE device;

   WDF_OBJECT_ATTRIBUTES woa;
   WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&woa, FDO_EXTENSION);

   // ...initialize the DeviceInit...
   status = WdfDeviceCreate(&DeviceInit, &woa, &device);

   if (!NT_SUCCESS(status)) {
      return status;
   }

   PFDO_EXTENSION pFdoExt = GetFdoExt(device);
   status = WdfIoTargetCreate(device, WDF_NO_OBJECT_ATTRIBUTES, &pFdoExt->SelfTarget);
   if (!NT_SUCCESS(status)) {
      return status;
   }

   // open the WDFIOTARGET to point our own PDEVICE_OBJECT
   WDF_IO_TARGET_OPEN_PARAMS openParams;
   WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE(openParams, WdfDeviceWdmGetDeviceObject(device));

   status = WdfIoTargetOpen(pFdoExt->SelfTarget, &openParams);
   if (!NT_SUCCESS(status)) {
      return status;
   }
   ...
   return status;
}

EvtChildListCreateDevice for the PDO

NTSTATUS EvtChildListCreateDevice(
    WDFCHILDLIST ChildList, 
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
    PWDFDEVICE_INIT ChildInit
    )
{
   WDFDEVICE pdo;
   NTSTATUS status;

   WDF_OBJECT_ATTRIBUTES woa;
   WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&woa, PDO_EXTENSION);

   status = WdfDeviceCreate(&ChildInit, &woa, &device);
   if (!NT_SUCCESS(status)) {
      return status;
   }

   PPDO_EXTENSION pPdoExt = GetPdoExt(device);
   PFDO_EXTENSION pFdoExt = GetFdoExt(WdfPdoGetParent(device));

   pPdoExt->ParentTarget = pFdoExt->SelfTarget;
   ...
   return status;
}

EvtIoDefault for the PDO

typedef
VOID EvtIoDefault(WDFQUEUE Queue, WDFREQUEST Request)

{
    // ...  extract Request type ...
    if (RequestShouldBeSentToParent()) {
       WdfRequestFormatRequestUsingCurrentType(Request);
       WdfRequestSend(Request, GetPdoExt(WdfIoQueueGetDevice(Queue))->ParentTarget);
    }
}

As you can see, this is a bit cumbersome! While it works, it is not ideal. The KMDF team addressed this issue in v1.9 by adding 2 new DDIs that must be used together

WdfPdoInitAllowForwardingRequestToParent which tells KMDF that you will be forwarding IO from a PDO to the parent FDO. Internally this sets up some bookkeeping and, more importantly, sets the PDO’s PDEVICE_OBJECT’s StackSize to the FDO’s PDEVICE_OBJECT StackSize+1 so that there will be enough stack locations in the underlying PIRP for both the parent and child stacks
WdfRequestForwardToParentDeviceIoQueue which removes the need for the custom WDFIOTARGET and WdfRequestSend and directly presents the PDO’s WDFREQUEST to the FDO’s WDFQUEUE

Let’s now rewrite the 3 code snippets to make use of these new DDIs, new code in red

NEW EvtDriverDeviceAdd for the FDO

NTSTATUS EvtDriverDeviceAdd(WDFDRIVER Driver, PWDFDEVICE_INIT DeviceInit) 
{
   WDFDEVICE device;

   WDF_OBJECT_ATTRIBUTES woa;
   WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&woa, FDO_EXTENSION);

   // ...initialize the DeviceInit...
   status = WdfDeviceCreate(&DeviceInit, &woa, &device);

   if (!NT_SUCCESS(status)) {
      return status;
   }

   PFDO_EXTENSION pFdoExt = GetFdoExt(device);

   status = WdfIoTargetCreate(device, WDF_NO_OBJECT_ATTRIBUTES, &pFdoExt->SelfTarget);
   if (!NT_SUCCESS(status)) {
      return status;
   }

   // open the WDFIOTARGET to point our own PDEVICE_OBJECT
   WDF_IO_TARGET_OPEN_PARAMS openParams;
   WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE(openParams, WdfDeviceWdmGetDeviceObject(device));

   status = WdfIoTargetOpen(pFdoExt->SelfTarget, &openParams);
   if (!NT_SUCCESS(status)) {
      return status;
   }



   // initialize a WDF_IO_QUEUE_CONFIG to your needs
   status = WdfIoQueueCreate(device, ..., &pFdoExt->>ChildProcessingQueue);
   if (!NT_SUCCESS(status)) {
      return status;
   }

   ...
   return status;
}

NEW EvtChildListCreateDevice for the PDO

NTSTATUS EvtChildListCreateDevice(
    WDFCHILDLIST ChildList, 
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
    PWDFDEVICE_INIT ChildInit
    )
{
   WDFDEVICE pdo;
   NTSTATUS status;

   WDF_OBJECT_ATTRIBUTES woa;
   WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&woa, PDO_EXTENSION);


   WdfPdoInitAllowForwardingRequestToParent(ChildInit);
   

   status = WdfDeviceCreate(&ChildInit, &woa, &device);
   if (!NT_SUCCESS(status)) {
      return status;
   }

   PPDO_EXTENSION pPdoExt = GetPdoExt(device);
   PFDO_EXTENSION pFdoExt = GetFdoExt(WdfPdoGetParent(device));

   pPdoExt->ParentTarget = pFdoExt->SelfTarget;
   ...
   return status;
}

NEW EvtIoDefault for the PDO

VOID EvtIoDefault(WDFQUEUE Queue, WDFREQUEST Request)

{
    // ...  extract Request type ...
    if (RequestShouldBeSentToParent()) {

       WdfRequestFormatRequestUsingCurrentType(Request);
       WdfRequestSend(Request, GetPdoExt(WdfIoQueueGetDevice(Queue))->ParentTarget);


       WDF_REQUEST_FORWARD_OPTIONS options;
       WDF_REQUEST_FORWARD_OPTIONS_INIT(&options);
       options.Flags = WDF_REQUEST_FORWARD_OPTIONS_FLAGS;


       status = WdfRequestForwardToParentDeviceIoQueue(
           Request, 
           GetFdoExt(WdfPdoGetParent(WdfIoQueueGetDevice(Queue)))->ChildProcessingQueue,
           &options);

    }
}

Using KeAcquireSpinLockAtDpcLevel is only a perf gain if you know you are DISPATCH_LEVEL

doronh — Sat, 29 Mar 2008 01:42:00 GMT

Well, that is certainly a long title ;).

First, let us look at an approximate implementation of KeAcquireSpinLock and KeRaiseIrql (and yes I know that KeRaiseIrql is really a #define to KfRaiseIrql, but it is the same thing that happens in the end…)

KIRQL KeAcquireSpinLock(PKSPIN_LOCK SpinLock, PKIRQL PreviousIrql)
{
    KeRaiseIrql(DISPATCH_LEVEL, PreviousIrql);
    [spin on the lock until it has been acquired]
}

VOID KeRaiseIrql(KIRQL NewIrql, PKIRQL, PKIRQL OldIrql)
{
    OldIrql = KeGetCurrentIrql();
    [raise IRQL to NewIrql]
}

What I want to emphasize is that KeAcquireSpinLock will retrieve the current IRQL (to know what to restore the IRQL to when the lock is released) as a part of acquiring the spin lock. Retrieving the current irql is a relatively expensive operation. Enter KeAcquireSpinLockAtDpcLevel. KeAcquireSpinLockAtDpcLevel does away with the IRQL change and just implements [spin on the lock until it has been acquired], but it does this with a large caveat…you must be running at DISPATCH_LEVEL (in reality it requires IRQL >= DISPATCH_LEVEL, but that is another discussion for another day) . It requires DISPATCH_LEVEL or higher so that you do not deadlock. Another caveat to effectively use KeAcquireSpinLockAtLevel you must know 100% that you are at DISPATCH_LEVEL. Naively, one could think that the following code optimizes for both cases

if (KeGetCurrentIrql() < DISPATCH_LEVEL) {
    KeAcquireSpinLock(&lock, &oldIrql);
}
else {
    KeAcquireSpinLockAtDpcLevel(&lock);
}

But the problem here is that in the case of the current IRQL < DISPATCH_LEVEL, the current IRQL is being retrieved twice (once in your code, once in KeAcquireSpinLock), so this relatively expensive operation is being performed twice when it should be performed only once. What all of this boils down to is that you must know with 100% certainty that the current IRQL is DISPATCH_LEVEL before you can use KeAcquireSpinLockAtDpcLevel effectively. Here are a couple of contexts here you can know for certain that the IRQL is DISPATCH_LEVEL.

In a DPC (for ISR, for a timer, your own)
After you have acquired a spin lock. In the case where you have nested locked being acquired (first A, then B), after you have called KeAcquireSpinLock(&A) you can then call KeAcquireSpinLockAtDpcLevel(&B)

Notice that a completion routine is not guaranteed to be called at IRQL == DISPATCH_LEVEL! While you may see that it is called at dispatch, it is not something that you can rely on 100% of the time. For instance, the lower driver could complete the IRP at passive level in an error condition.

Returning failure from DriverEntry

doronh — Tue, 18 Mar 2008 02:56:00 GMT

One thing that is easily overlooked about implementing DriverEntry is that upon return !NT_SUCCESS, DriverUnload is not called. I mentioned this anecdotally in a previous post, but it is worth expanding on. I was bit by this oversight when I was working on the Bluetooth stack. Driver verifier correctly identified that my driver had leaked pool. The code looked something like this

// Globals
UNICODE_STRING gRegistryPath = { 0 };

NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath)
{
    NTSTATUS status;

    DriverObject->DriverUnload = DriverUnload;

    gRegistryPath.Length = RegistryPath->Length;
    gRegistryPath.MaximumLength = RegistryPath->MaximumLength;
    gRegistryPath.Buffer = (PWCHAR) ExAllocatePoolWithTag(PagedPool, gRegistryPath.MaximumLength, [tag]);
    if (gRegistryPath.Buffer == NULL) { return STATUS_INSUFFICIENT_RESOURCES; }
    RtlCopyMemory(gRegistryPath.Buffer, RegistryPath->Buffer, gRegistryPath.Length);

    status = RegisterWithPortDriver(DriverObject, ...);
    if (!NT_SUCCESS(status)) { return status; } <== leak right here!

    // ... other init ...

    return status;
}

void DriverUnload(PDRIVER_OBJECT DriverObject)
{
    ExFreePool(gRegistryPath.Buffer);
    RtlZeroMemory(&gRegistryPath, sizeof(gRegistryPath));
}

While many WDM drivers do very little outside of initializing the dispatch table and other fields in their DriverObject, a miniport driver or a KMDF driver must register with their port driver (like ScsiPortInitialize) or framework (WdfDriverCreate) and this registration can introduce failure in DriverEntry (just like in my code sample above). What to do?

In a WDM driver you have to be very careful and manage this manually. Either you have a common error exit path out of DriverEntry which performs the cleanup (or manually calls your DriverUnload routine) or cleanup on each possible point of error. This pattern is very easy to get wrong and is not very maintainable, it is quite easy to add a new allocation and forget to cleanup it up later.

In a KMDF driver things are a bit easier to manage if you follow a particular pattern. While EvtDriverUnload has the same problems as the WDM DriverUnload, the EvtObjectCleanup routine registered on the WDFDRIVER is called in both scenarios. To re-emphasize, the EvtObjectCleanup registered on WDFDRIVER will be called when either DriverEntry returns !NT_SUCCESS or if your driver is gracefully unloaded later. This means that if you put all of your cleanup in the cleanup routine your DriverEntry implemention becomes much simpler. The one caveat is that the call to WdfDriverCreate must come before any allocations in your driver or state chaning APIs. WPP_INIT_TRACING is one such state changing API where you must undo its effects by calling WPP_CLEANUP. Quite a few WDK samples show this pattern (although suprisingly to me, not all!), let us look at the nonpnp sample (%wdk%\src\kmdf\nonpnp\sys\nonpnp.c)

NTSTATUS
DriverEntry(
    IN OUT PDRIVER_OBJECT   DriverObject,
    IN PUNICODE_STRING      RegistryPath
    )
{
    NTSTATUS                       status;
    WDF_DRIVER_CONFIG              config;
    WDFDRIVER                      hDriver;
    PWDFDEVICE_INIT                pInit = NULL;
    WDF_OBJECT_ATTRIBUTES          attributes;

    WDF_DRIVER_CONFIG_INIT(&config, WDF_NO_EVENT_CALLBACK);

    // Tell the framework that this is non-pnp driver so that it doesn't set the default AddDevice routine.
    config.DriverInitFlags |= WdfDriverInitNonPnpDriver;

    // NonPnp driver must explicitly register an unload routine for the driver to be unloaded.
    config.EvtDriverUnload = NonPnpEvtDriverUnload;

    // Register a cleanup callback so that we can call WPP_CLEANUP when
    // the framework driver object is deleted during driver unload.
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    attributes.EvtCleanupCallback = NonPnpEvtDriverContextCleanup;

    status = WdfDriverCreate(DriverObject,
                            RegistryPath,
                            &attributes,
                            &config,
                            &hDriver);
    if (!NT_SUCCESS(status)) {
        KdPrint (("NonPnp: WdfDriverCreate failed with status 0x%x\n", status));
        return status;
    }

    // Since we are calling WPP_CLEANUP in the DriverContextCleanup
    // callback we should initialize WPP Tracing after WDFDRIVER
    // object is created to ensure that we cleanup WPP properly
    // if we return failure status from DriverEntry. This
    // eliminates the need to call WPP_CLEANUP in every path
    // of DriverEntry.
    WPP_INIT_TRACING( DriverObject, RegistryPath );

    ...

    return status;
}

VOID NonPnpEvtDriverContextCleanup(WDFDRIVER Driver)
{
    WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver));
}

The red comments show what is going on. Hopefully the code is self explanatory.

Incidentally, another pattern you can use for global memory allocations is to allocate the memory with WdfMemoryCreate without specifying a parent object. The WDFDRIVER will be the parent object by default and since all child objects are destroyed when the parent is destroyed, all of your allocations will be destroyed after EvtDriverUnload has been called when the WDFDRIVER is destroyed in the unload path.

How to share HW resources with another driver not in the same PnP hierarchy

doronh — Thu, 25 Oct 2007 01:56:23 GMT

First, I have to say that I don't agree with this design pattern at all. I think it leads to too many problems and complications that are not worth the pain. The only reason I am writing this entry is that I have seen so many people get this wrong or not account for some details and I want to make sure that if such a driver is installed, the stability of the system is not compromised. The scenario I am covering is not the case where you are enumerating child devices and want to share resources assigned to the parent amongst the children. Rather, this is sharing HW resources assigned to your device (device A) with another device (device B). Device B can be a legacy NT4 style device or another PnP device stack, it doesn't matter.

There are 3 aspects to the issue that you must solve:

Handing off the resources to device B. This means that device B will open a handle against device A and send an internal IOCTL (e.g. IOCTL_INTERNAL_GET_RESOURCES) which device A completes with the appropriate values. If the number of resources is fixed, this is easy. If the number of resources varies, this can get complicated.
Coordinating access to the resources between device A and device B. If both drivers want to touch the resources at the same time, you now have to synchronize between 2 components and that can get very complicated, especially if there are callbacks involved.
Only touching the resources when the device has power. This is easy for device A to do since it is the power policy owner for the device and sees pnp state changing and device power irps. This is not easy for device B to do though.

Aspects number 1 and 2 I will leave for you to solve. Number 3 is where things get interesting. There are scenarios where the device can lose power:

PnP graceful remove (query remove, remove)
PnP surprise removal
PnP stop
System power state change (e.g. a standby or hibernate)

The first 2 scenarios in green are easily solved. Device B registers for PnP notifications on the file handle that it opens and it will be told when a PnP remove or surprise removal occurs. If you are using KMDF, the WDFIOTARGET automatically does this for you. But there is a catch to the surprise removal notification...it is sent to device B after device A has already processed the PnP IRP. This means that there is a window where device B thinks it has valid resources, but in reality it does not. File handle notifications do not solve the last 2 scenarios though and the surprise removal case does not work well, so it would be nice if there was one solution for all 4 scenarios.

The solution is that device B must register 2 callbacks with device A, a power up and power down callback (they can be condensed to one callback with an additional passed in parameter indicating power state if you want). These callbacks should be set at the same time that the resources are acquired so that there is no window where the resources have been acquired, the device loses power and the callback has not yet been set notifying device B of the power state change. These callbacks can be passed from device B to device in any number of ways. Two traditional ways are

To pass the callbacks in a buffer in an internal IOCTL (you can overload IOCTL_INTERNAL_GET_RESOURCES if you want)
To send a IRP_MN_QUERY_INTERFACE with these callbacks as input values in the INTERFACE based structure as I describe in this post

Once the callbacks have been set, device A must call them at the right time. In a KMDF driver, it is a very simple implementation. You call device B's power up callback in EvtDeviceSelfManagedIoRestart and device B's power down routine in EvtDeviceSelfManagedIoSuspend. This covers all cases because KMDF treats PnP state changes as implicit power changes, powering down the device and using the same callbacks for all cases. This also covers the surprise removal window because device B is now notified at the beginning of device A's power down instead of after it. One final thing to consider is what device B thinks the initial power state of device A is in. Ideally, device B should assume device A is in low power and should not touch the retrieved resources until its power up callback has been invoked. This would mean that the initial call to device B's power up call might occur outside of EvtDeviceSelfManagedIoRestart, perhaps immediately after completing the IOCTL_INTERNAL_GET_RESOURCES request.

If you are writing a WDM driver, well, I will leave that implementation up to you ;).

Supporting query interface in KMDF

doronh — Mon, 12 Mar 2007 21:25:00 GMT

In my last post I talked about bidirectional interfaces which can have both input and output parameters. KMDF supports both unidirectional and bidirectional interfaces. As is the case with many KMDF APIs and behaviors, we allow you to implement the easy pattern with little to no work and let you opt in to more complicated functionality as needed. Query interface support follows this philosophy.

If you want to support a unidirectional interface which only contains output parameters, you have very little code to write. First, declare and initialize the interface as you would want it to be returned to the requestor. Second, declare and initialize a WDF_QUERY_INTERFACE_CONFIG structure with your interface. Finally, you call WdfDeviceAddQueryInterface(). Here is a snippet from the WDK KMDF toaster bus sample which demonstrates how easy this is

WDF_QUERY_INTERFACE_CONFIG  qiConfig;
TOASTER_INTERFACE_STANDARD  ToasterInterface;

//
// Create a copy of the interface that the framework will use when
// completing the query interface request.
//
RtlZeroMemory(&ToasterInterface, sizeof(ToasterInterface));

ToasterInterface.InterfaceHeader.Size = sizeof(ToasterInterface);
ToasterInterface.InterfaceHeader.Version = 1;
ToasterInterface.InterfaceHeader.Context = (PVOID) hChild;

//
// Let the framework handle reference counting.
//
ToasterInterface.InterfaceHeader.InterfaceReference =
    WdfDeviceInterfaceReferenceNoOp;
ToasterInterface.InterfaceHeader.InterfaceDereference =
    WdfDeviceInterfaceDereferenceNoOp;

ToasterInterface.GetCrispinessLevel  = Bus_GetCrispinessLevel;
ToasterInterface.SetCrispinessLevel  = Bus_SetCrispinessLevel;
ToasterInterface.IsSafetyLockEnabled = Bus_IsSafetyLockEnabled;

WDF_QUERY_INTERFACE_CONFIG_INIT(&qiConfig,
                                (PINTERFACE) &ToasterInterface,
                                &GUID_TOASTER_INTERFACE_STANDARD,
                                NULL);

status = WdfDeviceAddQueryInterface(hChild, &qiConfig);
if (!NT_SUCCESS(status)) {
    return status;
}

But what about other scenarios? There are 3 other patterns that apply to handling a query interface request:

You want to selectively succeed, fail, or pass down the query interface request based on state or previous requests
You want to capture input parameters in the request and optionally set output parameters
You want forward the request down to the parent stack (PDO only)

Selectively succeed, fail, or pass down the request

Typically a query interface request is processed regardless of the previous queries or device state, but not always. For instance, let's say you want to only handle out the interface to one requestor (it would be available once it is dereferenced). Another example might be that you want to determine the status of the query interface request based on the capabilities exposed lower in the device stack. Finally, to process the query interface, you might be required to allocate memory (which could lead to failure if you cannot allocate the required buffer). To allow your driver to determine the status, check state, perform your custom action, etc. you specify a EvtDeviceProcessQueryInterfaceRequest function pointer in your WDF_QUERY_INTERFACE_CONFIG structure after calling WDF_QUERY_INTERFACE_CONFIG_INIT(). To succeed the query interface request, return a value which is NT_SUCCESS(), likewise to fail a request, return a value which is !NT_SUCCESS(). To instruct the framework to pass down the request to the lower stack, you return a special value, STATUS_NOT_SUPPORTED.

Capturing input parameters in the request

There is a field in WDF_QUERY_INTERFACE_CONFIG which controls how the framework treats the interface buffer itself. If ImportInterface is FALSE (the default value), the interface buffer is treated as a pure output buffer and the framework will copy over the interface to return directly into the requestor's buffer (and subsequently overwriting any values the requestor initialized the buffer with). If ImportInterface is TRUE, the framework does not touch the requestor's buffer. This allows you to inspect the requestor's buffer first and copy data from it. By setting ImportInterface to TRUE, there are two direct side effects that you must deal with. First, you must specify a EvtDeviceProcessQueryInterfaceRequest function when adding the interface. Second, and most importantly, your driver must now copy all output values into the requestor's buffer because the framework no longer does this for you!

Forwarding the request to the parent's stack

There are some query interface requests that must be forwarded from the PDO down to the parent's stack (and most likely to be completed by the parent's own PDO). For example, look at usbccgp (the USB generic parent driver). This driver does not support every single USBHUB interface, yet it must maintain compatibility with the hub's supported interfaces. To do this, it forwards all unhandled requests down from the PDO it created down the parent's stack. The framework can automatically provide this functionality to your driver if you set SendQueryToParentStack to TRUE.

INTERFACEs can contain both input and output parameters…and not just function pointers

doronh — Wed, 07 Mar 2007 09:01:00 GMT

When you look at the documentation for an INTERFACE and IRP_MN_QUERY_INTERFACE, it mentions that the INTERFACE structure is the input provided to the interface provider (set the by the driver querying for the interface) and the remainder of the interface structure is considered output (set by the driver completing the query interface request). What it doesn't says is that the interface can contain more input parameters then just the INTERFACE related fields. Furthermore, the interface can contain additional datatypes other then function pointers. This can be a very powerful design pattern, the querying driver can provide the implementer of the interface its own callbacks and data in addition to acquiring functions and data from the interface implementer.

First, let's take a previous example of REENUMERATE_SELF_INTERFACE_STANDARD which is a classic example of input and output parameters in an interface. In this case the structure reflects what the documentation says. The querying driver fills in the INTERFACE related fields and the bus driver fills in the SurpriseRemoveAndReenumerateSelf field.

typedef struct _REENUMERATE_SELF_INTERFACE_STANDARD {
    //
    // generic interface header
    //
    USHORT Size; 
    USHORT Version; 
    PVOID Context; 
    PINTERFACE_REFERENCE InterfaceReference; 
    PINTERFACE_DEREFERENCE InterfaceDereference; 
    //
    // Self-reenumeration interface
    //
    PREENUMERATE_SELF SurpriseRemoveAndReenumerateSelf; 
} REENUMERATE_SELF_INTERFACE_STANDARD, *PREENUMERATE_SELF_INTERFACE_STANDARD;

Next, let's look at an interface which has additional input parameters. I will try to put this into a real world context so that it is more concrete then creating fictional interfaces. Let's say that you have a piece of hardware that has multiple functions which share a common set of hardware resources (registers, interrupts, DMA, etc) between all of the functions. The shared hardware resources must be managed by an entity other then each function (which means that you cannot use mf.sys to split the functions apart). In this scenario, you would write a bus driver and enumerate a child PDO stack for every function on the device. But now you have a couple of design problems that you must solve:

How is the parent FDO going to notify a function that something asynchronous occurred (like an interrupt for a specific function)?
How is each child going to know what hardware resources to use?

An interface which contains both input and output parameters can solve both problems. I will first present the data structures and types and then explain them in detail

typedef PVOID INTERRUPT_CONTEXT;
typedef VOID (*PFN_MY_ACQUIRE_INTERRUPT_LOCK)(INTERRUPT_CONTEXT Context);
typedef VOID (*PFN_MY_RELEASE_INTERRUPT_LOCK)(INTERRUPT_CONTEXT Context);

typedef BOOLEAN (*PFN_FUNCTION_ISR)(PVOID Context);


typedef struct _MY_RESOURCES_INTERFACE {
    //
    // generic interface header
    //
    USHORT Size; 
    USHORT Version; 
    PVOID Context; 
    PINTERFACE_REFERENCE InterfaceReference; 
    PINTERFACE_DEREFERENCE InterfaceDereference; 

    //
    // Additional input parameters
    //
    // ISR routine for this function.  The FDO will call this routine when the ISR
    // fires for this function.
    //
    PFN_FUNCTION_ISR IsrRoutine;
    PVOID IsrRoutineContext;

    //
    // Output parameters
    //
    // The start and length of the assigned resources for this function.  These 
    // resources are exclusive to the function and are not shared
    //
    PUCHAR ResourcesStart;
    ULONG ResourcesLength;

    PFN_MY_ACQUIRE_INTERRUPT_LOCK AcquireInterruptLock;
    PFN_MY_RELEASE_INTERRUPT_LOCK ReleaseInterruptLock;
    INTERRUPT_CONTEXT InterruptContxt

} MY_RESOURCES_INTERFACE, *P MY_RESOURCES_INTERFACE;

The "additional" input parameters answer the first question of how is the FDO going to notify the function's stack that an interrupt occurred. The FDO for the function provides the IsrRoutine and IsrRoutineContext values and the bus driver stores these values away in the bus driver FDO context. For instance, the function's FDO code to initialize the structure before sending it down the stack would look like this

BOOLEAN FunctionIsr(PVOID Context)
{
    WDFDEVICE device = (WDFDEVICE) Context;
    //...
    return TRUE;
}

MY_RESOURCES_INTERFACE interface;
PDEVICE_CONTEXT pDevContext = GetDevExt(Device);


RtlZeroMemory(&interface, sizeof(inteface));
interface.Size = sizeof(interface);
interface.Version = 1;

interface.IsrRoutine = FunctionIsr;
interface.IsrRoutineContext = Device;

After the query interface request has been successfully sent down the stack synchronously, the function's FDO can retrieve the output parameters.

pDevExt->ResourcesStart = interface.ResourcesStart;
pDevExt->ResourcesLength = interface.ResourcesLength;

pDevExt->AcquireInterruptLock = interface.AcquireInterruptLock;
pDevExt->ReleaseInterruptLock = interface.ReleaseInterruptLock;
pDevExt->InterruptContext = interface.InterruptContext;

The output parameters answer the second question of "how is the function going to know which resources to use? In this example, there is only one set of registers. You could easily add more fields or additional functions to provide a richer interface to retrieve a dynamic set of registers if needed. When the bus driver processes this query interface request in its PDO, it will store the input parameters IsrRoutine and IsrRoutineContext in its extension and assign values to all of the output parameters

VOID ParentAcquireInterruptLock(INTERRUPT_CONTEXT Context) { WdfInterrupteAcquireLock((WDFINTERRUPT) Context); }
VOID ParentReleaseInterruptLock(INTERRUPT_CONTEXT Context) { WdfInterrupteReleaseLock((WDFINTERRUPT) Context); }

PPDO_EXTENSION pPdoExt = GetPdoExt(Device);
PPARENT_EXTENSION pParentDevExt = GetParentExt(WdfPdoGetParent(Device));

// store input parameters
pParentDevExt->Functions[pPdoExt->FunctionIndex].IsrRoutine = pInterface->IsrRoutine;
pParentDevExt->Functions[pPdoExt->FunctionIndex].IsrRoutineContext = pInterface->IsrRoutineContext;

// set output parameters
pInterface->AcquireInterruptLock = ParentAcquireInterruptLock;
pInterface->ReleaseInterruptLock = ParentReleaseInterruptLock;
pInterface->InterruptContext = (INTERRUPT_CONTEXT) pParentDevExt->Interrupt;

pInterface ->ResourcesStart = pParentExt->Functions[pPdoExt->FunctionIndex].ResourcesStart;
pInterface ->ResourcesLength = pParentExt->Functions[pPdoExt->FunctionIndex].ResourcesLength;

So, hopefully this gives you a glimpse of what you can do with an interface between drivers in a device stack. It can be a very powerful design pattern that can solve some difficult problems. Could you have done this with a more private mechanism like an internal IOCTL? Yes, you could, but it would be more work and it is much easier to use the existing mechanism rather than invent your own.