windows wdf 驱动开发总结(3)-usb驱动
(28) WdfDeviceAllocAndQueryProperty
函数功能：allocates a buffer and retrieves a specified device property
NTSTATUS
WdfDeviceAllocAndQueryProperty(
IN WDFDEVICE Device,
IN DEVICE_REGISTRY_PROPERTY DeviceProperty,
IN POOL_TYPE PoolType,
IN OPTIONAL PWDF_OBJECT_ATTRIBUTES PropertyMemoryAttributes,
OUT WDFMEMORY* PropertyMemory
);
参数说明：
Device
A handle to a framework device object.
DeviceProperty
A DEVICE_REGISTRY_PROPERTY-typed enumerator that identifies the device property to be retrieved.
PoolType
A POOL_TYPE-typed enumerator that specifies the type of memory to be allocated.
PropertyMemoryAttributes
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that describes object attributes for the memory object that the function will allocate. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
PropertyMemory
A pointer to a WDFMEMORY-typed location that receives a handle to a framework memory object.
typedef struct _WDF_OBJECT_ATTRIBUTES {
ULONG Size;
PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
WDF_EXECUTION_LEVEL ExecutionLevel;
WDF_SYNCHRONIZATION_SCOPE SynchronizationScope;
WDFOBJECT ParentObject;
size_t ContextSizeOverride;
PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;
(29) WdfMemoryGetBuffer
函数功能：returns a pointer to the buffer that is associated with a specified memory object.
PVOID
WdfMemoryGetBuffer(
IN WDFMEMORY Memory,
OUT OPTIONAL size_t* BufferSize
);
Parameters
Memory
A handle to a framework memory object.
BufferSize
A pointer to a location that receives the size, in bytes, of the memory buffer. This parameter is optional and can be NULL.
Return Value
WdfMemoryGetBuffer returns a pointer to the memory buffer.
(30) WdfDeviceConfigureRequestDispatching
函数功能：causes the framework to queue a specified type of I/O requests to a specified I/O queue.
NTSTATUS
WdfDeviceConfigureRequestDispatching(
IN WDFDEVICE Device,
IN WDFQUEUE Queue,
IN WDF_REQUEST_TYPE RequestType
);
Parameters
Device
Supplies a handle to a framework device object.
Queue
Supplies a handle to a framework queue object.
RequestType
Supplies a WDF_REQUEST_TYPE-typed enumerator that identifies the type of request to be queued. The only valid enumerators are:
WdfRequestTypeCreate
WdfRequestTypeRead
WdfRequestTypeWrite
WdfRequestTypeDeviceControl
WdfRequestTypeDeviceControlInternal
返回值：
如果成功,返回STATUS_SUCCESS，否则：返回STATUS_INVALID_PARAMETER,
STATUS_INSUFFCIENT_RESOURCES, STATUS_SDF_BUSY
(31) EventWriteReadStart(&activity, WdfIoQueueGetDevice(Queue), (ULONG)Length);
(32) EventWriteReadFail(&activity, WdfIoQueueGetDevice(Queue), status);
EventWriteReadStop(&activity,
WdfIoQueueGetDevice(WdfRequestGetIoQueue(Request)),
bytesRead,
status,
usbCompletionParams->UsbdStatus);
翻译：Developing Drivers with the Microsoft windows driver foundation
第8章 I/O Flow and Dispatching
1)Common I/O request types
基本的I/O 请求：create，close，read，write，device I/O control
Create requests
应用程序调用windows API Create 函数，打开file，目录(directory),设备(device).如果成功，返回一个file handle 。
Cleanup and Close Requests
应用调用Closehandle关闭句柄。当所有的file object 都关闭后，I/O管理器发送cleanup request 给驱动。
Read and write requests
ReadFile函数和WriteFile函数
（38）WDM中建立vendor请求函数
void UsbBuildVendorRequest(
[in] PURB Urb,
[in] USHORT Function,
[in] USHORT Length,
[in] ULONG TransferFlags,
[in] UCHAR ReservedBits,
[in] UCHAR Request,
[in] USHORT Value,
[in] USHORT Index,
[in, optional] PVOID TransferBuffer, //缓冲区
[in, optional] PMDL TransferBufferMDL,
[in] ULONG TransferBufferLength,//传输的长度
[in] PURB Link
);
（39）WDF_REQUEST_TYPE
typedef enum _WDF_REQUEST_TYPE {
WdfRequestUndefined = 0,
WdfRequestCreate = 1,
WdfRequestCleanup = 2,
WdfRequestRead = 3,
WdfRequestWrite = 4,
WdfRequestDeviceIoControl = 5,
WdfRequestClose = 6,
WdfRequestUsb = 7,
WdfRequestOther = 8,
WdfRequestInternalIoctl = 9,
WdfRequestTypeNoFormat = 10,
WdfRequestFlushBuffers = 11,
WdfRequestQueryInformation = 12,
WdfRequestSetInformation = 13,
WdfRequestMaximum
} WDF_REQUEST_TYPE;
（40）GetFileContext
函数功能：
(41) WdfRequestGetFileObject
函数功能：retrieves the framework file object that is associated with a specified I/O request.
函数原型：
WDFFILEOBJECT
WdfRequestGetFileObject(
IN WDFREQUEST Request
)
Parameters
Request
A handle to a framework request object.
Return Value
WdfRequestGetFileObject returns a handle to the framework file object, if the framework has created a file object for the specified request. Otherwise, this method returns NULL. (A driver typically tests for a NULL return value only if it sets the WdfFileObjectCanBeOptional bit flag in the WDF_FILEOBJECT_CONFIG structure.)
A bug check occurs if the driver supplies an invalid object handle.
（42）WDF_DECLARE_CONTEXT_TYPE_WITH_NAME
函数功能：macro creates an accessor method with a specified name for a driver's object-specific context space
Parameters
_contexttype
The symbol name of a driver-defined structure. The structure must describe the contents of an object's context space.
_castingfunction
A C-language routine name. The macro uses this name as the name for the accessor method that it creates for the object's context space.
（43） WDF_USB_PIPE_INFORMATION_INIT
函数功能：initializes a WDF_USB_PIPE_INFORMATION structure.
VOID
WDF_USB_PIPE_INFORMATION_INIT(
PWDF_USB_PIPE_INFORMATION Info
);
The WDF_USB_PIPE_INFORMATION_INIT function zeros the WDF_USB_PIPE_INFORMATION structure and sets the structure's Size member.
（44） WdfUsbTargetPipeGetInformation
函数功能：retrieves information about a USB pipe and its endpoint.
VOID
WdfUsbTargetPipeGetInformation(
IN WDFUSBPIPE Pipe,
OUT PWDF_USB_PIPE_INFORMATION PipeInformation,
);
Parameters
Pipe
A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.
PipeInformation
A pointer to a caller-allocated WDF_USB_PIPE_INFORMATION structure that receives information about the pipe and endpoint.
（45 WdfRequestRetrieveOutputWdmMdl
函数功能：retrieves a memory descriptor list (MDL) that represents an I/O request's output buffer.
NTSTATUS
WdfRequestRetrieveOutputWdmMdl(
IN WDFREQUEST Request,
OUT PMDL* Mdl
);
Parameters
Request
A handle to a framework request object.
Mdl
A pointer to a location that receives a pointer to an MDL.
（45） MmGetMdlVirtualAddress
函数功能：returns the base virtual address of a buffer described by an MDL.
PVOID
MmGetMdlVirtualAddress(
IN PMDL Mdl
);
Parameters
Mdl
Pointer to an MDL that describes the buffer for which to return the initial virtual address.
返回值：returns the starting virtual address of the MDL.
（46） IoAllocateMdl
函数功能：allocates a memory descriptor list (MDL) large enough to map a buffer, given the buffer's starting address and length. Optionally, this routine associates the MDL with an IRP.
PMDL
IoAllocateMdl(
__in_opt PVOID VirtualAddress,
__in ULONG Length,
__in BOOLEAN SecondaryBuffer,
__in BOOLEAN ChargeQuota,
__inout_opt PIRP Irp OPTIONAL
);
Parameters
VirtualAddress
Pointer to the base virtual address of the buffer the MDL is to describe.
Length
Specifies the length, in bytes, of the buffer that the MDL is to describe. For more information, see the following Comments section.
SecondaryBuffer
Indicates whether the buffer is a primary or secondary buffer. This parameter determines how the MDL is to be linked to the IRP. All buffers except the first buffer described by an MDL in an IRP are considered secondary buffers. This field must be FALSE if no IRP is associated with the MDL. For more information, see the following Comments section.
ChargeQuota
Reserved for system use. Drivers must set this parameter to FALSE.
Irp
Pointer to an IRP to be associated with the MDL. If the Irp pointer is non-NULL, the allocated MDL is associated with the specified IRP's MDL list, according to the value of SecondaryBuffer.
Return Value
IoAllocateMdl returns a pointer to an MDL, or, if the MDL cannot be allocated, it returns NULL.
（47） IoBuildPartialMdl
函数功能：builds a new memory descriptor list (MDL) that represents part of a buffer that is described by an existing MDL.
VOID
IoBuildPartialMdl(
__in PMDL SourceMdl,
__inout PMDL TargetMdl,
__in PVOID VirtualAddress,
__in ULONG Length
);
Parameters
SourceMdl
A pointer to an MDL that describes the original buffer, of which a subrange is to be mapped.
TargetMdl
A pointer to a caller-allocated MDL. This MDL must be large enough to describe the pages in the subrange that are specified by VirtualAddress and Length.
VirtualAddress
A pointer to the base virtual address for the subrange to be described by the TargetMdl.
Length
Specifies the length, in bytes, to be mapped by the TargetMdl. This value, in combination with VirtualAddress, must specify a buffer that is a proper subrange of the buffer that is described by SourceMdl. If Length is zero, the subrange to be mapped starts at VirtualAddress and includes the remaining range described by the SourceMdl
评论：
This routine builds a target MDL that describes a subrange of the buffer that is described by the source MDL. This subrange is specified by the VirtualAddress and Length parameters. The SourceMdl and TargetMdl parameters point to the source MDL and target MDL.
（48） WdfMemoryCreate
函数功能：creates a framework memory object and allocates a memory buffer of a specified size.
NTSTATUS
WdfMemoryCreate(
IN OPTIONAL PWDF_OBJECT_ATTRIBUTES Attributes,
IN POOL_TYPE PoolType,
IN OPTIONAL ULONG PoolTag,
IN size_t BufferSize,
OUT WDFMEMORY* Memory,
OUT OPTIONAL PVOID* Buffer
);
Parameters
Attributes
A pointer to a WDF_OBJECT_ATTRIBUTES structure that contains object attributes for the new memory object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
PoolType
A POOL_TYPE-typed value that specifies the type of memory to be allocated.
PoolTag
A driver-defined pool tag for the allocated memory. Debuggers display this tag. Drivers typically specify a character string of up to four characters, delimited by single quotation marks, in reverse order (for example, 'dcba'). The ASCII value of each character in the tag must be between 0 and 127. Debugging your driver is easier if each pool tag is unique.
If PoolTag is zero, the framework provides a default pool tag that uses the first four characters of your driver's kernel-mode service name. If the service name begins with "WDF" (the name is not case sensitive and does not include the quotation marks), the next four characters are used. If fewer than four characters are available, "FxDr" is used.
For KMDF versions 1.5 and later, your driver can use the DriverPoolTag member of the WDF_DRIVER_CONFIG structure to specify a default pool tag.
BufferSize
The nonzero specified size, in bytes, of the buffer.
Memory
A pointer to a location that receives a handle to the new memory object.
Buffer
A pointer to a location that receives a pointer to the buffer that is associated with the new memory object. This parameter is optional and can be NULL.
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
sizeof(USB_DEVICE_DESCRIPTOR),
&devContext->DeviceDescriptor,
&usbDeviceDescriptor
);
（49） WdfUsbTargetPipeWdmGetPipeHandle
函数功能：returns the USBD_PIPE_HANDLE-typed handle that is associated with a specified framework pipe object
USBD_PIPE_HANDLE
WdfUsbTargetPipeWdmGetPipeHandle(
IN WDFUSBPIPE UsbPipe
);
(50) UsbBuildInterruptOrBulkTransferRequest
函数功能：formats an URB to send or receive data on a bulk pipe, or to receive data from an interrupt pipe.
VOID
UsbBuildInterruptOrBulkTransferRequest(
IN OUT PURB Urb,
IN USHORT Length,
IN USBD_PIPE_HANDLE PipeHandle,
IN PVOID TransferBuffer OPTIONAL,
IN PMDL TransferBufferMDL OPTIONAL,
IN ULONG TransferBufferLength,
IN ULONG TransferFlags,
IN PURB Link
);
Parameters
Urb
Pointer to an URB to be formatted as an interrupt or bulk transfer request.
Length
Specifies the size, in bytes, of the URB.
PipeHandle
Specifies the handle for this pipe returned by the HCD when a configuration was selected.
TransferBuffer
Pointer to a resident buffer for the transfer or is NULL if an MDL is supplied in TransferBufferMDL. The contents of this buffer depend on the value of TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, this buffer will contain data read from the device on return from the HCD. Otherwise, this buffer contains driver-supplied data to be transferred to the device.
TransferBufferMDL
Pointer to an MDL that describes a resident buffer or is NULL if a buffer is supplied in TransferBuffer. The contents of the buffer depend on the value of TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, the described buffer will contain data read from the device on return from the HCD. Otherwise, the buffer contains driver-supplied data to be transferred to the device. The MDL must be allocated from nonpaged pool.
TransferBufferLength
Specifies the length, in bytes, of the buffer specified in TransferBuffer or described in TransferBufferMDL.
TransferFlags
Specifies zero, one, or a combination of the following flags:
USBD_TRANSFER_DIRECTION_IN
Is set to request data from a device. To transfer data to a device, this flag must be clear.
USBD_SHORT_TRANSFER_OK
Can be used if USBD_TRANSFER_DIRECTION_IN is set. If set, directs the HCD not to return an error if a packet is received from the device that is shorter than the maximum packet size for the endpoint. Otherwise, a short request returns an error condition.
Link
Must be set to NULL. .
调用例子：
UsbBuildInterruptOrBulkTransferRequest(urb,
sizeof(struct _URB_BULK_OR_INTERRUPT_TRANSFER),
usbdPipeHandle,
NULL,
newMdl,
stageLength,
urbFlags,
NULL);
(51) WdfRequestSetCompletionRoutine
函数功能：registers or deregisters a completion routine for the specified framework request object.
Parameters
Request [in]
A handle to a framework request object.
CompletionRoutine [in, optional]
A pointer to a CompletionRoutine callback function, if the driver is registering a completion routine, or NULL of the driver is deregistering a previously registered completion routine.
CompletionContext [in, optional]
An untyped pointer to driver-defined context information that the framework passes to the CompletionRoutine callback function. This parameter is optional and can be NULL.
(52) WdfRequestSetInformation
函数功能：sets completion status information for a specified I/O request.
VOID WdfRequestSetInformation(
[in] WDFREQUEST Request,
[in] ULONG_PTR Information
);
Parameters
Request [in]
A handle to a framework request object.
Information [in]
Driver-defined completion status information for the request.
评论：
Framework-based drivers use the WdfRequestSetInformation method to supply driver-specific information that is associated with the completion of an I/O request, such as the number of bytes transferred. Other drivers can obtain this information by calling WdfRequestGetInformation.
(53) MmPrepareMdlForReuse
函数功能：macro releases the resources that are associated with a partial MDL so that the MDL can be reused.
VOID MmPrepareMdlForReuse(
[in] PMDL Mdl
);
Parameters
Mdl [in]
A pointer to a partial MDL that is to be prepared for reuse.
Return Value
None
(53) WDF_WORKITEM_CONFIG_INIT
函数功能：initializes a driver's WDF_WORKITEM_CONFIG structure.
VOID WDF_WORKITEM_CONFIG_INIT(
__out PWDF_WORKITEM_CONFIG Config,
__in PFN_WDF_WORKITEM EvtWorkItemFunc
);
参数：
Config [out]
A pointer to the caller-allocated WDF_WORKITEM_CONFIG structure to initialize.
EvtWorkItemFunc [in]
The address of the driver's EvtWorkItem event callback function.
评论：
该函数必须在WdfWorkItemCreate.函数之前调用，The WDF_WORKITEM_CONFIG_INIT function stores the pointer that the EvtWorkItemFunc parameter specifies and sets the AutomaticSerialization member of the WDF_WORKITEM_CONFIG structure that is pointed to by the Config parameter to TRUE.
typedef struct _WDF_WORKITEM_CONFIG {
ULONG Size;
PFN_WDF_WORKITEM EvtWorkItemFunc;
BOOLEAN AutomaticSerialization;
} WDF_WORKITEM_CONFIG, *PWDF_WORKITEM_CONFIG;
Size
The size, in bytes, of this WDF_WORKITEM_CONFIG structure.
EvtWorkItemFunc
The address of an EvtWorkItem event callback function
AutomaticSerialization
A Boolean value that, if TRUE, indicates that the framework will synchronize execution of the EvtWorkItem callback function，if FALSE, the framework does not synchronize execution of the EvtWorkItem callback function
（54）WdfWorkItemCreate
函数功能：creates a framework work-item object, which can subsequently be added to the system's work-item queue.
NTSTATUS WdfWorkItemCreate(
[in] PWDF_WORKITEM_CONFIG Config,
[in] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFWORKITEM *WorkItem
);
Parameters
Config [in]
A pointer to a caller-allocated WDF_WORKITEM_CONFIG structure that the driver must have already initialized by calling WDF_WORKITEM_CONFIG_INIT.
Attributes [in]
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies attributes for the work-item object.
WorkItem [out]
A pointer to a variable that receives a handle to the new work-item object.
（55）WdfWorkItemEnqueue
函数功能：将work-item 对象添加到work-item 队列
adds a specified framework work-item object to the system's work-item queue.
VOID WdfWorkItemEnqueue(
[in] WDFWORKITEM WorkItem
);
参数：
WorkItem [in]
A handle to a framework work-item object that is obtained from a previous call to WdfWorkItemCreate.
评论：
After the driver calls WdfWorkItemCreate to create a work item, the driver must call WdfWorkItemEnqueue to add the work item to the system's work-item queue. A system worker thread subsequently removes the work item from the queue and calls the work item's EvtWorkItem callback function. The system removes the work items in the order that they were added to the queue.
Wdk 1.7 后的版本可以重用work-Item,即重入队列WdfWorkItemEnqueue
(56)WDFWORKITEM对象
许多函数必须在PASSIVE_LEVER中断级别上执行，但有时候，所有的例程的运行级别大于PASSIVE_LEVER,怎样解决这个问题，降低IRQL肯定不行，不过如果运行在IRQL<=DISPATCH_LEVER级别上，则可以排队一个工作项(work-item)，之后这个工作项会请求一个回调例程。回调将发生在PASSIVE_LEVER级别上，在由操作系统所拥有的一个工作项线程的环境中运行。
VOID WdfWorkitemFlush(In WDFWORKITEM WorkItem)
等待工作项结束，PASSIVE_LEVEL中断级别调用。
（57）WdfWorkItemGetParentObject
函数功能：returns the framework object that a specified work item is associated with.
WDFOBJECT WdfWorkItemGetParentObject(
[in] WDFWORKITEM WorkItem
);
Parameters
WorkItem [in]
A handle to a framework work-item object that is obtained from a previous call to WdfWorkItemCreate.
Return Value
WdfWorkItemGetParentObject returns a handle to the framework object that the driver specified as the ParentObject member of the driver's WDF_OBJECT_ATTRIBUTES structure when the driver previously called WdfWorkItemCreate.
typedef struct _WDF_OBJECT_ATTRIBUTES {
ULONG Size;
PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
WDF_EXECUTION_LEVEL ExecutionLevel;
WDF_SYNCHRONIZATION_SCOPE SynchronizationScope;
WDFOBJECT ParentObject;
size_t ContextSizeOverride;
PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;
(58)WDF支持bulk 和中断端点及默认的端点0.为了和同步端点进行通信，KMDF驱动创建一个URB,USBD function格式化URB，采用WDF函数将URB插入I/O request object, 采用WdfRequestSend函数发送到I/O target。具体例子见Usbsamp的Isorwr.c。
WDF drivers for USB devices should use the specialized USB I/O target support that both UMDF and KMDF provide. WDF defines three types of objects for use with USB I/O targets:
· A USB target device object represents a USB device and provides methods for retrieving information about the device and sending control requests to the device.
· A USB interface object represents an individual interface and supports methods with which a driver can select an alternate setting and retrieve information about the setting.
· A USB target pipe object represents an individual pipe—that is, an endpoint that is configured in the current alternate setting for an interface.
A driver creates target device, interface, and target pipe objects during USB configuration, which typically occurs in the driver’s prepare hardware callback. Consequently:
· A UMDF function driver for a USB device must implement the IPnpCallbackHardware interface on the device callback object.
· A KMDF driver must register the EvtDeviceD0Entry, EvtDeviceD0Exit, and EvtPrepareHardware callbacks.
(59) WdfUsbTargetDeviceCreate
函数功能：creates a framework USB device object for a specified framework device object and opens the USB device for I/O operations.
NTSTATUS WdfUsbTargetDeviceCreate(
[in] WDFDEVICE Device,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFUSBDEVICE *UsbDevice
);
Parameters
Device [in]
A handle to a framework device object.
Attributes [in, optional]
A pointer to a caller-supplied WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new USB device object. (The structure's ParentObject member must be NULL.) This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
UsbDevice [out]
A pointer to a location that receives a handle to the new framework USB device object.
Return Value
returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:
WDF also supports methods that perform the following types of device-specific requests for the USB device I/O target:
· Format and send device I/O control requests to the control pipe.
· Retrieve other information about the device.
· Reset and cycle power on the port. (KMDF only)
· Format and send WDM URBs. (KMDF only)
（60）How to Send an I/O Request to a USB I/O Target
To send an I/O request to a USB I/O target, a driver follows the same steps as for any other I/O target:
1. Create the request or use a request that the framework delivered.
2. Set up the memory objects and buffers for the request.
3. Format the request.
4. Set an I/O completion callback for the request, if appropriate.
5. Send the request.
WDF provides USB-specific methods to format the request, to send certain types of requests, and to retrieve completion parameters.
（61）WdfUsbTargetDeviceFormatRequestForCyclePort
函数：builds a power-cycle request for the port to which a specified device is attached, but it does not send the request.
NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request
);
Parameters
UsbDevice [in]
A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreate.
Request [in]
A handle to a framework request object. For more information, see the following Remarks section.
（62）WdfUsbTargetDeviceCyclePortSynchronously
函数功能；power-cycles the USB port to which a specified device is attached
NTSTATUS WdfUsbTargetDeviceCyclePortSynchronously(
[in] WDFUSBDEVICE UsbDevice
);
参数说明：
Parameters
UsbDevice [in]
A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreate.
Return Value
returns the I/O target's completion status value if the operation succeeds.
（63）send a request to a USB I/O target, a KMDF driver uses the methods shown in:
| To send this type of request … |
Use this method … |
| Cycle power on port (asynchronous) |
WdfUsbTargetDeviceFormatRequestForCyclePort and WdfRequestSend |
| Cycle power on port (synchronous) |
WdfUsbTargetDeviceCyclePortSynchronously |
| Device I/O control (asynchronous) |
WdfUsbTargetDeviceFormatRequestForControlTransfer and WdfRequestSend |
| Device I/O control (synchronous) |
WdfUsbTargetDeviceSendControlTransferSynchronously |
| Get string descriptor (synchronous or asynchronous) |
WdfUsbTargetDeviceFormatRequestForString and WdfRequestSend |
| Reset port (synchronous only) |
WdfUsbTargetDeviceResetPortSynchronously |
| URB (asynchronous) |
WdfUsbTargetDeviceFormatRequestForRead and WdfRequestSend |
| URB (synchronous) |
WdfUsbTargetDeviceSendUrbSynchronously |
| To send this type of request … |
Use this method … |
| Abort synchronous) |
WdfUsbTargetPipeAbortSynchronously |
| Abort (asynchronous) |
WdfUsbTargetPipeFormatRequestForAbort and WdfRequestSend |
| Read (asynchronous) |
WdfUsbTargetPipeFormatRequestForRead and WdfRequestSend |
| Read (synchronous) |
WdfUsbTargetPipeReadSynchronously |
| Reset (asynchronous) |
WdfUsbTargetPipeFormatRequestForReset and WdfRequestSend |
| Reset (synchronous) |
WdfUsbTargetPipeResetSynchronously |
| URB (asynchronous) |
WdfUsbTargetPipeFormatRequestForUrb and WdfRequestSend |
| URB (synchronous) |
WdfUsbTargetPipeSendUrbSynchronously |
| Write (asynchronous) |
WdfUsbTargetPipeFormatRequestForWrite and WdfRequestSend |
| Write (synchronous) |
WdfUsbTargetPipeWriteSynchronously |
(64) 'Developing drivers with the Windows Driver Framework'
(65)WDM和WDF 比较如下：
EvtPrepareHardware |
↑IRP_MN_START_DEVICE |
EvtReleaseHardware |
↓IRP_MN_STOP_DEVICE ↓IRP_MN_SURPRISE_REMOVAL ↓IRP_MN_REMOVE_DEVICE |
EvtDeviceD0Entry |
↑IRP_MN_START_DEVICE ↑ IRP_MN_SET_POWER – D0 Irp |
EvtDeviceD0Exit |
↓ IRP_MN_SET_POWER – Dx Irp ↓IRP_MN_SURPRISE_REMOVAL ↓IRP_MN_REMOVE_DEVICE ↓IRP_MN_STOP_DEVICE |
EvtDeviceContextCleanup |
↓IRP_MN_REMOVE_DEVICE |
WDFDRIVER |
Driver object |
WDFDEVICE |
Device object |
WDFQUEUE |
Cancel-safe queue/Dispatching /Serialization/Auto-locking/Synch with PnP |
WDFREQUEST |
IRP |
WDFINTERRUPT |
Interrupt |
WDFDPC |
DPC |
WDFWORKITEM |
Work item |
WDFDMAENABLER |
DMA adapter object |
WDFIOTARGET |
Sending I/O to another driver - IoCallDriver |
WDFWAITLOCK |
Event dispatcher object – passive level lock |
WDFSPINLOCK |
Spinlock |
WDFMEMORY |
Kernel pool - refcounted |
WDFKEY |
Registry access |
(66) WdfDeviceInitSetIoType
函数功能：sets the method that a driver will use to access the data buffers that are included in read and write requests for a specified device.
VOID WdfDeviceInitSetIoType(
[in] PWDFDEVICE_INIT DeviceInit,
[in] WDF_DEVICE_IO_TYPE IoType
);
参数：
DeviceInit [in]
A pointer to a WDFDEVICE_INIT structure.
IoType [in]
A WDF_DEVICE_IO_TYPE-typed enumerator that identifies the method that the driver will use to access data buffers that it receives for read and write requests.
typedef enum _WDF_DEVICE_IO_TYPE {
WdfDeviceIoUndefined = 0,
WdfDeviceIoNeither = 1,
WdfDeviceIoBuffered = 2,
WdfDeviceIoDirect = 3
} WDF_DEVICE_IO_TYPE, *PWDF_DEVICE_IO_TYPE;
Constants
WdfDeviceIoUndefined
Reserved for system use.
WdfDeviceIoNeither
Neither buffered nor direct I/O will be used to access data buffers.
WdfDeviceIoBuffered
Buffered I/O will be used to access data buffers.
WdfDeviceIoDirect
Direct I/O will be used to access data buffers.
评论：
If a driver calls WdfDeviceInitSetIoType, it must do so before it calls WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.
调用示例：
WdfDeviceInitSetIoType(DeviceInit, WdfDeviceIoBuffered); //设置缓冲区读写类型WdfDeviceInitSetIoType(DeviceInit, WdfDeviceIoDirect);
(67) WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
函数功能：initializes a driver's WDF_OBJECT_ATTRIBUTES structure and inserts an object's driver-defined context information into the structure.
void WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
WDF_OBJECT_ATTRIBUTES_INIT _attributes,
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE _contexttype
);
参数：
_attributes
The name of an object's WDF_OBJECT_ATTRIBUTES structure.
_contexttype
The name of a driver-defined structure that describes the contents of the object's context space.
(68) WDF_DEVICE_PNP_CAPABILITIES_INIT
函数功能：initializes a WDF_DEVICE_PNP_CAPABILITIES structure.
VOID WDF_DEVICE_PNP_CAPABILITIES_INIT(
__out PWDF_DEVICE_PNP_CAPABILITIES Caps
);
Caps [out]
A pointer to a driver-supplied WDF_DEVICE_PNP_CAPABILITIES structure.
评论：
The WDF_DEVICE_PNP_CAPABILITIES_INIT function zeros the specified WDF_DEVICE_PNP_CAPABILITIES structure, sets the structure's Size member, and sets other members to default values.
typedef struct _WDF_DEVICE_PNP_CAPABILITIES {
ULONG Size;
WDF_TRI_STATE LockSupported;
WDF_TRI_STATE EjectSupported;
WDF_TRI_STATE Removable;
WDF_TRI_STATE DockDevice;
WDF_TRI_STATE UniqueID;
WDF_TRI_STATE SilentInstall;
WDF_TRI_STATE SurpriseRemovalOK;
WDF_TRI_STATE HardwareDisabled;
WDF_TRI_STATE NoDisplayInUI;
ULONG Address;
ULONG UINumber;
} WDF_DEVICE_PNP_CAPABILITIES, *PWDF_DEVICE_PNP_CAPABILITIES;
（69）WdfDeviceSetPnpCapabilities
函数功能：reports a device's Plug and Play capabilities
VOID WdfDeviceSetPnpCapabilities(
[in] WDFDEVICE Device,
[in] PWDF_DEVICE_PNP_CAPABILITIES PnpCapabilities
);
参数：
Device [in]
A handle to a framework device object.
PnpCapabilities [in]
A pointer to a driver-allocated WDF_DEVICE_PNP_CAPABILITIES structure.
评论：
A driver typically calls from within one of the following callback functions:
· EvtDriverDeviceAdd
· EvtDevicePrepareHardware
· EvtDeviceD0Entry (if the PreviousState parameter's value is WdfPowerDeviceD3Final)
· EvtDeviceSelfManagedIoInit
· EvtChildListCreateDevice
WDF_DEVICE_PNP_CAPABILITIES pnpCaps;
WDF_DEVICE_PNP_CAPABILITIES_INIT(&pnpCaps);
pnpCaps.SurpriseRemovalOK = WdfTrue;
WdfDeviceSetPnpCapabilities(
device,
&pnpCaps
);
(70) WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE
函数功能：initializes a driver's WDF_IO_QUEUE_CONFIG structure.
VOID WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(
__out PWDF_IO_QUEUE_CONFIG Config,
__in WDF_IO_QUEUE_DISPATCH_TYPE DispatchType
);
Config [out]
A pointer to the driver's WDF_IO_QUEUE_CONFIG structure.
DispatchType [in]
A WDF_IO_QUEUE_DISPATCH_TYPE enumerator that identifies the request dispatching type for the queue.
typedef struct _WDF_IO_QUEUE_CONFIG {
ULONG Size;
WDF_IO_QUEUE_DISPATCH_TYPE DispatchType;
WDF_TRI_STATE PowerManaged;
BOOLEAN AllowZeroLengthRequests;
BOOLEAN DefaultQueue;
PFN_WDF_IO_QUEUE_IO_DEFAULT EvtIoDefault;
PFN_WDF_IO_QUEUE_IO_READ EvtIoRead;
PFN_WDF_IO_QUEUE_IO_WRITE EvtIoWrite;
PFN_WDF_IO_QUEUE_IO_DEVICE_CONTROL EvtIoDeviceControl;
PFN_WDF_IO_QUEUE_IO_INTERNAL_DEVICE_CONTROL EvtIoInternalDeviceControl;
PFN_WDF_IO_QUEUE_IO_STOP EvtIoStop;
PFN_WDF_IO_QUEUE_IO_RESUME EvtIoResume;
PFN_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtIoCanceledOnQueue;
union {
struct {
ULONG NumberOfPresentedRequests;
} Parallel;
} Settings;
} WDF_IO_QUEUE_CONFIG, *PWDF_IO_QUEUE_CONFIG;
(71) WdfDeviceConfigureRequestDispatching
函数功能：causes the framework to queue a specified type of I/O requests to a specified I/O queue.
NTSTATUS WdfDeviceConfigureRequestDispatching(
[in] WDFDEVICE Device,
[in] WDFQUEUE Queue,
[in] WDF_REQUEST_TYPE RequestType
);
参数：
Device [in]
Supplies a handle to a framework device object.
Queue [in]
Supplies a handle to a framework queue object.
RequestType [in]
Supplies a WDF_REQUEST_TYPE-typed enumerator that identifies the type of request to be queued. The only valid enumerators are:
WdfRequestTypeCreate
WdfRequestTypeRead
WdfRequestTypeWrite
WdfRequestTypeDeviceControl
WdfRequestTypeDeviceControlInternal
返回值：
If the operation succeeds, the method returns STATUS_SUCCESS. Additional return values include:
评论：
Each call to WdfDeviceConfigureRequestDispatching specifies one request type. If you want a single I/O queue to receive multiple types of requests (for example, read and write requests), your driver can call WdfDeviceConfigureRequestDispatching multiple times for a single I/O queue.
（72）WdfUsbTargetDeviceRetrieveInformation
函数功能：method retrieves information about the USB device that is associated with a specified framework USB device object.
NTSTATUS WdfUsbTargetDeviceRetrieveInformation(
[in] WDFUSBDEVICE UsbDevice,
[out] PWDF_USB_DEVICE_INFORMATION Information
);
参数：
Parameters
UsbDevice [in]
A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreate.
Information [out]
A pointer to a caller-allocated WDF_USB_DEVICE_INFORMATION structure that receives USB device information.
typedef struct _WDF_USB_DEVICE_INFORMATION {
ULONG Size;
USBD_VERSION_INFORMATION UsbdVersionInformation;
ULONG HcdPortCapabilities;
ULONG Traits;
} WDF_USB_DEVICE_INFORMATION, *PWDF_USB_DEVICE_INFORMATION;
参数：
Size
The size, in bytes, of this structure.
UsbdVersionInformation
A USBD_VERSION_INFORMATION structure that provides version information for the host controller driver (HCD) and the USB specification version that the device supports.
HcdPortCapabilities
A set of bit flags that identify HCD-supported port capabilities. The flags are defined in Usbbusif.h. Flag names have a prefix of USB_HCD_CAPS_. The only flag that is currently available is USB_HCD_CAPS_SUPPORTS_RT_THREADS. If this flag is set, the host controller supports real-time threads.
Traits
A set of bit flags that identify device traits. The flags are defined by the WDF_USB_DEVICE_TRAITS enumeration.
typedef enum _WDF_USB_DEVICE_TRAITS {
WDF_USB_DEVICE_TRAIT_SELF_POWERED = 0x00000001,
WDF_USB_DEVICE_TRAIT_REMOTE_WAKE_CAPABLE = 0x00000002,
WDF_USB_DEVICE_TRAIT_AT_HIGH_SPEED = 0x00000004
} WDF_USB_DEVICE_TRAITS;
参数：
WDF_USB_DEVICE_TRAIT_SELF_POWERED
The device is self-powered.
WDF_USB_DEVICE_TRAIT_REMOTE_WAKE_CAPABLE
The device has a remote wakeup capability.
WDF_USB_DEVICE_TRAIT_AT_HIGH_SPEED
The device is operating at high speed.
The WDF_USB_DEVICE_TRAITS enumeration is used in the WDF_USB_DEVICE_INFORMATION structure.