Driver Module Framework (DMF)

Convention	Meaning
DMF	Driver Module Framework
WDF	Windows Driver Framework (KMDF or UMDF).
WDM	Windows Driver Model. The layered driver model that the Windows operating system uses to organize device drivers.
Module	A DMF Module. A set of code that has a specific structure that is compatible with the DMF framework.
Child Module	A Module that is instantiated by another Module.
Parent Module	A Module that instantiates a Child Module.
Client Driver	A WDF device driver that uses DMF.
Client	The user of a Module; the code being served by a Module. It can either be a Parent Module or a Client Driver.
Library	A library of DMF Modules. It differs from "library" which is an arbitrary .lib file which contains reusable code in a binary format.
Module Include File	An .h file that contains all the information needed for a Client to instantiate and use a Module.
Library Include File	An .h file that contains all the information needed for a Client to instantiate and use Modules in a specific Library.

Documentation Guide This document is part of a family of documents that explain DMF...

Document Title	Purpose
Device Driver Writing Considerations: An Introduction to DMF	This document discusses issues device driver authors need to consider when writing device drivers. Furthermore, this document lays out the case for why DMF exists and why it can help device driver programmers.
Driver Module Framework (DMF) (this document)	This document explains the DMF API and how to use it. As you read this document, please have access to the source code so you can have a better view of how the APIs are used.
BranchTrack	This document explains what BranchTrack is and how to use it. (BranchTrack requires DMF.) As you read this document, please have access to the source code so you can have a better view of how the APIs are used.

What is the Driver Module Framework (DMF)?

DMF is a framework designed for Windows device driver developers.

Goals of DMF

DMF has the following goals:

Provide programmers a framework to design and implement encapsulated blocks of code, termed Modules, inside their device drivers. These Modules act like small device drivers inside the driver that is built and installed.
Enable true code sharing through reusable Modules. Eliminate "copy (from original driver) and change (in new driver)" method of sharing code.
Reduce the number of lines of code a programmer needs to write in a driver. The goal is for programmers to write only the "business logic" of the driver. In some cases, the number of lines of unique code (that performs the "business logic" of the driver) has been shown to be as low as 0.07% of the total lines of code in the driver.
Continue the layering architecture of Windows Kernel inside the device driver.
Enable use of object-oriented programming constructs without requiring an object-oriented programming language. Modules have attributes similar to C++ classes: private data, private methods, public methods, a constructor, and a destructor. Modules also support inheritance, with additional attributes that make these "objects" suitable for device driver programming.
Make it easier for individual contributors to work in parallel on different aspects of a driver's tasks. Each Module is self-contained, so programmers only need to consider that Module.
Make device driver programming for Windows easier, cheaper, and more fun while increasing code quality.

How does DMF Achieve the Above Goals?

DMF achieves the above goals by:

Providing a consistent interface to create and manage Modules, regardless of their functionality.
Allowing programmers to reuse existing Modules directly, subclass Modules, modify existing Modules, and create new Modules.
Providing runtime lifetime management of Modules as well as features like memory allocation and synchronization.
Automatically dispatching all callbacks from WDF into the device driver to each of its instantiated Modules.
Allowing Modules to easily contain other Modules, which in turn can contain other Modules.
Allowing all of a driver's functionality to be in one or more Modules. In this case, no driver-specific code is needed.
Making every Module directly usable by any driver that uses DMF or by another Module.
Allowing a Module to have its own context (similar to a device driver's Device Context) and Module-specific configuration.
Enabling Modules to perform any function. A Module can expose data structures (e.g., hash table), programming patterns (e.g., continuous reader or IOCTL handling), devices (e.g., virtual keyboard), and hardware buses (e.g., I2C or HID).
Using WDF to create objects (Modules) from common driver patterns. DMF is not a wrapper around WDF.
Making it easy to convert common device driver programming patterns into objects, and thus Modules that can be easily reused.

In this document:

A Module is a self-contained unit of code. It can be considered an object in the object-oriented programming model.
The Client Driver is the WDF device driver that uses DMF.
A Client is either a Client Driver or another Module. A Module is agnostic about whether its parent is a Client Driver or another Module.

How DMF Works in a Client Driver

This section provides an overview of how DMF fits in the device driver ecosystem.

Differences between a DMF driver and a traditional (non-DMF) Driver.

These diagrams show the differences between a hypothetical driver that uses DMF and a hypothetical driver that does not.

Note: The Modules listed above are a subset of all available Modules. Any Client Driver can use any number of Modules. Currently, about 50 Modules are available. Programmers are encouraged to write new Modules.

Differences

This table lists the differences between the two drivers:

Task	Traditional	DMF
Data used by Driver (Device Context)	All data is held in the Device Context and is accessible to all code.	Each Module can only access its own data. The Client-specific code and other Modules cannot access other Modules' data. Modules cannot access the Client Driver's data.
Callbacks	WDF sends callbacks to the Client Driver, which must execute proper code for each code block as needed.	WDF sends callbacks to DMF. DMF dispatches those callbacks to each Module and the Client Driver. Each Module handles the callback for its own needs. The Client Driver and other Modules have no knowledge of whether or how other Modules handle callbacks.
Locking	The Client Driver is responsible for locking and synchronizing all code blocks and the Device Context. The Client Driver must create the locks.	The Client Driver is only responsible for locking its own code and data in its Device Context. Each Module has its own lock and is responsible for locking its own code and data.
Code Visibility	Any code can easily call any code block in any order.	The Client Driver can only call top-level Modules. Child Modules can only be called directly by immediate Parent Modules.
WDF/WDM access	Full access.	Full access.
Code reuse	Difficult and requires careful planning. Interfaces will most likely differ.	Easy and requires no additional planning. Interfaces are already defined and always consistent.

You can design a traditional driver that acts like a DMF driver, but this requires careful planning, expert device driver programmers, and significant additional code that would not normally be present. For this reason, drivers are rarely designed with all the features that a DMF driver has.

DMF Container Driver

In this type of driver, there is no specific Client Driver code other than to instantiate DMF Modules and potentially handle Module-specific callbacks. There is no Device Context. The DMF Modules act like small drivers and perform all their work (the driver's "business logic") individually without knowledge of the other Modules. All Modules receive WDF callbacks as if they were a normal WDF driver. Note: This type of Client Driver has no Device Context. However, each Module has its own Context.

DMF Non-Container Driver

In this type of driver, the Client Driver has a Device Context. The Client Driver instantiates Modules and uses them to perform work (the device driver's "business logic"). However, there is also unique driver code that is not part of any Module. This is a classic WDF driver that uses DMF Modules to offload some of its code and work. Note: This type of Client Driver has a Device Context.

(In the above diagrams, the blue boxes contain code that performs the work ("business logic") of the Client Driver.)

WDF driver that uses only Dynamic DMF Modules

In this type of driver, the Client Driver uses only Dynamic Modules. Dynamic Modules do not support WDF callbacks, so they can be instantiated at any time. (Static Modules must be instantiated in the DmfModulesAdd callback during DeviceAdd so that they receive any WDF callback starting with EvtDevicePrepareHardware.) Both Static and Dynamic Modules may be instantiated in DmfModulesAdd, but only Dynamic Modules can be instantiated after DeviceAdd. Note: In drivers that only use Dynamic Modules, you do not need to call the DMF hooking functions or DMF_ModulesCreate().

Examples of Modules

Here are examples of Modules. This is only a partial list of generic Modules; the number of Modules keeps increasing. More Modules exist that perform more complex, driver/platform-specific tasks. For the complete list and an explanation of what each Module does, see the document, DMF Modules Overview.

Buffers

DMF_BufferPool
DMF_BufferQueue
DMF_PingPongBuffer
DMF_RingBuffer
DMF_ThreadedBufferQueue

Data Structures

DMF_HashTable

Task Execution

DMF_QueuedWorkitem
DMF_ScheduledTask
DMF_Thread

Targets

DMF_AcpiTarget
DMF_ContinuousRequestTarget
DMF_DeviceInterfaceTarget
DMF_GpioTarget
DMF_HidTarget
DMF_I2cTarget
DMF_ResourceHub
DMF_SelfTarget
DMF_SerialTarget
DMF_SpiTarget

User Notification

DMF_NotifyUserWithEvent
DMF_NotifyUserWithRequest

Driver Patterns

DMF_AcpiNotification
DMF_AlertableSleep
DMF_CrashDump
DMF_IoctlHandler
DMF_Pdo

Properties of Modules

This section provides an overview of DMF Modules:

DMFMODULE is of type WDFOBJECT

A Module is declared in code using DMFMODULE. Like WDFDEVICE, which inherits from WDFOBJECT, DMFMODULE also inherits from WDFOBJECT. Therefore, DMFMODULE has all the characteristics of a WDFOBJECT, such as Reference Count, Context Space, and Parent Object. In addition, functions that act upon WDFOBJECT also act upon DMFMODULE.

Module is Object Oriented

Modules have private and public data and methods, much like C++ objects. Modules specifically contain:

Module Config: A structure specific to the Module that allows the Client to configure the Module using Module-specific parameters.
Module Methods: Allow a Client to execute Module-specific functions using Module and Method-specific parameters.
Module Callbacks: Callback functions from DMF and/or WDF into the Module so it can perform necessary actions at that time.
Module Attributes: Indicate the Module's parent.
Context: Contains private data that the Module needs while it is instantiated. This is similar to a device driver's Device Context.
Private Methods: Code internal to the Module that is not exposed to Clients. These are private and are called by the Module's Methods and internal callbacks.

Modules Have a Predefined Lifecycle

Create: DMF resources are allocated and prepared.
Open: Module-specific resources are allocated and prepared. The Module's work may happen here.
Use: Modules perform work on their own and handle requests and do work on behalf of the Client.
Close: Module-specific resources are released.
Destroy: DMF resources are released.

Modules Have a Hierarchy

Modules can only communicate with each other when they are in a parent-child relationship.
Modules can never communicate with each other when they are siblings.
Modules can be extended by using other Modules and using inheritance.
Client Drivers may not use Modules that are not properly instantiated.

Properties of Modules

The above generic properties that make Modules object-oriented are used to give Modules these properties that are specifically useful in drivers:

Clients access Modules via Module instance handles. Each Module manages its own state using its own Module Private Context (similar to a Device Context). However, this Module Private Context is only accessible and visible to the Module itself. Neither the Client nor any other Module has access to that Module Private Context.
Each Module receives all WDF callbacks, such as EvtDevicePrepareHardware.
Modules can, and usually do, use other Child Modules. This allows the layered architecture in WDM to exist inside the Client Driver. (The driver author designs the layering.)
DMF is responsible for the direct creation and destruction of all Modules. DMF allocates memory for DMF-specific resources for each instantiated Module. DMF also allocates the Module's Context.
DMF dispatches all WDF callbacks that WDF sends to the Client Driver to each Module and its Child Modules recursively. Dispatching to Modules happens before the callback is dispatched to the Client Driver's callbacks. (Client Driver WDF callbacks occur after all the instantiated Modules' WDF callbacks have occurred, except during the unwinding path, in which case they happen in reverse order.)
Modules may only communicate with each other via a parent-child relationship. Modules are specifically prevented from communicating in a sibling-sibling relationship. This is necessarily true because of point 1.
DMF provides a common way to instantiate and initialize a Module. This makes it easier and less error-prone for the driver writer to incorporate a Module. It also makes it easier for the Module creator to create the Module because there are many existing samples to learn from, and the interface to Clients is well-defined.
The Client does not need to lock Module data because each Module locks its own data using its own locks (which DMF provides for each Module).
The Client does not need to handle asynchronous arrival/removal of Module resources because each Module properly handles asynchronous arrival/removal of its underlying resources. DMF has APIs that help the Module author handle these issues robustly.
A Module can instantiate up to 16 Child Modules.
DMF Modules can be written and used in C or C++.
DMF Modules can be written and used in both Kernel-mode and User-mode drivers.

Properties of a DMF Driver

DMF drivers have the following properties:

DMF Drivers consist of zero or more (usually more than zero) instantiated Modules.
There may or may not be Client Driver-specific code that interacts with the instantiated Modules.
DMF Drivers are WDF Drivers that incorporate the DMF framework by adding a few extra steps when the Client Driver creates its WDFDEVICE.
Using predefined macros, you can easily create a DMF Driver without writing any of the code to initialize the driver and/or the Client Driver's WDFDEVICE.
DMF Drivers can be any type of device driver, including Function Driver, Filter Driver, Bus Driver, Kernel-mode Driver, or User-mode Driver.
A Client Driver can instantiate any number of Modules.
DMF Drivers do not prevent the Client Driver from using any WDF or WDM primitives.

Using DMF in an Existing Driver or a Driver that has a DeviceAdd callback

Note: In drivers that only use Dynamic Modules, you do not need to call the DMF hooking functions or to call DMF_ModulesCreate().

Aside from including the appropriate headers and libraries, there are four specific steps to using DMF in a driver that has a DeviceAdd callback (usually so it can have its own Device Context):

Hook DMF into the driver.
Initialize DMF.
Instantiate DMF Modules.
Use Modules.

This section explains steps 1 and 2 in detail with examples. Later sections explain steps 3 and 4 which are common for all drivers that use DMF. They are "Instantiating DMF Modules" and "Using DMF Modules".

Hook DMF into the driver

Note: In drivers that only use Dynamic Modules, you do not need to call the DMF hooking functions or to call DMF_ModulesCreate().

DMF must be "hooked" into the driver so that DMF can perform two important tasks:

Dispatch all WDF callbacks to each instantiated DMF Module while still allowing the Client Driver's callbacks to execute.
Manage the creation, destruction, and operation of each instantiated Module.

To accomplish the first task, DMF needs to tell WDF to call DMF for all possible WDF callbacks and needs to know what callbacks the Client Driver supports. This is accomplished using a set of calls into DMF that map directly to the types of WDF callbacks that exist.

Follow these steps:

First, include the DMF support as well as the definitions needed to use Modules in a specific Library by including the relevant Library Include File. The Library Include File, DmfModules.Library.h, contains all the definitions needed to use DMF as well as all the definitions for the Modules that come with the Framework.

#include "DmfModules.Library.h

Next, write the DriverEntry function as you would normallyit has nothing that is DMF-specific.

In the Client Driver's DeviceAdd callback, allocate an opaque DMF structure that is used later during initialization:

PDMFDEVICE_INIT dmfDeviceInit;
dmfDeviceInit = DMF_DmfDeviceInitAllocate(DeviceInit);

This structure is used to gather information about how the Client Driver operates and is used later to initialize DMF.

Next, the Client Driver must tell DMF what WDF callbacks it will use. There are four sets of WDF callbacks, each set corresponding to a DMF call.

Pnp Power Events
Pnp Power Policy Events
File Object Events
Default Queue Events

Each type of callback must be hooked because DMF needs to chain the Module's callbacks to the Client Driver's callbacks. [Note: The Client Driver must first call the DMF API before calling the WDF API to set the Client Driver callbacks.]

Pnp Power Event callbacks:

WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&Pnp);
Pnp.EvtDeviceD0Entry = DmfSampleEvtDeviceD0Entry;
Pnp.EvtDeviceD0Exit = DmfSampleEvtDeviceD0Exit;
Pnp.EvtDevicePrepareHardware = DmfSampleEvtDevicePrepareHardware;
Pnp.EvtDeviceReleaseHardware = DmfSampleEvtDeviceReleaseHardware;
DMF_DmfDeviceInitHookPnpPowerEventCallbacks(dmfDeviceInit, &Pnp);
WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &Pnp);

