WDF----PCI设备初始化
作为微软新一代驱动开发模型，WDF逐渐取代WDM成为驱动程序开发主流， 下面以AMCC S5933驱动代码为例，研究下WDF模式下PCIe设备的驱动开发是什么样的流程。
和WDM相似，系统启动后，会调用驱动程序里的入口函数DriverEntry()，代码如下：
NTSTATUS
DriverEntry(
IN PDRIVER_OBJECT DriverObject,
IN PUNICODE_STRING RegistryPath
)
/*++
Routine Description:
Installable driver initialization entry point.
This entry point is called directly by the I/O system.
Arguments:
DriverObject - Pointer to the driver object created by the I/O manager.
RegistryPath - Pointer to the driver specific key
\Registry
\Machine
\System
\CurrentControlSet
\Services
\<DriverName>
Return Value:
NTSTATUS
--*/
{
NTSTATUS status = STATUS_SUCCESS;
WDF_DRIVER_CONFIG config;
WDFDRIVER driver;
WDF_OBJECT_ATTRIBUTES attributes;
//
// Initialize WPP Tracing
//
WPP_INIT_TRACING( DriverObject, RegistryPath );
TraceEvents(TRACE_LEVEL_INFORMATION, AMCC_TRACE_INIT,
"DriverObject 0x%p", DriverObject);
TraceEvents(TRACE_LEVEL_INFORMATION, AMCC_TRACE_INIT,
"Built %s %s", __DATE__, __TIME__);
//
// Initialize the Driver Config structure..
//
WDF_DRIVER_CONFIG_INIT( &config, CommonEvtDeviceAdd );
//
// Register a cleanup callback so that we can call WPP_CLEANUP when
// the framework driver object is deleted during driver unload.
//
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.EvtCleanupCallback = CommonEvtDriverContextCleanup;
status = WdfDriverCreate( DriverObject,
RegistryPath,
&attributes,
&config,
&driver );
if (!NT_SUCCESS(status)) {
TraceEvents(TRACE_LEVEL_ERROR, AMCC_TRACE_INIT,
"WdfDriverCreate failed with status 0x%X\n", status);
//
// Cleanup tracing here because DriverContextCleanup will not be called
// as we have failed to create WDFDRIVER object itself.
// Please note that if your return failure from DriverEntry after the
// WDFDRIVER object is created successfully, you don't have to
// call WPP cleanup because in those cases DriverContextCleanup
// will be executed when the framework deletes the DriverObject.
//
WPP_CLEANUP(DriverObject);
}
return status;
}以上代码主要工作是创建设备对象，以及进行一些初始化工作：
1：WDF_DRIVER_CONFIG_INIT( &config, CommonEvtDeviceAdd ) 将初始化WDF_DRIVER_CONFIG这样一个结构体，并填充回调函数CommonEvtDeviceAdd 。
2：WdfDriverCreate( DriverObject, RegistryPath, &attributes, &config, &driver )将创建驱动对象。
回调函数CommonEvtDeviceAdd的代码如下：
NTSTATUS
CommonEvtDeviceAdd(
IN WDFDRIVER Driver,
IN PWDFDEVICE_INIT DeviceInit
)
/*++
Routine Description:
EvtDeviceAdd is called by the framework in response to AddDevice
call from the PnP manager. It is responsible for initializing and
creating a WDFDEVICE object.
Arguments:
Driver - Handle to a framework driver object created in DriverEntry
DeviceInit - Pointer to a framework-allocated WDFDEVICE_INIT structure.
Return Value:
NTSTATUS
--*/
{
NTSTATUS status = STATUS_SUCCESS;
WCHAR enumeratorName[64] = {0};
ULONG returnSize;
UNICODE_STRING unicodeEnumName, temp;
WDF_OBJECT_ATTRIBUTES attributesForRequests;
PAGED_CODE();
TraceEvents(TRACE_LEVEL_INFORMATION, AMCC_TRACE_INIT,
"CommonEvtDeviceAdd: Init 0x%p", DeviceInit);
//
// Get the device enumerator name to detect whether the device being
// added is a PCI device or root-enumerated non pnp ISA device.
// It's okay to WDM functions when there is no appropriate WDF
// interface is available.
//
status = WdfFdoInitQueryProperty(DeviceInit,
DevicePropertyEnumeratorName,
sizeof(enumeratorName),
enumeratorName,
&returnSize);
if(!NT_SUCCESS(status)){
return status;
}
//
// Context is used only for the PCI device.
//
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributesForRequests, REQUEST_CONTEXT);
WdfDeviceInitSetRequestAttributes(DeviceInit, &attributesForRequests);
//
// WdfFdoInitQueryProperty returns a NULL-terminated WCHAR string.
// So don't worry about buffer overrun.
//
RtlInitUnicodeString(&unicodeEnumName, enumeratorName);
RtlInitUnicodeString(&temp, L"PCI");
if(RtlCompareUnicodeString(&unicodeEnumName, &temp, TRUE) == 0) {
//
// It's a PCI device.
//
return AmccPciAddDevice(Driver, DeviceInit);
}
//
// We root-enumerated the non pnp ISA device by manualy installing the
// driver. So the enumerator should be Root.
//
RtlInitUnicodeString(&temp, L"Root");
if(RtlCompareUnicodeString(&unicodeEnumName, &temp, TRUE) == 0) {
//
// It's an non pnp ISA device.
//
return AmccIsaEvtDeviceAdd(Driver, DeviceInit);
}
ASSERTMSG("Unknown device", FALSE);
return STATUS_DEVICE_CONFIGURATION_ERROR;
}
该函数主要职责是创建并初始化设备对象。本段代码比较特殊，会判断设备为PCI设备还是ISA设备，本例中我们只讨论PCI，看看AmccPciAddDevice(Driver, DeviceInit)函数里里具体如何创建并初始化设备对象的， 代码如下：
NTSTATUS
AmccPciAddDevice(
_In_ WDFDRIVER Driver,
_Inout_ PWDFDEVICE_INIT DeviceInit
)
/*++
Routine Description:
EvtDeviceAdd is called by the framework in response to AddDevice
call from the PnP manager. It is responsible for initializing and
creating a WDFDEVICE object.
Any work that should be done after the object is created should be
deferred until EvtDeviceSoftwareInit, as that callback will be made
with the device lock held (if there is one.)
Arguments:
Driver - Handle to a framework driver object created in DriverEntry
DeviceInit - Pointer to a framework-allocated WDFDEVICE_INIT structure.
Return Value:
NTSTATUS
--*/
{
NTSTATUS status = STATUS_SUCCESS;
WDF_PNPPOWER_EVENT_CALLBACKS pnpPowerCallbacks;
WDF_OBJECT_ATTRIBUTES fdoAttributes;
WDF_INTERRUPT_CONFIG interruptConfig;
WDF_OBJECT_ATTRIBUTES interruptAttributes;
WDF_IO_QUEUE_CONFIG ioQueueConfig;
PAMCC_DEVICE_EXTENSION devExt;
WDFQUEUE hQueue;
WDFDEVICE device;
PAGED_CODE();
TraceEvents(TRACE_LEVEL_INFORMATION, AMCC_TRACE_INIT,
"AmccPciAddDevice: 0x%p", Driver);
//
// Zero out the PnpPowerCallbacks structure.
//
WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
//
// Set Callbacks for any of the functions we are interested in.
// If no callback is set, Framework will take the default action
// by itself.
//
pnpPowerCallbacks.EvtDevicePrepareHardware = AmccPciEvtDevicePrepareHardware;
pnpPowerCallbacks.EvtDeviceReleaseHardware = AmccPciEvtDeviceReleaseHardware;
pnpPowerCallbacks.EvtDeviceD0Entry = AmccPciEvtDeviceD0Entry;
pnpPowerCallbacks.EvtDeviceD0Exit = AmccPciEvtDeviceD0Exit;
//
// Register the PnP Callbacks..
//
WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &pnpPowerCallbacks);
//
// Set various attributes for this device
//
WdfDeviceInitSetIoType( DeviceInit, WdfDeviceIoDirect );
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&fdoAttributes, AMCC_DEVICE_EXTENSION);
fdoAttributes.EvtCleanupCallback = AmccPciContextCleanup;
//
// We want all the queue callbacks, cancel routine, and DpcForIsr to be serialized
// at the device level, so we don't have worry about any synchronization issues.
//
fdoAttributes.SynchronizationScope = WdfSynchronizationScopeDevice;
status = WdfDeviceCreate( &DeviceInit, &fdoAttributes, &device );
if ( !NT_SUCCESS(status) ) {
TraceEvents(TRACE_LEVEL_ERROR, AMCC_TRACE_INIT,
"WdfDeviceInitialize failed 0x%X", status);
return status;
}
//
// Device Initialization is complete.
// Get the Device Extension and initialize it.
//
devExt = AmccPciGetDevExt(device);
devExt->Device = device;
TraceEvents(TRACE_LEVEL_INFORMATION, AMCC_TRACE_INIT,
"PDO 0x%p, FDO 0x%p, DevExt 0x%p",
WdfDeviceWdmGetPhysicalDevice(device),
WdfDeviceWdmGetDeviceObject( device ), devExt);
//
// This device generates an interrupt. So create an interrupt object which
// will later be associated with the devices resources and connected
// by the Framework.
//
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&interruptAttributes, INTERRUPT_DATA);
//
// Configure the Interrupt object
//
WDF_INTERRUPT_CONFIG_INIT(&interruptConfig,
AmccPciEvtInterruptIsr,
AmccPciEvtInterruptDpc);
status = WdfInterruptCreate(device,
&interruptConfig,
&interruptAttributes,
&devExt->WdfInterrupt);
if (!NT_SUCCESS (status))
{
TraceEvents(TRACE_LEVEL_ERROR, AMCC_TRACE_INIT,
"WdfInterruptCreate failed: %!STATUS!\n", status);
return status;
}
//
// The S5933 requires DMA buffers be aligned on a 32-bit boundary
//
// NOTE: Read the existing alignment value. If it is greater than
// or equal then keep it. If it is less then update the
// alignment requirement field with this device's required
// value.
//
// NOTE: See the MSDN section titled "Initializing a Device Object"
// for details on how to specify this alignment value.
//
// NOTE: AMCC5933_ALIGNMENT__32BITS is equated to (4-1) for 32-bit
// alignment.
//
{
ULONG alignReq;
alignReq = WdfDeviceGetAlignmentRequirement( device );
if (alignReq < AMCC5933_ALIGNMENT__32BITS) {
//
// Set the S5933 alignment requirement as new value.
//
WdfDeviceSetAlignmentRequirement( device,
AMCC5933_ALIGNMENT__32BITS);
}
}
//
// Register I/O callbacks.
//
// Create a sequential IO Queue for serial operation. That means all the requests (Read/Write
// & IOCTL) are serialized to the device. Until the driver completes the request presented to it,
// the framework will not schedule another one. The requests held in the framework will be
// cancelled automatically if the source of request (application) terminate or cancels it.
//
WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE( &ioQueueConfig,
WdfIoQueueDispatchSequential);
ioQueueConfig.EvtIoDefault = AmccPciEvtIoDefault;
//
// By default, Static Driver Verifier (SDV) displays a warning if it
// doesn't find the EvtIoStop callback on a power-managed queue.
// The 'assume' below causes SDV to suppress this warning. If the driver
// has not explicitly set PowerManaged to WdfFalse, the framework creates
// power-managed queues when the device is not a filter driver. Normally
// the EvtIoStop is required for power-managed queues, but for this driver
// it is not needed b/c the driver doesn't hold on to the requests for
// long time or forward them to other drivers.
// If the EvtIoStop callback is not implemented, the framework waits for
// all driver-owned requests to be done before moving in the Dx/sleep
// states or before removing the device, which is the correct behavior
// for this type of driver. If the requests were taking an indeterminate
// amount of time to complete, or if the driver forwarded the requests
// to a lower driver/another stack, the queue should have an
// EvtIoStop/EvtIoResume.
//
__analysis_assume(ioQueueConfig.EvtIoStop != 0);
status = WdfIoQueueCreate( device,
&ioQueueConfig,
WDF_NO_OBJECT_ATTRIBUTES,
&hQueue );
__analysis_assume(ioQueueConfig.EvtIoStop == 0);
if (!NT_SUCCESS (status)) {
//
// We don't have worry about deleting the device here because framework will automatically
// cleanup that when the driver unloads.
//
TraceEvents(TRACE_LEVEL_ERROR, AMCC_TRACE_INIT,
"WdfIoQueueCreate failed %!STATUS!", status);
return status;
}
//
// Register an interface so that application can find and talk to us.
// NOTE: See the note in Public.h concerning this GUID value.
//
status = WdfDeviceCreateDeviceInterface( device,
(LPGUID) &GUID_DEVINTERFACE_AMCC_PCI,
NULL );
if (!NT_SUCCESS(status)) {
TraceEvents(TRACE_LEVEL_ERROR, AMCC_TRACE_INIT,
"<-- AMCCAddDevice: WdfDeviceCreateDeviceInterface failed %!STATUS!", status);
return status;
}
devExt->MaximumTransferLength = MAXIMUM_REQUEST_CONTEXT_LENGTH;
//
// Set the maximum physical pages for now, but this value may change if
// there aren't enough map registers
//
devExt->MaximumPhysicalPages = MAXIMUM_PHYSICAL_PAGES;
return status;
}
以上代码主要完成以下工作：
1：初始化一个WDF_PNPPOWER_EVENT_CALLBACKS结构体并注册我们需要的回调函数，如：AmccPciEvtDevicePrepareHardware;AmccPciEvtDeviceReleaseHardware; AmccPciEvtDeviceD0Entry;AmccPciEvtDeviceD0Exit;
2：设置一些额外属性
3：调用WdfDeviceCreate( &DeviceInit, &fdoAttributes, &device )创建设备对象
4：配置以及注册中断对象
5：创建及配置I/O queue
5：根据GUID创建设备接口供上层程序调用
DriverEntry （驱动程序入口）
WDF_DRIVER_CONFIG_INIT （初始化Driver Config structure，注册CommonEvtDeviceAdd回调函数）
WdfDriverCreate （创建驱动对象）
↓
CommonEvtDeviceAdd （调用AmccPciAddDevice函数）
↓
AmccPciAddDevice （注册各种回调函数，创建设备对象，创建I/O队列以及设备接口等等）
通过以上步骤，就完成了PCIe设备的初始化工作。
主要流程和WDM是大同小异的，WDF只是在WDM的基础上进行了封装，使得其开发更贴近于面向对象思想，更容易上手！