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.