Pnp Power Policy callbacks:

DMF_DmfDeviceInitHookPowerPolicyEventCallbacks(dmfDeviceInit, NULL);

File Object Event callbacks:

DMF_DmfDeviceInitHookFileObjectConfig(dmfDeviceInit, NULL);

In the above example, the Client Driver does not register for any Power Policy or File Object Event callbacks, but the DMF API must still be called. This is mandatory because the Client Driver does not know what callbacks are supported by each Module.

[Note: The Client Driver must call the above three functions regardless of whether or not the Client Driver supports the corresponding callbacks.]

There is one more set of important callbacks that must be hooked: The WDFQUEUE callbacks for the default queue:

WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&queueConfig, WdfIoQueueDispatchParallel);
queueConfig.PowerManaged = WdfTrue;
queueConfig.EvtIoDeviceControl = DmfSampleEvtIoDeviceControl;
queueConfig.EvtIoInternalDeviceControl = DmfSampleEvtIoDeviceControl;
DMF_DmfDeviceInitHookQueueConfig(dmfDeviceInit, &queueConfig);
ntStatus = WdfIoQueueCreate(device, &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, &queue);

If the Client Driver has no queue, you do not need to call this function. In this case, DMF will create a default queue so that any Modules that support IOCTLs (which need the default queue) will function properly.

Filter Drivers

WDF Client Drivers that are filter drivers must tell WDF they are filter drivers by calling WdfFdoInitSetFilter(). Similarly, when a Client Driver makes that call, it must also tell DMF that it is a filter by calling DMF_DmfFdoSetFilter().

There are two reasons for this:

DMF is able to comply with WDF's rules that WDFREQUESTs should be passed down the stack in filter drivers.
Modules that handle WDFREQUESTs are able to comply with WDF's rules for filter drivers.

Here is an example of this sequence:

// This is a filter driver that loads on OSRUSBFX2 driver.
//
WdfFdoInitSetFilter(DeviceInit);

// DMF Client Drivers that are filter drivers must also make this call.
//
DMF_DmfFdoSetFilter(dmfDeviceInit);

Finally, with regard to filter drivers, note the following:

In filter drivers, DMF automatically passes any WDFREQUEST that Modules (or the Client driver) does not handle.
In non-filter drivers, DMF returns STATUS_NOT_SUPPORTED for any WDFREQUEST that Modules (or the Client driver) do not handle.

Initialize DMF

Note: In drivers that only use Dynamic Modules, you do not need to call the DMF hooking functions or to call DMF_ModulesCreate().

Using the above steps, DMF is hooked into the Client Driver but is not yet initialized. The next step is to initialize DMF.

DMF_EVENT_CALLBACKS dmfEventCallbacks;
DMF_EVENT_CALLBACKS_INIT(&dmfEventCallbacks);
dmfEventCallbacks.EvtDmfDeviceModulesAdd = DmfDeviceModulesAdd;
DMF_DmfDeviceInitSetEventCallbacks(dmfDeviceInit,
                                   &dmfEventCallbacks);
ntStatus = DMF_ModulesCreate(device,
                             &dmfDeviceInit);
if (!NT_SUCCESS(ntStatus))
{
    goto Exit;
}

The above code does the following:

Sets a callback that DMF will call when it is ready to instantiate Modules. This tells DMF which Modules to instantiate.
Initialize DMF itself.

In the above example, DmfDeviceModulesAdd is the function that DMF will call to get the list of Modules that the Client Driver will use. This function is where the Client Driver configures each of the Modules that it uses.

Now the Client Driver is ready to instantiate Modules. See the section "Instantiating DMF Modules".

Using DMF in a Driver That Does Not Have a DeviceAdd callback

The preferred way to use DMF is for all work in a Client Driver to be done by the Modules and corresponding Client Driver callbacks. In this case, the Client Driver is a "container" of Modules. These types of Client Drivers do not have their own Device Context. They do not need to create the typical DriverEntry and Device Add functions and all the Client Driver code is in a single file called DmfInterface.c.

All DMF drivers are WDF drivers; therefore, they must follow WDF rules. One of those rules is to declare function prototypes for callbacks prior to their use so that SAL can properly analyze code. In the code snippet below, you can see those lines.

DMF provides macros that make it simple to initialize a DMF driver. These macros provide standard code that most DMF drivers need to initialize WDF and connect WDF to DMF. See the section, "Client Driver Initialization Macros". In some cases, the code the macros provide may not be adequate. In that case, you do not need to use the macros. Instead, the programmer must write the WDF initialization code directly and write the code to connect WDF to DMF. See "Client Driver DMF Initialization Functions".

These macros are:

DMF_DEFAULT_DRIVERENTRY
DMF_DEFAULT_DRIVERCLEANUP
DMF_DEFAULT_DEVICEADD

To initialize a DMF driver that does not have its own Device Context, follow these steps:

First, include the DMF support as well as the definitions needed to use Modules in a specific Library by including the relevant Library Include File. The Library Include File, DmfModules.Library.h, contains all the definitions needed to use DMF as well as all the definitions for the Modules that come with the Framework.
Declare WDF function prototypes.
Write the comment that the WPP scanner needs.
Use the above macros to define DriverEntry, Driver Cleanup and Device Add.

The following code example shows the above steps:

#include "DmfModules.Library.h"
DRIVER_INITIALIZE DriverEntry;
EVT_WDF_DRIVER_DEVICE_ADD StorageFwUpdateDeviceAdd;
EVT_WDF_OBJECT_CONTEXT_CLEANUP StorageFwUpdateDriverContextCleanup;
EVT_DMF_DEVICE_MODULES_ADD DmfDeviceModulesAdd;

/*WPP_INIT_TRACING(); (This comment is necessary for WPP Scanner.)*/
#pragma code_seg("INIT")
DMF_DEFAULT_DRIVERENTRY(DriverEntry, 
                        StorageFwUpdateDriverContextCleanup,
                        StorageFwUpdateDeviceAdd)
#pragma code_seg()

#pragma code_seg("PAGED")
DMF_DEFAULT_DRIVERCLEANUP(StorageFwUpdateDriverContextCleanup)
DMF_DEFAULT_DEVICEADD(StorageFwUpdateDeviceAdd,
                      DmfDeviceModulesAdd)
#pragma code_seg()

In this case DMF will perform all the hooking in addition to creating the driver's WDFDEVICE and initializing DMF. Now, you only need to write the function that instantiates the Modules. In the above example, it is called DmfDeviceModulesAdd.

If your file is a C++ file, you need to surround the prototypes with extern "C" as in this example:

#include "DmfModules.Library.h"

extern "C"
{
DRIVER_INITIALIZE DriverEntry;
EVT_WDF_DRIVER_DEVICE_ADD StorageFwUpdateDeviceAdd;
EVT_WDF_OBJECT_CONTEXT_CLEANUP StorageFwUpdateDriverContextCleanup;
EVT_DMF_DEVICE_MODULES_ADD DmfDeviceModulesAdd;
}

/*WPP_INIT_TRACING(); (This comment is necessary for WPP Scanner.)*/
#pragma code_seg("INIT")
DMF_DEFAULT_DRIVERENTRY(DriverEntry,
                        StorageFwUpdateDriverContextCleanup,
                        StorageFwUpdateDeviceAdd)
#pragma code_seg()

#pragma code_seg("PAGED")
DMF_DEFAULT_DRIVERCLEANUP(StorageFwUpdateDriverContextCleanup)
DMF_DEFAULT_DEVICEADD(StorageFwUpdateDeviceAdd,
                      DmfDeviceModulesAdd)
#pragma code_seg()

Now the Client Driver is ready to instantiate Modules. See the section "Instantiating DMF Modules".

Instantiating DMF Modules

Note: In drivers that only use Dynamic Modules, you do not need to call the DMF hooking functions or to call DMF_ModulesCreate().

This section is common to all types of DMF drivers. Most DMF drivers will instantiate at least one Module. If you have followed the steps above, DMF will call the callback function that allows the Client Driver to list and configure the Modules to be used:

This is the signature for that function:

#pragma code_seg("PAGED")
_IRQL_requires_max_(PASSIVE_LEVEL)
VOID
DmfDeviceModulesAdd(
    _In_ WDFDEVICE Device,
    _In_ PDMFMODULE_INIT DmfModuleInit
    )

Recall that most Modules have Module-specific configuration parameters. It is the job of the Client Driver to set the configuration of each Module and then call a DMF API that adds that Module to a list of Modules that will be instantiated. To do so, follow this example:

First, declare a single local structure (on the stack) that stores the Module Attributes. Note: You only need a single instance of this structure for all modules that are instantiated.

DMF_MODULE_ATTRIBUTES moduleAttributes;

Next, declare a Module-specific Config structure for each Module that will be instantiated. Look at the Module's header file to know what structure to use. Here is shown the Config structure for the BufferPool Module. Not all Modules require a Config structure, and not all parameters of a Config structure are necessarily required. See the Module documentation for details.

DMF_CONFIG_BufferPool bufferPoolModuleConfig;

Next, initialize and populate the Module's Config and Attributes structure. It takes as parameters the Module-specific Config structure and the Module Attributes structure.

DMF_CONFIG_BufferPool_AND_ATTRIBUTES_INIT(&moduleConfigBufferPool,
                                          &moduleAttributes);
moduleConfigBufferPool.BufferPoolMode = BufferPool_Mode_Source;
moduleConfigBufferPool.Mode.SourceSettings.EnableLookAside = TRUE;
moduleConfigBufferPool.Mode.SourceSettings.BufferCount = BRANCHTRACK_NUMBER_OF_BUFFERS;
moduleConfigBufferPool.Mode.SourceSettings.PoolType = NonPagedPoolNx;
moduleConfigBufferPool.Mode.SourceSettings.BufferSize = moduleConfigHashTable.MaximumKeyLength;
moduleConfigBufferPool.Mode.SourceSettings.BufferContextSize = 0;

Finally, add the Module to the list of Modules that will be instantiated. This API allows the Client Driver to save a copy of the DMFMODULE for later use. If the Client Driver has no Device Context or does not need to save the DMFMODULE, then the last argument can be NULL.

DMF_DmfModuleAdd(DmfModuleInit,
                 &moduleAttributes,
                 WDF_NO_OBJECT_ATTRIBUTES,
                 &moduleContext->DmfObjectBufferPool);

Follow the above steps for each Module that is to be instantiated. Here are more examples:

// AcpiTarget
// ----------
//

DMF_CONFIG_AcpiTarget_AND_ATTRIBUTES_INIT(&moduleConfigAcpiTarget,
                                          &moduleAttributes);
moduleConfigAcpiTarget.DsmRevision = 1;
moduleConfigAcpiTarget.Guid = GUID_DSM_PCIE;
DMF_DmfModuleAdd(DmfModuleInit,
                 &moduleAttributes,
                 WDF_NO_OBJECT_ATTRIBUTES,
                 &deviceContext->DmfModuleAcpiTarget);

// CrashDump
// ---------
//
DMF_CONFIG_CrashDump_AND_ATTRIBUTES_INIT(&moduleConfigCrashDump,
                                         &moduleAttributes);
moduleConfigCrashDump.ComponentName = CRASH_DUMP_COMPONENT_NAME;
// This driver only uses its FIFO Crash Dump buffer.
//
moduleConfigCrashDump.BufferSize = CRASH_DUMP_DATA_FIFO_SIZE_OF_BUFFER;
moduleConfigCrashDump.BufferCount = CRASH_DUMP_DATA_FIFO_NUMBER_OF_BUFFERS;
// The ring buffer which contains the log.
//
moduleConfigCrashDump.RingBufferDataGuid = DmfSampleDriver_CrashDump_GUID_Fifo;
DMF_DmfModuleAdd(DmfModuleInit,
                 &moduleAttributes,
                 WDF_NO_OBJECT_ATTRIBUTES,
                 &deviceContext->DmfModuleCrashDump);

// HidPortableDeviceButtons
// -----------------------
//
DMF_CONFIG_HidPortableDeviceButtons_AND_ATTRIBUTES_INIT(&moduleConfigHidPortableDeviceButtons,
                                                        &moduleAttributes);
moduleConfigHidPortableDeviceButtons.ProductId = HIDID_PRODUCT_VHF_BUTTONS;
moduleConfigHidPortableDeviceButtons.VendorId =	HIDID_VENDOR_MICROSOFT;
moduleConfigHidPortableDeviceButtons.VersionNumber = 0x0002;
DMF_DmfModuleAdd(DmfModuleInit, 
                 &moduleAttributes,
                 WDF_NO_OBJECT_ATTRIBUTES,
                 &deviceContext->DmfModuleHidPortableDeviceButtons);

// RingBuffer
// ----------
//
DMF_CONFIG_RingBuffer_AND_ATTRIBUTES_INIT(&moduleConfigRingBuffer,
                                          &moduleAttributes);
moduleConfigRingBuffer.ItemCount = RING_BUFFER_MAXIMUM_NUMBER_OF_ENTRIES;
moduleConfigRingBuffer.ItemSize = sizeof( BUTTON_DATA );
DMF_DmfModuleAdd(DmfModuleInit,
                 &moduleAttributes,
                 WDF_NO_OBJECT_ATTRIBUTES,
                 &deviceContext->DmfModuleButtonFifo);

That is all you need to do to instantiate a Module. When this callback function returns, DMF will actually instantiate the Modules that have been added to the list.

If the Client Driver has a Device Context and it saved a copy of the DMFMODULE, then the Client Driver can start using the Modules directly. See the section below called, "Using Modules". If the Client Driver has no Device Context, then the Modules are not directly used; they just operate on their own.

Instantiating Dynamic Modules

In some rare cases, a Client may instantiate a Module directly without using the DmfModulesAdd callback. For example, a Client (driver or Module) may want to use a Module to perform a query before instantiating other Modules. DMF supports this ability. However, there is one restriction: It is only possible to open a Module dynamically if the Module does not support WDF callbacks. This makes sense because if the Module is created, opened and used dynamically it means it can happen at any time. In this case, the Module cannot operate as intended by the Module author because there is no guarantee that its WDF callbacks will be called.

To open a Module dynamically, follow these steps:

Synchronous Dynamic Instantiation

Use these steps to open a Module that does not register for a DMF_[ModuleName]_NotificationRegister callback.

Declare a DMF_MODULE_ATTRIBUTES structure.
Declare a DMF_CONFIG_[ModuleName] if the Module has a Config structure.
Populate the above two structures properly.
Declare a DMFMODULE object.
Prepare to call the Module's Create function by using DMF_CONFIG_[ModuleName]_AND_ATTRIBUTES_INIT() or DMF_[ModuleName]_AND_ATTRIBUTES_INIT(). See the section, Dynamic Module Access API.
Call the Module's Create function using the above two structures and retrieve a DMFMODULE and save it in the variable declared in step 4. [See the section, The Module Create Function.]
Call the Module's Methods as needed passing the DMFMODULE from step 6.
Finally, destroy the DMFMODULE using WdfObjectDelete() or let WDF delete it automatically when its parent WDFOBJECT is deleted.

Asynchronous Notification Dynamic Instantiation

Use these steps to dynamically instantiate a Module that registers for a DMF_[ModuleName]_NotificationRegister callback.

Declare a DMF_MODULE_ATTRIBUTES structure. You must set its DMF_MODULE_EVENT_CALLBACKS structure's EvtModuleOnDeviceNotificationOpen callback (and optionally the EvtModuleOnDeviceNotificationPostOpen callback).
Declare a DMF_CONFIG_[ModuleName] if the Module has a Config structure.
Populate the above two structures properly.
Declare a DMFMODULE object.
Prepare to call the Module's Create function by using DMF_CONFIG_[ModuleName]_AND_ATTRIBUTES_INIT() or DMF_[ModuleName]_AND_ATTRIBUTES_INIT(). [See the section, Dynamic Module Access API].
Call the Module's Create function using the above two structures and retrieve a DMFMODULE and save it in the variable declared in step 4. [See the section, The Module Create Function.]
[Wait for the callback set in step 1 to occur.] Now, the rest of the driver can use the Module. Note: The Client may also register for notification that the underlying device is removed and stop using the Module. If the Client calls a Module's method while or after the underlying target has been removed, an error is gracefully returned to the Client.
Call the Module's Methods as needed passing the DMFMODULE from step 7.
Finally, destroy the DMFMODULE using WdfObjectDelete() or let WDF delete it automatically when its parent WDFOBJECT is deleted.

Destroying a Dynamic Module

IMPORTANT: When a Dynamic Module is created, it is best to not set its parent it to another WDFOBJECT. Instead, it is best to delete it directly using WdfObjectDelete(). The reason is that when WDF deletes objects, sometimes the order in which it does so does not match the DMF parent/child relationships. This can cause a Child Module to be deleted before its parent has executed its cleanup code. In most cases, setting the parent to another WDFOBJECT works, but not in all cases. So it is best to never set the parent to another WDF object.

Here is an example of the above sequence showing the Dmf_AcpiTarget Module dynamically instantiated:

NTSTATUS
ConfigurationDetermine(
    DEVICE_CONTEXT* DeviceContext
    )
{

    NTSTATUS ntStatus;
    DMF_MODULE_ATTRIBUTES moduleAttributes;
    DMF_CONFIG_AcpiTarget acpiTargetModuleConfig;
    DMFMODULE dmfModuleAcpiTarget;
    ULONG returnBufferSize;
    WDF_OBJECT_ATTRIBUTES attributes;

    dmfModuleAcpiTarget = NULL;

    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    // NOTE: Do not set parent of the Module.
    //

    DMF_CONFIG_AcpiTarget_AND_ATTRIBUTES_INIT(&acpiTargetModuleConfig,
                                              &moduleAttributes);
    acpiTargetModuleConfig.DsmRevision = 1;
    acpiTargetModuleConfig.Guid = GUID_DSM_CONFIGURATION;

    // Create a Dynamic Module.
    //
    ntStatus = DMF_AcpiTarget_Create(DeviceContext->WdfDevice,
                                     &moduleAttributes,
                                     &attributes,
                                     &dmfModuleAcpiTarget);
    if (!NT_SUCCESS(ntStatus))
    {
        goto Exit;
    }
    
    // Get configuration information using the Dynamic Module's Methods.
    //
    ntStatus = DMF_AcpiTarget_InvokeDsm(dmfModuleAcpiTarget,
                                        CONFIGURATION_INFORMATION,
                                        0,
                                        &DeviceContext->ConfigurationInformation,
                                        &returnBufferSize);
    if (!NT_SUCCESS(ntStatus))
    {
        DeviceContext->ConfigurationInformation = 0;
    }
Exit:
    if (dmfModuleAcpiTarget != NULL)
    {
        WdfObjectDelete(dmfModuleAcpiTarget);
    }
    return ntStatus;
}

Transport Modules

One of the most powerful features of DMF is that it allows programmers to easily implement an important programming paradigm, namely the idea of a Protocol-Transport. Using this paradigm, one can implement the important object-oriented programming pattern known as Composition.

The Protocol-Transport paradigm is useful when one has a Protocol that is to be implemented on several types of Transports. It is useful, in this case, to write the Protocol one time using a common lower interface. Then, each of the multiple Transports are written using the same upper interface.

In DMF, this is accomplished using Parent-Child Modules. In this case, the Protocol is located in the Parent Module. The Transports are located in multiple Child Modules.

Normally, Child Modules are statically created by the Parent during Module creation. The Client of the Parent has no knowledge of the Child Modules instantiated by the Parent Module.

However, using DMF's Transport Module concept, the Client has the ability to determine a Child Module that the Parent Module will instantiate. In this way, the Client decides the underlying transport the Parent Module uses.

A Transport Module is the same as any other Modules, except that it implements a Method using a specific signature. Transport Modules can be used both as normal (non-Transport Modules) and as Transport Modules.

A Parent Module that needs to use a Transport Module must always use a Transport Module. In this case, when the Module is created the MODULE_OPTIONS_TRANSPORT_REQUIRED bit must be set in the Module Options. When this bit is set, just after the Module (and any Child Modules) have been created, DMF will call a callback function that allows the Client of the Module to create the required Transport Module. DMF will then add that additional Child Module to the list of Child Modules.

Finally, when the Parent Module needs to call the Transport Module, it does so using the Transport Module's Transport Method. This Method has the same signature for all Transport Modules which allows the C compiler to compile correctly.

Using Modules

Once a Module is instantiated, there are three ways the Client uses the Module.

The Module operates on its own by directly receiving WDF callbacks via DMF.
The Module operates on its own by directly receiving DMF callbacks sent by DMF.
The Client calls Module Methods. These Methods are specific to the Module and perform work that only that Module understands.

Note that the options above are not mutually exclusive. Modules can expose any combination of DMF and WDF callbacks as well as Module Methods.

The Client need not be concerned about items 1 and 2 above. Those two paths are the responsibility of the Module author. The Module author does not need to be concerned with what the Client or any other Module does. All actors are only concerned with and responsible for their own code, and there exists a strong boundary between Modules and Client code. Simply instantiating the Module allows paths 1 and 2 to happen automatically and independently without further interaction from the Client.

The Client Driver interacts with a Module via the Module's Methods (if any) and Client Callbacks (if any). If the Module has no Methods or Client Callbacks, then the Client Driver does not, and cannot, interact with the Module directly.

When a Client wants to know what Module Methods the Module exposes, the Client simply refers to the Module's .h file, which has the publicly available Methods listed. Each Module also has a corresponding .md file that explains all the Methods the Module exposes.

All Module Methods require that the Module's handle be sent as the first parameter. The Client receives this handle when the Module is instantiated. It is up to the Client to store this handle for later use.

Here is an example of a Module Method:

NTSTATUS
DMF_RingBuffer_Write(
    _In_ DMFMODULE DmfModule,
    _In_reads_(SourceBufferSize) UCHAR* SourceBuffer,
    _In_ ULONG SourceBufferSize
    );

This Method receives the instantiated DMFMODULE for a Module that exposes a FIFO. It also accepts an address of a buffer and the length of that buffer. This Method reads the next entry in the Module's FIFO and returns it to the caller.

Here is an example of a how a Client uses a Method:

ntStatus = DMF_RingBuffer_Write(deviceContext->DmfModuleButtonFifo,
                                ( PUCHAR )&buttonData,
                                sizeof( buttonData ));

The first parameter is the Module's handle. This handle is obtained when the Module is instantiated. The rest of the parameters are specific to that Module's Method. Methods can have any number of parameters.

It is not possible to use a Module's Method without a valid handle to an instance of the Module. This guarantees that when the Module's Method is called, the Module's internal data structures are ready to be used. It is the responsibility of the Module's author to make sure that as long as a valid DMFMODULE is passed, the Method must operate gracefully.

Note the separation of work between Modules and Clients. This separation limits the number of code paths and eliminates dependencies that may be difficult to see or understand. In turn, it makes code easier to write, understand, maintain, and reuse.

WPP Tracing Module Traces From A Client Driver

DMF Modules emit WPP trace statements using WPP logging. The Client driver can cause those statements to emit along with the Client driver's own tracing. To do so, the Client driver must define a WPP_CONTROL_GUID and WPP Control Bit in addition to the WPP_CONTROL_GUID and WPP Control Bits defined by the Client driver.

Specifically, the Client driver must define the above in this manner:

// NOTE: Each Client must create a unique GUID. Do not use the GUID in this sample.
//
WPP_DEFINE_CONTROL_GUID( \
    DmfLibraryTraceGuid, (74DC7AB3,690B,480A,87A4,3627882A831C), \
    WPP_DEFINE_BIT(DMF_TRACE) \
)

For example, here is how a Client driver defines the above GUID along with the Client driver's GUIDs.

// Define the tracing flags.
//
// Tracing GUID - {1AE05C6D-9140-41DC-BFBD-C8C4391FD95F}
//
#define WPP_CONTROL_GUIDS \
WPP_DEFINE_CONTROL_GUID( \
    DmfLibraryTraceGuid, (74DC7AB3,690B,480A,87A4,3627882A831C), \
    WPP_DEFINE_BIT(DMF_TRACE) \
) \
WPP_DEFINE_CONTROL_GUID( \
    DmfSampleDriverTraceGuid, {1AE05C6D,9140,41DC,BFBD,C8C4391FD95F} \
    WPP_DEFINE_BIT(MYDRIVER_ALL_INFO) \
    WPP_DEFINE_BIT(TRACE_DRIVER) \
    WPP_DEFINE_BIT(TRACE_DEVICE) \
    WPP_DEFINE_BIT(TRACE_QUEUE) \
    WPP_DEFINE_BIT(TRACE_USP) \
)

// This comment block is scanned by the trace preprocessor to define our
// Trace function.
//
// USEPREFIX and USESUFFIX strip all trailing whitespace, so we need to surround
// FuncExit messages with brackets
//
// begin_wpp config
// FUNC Trace{FLAG=MYDRIVER_ALL_INFO}(LEVEL, MSG, \...);
// FUNC TraceEvents(LEVEL, FLAGS, MSG, \...);
// FUNC FuncEntry{LEVEL=TRACE_LEVEL_VERBOSE}(FLAGS);
// FUNC FuncEntryArguments{LEVEL=TRACE_LEVEL_VERBOSE}(FLAGS, MSG, \...);
// FUNC FuncExit{LEVEL=TRACE_LEVEL_VERBOSE}(FLAGS, MSG, \...);
// FUNC FuncExitVoid{LEVEL=TRACE_LEVEL_VERBOSE}(FLAGS);
// FUNC TraceError{LEVEL=TRACE_LEVEL_ERROR}(FLAGS, MSG, \...);
// FUNC TraceInformation{LEVEL=TRACE_LEVEL_INFORMATION}(FLAGS, MSG, \...);
// FUNC TraceVerbose{LEVEL=TRACE_LEVEL_VERBOSE}(FLAGS, MSG, \...);
// FUNC FuncExitNoReturn{LEVEL=TRACE_LEVEL_VERBOSE}(FLAGS);
// USEPREFIX(FuncEntry, "%!STDPREFIX! [%!FUNC!] --> Entry");
// USEPREFIX(FuncEntryArguments, "%!STDPREFIX! [%!FUNC!] --> Entry <");
// USEPREFIX(FuncExit, "%!STDPREFIX! [%!FUNC!] <-- Exit <");
// USESUFFIX(FuncExit, ">");
// USEPREFIX(FuncExitVoid, "%!STDPREFIX! [%!FUNC!] <-- Exit");
// USEPREFIX(TraceError, "%!STDPREFIX! [%!FUNC!] ERROR:");
// USEPREFIX(TraceEvents, "%!STDPREFIX! [%!FUNC!] ");
// USEPREFIX(TraceInformation, "%!STDPREFIX! [%!FUNC!] ");
// USEPREFIX(TraceVerbose, "%!STDPREFIX! [%!FUNC!] ");
// USEPREFIX(FuncExitNoReturn, "%!STDPREFIX! [%!FUNC!] <--");
// end_wpp

Important

Make sure the project file enables WPP tracing using these entries:

<WppKernelMode>true</WppKernelMode>
<WppTraceFunction>TraceEvents(LEVEL,FLAGS,MSG,...)</WppTraceFunction>
<WppGenerateUsingTemplateFile>{km-WdfDefault.tpl}*.tmh</WppGenerateUsingTemplateFile>

(See the sample projects.)

Filtering WPP Tracing

Due to the fact that much of WPP functionality is determined at compile time, it is not possible to easily add fine control of WPP tracing of code inside DMF Modules using WPP Control Bits. Thus, the single bit, DMF_TRACE, emits all DMF related tracing.

It is possible to turn on/off DMF tracing by enabling/disabling the DMF tracing GUID in TraceView.exe. It is also possible to filter tracing by filtering on the many available fields available for each trace.

In Flight Recording (IFR) Of Trace Messages From Modules

DMF enables In Flight Recording (IFR) of trace messages by default. This ensures that trace messages from all DMF Modules are continuously recorded in the default trace buffer associated with the client driver with minimal setup.

However, it is possible for trace messages from one Module to overwrite trace messages from another Module. In these cases, it is useful to use the custom IFR feature, provided by WDF for Kernel-mode drivers to create separate trace buffers for each Module. This can be easily done in DMF by setting a non-zero value for the InFlightRecorderSize field in the Module's descriptor while creating the Module.

For example:

// Module must provide a non-zero size for its custom IFR buffer before
calling DMF_ModuleCreate.
//
DmfModuleDescriptor_BufferPool.InFlightRecorderSize = DMF_IN_FLIGHT_RECORDER_SIZE_DEFAULT;

Once this value is set, DMF creates a custom buffer of the specified size when the Module is created and stores its handle in the DMF_OBJECT structure. DMF also takes care of deleting this buffer when the Module is destroyed. The Module can obtain a handle to the custom buffer by calling the DMF_InFlightRecorderGet function. Once the Module has a handle to the buffer, it can pass this handle to the LogEvents function (instead of TraceEvents) to trace messages that will be recorded as part of the custom log buffer.

// Example of tracing with the IFR Log handle.
//
RECORDER_LOG inFlightRecorder = DMF_InFlightRecorderGet(DmfModule);

LogEvents(inFlightRecorder, TRACE_LEVEL_VERBOSE, DMF_TRACE, "This trace messages will be logged in the Module's IFR buffer");

For more information on IFR feature provided by WDF, please refer to:

https://docs.microsoft.com/en-us/windows-hardware/drivers/devtest/using-wpp-recorder

https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/using-wpp-software-tracing-in-kmdf-and-umdf-2-drivers

The Structure of a Module

The structure of a Module is consistent among all Modules. This consistency is important because Modules are designed to be easily shared and read by many people.

Every Module has three mandatory files:

Module's .c file
Module's .h file
Module's .md file

In addition, Modules may have one optional file:

Module's _Public.h file

The Module .h File

This file contains information that allows Clients to use the Module. Specifically, it contains the following in this order:

Enumerations and structures used in the Module Config.
The Module Config.
The Module macros' definitions.
Prototypes of the Module's Methods.

Private definitions used only by the Module are not placed in this file. Definitions necessary for user-mode interaction (such as IOCTLs and their corresponding data structures) are not placed in this file.

In the following example, note the use of the DECLARE_DMF_MODULE macro. This macro automatically defines all the public functions that Clients use to instantiate the Module.

/*++

Copyright (c) Microsoft Corporation. All rights reserved.

Licensed under the MIT license.

Module Name:

    Dmf_ResourceHub.h

Abstract:

    Companion file to Dmf_ResourceHub.c.

Environment:

    Kernel-mode Driver Framework
    User-mode Driver Framework

--*/

#pragma once

#if !defined(DMF_USER_MODE)

// Client Driver callback to get TransferList from Spb.
//
typedef
_Function_class_(EVT_DMF_ResourceHub_DispatchTransferList)
_IRQL_requires_max_(DISPATCH_LEVEL)
_IRQL_requires_same_
NTSTATUS
EVT_DMF_ResourceHub_DispatchTransferList(_In_ DMFMODULE DmfModule,
                                         _In_ SPB_TRANSFER_LIST* SpbTransferListBuffer,
                                         _In_ size_t SpbTransferListBufferSize,
                                         _In_ USHORT I2CSecondaryDeviceAddress,
                                         _Out_ size_t *TotalTransferLength);

typedef enum
{
    Reserved = 0,
    I2C,
    SPI,
    UART
} DIRECTFW_SERIAL_BUS_TYPE;

// Client uses this structure to configure the Module specific parameters.
//
typedef struct
{
    // TODO: Currently only I2C is supported.
    //
    DIRECTFW_SERIAL_BUS_TYPE TargetBusType;

    // Callback to get TransferList from Spb.
    //
    EVT_DMF_ResourceHub_DispatchTransferList* EvtResourceHubDispatchTransferList;
} DMF_CONFIG_ResourceHub;

// This macro declares the following functions:
// DMF_ResourceHub_ATTRIBUTES_INIT()
// DMF_CONFIG_ResourceHub_AND_ATTRIBUTES_INIT()
// DMF_ResourceHub_Create()
//
DECLARE_DMF_MODULE(ResourceHub)

// Module Methods
//
#endif // !defined(DMF_USER_MODE)

// eof: Dmf_ResourceHub.h
//

The Module .c File

Every Module has all its code in a single .c or .cpp file. This file also contains all the private code and data structures the Module uses.

Each Module consists of these sections in this order: (Note: Even if the Module has no code in a section, always include the section headers.)

File Header
DMF Include
WPP Definitions
Module Private Enumerations and Structures
Module Context
Module Macros
Module Private Code
Module WDF Callbacks
Module DMF Callbacks
Module Descriptors
Public Calls by Client (Includes Module Create Function)
- Module Create Function (more in section 3.6)
- Module Methods

Section 1: File Header

The file header section contains the copyright notice, the file name, a short description of the purpose of the Module and the environment it is designed to work in.

/*++

Copyright (c) Microsoft Corporation. All rights reserved.

Licensed under the MIT license.

Module Name:

    Dmf_ResourceHub.c

Abstract:

    Resource Hub support code.

Environment:

    Kernel-mode Driver Framework
    User-mode Driver Framework

--*/

Section 2: DMF Include

Every Module always includes the include file for the Library in which the Module is located. This include file always includes the DMF core include files as well as the Library include file for the Library it depends on. Since every Library is a superset of all the Libraries it depends on, Clients need only include the name of a single Library:

// DMF and this Module's Library specific definitions.
//
#include "DmfModules.Library.h"
#include "DmfModules.Library.Trace.h"

Section 3: WPP Definitions

A corresponding include file that contains definitions needed for WPP tracing must also be included. Finally, the corresponding .tmh file for the .c/.cpp file must be included:

#include "Dmf_[ModuleName].tmh"

Section 4: Module Private Enumerations and Structures

If the Module's private code uses enumerations and data structures, they are placed here. These are not accessible outside of this Module. Non-DMF-specific include files that contain definitions needed by the Module are also included here:

/////////////////////////////////////////////////////////////////////////////////////////////////
// Module Private Enumerations and Structures
/////////////////////////////////////////////////////////////////////////////////////////////////
//

#define RESHUB_USE_HELPER_ROUTINES
#include "reshub.h"
#include <Spb.h>

typedef struct _RESOURCEHUB_FILEOBJECT_CONTEXT
{
    USHORT SecondaryDeviceAddress;
    WDFMEMORY ConnectionProperties;
} RESOURCEHUB_FILEOBJECT_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(RESOURCEHUB_FILEOBJECT_CONTEXT,
                                   ResourceHub_FileContextGet);

Section 5: Module Context

The Module's Context is similar to a driver's device context. This data structure contains all the information needed while the Module is running. For example, it may contain handles to Child Modules or timers or other WDF primitives as well as flags and buffers. This structure is only visible to this file. Place the definition of the Module's Context in this section. It may use enumerations and structures defined above.

/////////////////////////////////////////////////////////////////////////////////////////////////
// Module Private Context
/////////////////////////////////////////////////////////////////////////////////////////////////
//

// Contains the WDF IO Target as well as all the structures needed for
// streaming requests.
//
typedef struct
{
    WDFIOTARGET ResourceHubTarget;
} DMF_CONTEXT_ResourceHub;

Section 6: Module Macros

This section contains definitions that standardize the way Modules access the Private Context and Config. Each Module always has exactly two macros that automatically define macros that allow the Module to access its Context and its Config. The macros are always used even if there is no Context and/or Config because the macros also define other functions that are used internally by DMF.

[Note: Always use these macros in the Module's .c file, not the Module's .h file, to ensure they are private to the Module. Clients should never have access to functions defined by these macros.]

DMF_MODULE_DECLARE_CONTEXT

This macro indicates that the Module has a Context (defined just above this macro). It automatically defines a function called DMF_CONTEXT_GET() that allows Modules to access their Context given a DMFMODULE:

// This macro declares the following function:
// DMF_CONTEXT_GET()
//
DMF_MODULE_DECLARE_CONTEXT(ResourceHub)

DMF_MODULE_DECLARE_CONFIG

This macro indicates that the Module has a Config (defined in the Module's .h file). It automatically defines a function called DMF_CONFIG_GET() that allows Modules to access their Config given a DMFMODULE:

// This macro declares the following function:
// DMF_CONFIG_GET()
//
DMF_MODULE_DECLARE_CONFIG(ResourceHub)

DMF_MODULE_DECLARE_NO_CONTEXT

This macro indicates that the Module has no Context. Use this macro to make the Module standard and for possible additional features in the future. This macro also defines other definitions used internally by DMF.

// This Module has no Context.
//
DMF_MODULE_DECLARE_NO_CONTEXT(PdoCreate)

DMF_MODULE_DECLARE_NO_CONFIG

This macro indicates that the Module has no Config. Use this macro to make the Module standard and for possible additional features in the future.

// This Module has no Config.
//
DMF_MODULE_DECLARE_NO_CONFIG(Registry)

Section 7: Module Private Code

This section contains functions that are called by the Module's callbacks and Methods. This code contains the Module's functionality and is very specific to this Module. Note there may be zero, one or more than one function in this section.

This code is only ever called by Module's callbacks or Module Methods. DMF and Clients never call this code.

///////////////////////////////////////////////////////////////////////////////////////////////////////
// DMF Module Support Code
///////////////////////////////////////////////////////////////////////////////////////////////////////
//
#define INTERNAL_SERIAL_BUS_SIZE(Desc) ((ULONG)(Desc)->Length + \
                                         RTL_SIZEOF_THROUGH_FIELD(PNP_SERIAL_BUS_DESCRIPTOR, Length))

#include "pshpack1.h"
typedef struct _DIRECTFW_I2C_CONNECTION_DESCRIPTOR_SUBTYPE
{
    UINT32 ConnectionSpeed;
    USHORT SecondaryDeviceAddress;
    UCHAR VendorDefinedData[ANYSIZE_ARRAY];
} DIRECTFW_I2C_CONNECTION_DESCRIPTOR_SUBTYPE;

#include "poppack.h"
#pragma code_seg("PAGE")
NTSTATUS
ResourceHub_ConnectResourceHubIoTarget(
    _Inout_ DMFMODULE DmfModule,
    _In_opt_ PLARGE_INTEGER Id,
    _Out_ WDFIOTARGET * RootHubIoTarget
    )
/*++

Routine Description:

    Opens an I/O target to the Resource Hub.
    If Id is left NULL, the target is opened to the Resource Hub directly,
    and can then be used to query for connection properties.
    If Id is specified, the target is opened to the RH with this Id as the
    filename. Internally the RH redirects the I/O target such that requests made
    against the target are sent to the device represented by that Id.

Arguments:

    DmfModule - This Module's handle.
    Id - Connection ID received as part of FileCreate callback or PrepareHardware resources.
    RootHubIoTarget - Opened I/O target to the Resource Hub, using a filename constructed from the value Id.

Return Value:

    NTSTATUS

--*/
{
    NTSTATUS ntStatus;
    WDF_OBJECT_ATTRIBUTES attributes;
    DECLARE_UNICODE_STRING_SIZE(resourceHubFileName,
                                RESOURCE_HUB_PATH_SIZE);
    WDF_IO_TARGET_OPEN_PARAMS openParameters;

    PAGED_CODE();

    DmfAssert(DmfModule != NULL);
    DmfAssert(RootHubIoTarget != NULL);

    // Create an IO target to the controller driver via the resource hub.
    //
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    attributes.ParentObject = DmfModule;

    ntStatus = WdfIoTargetCreate(DMF_AttachedDeviceGet(DmfModule),
                                 &attributes,
                                 RootHubIoTarget);
    if (! NT_SUCCESS(ntStatus))
    {
        TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                    "WdfIoTargetCreate fails: ntStatus=%!STATUS!", ntStatus);
        *RootHubIoTarget = NULL;
        goto Exit;
    }
    // Create controller driver string from descriptor information.
    //
    if (Id != NULL)
    {
        RESOURCE_HUB_CREATE_PATH_FROM_ID(&resourceHubFileName,
                                         Id->LowPart,
                                         Id->HighPart);
    }
    else
    {
        RtlInitUnicodeString(&resourceHubFileName,
                             RESOURCE_HUB_DEVICE_NAME);
    }

    WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(&openParameters,
                                                &resourceHubFileName,
                                                STANDARD_RIGHTS_ALL);

    // Open the controller driver / Resource Hub I/O target.
    //
    ntStatus = WdfIoTargetOpen(*RootHubIoTarget,
                               &openParameters);

    if (! NT_SUCCESS(ntStatus))
    {
        TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                    "WdfIoTargetOpen fails: ntStatus=%!STATUS!", ntStatus);
        goto Exit;
    }

Exit:

    if (! NT_SUCCESS(ntStatus) &&
        (*RootHubIoTarget != NULL))
    {
        WdfObjectDelete(*RootHubIoTarget);
        *RootHubIoTarget = NULL;
    }

    FuncExit(DMF_TRACE_ResourceHub, "ntStatus=%!STATUS!", ntStatus);
    return ntStatus;
}
#pragma code_seg()

NOTE: See Dmf_ResourceHub.c to see the rest of the code in this section.

Section 8: Module WDF Callbacks

This section contains definitions of all the WDF callbacks that the Module supports. Only callbacks that the Module supports are listed. Unsupported callbacks use DMF's generic version of those callbacks which in most (but not all) cases, simply perform validation in DEBUG build.

(Callbacks in italics indicate callbacks that are almost never used because DMF contains special support which generally eliminates the need for these specific callbacks.) See the table below for more information about the callbacks in italics.

This is the list of WDF callbacks that DMF supports:

DMF_[ModuleName]_PrepareHardware
DMF_[ModuleName]_ReleaseHardware
DMF_[ModuleName]_D0Entry
DMF_[ModuleName]_D0EntryPostInterruptsEnabled
DMF_[ModuleName]_D0ExitPreInterruptsDisabled
DMF_[ModuleName]_D0Exit
DMF_[ModuleName]_DeviceIoControl
DMF_[ModuleName]_InternalDeviceIoControl
DMF_[ModuleName]_SelfManagedIoCleanup
DMF_[ModuleName]_SelfManagedIoFlush
DMF_[ModuleName]_SelfManagedIoInit
DMF_[ModuleName]_SelfManagedIoSuspend
DMF_[ModuleName]_SelfManagedIoRestart
DMF_[ModuleName]_SurpriseRemoval
DMF_[ModuleName]_QueryRemove
DMF_[ModuleName]_QueryStop
DMF_[ModuleName]_RelationsQuery
DMF_[ModuleName]_UsageNotificationEx
DMF_[ModuleName]_ArmWakeFromS0
DMF_[ModuleName]_WakeFromS0Triggered
DMF_[ModuleName]_ArmWakeFromSxWithReason
DMF_[ModuleName]_DisarmWakeFromSx
DMF_[ModuleName]_WakeFromSxTriggered
DMF_[ModuleName]_FileCreate
DMF_[ModuleName]_FileCleanup
DMF_[ModuleName]_FileClose
DMF_[ModuleName]_QueueIoRead
DMF_[ModuleName]_QueueIoWrite

Rarely Used Callbacks

This section contains notes about the entries in the above table that are in italics.

Module	Notes
DMF_[ModuleName]_PrepareHardware and DMF_[ModuleName]_ReleaseHardware	Modules should generally not support DMF_[ModuleName]_PrepareHardware and DMF_[ModuleName]_ReleaseHardware. Instead, set the Module Open Option to indicate when the Modules' DMF_[ModuleName]_Open and DMF_[ModuleName]_Close callbacks are be called. Also, Modules that need resources define DMF_[ModuleName]_ResourcesAssign. For more information about why DMF_[ModuleName]_PrepareHardware and DMF_[ModuleName]_ReleaseHardware are rarely used, please see 7.3.1 and 7.3.2. Also, please see section 7.1.1 which describes Module Open Options.
DMF_[ModuleName]_DeviceIoControl and DMF_[ModuleName]_InternalDeviceIoControl	Instead of using these callbacks, it is much easier to use DMF_IoctlHandler. This Module is designed to easily manage the routing of IOCTLs between the different Modules and Client driver code. Also, this Module will perform validation and access control based on table of supported IOCTLs. For more information please see DMF_IoctlHandler.md. Also, please see 7.3.7 and 7.3.8.

Module

Notes

DMF_[ModuleName]_PrepareHardware and DMF_[ModuleName]_ReleaseHardware

Modules should generally not support DMF_[ModuleName]_PrepareHardware and DMF_[ModuleName]_ReleaseHardware. Instead, set the Module Open Option to indicate when the Modules' DMF_[ModuleName]_Open and DMF_[ModuleName]_Close callbacks are be called. Also, Modules that need resources define DMF_[ModuleName]_ResourcesAssign. For more information about why DMF_[ModuleName]_PrepareHardware and DMF_[ModuleName]_ReleaseHardware are rarely used, please see 7.3.1 and 7.3.2. Also, please see section 7.1.1 which describes Module Open Options.

DMF_[ModuleName]_DeviceIoControl and DMF_[ModuleName]_InternalDeviceIoControl

Instead of using these callbacks, it is much easier to use DMF_IoctlHandler. This Module is designed to easily manage the routing of IOCTLs between the different Modules and Client driver code. Also, this Module will perform validation and access control based on table of supported IOCTLs. For more information please see DMF_IoctlHandler.md. Also, please see 7.3.7 and 7.3.8.

///////////////////////////////////////////////////////////////////////////////////////////////////////
// Wdf Module Callbacks
///////////////////////////////////////////////////////////////////////////////////////////////////////
//

#pragma code_seg("PAGE")
_IRQL_requires_max_(PASSIVE_LEVEL)
static
BOOLEAN
DMF_ResourceHub_ModuleFileCreate(
    _In_ DMFMODULE DmfModule,
    _In_ WDFDEVICE Device,
    _In_ WDFREQUEST Request,
    _In_ WDFFILEOBJECT FileObject
    )
/*++

Routine Description:

    File Create callback. Use this callback to open a connection to ACPI.

Arguments:

    DmfModule - The given DMF Module.
    Device - WDF device object.
    Request - WDF Request with IOCTL parameters.
    FileObject - WDF file object that describes a file that is being opened for the specified request.

Return Value:

    TRUE if this Module handled the callback; false, otherwise.

--*/
{
    BOOLEAN handled;
    DMF_CONTEXT_ResourceHub* moduleContext;
    PUNICODE_STRING fileName;
    UNICODE_STRING filePart;
    LARGE_INTEGER id;
    NTSTATUS ntStatus;
    WDFMEMORY connectionProperties;
    VOID* connectionPropertiesBuffer;
    size_t connectionPropertiesLength;
    DIRECTFW_SERIAL_BUS_TYPE serialBusType;
    VOID* typeSpecificData;
    ULONG typeSpecificDataLength;
    USHORT secondaryDeviceAddress;
    size_t filenameLength;
    WDF_OBJECT_ATTRIBUTES attributes;
    RESOURCEHUB_FILEOBJECT_CONTEXT* fileContext;

    PAGED_CODE();

    UNREFERENCED_PARAMETER(Device);

    FuncEntry(DMF_TRACE_ResourceHub);

    DmfAssert(Device == DMF_AttachedDeviceGet(DmfModule));
    DmfAssert(Request != NULL);
    DmfAssert(FileObject != NULL);

    moduleContext = DMF_CONTEXT_GET(DmfModule);

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes,
                                            RESOURCEHUB_FILEOBJECT_CONTEXT);

    ntStatus = WdfObjectAllocateContext(FileObject,
                                        &attributes,
                                        (VOID**)&fileContext);

    fileContext = ResourceHub_FileContextGet(FileObject);
    handled = FALSE;
    ntStatus = STATUS_SUCCESS;
    connectionProperties = NULL;
    filenameLength = 0;
    fileName = WdfFileObjectGetFileName(FileObject);
    if ((fileName != NULL) &&
        (fileName->Length != 0))
    {
        //If the string is null-terminated, Length does not include the trailing null character.
        //So use MaximumLength field instead.
        //
        RtlInitEmptyUnicodeString(&filePart,
                                  fileName->Buffer,
                                  fileName->MaximumLength);

        // The file-name part received may begin with a leading backslash
        // in the form "\0000000012345678". If the first character is a
        // backslash, skip it.
        //
        filePart.Length = fileName->Length;
        if (filePart.Length >= sizeof(WCHAR) && filePart.Buffer[0] == L'\\')
        {
            ++filePart.Buffer;
            filePart.Length -= sizeof(WCHAR);
            filePart.MaximumLength -= sizeof(WCHAR);
        }

        if (filePart.Length < sizeof(WCHAR))
        {
            TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub, "Invalid fileName parameter");
            ntStatus = STATUS_INVALID_PARAMETER;
            goto Exit;
        }

        filePart.MaximumLength = sizeof(WCHAR);
        ntStatus = RtlStringCchLengthW(filePart.Buffer,
                                       filePart.MaximumLength,
                                       &filenameLength);
        if (! NT_SUCCESS(ntStatus))
        {
            TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub, "Invalid fileName parameter");
            goto Exit;
        }

        // Retrieve ACPI resource descriptor for this connection from Resource Hub.
        //
        RESOURCE_HUB_ID_FROM_FILE_NAME(filePart.Buffer,
                                       &id);

        ntStatus = ResourceHub_QueryConnectionProperties(DmfModule,
                                                         &id,
                                                         FileObject,
                                                         &connectionProperties);
        if (! NT_SUCCESS(ntStatus))
        {
            TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                        "ResourceHub_QueryConnectionProperties fails: ntStatus=%!STATUS!",
                        ntStatus);
            goto Exit;
        }

        // Only I2C GenericSerialBus descriptors are supported. Extract the secondaryDevice address.
        //
        connectionPropertiesBuffer = WdfMemoryGetBuffer(connectionProperties,
                                                        &connectionPropertiesLength);
        if (connectionPropertiesBuffer == NULL)
        {
            ntStatus = STATUS_UNSUCCESSFUL;
            TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub, "No resources	returned from RH query");
            goto Exit;
        }

        ntStatus = ResourceHub_ParseGenericSerialBusDescriptor(DmfModule,
                                                               connectionPropertiesBuffer,
                                                               connectionPropertiesLength,
                                                               &serialBusType,
                                                               &typeSpecificData,
                                                               &typeSpecificDataLength,
                                                               NULL);
        if (! NT_SUCCESS(ntStatus))
        {
            TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                        "ResourceHub_ParseGenericSerialBusDescriptor fails:
                        ntStatus=%!STATUS!", ntStatus);
            goto Exit;
        }

        if (serialBusType != I2C)
        {
            ntStatus = STATUS_UNSUCCESSFUL;
            TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                        "GenericSerialBus descriptor subtype not I2C: 0x%x
                        ntStatus=%!STATUS!", serialBusType, ntStatus);
            goto Exit;
        }

        ntStatus = ResourceHub_ParseI2CSerialBusDescriptorSubtype(DmfModule,
                                                                  typeSpecificData,
                                                                  typeSpecificDataLength,
                                                                  &secondaryDeviceAddress);
        if (! NT_SUCCESS(ntStatus))
        {
            TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                        "ResourceHub_ParseI2CSerialBusDescriptorSubtype fails:
                        ntStatus=%!STATUS!", ntStatus);
            goto Exit;
        }

        // Success.
        //
        TraceEvents(TRACE_LEVEL_INFORMATION, DMF_TRACE_ResourceHub,
                    "secondaryDeviceAddress=0x%X request=0x%p", secondaryDeviceAddress,
                    Request);
        fileContext->SecondaryDeviceAddress = secondaryDeviceAddress;
        WdfRequestComplete(Request,
                           ntStatus);
        handled = TRUE;
    }

Exit:

    if (connectionProperties != NULL)
    {
        WdfObjectDelete(connectionProperties);
    }

    FuncExit(DMF_TRACE_ResourceHub, "ntStatus=%!STATUS!", ntStatus);

    return handled;
}
#pragma code_seg()

NOTE: See Dmf_ResourceHub.c to see the rest of the code in this section.

Section 9: Module DMF Callbacks

This section contains definitions of all the DMF callbacks that the Module supports. See section "Module DMF Callbacks" for the full list.

///////////////////////////////////////////////////////////////////////////////////////////////////////
// DMF Module Callbacks
///////////////////////////////////////////////////////////////////////////////////////////////////////
//

IoctlHandler_IoctlRecord ResourceHub_IoctlSpecification[] =
{
    { IOCTL_SPB_EXECUTE_SEQUENCE, sizeof(SPB_TRANSFER_LIST), 0, ResourceHub_IoctlClientCallback_SpbExecuteSequence }
};

#pragma code_seg("PAGE")
_IRQL_requires_max_(PASSIVE_LEVEL)
VOID
DMF_ResourceHub_ChildModulesAdd(
    _In_ DMFMODULE DmfModule,
    _In_ DMF_MODULE_ATTRIBUTES* DmfParentModuleAttributes,
    _In_ PDMFMODULE_INIT DmfModuleInit
    )
/*++

Routine Description:

    Configure and add the required Child Modules to the given Parent Module.

Arguments:

    DmfModule - The given Parent Module.
    DmfParentModuleAttributes - Pointer to the parent DMF_MODULE_ATTRIBUTES structure.
    DmfModuleInit - Opaque structure to be passed to DMF_DmfModuleAdd.

Return Value:

    None

--*/
{
    DMF_MODULE_ATTRIBUTES moduleAttributes;
    DMF_CONFIG_IoctlHandler ioctlHandlerModuleConfig;

    UNREFERENCED_PARAMETER(DmfParentModuleAttributes);
    UNREFERENCED_PARAMETER(DmfModule);

    PAGED_CODE();

    FuncEntry(DMF_TRACE_ResourceHub);

    // IoctlHandler
    // ------------
    //
    DMF_CONFIG_IoctlHandler_AND_ATTRIBUTES_INIT(&ioctlHandlerModuleConfig,
                                                &moduleAttributes);
    // NOTE: No GUID is necessary because device interface is not created.
    //
    ioctlHandlerModuleConfig.AccessModeFilter = IoctlHandler_AccessModeDefault;
    ioctlHandlerModuleConfig.EvtIoctlHandlerAccessModeFilter = NULL;
    ioctlHandlerModuleConfig.IoctlRecordCount = ARRAYSIZE(ResourceHub_IoctlSpecification);
    ioctlHandlerModuleConfig.IoctlRecords = ResourceHub_IoctlSpecification;
    DMF_DmfModuleAdd(DmfModuleInit,
                     &moduleAttributes,
                     WDF_NO_OBJECT_ATTRIBUTES,
                     NULL);

    FuncExitVoid(DMF_TRACE_ResourceHub);
}
#pragma code_seg()

#pragma code_seg("PAGE")
_IRQL_requires_max_(PASSIVE_LEVEL)
_Must_inspect_result_
static
NTSTATUS
DMF_ResourceHub_Open(
    _In_ DMFMODULE DmfModule
    )
/*++

Routine Description:

    Initialize an instance of a DMF Module of type ResourceHub.

Arguments:

    DmfModule - This Module's handle.

Return Value:

    NTSTATUS

--*/
{
    NTSTATUS ntStatus;
    DMF_CONTEXT_ResourceHub* moduleContext;

    PAGED_CODE();

    FuncEntry(DMF_TRACE_ResourceHub);

    ntStatus = STATUS_SUCCESS;

    moduleContext = DMF_CONTEXT_GET(DmfModule);

    // Create SPB Resource Hub target to receive messages sent by ACPI.
    //
    ntStatus = ResourceHub_RegisterForAcpiNotifications(DmfModule);
    if (! NT_SUCCESS(ntStatus))
    {
    TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                "ResourceHub_RegisterForAcpiNotifications fails: ntStatus=%!STATUS!",
                ntStatus);
    }

    FuncExit(DMF_TRACE_ResourceHub, "ntStatus=%!STATUS!", ntStatus);

    return ntStatus;
}
#pragma code_seg()

#pragma code_seg("PAGE")
_IRQL_requires_max_(PASSIVE_LEVEL)
static
VOID
DMF_ResourceHub_Close(
    _In_ DMFMODULE DmfModule
    )
/*++

Routine Description:

    Uninitialize an instance of a DMF Module of type ResourceHub.

Arguments:

    DmfModule - This Module's handle.

Return Value:

    NTSTATUS

--*/
{
    DMF_CONTEXT_ResourceHub* moduleContext;

    PAGED_CODE();

    FuncEntry(DMF_TRACE_ResourceHub);

    moduleContext = DMF_CONTEXT_GET(DmfModule);

    FuncExitVoid(DMF_TRACE_ResourceHub);
}
#pragma code_seg()

Section 10: Public Calls by Client (Includes Module Create Function)

This section contains all the code that is callable by Clients:

Module Create Function (see the section "The Module's Create Function").
Module Methods.

The prototype for the Create function is in the Module's .h file and is generated by a DMF macro. The prototypes for the Module Methods are also in the Module's .h file.

///////////////////////////////////////////////////////////////////////////////////////////////////////
// Public Calls by Client
///////////////////////////////////////////////////////////////////////////////////////////////////////
//

#pragma code_seg("PAGE")
_IRQL_requires_max_(PASSIVE_LEVEL)
_Must_inspect_result_
NTSTATUS
DMF_ResourceHub_Create(
    _In_ WDFDEVICE Device,
    _In_ DMF_MODULE_ATTRIBUTES* DmfModuleAttributes,
    _In_ WDF_OBJECT_ATTRIBUTES* ObjectAttributes,
    _Out_ DMFMODULE* DmfModule
    )
/*++

Routine Description:

    Create an instance of a DMF Module of type ResourceHub.

Arguments:

    Device - Client driver's WDFDEVICE object.
    DmfModuleAttributes - Opaque structure that contains parameters DMF needs to initialize the Module.
    ObjectAttributes - WDF object attributes for DMFMODULE.
    DmfModule - Address of the location where the created DMFMODULE handle is returned.

Return Value:

    NTSTATUS

--*/
{
    NTSTATUS ntStatus;
    DMF_MODULE_DESCRIPTOR dmfModuleDescriptor_ResourceHub;
    DMF_CALLBACKS_DMF dmfCallbacksDmf_ResourceHub;
    DMF_CALLBACKS_WDF dmfCallbacksWdf_ResourceHub;

    PAGED_CODE();

    FuncEntry(DMF_TRACE_ResourceHub);

    DMF_CALLBACKS_DMF_INIT(&dmfCallbacksDmf_ResourceHub);

    dmfCallbacksDmf_ResourceHub.DeviceOpen = DMF_ResourceHub_Open;
    dmfCallbacksDmf_ResourceHub.DeviceClose = DMF_ResourceHub_Close;
    dmfCallbacksDmf_ResourceHub.ChildModulesAdd = DMF_ResourceHub_ChildModulesAdd;

    DMF_CALLBACKS_WDF_INIT(&dmfCallbacksWdf_ResourceHub);

    dmfCallbacksWdf_ResourceHub.ModuleFileCreate = DMF_ResourceHub_ModuleFileCreate;

    DMF_MODULE_DESCRIPTOR_INIT_CONTEXT_TYPE(dmfModuleDescriptor_ResourceHub,
                                            ResourceHub,
                                            DMF_CONTEXT_ResourceHub,
                                            DMF_MODULE_OPTIONS_DISPATCH,
                                            DMF_MODULE_OPEN_OPTION_OPEN_PrepareHardware);

    dmfModuleDescriptor_ResourceHub.CallbacksDmf = &dmfCallbacksDmf_ResourceHub;
    dmfModuleDescriptor_ResourceHub.CallbacksWdf = &dmfCallbacksWdf_ResourceHub;

    ntStatus = DMF_ModuleCreate(Device,
                                DmfModuleAttributes,
                                ObjectAttributes,
                                &dmfModuleDescriptor_ResourceHub,
                                DmfModule);
    if (! NT_SUCCESS(ntStatus))
    {
        TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                    "DMF_ModuleCreate fails: ntStatus=%!STATUS!", ntStatus);
    }

    FuncExit(DMF_TRACE_ResourceHub, "ntStatus=%!STATUS!", ntStatus);

    return(ntStatus);
}
#pragma code_seg()

// Module Methods

//

// NOTE: This example does not list any Module Methods.

//

// eof: Dmf_ResourceHub.c

//

The Module _Public.h File

This file contains only definitions necessary for user-mode programs or other kernel-mode drivers to interact with the Module. Specifically, this file contains the IOCTL definitions and any enumerations and structures that are transferred to/from the Module.

Usually this file has:

The device interface GUID or the symbolic link name that the Module exposes.
The IOCTL definitions for the IOCTLs that the Module supports.
Enumerations and data structures transferred to/from the Module via IOCTLs.

This file must not contain any DMF-specific references because this file may be used in environments where DMF is not available. For example, a user-mode application may include this file and try to compile it using only the Windows SDK.

If a Module does not expose a device interface or a symbolic link, then this file is not necessary.

The Module .md File

This file contains the documentation for the Module. Like the Module code, this file has a specific format so that all Modules are documented in a consistent manner.

Example: Link a Module md file. [TODO]

The Module's Create Function

Every Module has a Create function. This is the function that initializes the structures that are necessary for a Module to be instantiated. Every Module Create function contains code specific to the Module.

The Module's Create function optionally performs another important task: It instantiates the Module's Child Modules (if any).

When a Module is created in a Client Driver via the DmfModulesAdd callback, the Module's Create function is called by DMF after DmfModulesAdd returns control to DMF.

Module Create functions are usually called by DMF, either when the Collection of Modules is created or when Child Modules are created. In some cases, it is possible for a Client, either a Module or Client driver, to call a Module's Create function directly. In this case, the Module is referred to as a Dynamic Module.

See DMF_[ModuleName]_Create for more information about the Module's Create function. This function is always the first function in the section named, "Public Calls by Client".

Contents of a Module's Create Function

These are the steps a Module's Create function should perform:

Define the Module's DMF callbacks. This step is optional if the Module does not support DMF callbacks. If the Module has Child Modules, it is in this structure where the callback that adds Child Modules is set.
Define the Module's WDF callbacks. This step is optional if the Module does not support WDF callbacks.
Define the Module's descriptor. This step is mandatory for all Modules. This descriptor also holds the DMF and WDF callback structures that are defined in the above steps.
Define the Module's Context. This step is mandatory for all Modules even if the Module does not define a Context. Use DMF_WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE if the Module has a Context. Use DMF_WDF_OBJECT_ATTRIBUTES_INIT if the Module does not have a Context.
Call the DMF API that creates an instance of the Module using all the definitions in the above steps.

The Module's Create function should not talk to hardware. Generally speaking, it should only perform the above steps. Allocation of Module-specific resources such as memory and timers should be done in the Module's DMF_[ModuleName]_Open callback.

Annotated Module Create function

Here is an example of a Module's Create function that shows the above steps. All Modules follow this pattern omitting steps as needed.

Note that this is an example of a Module that creates Child Modules. The callback function that adds the Child Modules (DMF_ResourceHub_ChildModulesAdd) is annotated afterward.

#pragma code_seg("PAGE")
_IRQL_requires_max_(PASSIVE_LEVEL)
_Must_inspect_result_
NTSTATUS
DMF_ResourceHub_Create(
    _In_ WDFDEVICE Device,
    _In_ DMF_MODULE_ATTRIBUTES* DmfModuleAttributes,
    _In_ WDF_OBJECT_ATTRIBUTES* ObjectAttributes,
    _Out_ DMFMODULE* DmfModule
    )
/*++

Routine Description:

    Create an instance of a DMF Module of type ResourceHub.

Arguments:

    Device - Client driver's WDFDEVICE object.
    DmfModuleAttributes - Opaque structure that contains parameters DMF needs to initialize the Module.
    ObjectAttributes - WDF object attributes for DMFMODULE.
    DmfModule - Address of the location where the created DMFMODULE handle is returned.

Return Value:

    NTSTATUS

--*/
{
    NTSTATUS ntStatus;

    PAGED_CODE();

    FuncEntry(DMF_TRACE_ResourceHub);

    // Step 1: Define Module's DMF callbacks.
    //

    DMF_CALLBACKS_DMF_INIT(&dmfCallbacksDmf_ResourceHub);
    dmfCallbacksDmf_ResourceHub.DeviceOpen = DMF_ResourceHub_Open;
    dmfCallbacksDmf_ResourceHub.DeviceClose = DMF_ResourceHub_Close;
    dmfCallbacksDmf_ResourceHub.ChildModulesAdd = DMF_ResourceHub_ChildModulesAdd;

    // Step 2: Define Module's WDF callbacks.
    //
    DMF_CALLBACKS_WDF_INIT(&dmfCallbacksWdf_ResourceHub);
    dmfCallbacksWdf_ResourceHub.ModuleFileCreate = DMF_ResourceHub_ModuleFileCreate;

    // Steps 3 and 4: Define Module's Descriptor.
    //
    DMF_MODULE_DESCRIPTOR_INIT_CONTEXT_TYPE(dmfModuleDescriptor_ResourceHub,
                                            ResourceHub,
                                            DMF_CONTEXT_ResourceHub,
                                            DMF_MODULE_OPTIONS_DISPATCH,
                                            DMF_MODULE_OPEN_OPTION_OPEN_PrepareHardware);
    dmfModuleDescriptor_ResourceHub.CallbacksDmf = &dmfCallbacksDmf_ResourceHub;
    dmfModuleDescriptor_ResourceHub.CallbacksWdf = &dmfCallbacksWdf_ResourceHub;

    // Step 5: Tell DMF to create the Module.
    //
    ntStatus = DMF_ModuleCreate(Device,
                                DmfModuleAttributes,
                                ObjectAttributes,
                                &dmfModuleDescriptor_ResourceHub,
                                DmfModule);
    if (! NT_SUCCESS(ntStatus))
    {
        TraceEvents(TRACE_LEVEL_ERROR, DMF_TRACE_ResourceHub,
                    "DMF_ModuleCreate fails: ntStatus=%!STATUS!", ntStatus);
    }

    FuncExit(DMF_TRACE_ResourceHub, "ntStatus=%!STATUS!", ntStatus);

    return(ntStatus);
}
#pragma code_seg()

How to Create One or More Child Modules

Child Modules are optionally created by a Module (the Parent Module) so that the Parent Module can use the Child Module's functionality or even create a superset of the Child Module's functionality. There are numerous examples of Modules that create Child Modules. For example, Dmf_ThreadedBufferQueue has two Child Modules, DMF_Thread and DMF_BufferQueue. DMF_BufferQueue, in turn, has two Child Modules of type DMF_BufferPool.

To review, here are some general notes about Child Modules:

There is no limit to the number of Child Modules a Module can have. Child Modules, in turn, can have any number of Child Modules.
Any Module can instantiate any other Module. Any Module can be instantiated by any other Module. (Of course, in practice there should be a logical and functional reason for doing so.)
Of course, a Module may not instantiate itself as a Child Module.
Child Modules are agnostic about their Parent Modules or whether their Parents are the Client Driver or another Module.
The code needed to add Child Modules is very similar to the code a Client Driver uses to instantiate a Modules.

Contents of a Module's ChildModulesAdd Callback

This callback is very similar to the callback used by Client drivers to instantiate Modules. This callback performs the following steps:

In the Parent Module's DMF_CALLBACKS_DMF structure set the ChildModulesAdd callback.
Define the callback function in the section of the file where DMF callback functions are defined.
DMF will call this callback when it is ready to get the list of Child Modules to add to the Parent.
Inside the callback, declare a DMF_MODULE_ATTRIBUTES structure. Important: Only declare a single instance of this structure. You must reuse this same instance for every Child Module. Keep passing the same instance to the functions in step 5. This structure maintains a list of all the Child Modules added in this callback.
For each Child Module to be added, declare and initialize that Module's corresponding Config structure and the DMF_MODULE_ATTRIBUTES using the Module's corresponding initialization macro. If the Module has no Config structure, initialize the DMF_MODULE_ATTRIBUTES using the Module's corresponding initialization macro.
If necessary, declare and initialize a DMF_MODULE_EVENT_CALLBACKS structure using DMF_MODULE_EVENT_CALLBACKS_INIT(). This allows the Parent Module to know when the Child Module opens and closes.
Finally, call DMF_DmfModuleAdd() using the above structures.
Perform the above steps for every Child Module that is to be added to the Parent Module.
After the callback returns, DMF will create and attach the Child Modules to the Parent Module. DMF will then dispatch callbacks to all the Modules in the tree as needed.

Annotated ChildModulesAdd Callback

This example shows the callback referenced above. This callback function adds a single Child Module to its Parent Module. There are many examples of Modules that have Child Modules in the Library.

#pragma code_seg("PAGE")
_IRQL_requires_max_(PASSIVE_LEVEL)
VOID
DMF_ResourceHub_ChildModulesAdd(
    _In_ DMFMODULE DmfModule,
    _In_ DMF_MODULE_ATTRIBUTES* DmfParentModuleAttributes,
    _In_ PDMFMODULE_INIT DmfModuleInit
    )
/*++

Routine Description:

    Configure and add the required Child Modules to the given Parent Module.

Arguments:

    DmfModule - The given Parent Module.
    DmfParentModuleAttributes - Pointer to the parent DMF_MODULE_ATTRIBUTES structure.
    DmfModuleInit - Opaque structure to be passed to DMF_DmfModuleAdd.

Return Value:

    None

--*/

{
    // Steps 1 to 3 happen in the Module's create function.
    //

    // Step 4: Declare an instance of DMF_MODULE_ATTRIBUTES.
    //
    DMF_MODULE_ATTRIBUTES moduleAttributes;
    DMF_CONFIG_IoctlHandler ioctlHandlerModuleConfig;

    UNREFERENCED_PARAMETER(DmfParentModuleAttributes);
    UNREFERENCED_PARAMETER(DmfModule);

    PAGED_CODE();

    FuncEntry(DMF_TRACE_ResourceHub);

    // Steps 5: Inititialize the DMF_MODULE_ATTRIBUTES and the Module's CONFIG structure.
    //

    // IoctlHandler
    // ------------
    //

    DMF_CONFIG_IoctlHandler_AND_ATTRIBUTES_INIT(&ioctlHandlerModuleConfig, &moduleAttributes);
    // NOTE: No GUID is necessary because device interface is not created.
    //
    ioctlHandlerModuleConfig.AccessModeFilter = IoctlHandler_AccessModeDefault;
    ioctlHandlerModuleConfig.EvtIoctlHandlerAccessModeFilter = NULL;
    ioctlHandlerModuleConfig.IoctlRecordCount = ARRAYSIZE(ResourceHub_IoctlSpecification);
    ioctlHandlerModuleConfig.IoctlRecords = ResourceHub_IoctlSpecification;
    // Step 6: Set callbacks to Parent. (Ommited as it is not necessary in this example.)
    //

    // Step 7: Tell DMF to add this Module as a Child Module of the Parent Module.
    //
    DMF_DmfModuleAdd(DmfModuleInit,
                     &moduleAttributes,
                     WDF_NO_OBJECT_ATTRIBUTES,
                     NULL);

    FuncExitVoid(DMF_TRACE_ResourceHub);
}
#pragma code_seg()

DMF Library Include File

DMF is designed so that Modules can be easily packaged and, optionally, distributed to external teams. DMF itself contains the core framework files, as well as a Library that contains Modules that are useful for many driver developers.

Generally, speaking, a team that uses DMF will create their own Library of Modules that contain code that is specific for the device drivers they work on. These Modules, of course, can be built using preexisting Modules in DMF or even Modules distributed by third parties.

It is a best practice for each team to build their own Library of Modules. To do so is easy as a template Library exists. That template Library has a project file as well as a Library Include File that are copied to make the initial project for the new Library.

Library Include File

Every Library has a Library Include File. This is a crucial file that contains the following:

DMF framework definitions.
Definitions needed to use Modules that come with DMF.
Definitions needed to use Modules in the (new) Library.
Includes for every Module in the (new) Library.

It is important to note that items one and two above are already included in DmfModules.Library.h. So, a Library Include File generally includes that file to satisfy requirements one and two above.

Using the Library Include File

Any Client that wants to use a Module in a specific Library needs to include that Library's Library Include File. This is true for both Module authors writing Modules for that Library as well as Client drivers that want to use Modules in the specific Library. When any Client includes the Library Include File, all of DMF as well as the Modules that come with DMF are accessible.

Sample Library Include File

It is critical that new Library Include Files contain exactly the same structure as other Library Include Files in order to ensure that Modules in the new Library work seamlessly with various Clients, including both C and C++ Clients.

Here is an example of a hypothetical Library which depends on the DMF Library and contains 3 Modules:

/*++

Copyright (c) Microsoft Corporation. All rights reserved.

Module Name:

    DmfModules.NewLibrary.h

Abstract:

    Definitions specific for the "NewLibrary" DMF Library.

Environment:

    Kernel/User Mode

--*/

#pragma once

// NOTE: The definitions in this file must be surrounded by this annotation to ensure
// that both C and C++ Clients can easily compile and link with Modules in this Library.
//

#if defined(__cplusplus)
extern "C"
{
#endif

// Include DMF Framework and Public Modules.
//
#include "..\Modules.Library\DmfModules.Library.h"

// Other library specific includes.
//

// All the Modules in this Library.
//

#include "Dmf_NewModule0.h"
#include "Dmf_NewModule1.h"
#include "Dmf_NewModule2.h"

#if defined(__cplusplus)
}
#endif

// eof: DmfModules.NewLibrary.h
//

Module Dependencies

Note that there may be dependencies between different Modules in a Library. In that case, the order of the includes for each Module is set by the author to resolve those dependencies so that Clients do not need to so.

In the example above, since Dmf_NewModule2.h needs definitions in Dmf_NewModule1.h, Dmf_NewModule1.h is listed before Dmf_NewModule2.h.

This is often the case when, for example, Dmf_NewModule2 instantiates a Child Module of type Dmf_NewModule1 and the Config for Dmf_NewModule2 contains definitions in Dmf_NewModule1.

DMF Client Driver API Reference

This section lists and explains all the structures and functions that DMF Client Drivers use to work with DMF.

DMF Client Drivers that have a Device Context need to perform the following tasks:

Hook DMF into WDF.
Create the DMF Device.
Tell DMF what Modules to use.

DMF Client Drivers that do not have a Device Context only need to perform step 3 above.

After that, the Client Driver is free to use the Modules via the Module Methods.

The APIs in this section allow a Client Driver to perform these steps.

Client Driver DMF Structures

This section lists and explains all the structures that DMF Client Drivers use to work with DMF.

PDMFDEVICE_INIT

A data structure allocated using DMF_DmfDeviceInitAllocate(). This structure is used by other DMF APIs in order to initialize DMF in a Client Driver. This is an opaque structure that the Client does not need to set directly. DMF will set the elements of this structure as its APIs are called.

DMF_EVENT_CALLBACKS

This structure tells DMF how to initialize. Specifically, it tells DMF the name of the function that DMF will call when it is ready to get the list of Modules to instantiate.

Use DMF_EVENT_CALLBACKS_INIT() to initialize this structure. Next, set the EvtDmfDeviceModulesAdd member to the function that the Client Driver uses to add Modules that will be instantiated. Then, pass that structure to DMF_DmfDeviceInitSetEventCallbacks.

Member	Description
Size	Size of the structure initialized by DMF_EVENT_CALLBACKS_INIT().
EVT_DMF_DEVICE_MODULES_ADD EvtDmfDeviceModulesAdd*	Set the EvtDmfDeviceModulesAdd member to the function that the Client Driver uses to add Modules that will be instantiated.
EVT_DMF_DEVICE_LOG EvtDmfDeviceLog*	Set the EvtDmfDeviceLog member to the function that the Client Driver uses to receive event log information from Modules.

Client Driver DMF Initialization Macros

This section lists and explains all the macros that DMF Clients use to initialize DMF. Client Drivers only need to use these macros if the Client Driver does not have its own DeviceAdd callback.

DMF_DEFAULT_DRIVERENTRY

DMF_DEFAULT_DRIVERENTRY(DmfDriverEntry,
                        DmfDriverContextCleanup,
                        DmfEvtDeviceAdd)

This macro is used by the Client Driver to tell DMF to use its own DriverEntry function.

Parameter	Description
DmfDriverEntry	This parameter must be set to "DriverEntry".
DmfDriverContextCleanup	This parameter can be any name of the Client Driver's choosing, but the same name must be used in DMF_DEFAULT_DRIVERCLEANUP.
DmfEvtDeviceAdd	This parameter can be any name of the Client Driver's choosing, but the same name must be used in DMF_DEFAULT_DEVICEADD.

Parameter	Description
DmfEvtDeviceAdd	This parameter can be any name of the Client Driver's choosing
DmfDeviceModuleAdd	This parameter can be any name of the Client Driver's choosing. The Client Driver must have a function that uses the same name with the proper signature. DMF uses this name to tell DMF the name of the function that the Client Driver uses to tell DMF the list of Modules to instantiate.

Parameter	Description
PDMFDEVICE_INIT DmfDeviceInit	The data structure created using DMF_DmfDeviceInitAllocate().
PWDF_FILEOBJECT_Config FileObjectConfig	The Client Driver passes an initialized instance of this structure (after the Client Driver has set its own callback functions) and before calling WDF_FILEOBJECT_Config_INIT().

Parameter	Description
PDMFDEVICE_INIT DmfDeviceInit	The data structure created using DMF_DmfDeviceInitAllocate().
PWDF_PNPPOWER_EVENT_CALLBACKS PnpPowerEventCallbacks	The Client Driver passes an initialized instance of this structure (after the Client Driver has set its own callback functions) and before calling WdfDeviceInitSetPnpPowerEventCallbacks().

Parameter	Description
PDMFDEVICE_INIT DmfDeviceInit	The data structure created using DMF_DmfDeviceInitAllocate().
PWDF_POWER_POLICY_EVENT_CALLBACKS PowerPolicyEventCallbacks	The Client Driver passes an initialized instance of this structure (after the Client Driver has set its own callback functions) and before calling WdfDeviceInitSetPnpPowerPolicyEventCallbacks().

Parameter	Description
PDMFDEVICE_INIT DmfDeviceInit	The data structure created using DMF_DmfDeviceInitAllocate().
PWDF_IO_QUEUE_CONFIG QueueConfig	The Client Driver passes an initialized instance of this structure (after the Client Driver has set its own callback functions) and before calling WdfIoQueueCreate().

Parameter	Description
PDMFDEVICE_INIT DmfDeviceInit	The data structure created using DMF_DmfDeviceInitAllocate().
WDF_OBJECT_ATTRIBUTES QueueObjectAttributes*	The Client Driver passes an initialized instance of this structure.

Parameter	Description
PDMFDEVICE_INIT DmfDeviceInit	The data structure created using DMF_DmfDeviceInitAllocate().
PDMF_EVENT_CALLBACKS DmfEventCallbacks	The Client Driver passes an initialized instance of this structure. Use DMF_EVENT_CALLBACKS_INIT() to initialize this structure. Then, prior to calling this API, set the name of the Client Driver's function (EvtDmfDeviceModulesAdd) that DMF will call to get the list of Modules to instantiate.

Parameter	Description
WDFDEVICE Device	The Client Driver's WDFDEVICE.
*PDMFDEVICE_INIT DmfDeviceInitPointer**	The address of an allocated and initialized instance of PDMFDEVICE_INIT.
PVOID ClientDriverContext	A ClientDriver specific context. This is optional and generally not used.

Member	Description
*EVT_DMF_MODULE_OnDeviceNotificationPostOpen EvtModuleOnDeviceNotificationPostOpen**	After the Module has been opened, this callback is called. This tells the Client that the Module is ready for use (meaning that its Module Context is initialized and Module Methods may be called). This callback can tell Clients that the Module's resources have arrived. The Module's Methods may be called from this callback.
*EVT_DMF_MODULE_OnDeviceNotificationPreClose EvtModuleOnDeviceNotificationPreClose**	Before a Module is closed, this callback is called. This tells the Client that the Module's Context will no longer be valid and its Module Methods should no longer be called. This callback can tell Clients that the Module's resources have been removed. The Module's Methods may be called from this callback.

Member	Description
Size	Indicates the size of this structure. It is initialized by DMF_CALLBACKS_WDF_INIT().
ModulePrepareHardware	Routes EvtDevicePrepareHardware to the Module. (WDFDEVICE)
ModuleReleaseHardware	Routes EvtDeviceReleaseHardware to the Module. (WDFDEVICE)
ModuleD0Entry	Routes EvtDeviceD0Entry to the Module. (WDFDEVICE)
ModuleD0EntryPostInterruptsEnabled	Routes EvtDeviceD0EntryPostInterruptsEnabled to the Module. (WDFDEVICE)
ModuleD0ExitPreInterruptsDisabled	Routes EvtDeviceD0ExitPreInterruptsDisabled to the Module. (WDFDEVICE)
ModuleD0Exit	Routes EvtDeviceD0Exit to the Module. (WDFDEVICE)
ModuleDeviceIoControl	Routes EvtQueueDeviceIoControl to the Module. (WDFQUEUE)
ModuleInternalDeviceIoControl	Routes EvtQueueInternalDeviceIoControl to the Module. (WDFQUEUE)
ModuleSelfManagedIoCleanup	Routes EvtDeviceSelfManagedIoCleanup to the Module. (WDFDEVICE)
ModuleSelfManagedIoFlush	Routes EvtDeviceSelfManagedIoFlush to the Module. (WDFDEVICE)
ModuleSelfManagedIoInit	Routes EvtDeviceSelfManagedIoInit to the Module. (WDFDEVICE)
ModuleSelfManagedIoSuspend	Routes EvtDeviceSelfManagedIoSuspend to the Module. (WDFDEVICE)
ModuleSelfManagedIoRestart	Routes EvtDeviceSelfManagedIoRestart to the Module. (WDFDEVICE)
ModuleSurpriseRemoval	Routes EvtDeviceSurpriseRemoval to the Module. (WDFDEVICE)
ModuleQueryRemove	Routes EvtDeviceQueryRemove to the Module. (WDFDEVICE)
ModuleQueryStop	Routes EvtDeviceQueryStop to the Module. (WDFDEVICE)
ModuleRelationsQuery	Routes EvtDeviceRelationsQuery to the Module. (WDFDEVICE)
ModuleUsageNotificationEx	Routes EvtDeviceUsageNotificationEx to the Module. (WDFDEVICE)
ModuleArmWakeFromS0	Routes EvtDeviceModuleArmWakeFromS0 to the Module. (WDFDEVICE)
ModuleWakeFromS0Triggered	Routes EvtDeviceWakeFromS0Triggered to the Module. (WDFDEVICE)
ModuleArmWakeFromSxWithReason	Routes EvtDeviceArmWakeFromSxWithReason to the Module. (WDFDEVICE)
ModuleDisarmWakeFromSx	Routes EvtDeviceDisarmWakeFromSx to the Module. (WDFDEVICE)
ModuleWakeFromSxTriggered	Routes EvtDeviceWakeFromSxTriggered to the Module. (WDFDEVICE)
ModuleFileCreate	Routes EvtFileCreate to the Module. (WDFDEVICE)
ModuleFileCleanup	Routes EvtFileCleanup to the Module. (WDFDEVICE)
ModuleFileClose	Routes EvtFileClose to the Module. (WDFDEVICE)
ModuleQueueIoRead	Routes EvtQueueIoRead to the Module. (WDFQUEUE)
ModuleQueueIoWrite	Routes EvtQueueIeWrite to the Module. (WDFQUEUE)

Parameter	Description
PDMFMODULE_INIT DmfModuleInit	A structure passed from DMF to the Client Drivers Module Add function.
*DMF_MODULE_ATTRIBUTES ModuleAttributes**	The structure that contains information about the Module to add. These are Module specific attributes.
*WDF_OBJECT_ATTRIBUTES ObjectAttributes**	A structure that contains information about the Module to add. These are DMF-specific attributes.
*DMFMODULE ResultantDmfModule**	An address where the Client Driver can receive the handle of the instantiated Module. This is optional and only necessary if the Client Driver will call the Module's Methods.

Value	Meaning
DMF_MODULE_OPEN_OPTION_OPEN_PrepareHardware	Tells DMF that the Module's Open callback should be called when the Client Driver receives an EvtDevicePrepareHardware callback. The Module's Close callback will be called when the Client Driver receives an EvtDeviceReleaseHardware callback.
DMF_MODULE_OPEN_OPTION_NOTIFY_PrepareHardware	Tells DMF that the Module's NotificationRegister callback should be called when the Client Driver receives an EvtDevicePrepareHardware callback. In this case, the Module will decide when the Open/Close callbacks are called (usually when the underlying interface has appeared/disappeared). The Module's NotificationUnregister callback will be called when the Client Driver receives an EvtDeviceReleaseHardware callback. Modules using this option must call DMF_ModuleOpen() and DMF_ModuleClose() from an asynchronous notification callback. In addition, the Module's Methods must also call DMF_ModuleReference() and DMF_ModuleDereference(). (See Notification Module Concepts.).
DMF_MODULE_OPEN_OPTION_OPEN_D0EntrySystemPowerUp	Tells DMF that the Module's Open callback should be called when the Client Driver receives an EvtDeviceD0Entry callback while the system is transitioning from Sx to S0 power state. The Module's Close callback will be called when the Client Driver receives an EvtDeviceD0Exit callback while the system is transitioning from S0 to Sx power state.
DMF_MODULE_OPEN_OPTION_OPEN_D0Entry	Tells DMF that the Module's Open callback should be called when the Client Driver receives an EvtDeviceD0Entry callback. The Module's Close callback will be called when the Client Driver receives an EvtDeviceD0Exit callback.
DMF_MODULE_OPEN_OPTION_NOTIFY_D0Entry	Tells DMF that the Module's notification register callback should be called when the Client Driver receives an EvtDeviceD0Entry callback. In this case, the Module will decide when the Open/Close callbacks are called (usually when the underlying interface has appeared/disappeared). The Module's NotificationUnregister callback will be called when the Client Driver receives an EvtDeviceD0Exit callback. Modules using this option must call DMF_ModuleOpen() and DMF_ModuleClose() from an asynchronous notification callback. In addition, the Module's Methods must also call DMF_ModuleReference() and DMF_ModuleDereference(). (See Notification Module Concepts.).
DMF_MODULE_OPEN_OPTION_OPEN_Create	Tells DMF that the Module should be opened/closed when the Module is created/destroyed. This is common for Modules that do not interact with hardware and, instead, expose support for data structures that just require memory resources. DMF will call the Module's Open callback soon after the Module is created. DMF will call the Module's Close callback right before the Module is destroyed.
DMF_MODULE_OPEN_OPTION_NOTIFY_Create	Tells DMF that the Module's Notification register/unregister callbacks should called when the Module is created/destroyed. DMF will call the Module's NotificationRegister callback soon after the Module is created. DMF will call the Module's NotificationUnregister callback right before the Module is destroyed. Modules using this option must call DMF_ModuleOpen() and DMF_ModuleClose() from an asynchronous notification callback. In addition, the Module's Methods must also call DMF_ModuleReference() and DMF_ModuleDereference(). (See Notification Module Concepts.).

Member	Description
Size	Indicates the size of this structure. It is initialized by DMF_MODULE_DESCRIPTOR_INIT().
Module Name	The name of the Module. It should match the name indicated by the Module's file name. This field is used for debugging purposes to make it easy to identify the Module.
ModuleOptions	Indicates whether the Module's locks are wait locks or spin locks. It is initialized by DMF_MODULE_DESCRIPTOR_INIT().
OpenOption	Indicates when DMF should open the Module. See DmfModuleOpenOption.
ModuleConfigSize	Indicates the size of the Module's Config structure (if any).
EntrypointsDmf	Tells DMF what DMF-specific callbacks this Module supports.
EntrypointsWdf	Tells DMF what WDF specific callbacks this Module supports.
BranchTrackInitialize	The name of the function that initializes BranchTrack for this Module. See the separate document that describes BranchTrack for more information.
NumberOfAuxiliaryLocks	The number of additional locks that should be created for this Module in addition to its default lock.
TransportMethod	Indicates the Module's Transport Method. When this member is set, the Module may be instantiated by a Client as a Transport Module.
InFlightRecorderSize	Indicates the size of the Module's custom IFR buffer if set to a non-zero value. By default, IFR traces will go to a common buffer for all Modules if this value is zero.

Member	Description
Size	Indicates the size of this structure. It is initialized by DMF_CALLBACKS_DMF_INIT().
ModuleInstanceDestroy	The callback function that is called when the Module is destroyed. Generally, it is not necessary for a Module to support this callback. In some rare cases, if an allocation or some resource is acquired in the Module's Create function, then this callback can be used to release that allocation or resource.
DeviceResourcesAssign	DMF calls this callback to allow the Module to retrieve the Client's Driver's resources.
DeviceNotificationRegister	DMF calls this callback to allow the Module to register for notification of an event that will tell the Module its required dependencies are available or not available.
DeviceNotificationUnregister	DMF calls this callback to allow the Module to unregister for notification of an event that will tell the Module its required dependencies are available or not available.
DeviceOpen	DMF calls this callback to open the Module. Generally speaking, the Module uses this callback to prepare its Context in preparation for later calls to other callbacks or for calls to its Module Methods by the Client.
DeviceClose	DMF calls this callback to close the Module. Generally speaking, the Module uses this callback to do the inverse of what it did in the DeviceOpen callback.
ChildModulesAdd	DMF calls this callback so that the Module can tell DMF about the Child Module(s) it needs to create.

Parameter	Description
DMFMODULE DmfModule	The given Parent Module.
*DMF_MODULE_ATTRIBUTES DmfParentModuleAttributes**	The Parent Module's attributes. In some cases it is necessary for the Child to know the Parent's attributes. (See DMF_BufferQueue.)
PDMFMODULE_INIT DmfModuleInit	An opaque structure created by DMF that must be passed to DMF_DmfModuleAdd().

Parameter	Description
DMFMODULE DmfModule	The Module's DMFMODULE. Use this handle to retrieve the Module's Context and Config.
WDFCMRESLIST ResourcesRaw	Raw resource information passed to Client Driver's EvtDevicePrepareHardware callback.
WDFCMRESLIST ResourcesTranslated	Translated resource information passed to Client Driver's EvtDevicePrepareHardware callback.

Parameter	Description
WDFDEVICE Device	The Client Driver's WDFDEVICE.
*DMF_MODULE_ATTRIBUTES DmfModuleAttributes**	Attributes that tell DMF how to create the function.
*WDF_OBJECT_ATTRIBUTES ObjectAttributes**	Attributes that tell DMF about the parent of the Module that is to be created.
*DMFMODULE DmfModule**	After the Module has been created (by this function), the resultant DMFMODULE is returned here.

Parameter	Description
PDMF_MODULE_DESCRIPTOR ModuleDescriptor	The structure buffer to initialize.
PSTR ModuleName	The name of the Module. It should match the Module's file name. This name is useful when debugging so that it is easy to know what Module the Module's handle refers to.
ULONG ModuleOptions	Flags that indicate attributes about the Module. Currently only these flags are supported: DMF_MODULE_OPTIONS_PASSIVE: Indicates that the Module uses wait locks because the Module is only used at PASSIVE_LEVEL. DMF_MODULE_OPTIONS_DISPATCH: Indicates that the Module uses spin locks because the Module is used at DISPATCH_LEVEL. DMF_MODULE_OPTIONS_DISPATCH_MAXIMUM: Indicates that the Module uses spin locks because the Module is used at DISPATCH_LEVEL by default. However, the Client may instantiate the Module using PASSIVE_LEVEL locks. (If cases where the Module allocates from the memory pool, the locks need to be PASSIVE_LEVEL locks if the Client chooses to allocate Paged Pool.) DMF_MODULE_OPTIONS_TRANSPORT_REQUIRED: Indicates that the Module requires that the Client instantiate a Transport Module.
DmfModuleOpenOption OpenOption	See DmfModuleOpenOption.

Parameter	Description
WDFDEVICE Device	The Client Driver's WDFDEVICE. This value is passed into the Module's Create function.
*DMF_MODULE_ATTRIBUTES DmfModuleAttributes**	Contains information DMF uses to create the Module. This value is passed into the Module's Create function.
PWDF_OBJECT_ATTRIBUTES DmfModuleObjectAttributes	Holds the Module's parent information.
PDMF_MODULE_DESCRIPTOR ModuleDescriptor	The descriptor that describes all the Module-specific information such as the callbacks it supports and the size of its Config structure.
*DMFMODULE DmfModule**	This value holds the handle of the created Module when this function returns success. It must be passed back to the caller of the Module's Create function.

Parameter	Description
DMFMODULE DmfModule	The Module's DMFMODULE
WDFREQUEST Request	The given WDFREQUEST.
NTSTATUS NtStatus	The NTSTATUS that is to be set in the WDFREQUEST.

Parameter	Description
DMFMODULE DmfModule	The Module's DMFMODULE.
Message	Indicates the reason for the call. Also, indicates the format of the Input and Output buffers.
InputBuffer	Specifies data sent to the Method. Message indicates the contents of this buffer.
InputBufferSize	Indicates the size of InputBuffer in bytes.
OutputBuffer	Specifies data returned by the Method. Message indicates the contents of this buffer.
OutputBufferSize	Indicates the size of OutputBuffer in bytes.

Feature Identifier	Purpose
DmfFeature_BranchTrack	Gives access to the BranchTrack Module.
DmfFeature_LiveKernelDump	Gives access to the LiveKernelDump Module.
DmfFeature_Performance	Gives access to the Performance Module. (Coming soon.)

Parameter	Description
WDFDEVICE Device	The given WDFDEVICE.
DmfFeatureType DmfFeature	Indicates which Feature Module to retrieve.

Parameter	Description
DMFMODULE DmfModule	The given DMFMODULE handle.
DmfFeatureType DmfFeature	Indicates which Feature Module to retrieve.

Parameter	Description
WDFDEVICE Device	The given WDFDEVICE.
DMF_CONFIG_BranchTrack* FilterBranchTrackConfig	BranchTrack Module Config.
PWDF_IO_QUEUE_CONFIG QueueConfig	The Client Driver passes an initialized structure or NULL if not used.
WCHAR* ControlDeviceName	The name of the Filter Control Device to create.

Parameter	Description
DMF_PORTABLE_EVENT* EventPointer	The address of the given event to wait for.
ULONG* TimeoutMs	Use NULL to indicate infinite wait. Otherwise, it is the address of a ULONG holding the number of milliseconds to wait.
BOOLEAN Alertable	TRUE to indicate the wait is alertable.

Parameter	Description
ULONG EventCount	The number of events in the event pointer array to wait for.
DMF_PORTABLE_EVENT* EventPointer	The address of the array of events to wait for.
BOOLEAN WaitForAll	Indicates that call waits for all events to be set.
ULONG* TimeoutMs	Use NULL to indicate infinite wait. Otherwise, it is the address of a ULONG holding the number of milliseconds to wait.
BOOLEAN Alertable	TRUE to indicate the wait is alertable.

Parameter	Description
PWDF_OBJECT_ATTRIBUTES LookasideAttributes
size_t BufferSize	Size of each buffer that is allocated from the lookaside list.
POOL_TYPE PoolType	PagedPool or NonPagedPoolNx. In User-mode all memory is pageable.
PWDF_OBJECT_ATTRIBUTES MemoryAttributes
ULONG PoolTag	Pool tag so for tracking memory leaks.
PDMF_PORTABLE_LOOKASIDELIST LookasidePointer	The address where the created lookaside list handle is created. Use this handle with APIs that use the lookaside list.

Parameter	Description
PDMF_PORTABLE_LOOKASIDELIST LookasidePointer	The address of the given lookaside list handle from which to allocate a buffer.
WDFMEMORY Memory*	Address of the WDF Memory Handle associated with the allocated memory.

Parameter	Description
DMFMODULE DmfModule	The Module from which the string is emitted.
DmfLogDataSeverity DmfLogDataSeverity	The severity of the message.
WCHAR FormatString*	The format string which is used to format the following variable arguments.
...	The variable argument list that contains the data to write in the string and emit to Client Driver.