Windows 驱动开发 - 8

    最后的一点开发工作：跟踪驱动。

一、驱动跟踪

    1. 包含TMH头文件

1. #include "step5.tmh"

    2. 初始化跟踪

            在DriverEntry中初始化。

1. WPP_INIT_TRACING( DriverObject, RegistryPath );
   
2. 
   
3.     WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
   
4. 
   
5.     attributes.EvtCleanupCallback = EvtDriverContextCleanup;

        (1) WPP跟踪初始化

                 WPP_INIT_TRACING

1. VOID
   
2.   WPP_INIT_TRACING(
   
3.     IN PDRIVER_OBJECT DriverObject,
   
4.     IN OPT PUNICODE_STRING RegistryPath
   
5.     );

        (2) WDF对象属性初始化

                WDF_OBJECT_ATTRIBUTES_INIT

1. VOID WDF_OBJECT_ATTRIBUTES_INIT(
   
2.   _Out_ PWDF_OBJECT_ATTRIBUTES Attributes
   
3. );

        (3) 设置回调事件 

              EvtDriverContextCleanup

1. EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
   
2. 
   
3. VOID EvtCleanupCallback(
   
4.   _In_ WDFOBJECT Object
   
5. )
   
6. { ... }

3. 清理跟踪

        使用WPP_CLEANUP宏。

1. VOID
   
2. WPP_CLEANUP(
   
3.     IN PDRIVER_OBJECT DriverObject
   
4. );

(1) 清理WDM驱动对象

       WdfDriverWdmGetDriverObject

1. PDRIVER_OBJECT WdfDriverWdmGetDriverObject(
   
2.   [in] WDFDRIVER Driver
   
3. );

    Windows 驱动开发编后话：

        我们的开发工作到此已经完成了。但是，这不是工作状态的驱动程序。

        后继还要进行IRQL、EvtIoStop、电源的细化处理、IOTarget（包括EvtIoDeviceControl）以及inf文件等等。

附：

step5.c

1. /*++
   
2. 
   
3. Step5: This steps shows:
   
4.        1) How to map KdPrint function to do WPP tracing
   
5. --*/
   
6. 
   
7. #include <stdarg.h> // To avoid build errors on Win2K due to WPP
   
8. #include "ntddk.h"
   
9. #include "wdf.h"
   
10. #include "prototypes.h"
    
11. #pragma warning(disable:4200) // suppress nameless struct/union warning
    
12. #pragma warning(disable:4201) // suppress nameless struct/union warning
    
13. #pragma warning(disable:4214) // suppress bit field types other than int warning
    
14. #include "usbdi.h"
    
15. #pragma warning(default:4200)
    
16. #pragma warning(default:4201)
    
17. #pragma warning(default:4214)
    
18. #include "wdfusb.h"
    
19. #include "initguid.h"
    
20. 
    
21. #include "step5.tmh"
    
22. 
    
23. DEFINE_GUID(GUID_DEVINTERFACE_OSRUSBFX2, // Generated using guidgen.exe
    
24.    0x573e8c73, 0xcb4, 0x4471, 0xa1, 0xbf, 0xfa, 0xb2, 0x6c, 0x31, 0xd3, 0x84);
    
25. // {573E8C73-0CB4-4471-A1BF-FAB26C31D384}
    
26. 
    
27. #define IOCTL_INDEX 0x800
    
28. #define FILE_DEVICE_OSRUSBFX2 0x65500
    
29. #define USBFX2LK_SET_BARGRAPH_DISPLAY 0xD8
    
30. #define BULK_OUT_ENDPOINT_INDEX 1
    
31. #define BULK_IN_ENDPOINT_INDEX 2
    
32. #define IOCTL_OSRUSBFX2_SET_BAR_GRAPH_DISPLAY CTL_CODE(FILE_DEVICE_OSRUSBFX2,\
    
33.                                                     IOCTL_INDEX + 5, \
    
34.                                                     METHOD_BUFFERED, \
    
35.                                                     FILE_WRITE_ACCESS)
    
36. typedef struct _DEVICE_CONTEXT {
    
37.   WDFUSBDEVICE UsbDevice;
    
38.   WDFUSBINTERFACE UsbInterface;
    
39.   WDFUSBPIPE BulkReadPipe;
    
40.   WDFUSBPIPE BulkWritePipe;
    
41. } DEVICE_CONTEXT, *PDEVICE_CONTEXT;
    
42. 
    
43. WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DEVICE_CONTEXT, GetDeviceContext)
    
44. 
    
45. 
    
46. NTSTATUS
    
47. DriverEntry(
    
48.     IN PDRIVER_OBJECT DriverObject,
    
49.     IN PUNICODE_STRING RegistryPath
    
50.     )
    
51. {
    
52.     WDF_DRIVER_CONFIG config;
    
53.     NTSTATUS status;
    
54.     WDF_OBJECT_ATTRIBUTES attributes;
    
55. 
    
56.     WPP_INIT_TRACING( DriverObject, RegistryPath );
    
57. 
    
58.     KdPrint(("DriverEntry of Step5\n"));
    
59. 
    
60.     WDF_DRIVER_CONFIG_INIT(&config, EvtDeviceAdd);
    
61. 
    
62.     //
    
63.     // Register a cleanup callback so that we can call WPP_CLEANUP when
    
64.     // the framework driver object is deleted during driver unload.
    
65.     //
    
66.     WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    
67.     attributes.EvtCleanupCallback = EvtDriverContextCleanup;
    
68. 
    
69.     status = WdfDriverCreate(DriverObject,
    
70.                         RegistryPath,
    
71.                         &attributes,
    
72.                         &config,
    
73.                         WDF_NO_HANDLE
    
74.                         );
    
75. 
    
76.     if (!NT_SUCCESS(status)) {
    
77.         KdPrint(("WdfDriverCreate failed %!STATUS!\n", status));
    
78.         //
    
79.         // Cleanup tracing here because DriverContextCleanup will not be called
    
80.         // as we have failed to create WDFDRIVER object itself.
    
81.         // Please note that if your return failure from DriverEntry after the
    
82.         // WDFDRIVER object is created successfully, you don't have to
    
83.         // call WPP cleanup because in those cases DriverContextCleanup
    
84.         // will be executed when the framework deletes the DriverObject.
    
85.         //
    
86.         WPP_CLEANUP(DriverObject);
    
87.     }
    
88. 
    
89.     return status;
    
90. }
    
91. 
    
92. VOID
    
93. EvtDriverContextCleanup(
    
94.     IN WDFDRIVER Driver
    
95.     )
    
96. {
    
97.     WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));
    
98. }
    
99. 
    
100. NTSTATUS
     
101. EvtDeviceAdd(
     
102.     IN WDFDRIVER Driver,
     
103.     IN PWDFDEVICE_INIT DeviceInit
     
104.     )
     
105. {
     
106.     WDF_OBJECT_ATTRIBUTES attributes;
     
107.     NTSTATUS status;
     
108.     WDFDEVICE device;
     
109.     PDEVICE_CONTEXT pDevContext;
     
110.     WDF_PNPPOWER_EVENT_CALLBACKS pnpPowerCallbacks;
     
111.     WDF_IO_QUEUE_CONFIG ioQueueConfig;
     
112. 
     
113.     UNREFERENCED_PARAMETER(Driver);
     
114. 
     
115.     WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
     
116.     pnpPowerCallbacks.EvtDevicePrepareHardware = EvtDevicePrepareHardware;
     
117.     WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &pnpPowerCallbacks);
     
118. 
     
119.     WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, DEVICE_CONTEXT);
     
120. 
     
121.     status = WdfDeviceCreate(&DeviceInit, &attributes, &device);
     
122.     if (!NT_SUCCESS(status)) {
     
123.         KdPrint(("WdfDeviceCreate failed %!STATUS!\n", status));
     
124.         return status;
     
125.     }
     
126. 
     
127.     pDevContext = GetDeviceContext(device);
     
128. 
     
129.     status = WdfDeviceCreateDeviceInterface(device,
     
130.                                 (LPGUID) &GUID_DEVINTERFACE_OSRUSBFX2,
     
131.                                 NULL);// Reference String
     
132.     if (!NT_SUCCESS(status)) {
     
133.         KdPrint(("WdfDeviceCreateDeviceInterface failed %!STATUS!\n", status));
     
134.         return status;
     
135.     }
     
136. 
     
137.     WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&ioQueueConfig,
     
138.                                     WdfIoQueueDispatchParallel);
     
139. 
     
140.     ioQueueConfig.EvtIoDeviceControl = EvtIoDeviceControl;
     
141.     ioQueueConfig.EvtIoRead = EvtIoRead;
     
142.     ioQueueConfig.EvtIoWrite = EvtIoWrite;
     
143. 
     
144.     status = WdfIoQueueCreate(device,
     
145.                          &ioQueueConfig,
     
146.                          WDF_NO_OBJECT_ATTRIBUTES,
     
147.                          WDF_NO_HANDLE);
     
148.     if (!NT_SUCCESS(status)) {
     
149.         KdPrint(("WdfIoQueueCreate failed %!STATUS!\n", status));
     
150.         return status;
     
151.     }
     
152. 
     
153.     return status;
     
154. }
     
155. 
     
156. 
     
157. NTSTATUS
     
158. EvtDevicePrepareHardware(
     
159.     IN WDFDEVICE Device,
     
160.     IN WDFCMRESLIST ResourceList,
     
161.     IN WDFCMRESLIST ResourceListTranslated
     
162.     )
     
163. {
     
164.     NTSTATUS status;
     
165.     PDEVICE_CONTEXT pDeviceContext;
     
166.     WDF_USB_DEVICE_SELECT_CONFIG_PARAMS configParams;
     
167.     WDFUSBPIPE pipe;
     
168. 
     
169.     UNREFERENCED_PARAMETER(ResourceList);
     
170.     UNREFERENCED_PARAMETER(ResourceListTranslated);
     
171. 
     
172.     pDeviceContext = GetDeviceContext(Device);
     
173.     
     
174.     //
     
175.     // Create the USB device if it is not already created.
     
176.     //
     
177.     if (pDeviceContext->UsbDevice == NULL) {
     
178.         status = WdfUsbTargetDeviceCreate(Device,
     
179.                                     WDF_NO_OBJECT_ATTRIBUTES,
     
180.                                     &pDeviceContext->UsbDevice);
     
181.         if (!NT_SUCCESS(status)) {
     
182.             KdPrint(("WdfUsbTargetDeviceCreate failed %!STATUS!\n", status));
     
183.             return status;
     
184.         }
     
185.     }
     
186. 
     
187.     WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);
     
188. 
     
189.     status = WdfUsbTargetDeviceSelectConfig(pDeviceContext->UsbDevice,
     
190.                                         WDF_NO_OBJECT_ATTRIBUTES,
     
191.                                         &configParams);
     
192.     if(!NT_SUCCESS(status)) {
     
193.         KdPrint(("WdfUsbTargetDeviceSelectConfig failed %!STATUS!\n", status));
     
194.         return status;
     
195.     }
     
196. 
     
197.     pDeviceContext->UsbInterface =
     
198.                 configParams.Types.SingleInterface.ConfiguredUsbInterface;
     
199. 
     
200.     pipe = WdfUsbInterfaceGetConfiguredPipe(pDeviceContext->UsbInterface,
     
201.                                        2, //PipeIndex,
     
202.                                        NULL);// pipeInfo
     
203. 
     
204.     pDeviceContext->BulkReadPipe = WdfUsbInterfaceGetConfiguredPipe(
     
205.                                                   pDeviceContext->UsbInterface,
     
206.                                                   BULK_IN_ENDPOINT_INDEX,
     
207.                                                   NULL);// pipeInfo
     
208. 
     
209.     WdfUsbTargetPipeSetNoMaximumPacketSizeCheck(pDeviceContext->BulkReadPipe);
     
210. 
     
211.     pDeviceContext->BulkWritePipe = WdfUsbInterfaceGetConfiguredPipe(
     
212.                                                   pDeviceContext->UsbInterface,
     
213.                                                   BULK_OUT_ENDPOINT_INDEX,
     
214.                                                   NULL);// pipeInfo
     
215. 
     
216.     WdfUsbTargetPipeSetNoMaximumPacketSizeCheck(pDeviceContext->BulkWritePipe);
     
217. 
     
218.     return status;
     
219. }
     
220. 
     
221. VOID
     
222. EvtIoDeviceControl(
     
223.     IN WDFQUEUE Queue,
     
224.     IN WDFREQUEST Request,
     
225.     IN size_t OutputBufferLength,
     
226.     IN size_t InputBufferLength,
     
227.     IN ULONG IoControlCode
     
228.     )
     
229. {
     
230.     WDFDEVICE device;
     
231.     PDEVICE_CONTEXT pDevContext;
     
232.     size_t bytesTransferred = 0;
     
233.     NTSTATUS status;
     
234.     WDF_USB_CONTROL_SETUP_PACKET controlSetupPacket;
     
235.     WDF_MEMORY_DESCRIPTOR memDesc;
     
236.     WDFMEMORY memory;
     
237.     WDF_REQUEST_SEND_OPTIONS sendOptions;
     
238. 
     
239.     UNREFERENCED_PARAMETER(InputBufferLength);
     
240.     UNREFERENCED_PARAMETER(OutputBufferLength);
     
241. 
     
242.     device = WdfIoQueueGetDevice(Queue);
     
243.     pDevContext = GetDeviceContext(device);
     
244. 
     
245.     switch(IoControlCode) {
     
246. 
     
247.     case IOCTL_OSRUSBFX2_SET_BAR_GRAPH_DISPLAY:
     
248. 
     
249.         if(InputBufferLength < sizeof(UCHAR)) {
     
250.             status = STATUS_BUFFER_OVERFLOW;
     
251.             bytesTransferred = sizeof(UCHAR);
     
252.             break;
     
253.         }
     
254. 
     
255.         status = WdfRequestRetrieveInputMemory(Request, &memory);
     
256.         if (!NT_SUCCESS(status)) {
     
257.             KdPrint(("WdfRequestRetrieveMemory failed %!STATUS!", status));
     
258.             break;
     
259.         }
     
260. 
     
261.         WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(&controlSetupPacket,
     
262.                                         BmRequestHostToDevice,
     
263.                                         BmRequestToDevice,
     
264.                                         USBFX2LK_SET_BARGRAPH_DISPLAY, // Request
     
265.                                         0, // Value
     
266.                                         0); // Index
     
267. 
     
268.         WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memDesc, memory, NULL);
     
269. 
     
270.        //
     
271.        // Send the I/O with a timeout to avoid hanging the calling
     
272.        // thread indefinitely.
     
273.        //
     
274.         WDF_REQUEST_SEND_OPTIONS_INIT(&sendOptions,
     
275.                                   WDF_REQUEST_SEND_OPTION_TIMEOUT);
     
276. 
     
277.         WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(&sendOptions,
     
278.                                          WDF_REL_TIMEOUT_IN_MS(100));
     
279. 
     
280.         status = WdfUsbTargetDeviceSendControlTransferSynchronously(
     
281.                                         pDevContext->UsbDevice,
     
282.                                         NULL, // Optional WDFREQUEST
     
283.                                         &sendOptions, // PWDF_REQUEST_SEND_OPTIONS
     
284.                                         &controlSetupPacket,
     
285.                                         &memDesc,
     
286.                                         (PULONG)&bytesTransferred);
     
287.         if (!NT_SUCCESS(status)) {
     
288.             KdPrint(("SendControlTransfer failed %!STATUS!", status));
     
289.             break;
     
290.         }
     
291.         break;
     
292. 
     
293.     default:
     
294.         status = STATUS_INVALID_DEVICE_REQUEST;
     
295.         break;
     
296.     }
     
297. 
     
298.     WdfRequestCompleteWithInformation(Request, status, bytesTransferred);
     
299. 
     
300.     return;
     
301. }
     
302. 
     
303. VOID
     
304. EvtIoRead(
     
305.     IN WDFQUEUE Queue,
     
306.     IN WDFREQUEST Request,
     
307.     IN size_t Length
     
308.     )
     
309. {
     
310.     WDFUSBPIPE pipe;
     
311.     NTSTATUS status;
     
312.     WDFMEMORY reqMemory;
     
313.     PDEVICE_CONTEXT pDeviceContext;
     
314.     BOOLEAN ret;
     
315. 
     
316.     UNREFERENCED_PARAMETER(Length);
     
317. 
     
318.     pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
     
319. 
     
320.     pipe = pDeviceContext->BulkReadPipe;
     
321. 
     
322.     status = WdfRequestRetrieveOutputMemory(Request, &reqMemory);
     
323.     if(!NT_SUCCESS(status)){
     
324.         goto Exit;
     
325.     }
     
326. 
     
327.     status = WdfUsbTargetPipeFormatRequestForRead(pipe,
     
328.                                         Request,
     
329.                                         reqMemory,
     
330.                                         NULL // Offsets
     
331.                                         );
     
332.     if (!NT_SUCCESS(status)) {
     
333.         goto Exit;
     
334.     }
     
335. 
     
336.     WdfRequestSetCompletionRoutine(
     
337.                             Request,
     
338.                             EvtRequestReadCompletionRoutine,
     
339.                             pipe);
     
340. 
     
341.     ret = WdfRequestSend(Request,
     
342.                     WdfUsbTargetPipeGetIoTarget(pipe),
     
343.                     WDF_NO_SEND_OPTIONS);
     
344.     if (ret == FALSE) {
     
345.         status = WdfRequestGetStatus(Request);
     
346.         goto Exit;
     
347.     } else {
     
348.         return;
     
349.     }
     
350. 
     
351. Exit:
     
352.     WdfRequestCompleteWithInformation(Request, status, 0);
     
353. 
     
354.     return;
     
355. }
     
356. 
     
357. VOID
     
358. EvtRequestReadCompletionRoutine(
     
359.     IN WDFREQUEST Request,
     
360.     IN WDFIOTARGET Target,
     
361.     PWDF_PEQUEST_COMPLETION_PARAMS CompletionParams,
     
362.     IN WDFCONTEXT Context
     
363.     )
     
364. {
     
365.     NTSTATUS status;
     
366.     size_t bytesRead = 0;
     
367.     PWDF_USB_REQUEST_COMPLETION_PARAMS usbCompletionParams;
     
368. 
     
369.     UNREFERENCED_PARAMETER(Target);
     
370.     UNREFERENCED_PARAMETER(Context);
     
371. 
     
372.     status = CompletionParams->IoStatus.Status;
     
373. 
     
374.     usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
     
375. 
     
376.     bytesRead = usbCompletionParams->Parameters.PipeRead.Length;
     
377. 
     
378.     if (NT_SUCCESS(status)){
     
379.         KdPrint(("Number of bytes read: %I64d\n", (INT64)bytesRead));
     
380.     } else {
     
381.         KdPrint(("Read failed - request status %!STATUS! UsbdStatus %!STATUS!\n",
     
382.                 status, usbCompletionParams->UsbdStatus));
     
383. 
     
384.     }
     
385. 
     
386.     WdfRequestCompleteWithInformation(Request, status, bytesRead);
     
387. 
     
388.     return;
     
389. }
     
390. 
     
391. VOID
     
392. EvtIoWrite(
     
393.     IN WDFQUEUE Queue,
     
394.     IN WDFREQUEST Request,
     
395.     IN size_t Length
     
396.     )
     
397. {
     
398.     NTSTATUS status;
     
399.     WDFUSBPIPE pipe;
     
400.     WDFMEMORY reqMemory;
     
401.     PDEVICE_CONTEXT pDeviceContext;
     
402.     BOOLEAN ret;
     
403. 
     
404.     UNREFERENCED_PARAMETER(Length);
     
405. 
     
406.     pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
     
407. 
     
408.     pipe = pDeviceContext->BulkWritePipe;
     
409. 
     
410.     status = WdfRequestRetrieveInputMemory(Request, &reqMemory);
     
411.     if(!NT_SUCCESS(status)){
     
412.         goto Exit;
     
413.     }
     
414. 
     
415.     status = WdfUsbTargetPipeFormatRequestForWrite(pipe,
     
416.                                               Request,
     
417.                                               reqMemory,
     
418.                                               NULL); // Offset
     
419.     if (!NT_SUCCESS(status)) {
     
420.         goto Exit;
     
421.     }
     
422. 
     
423.     WdfRequestSetCompletionRoutine(
     
424.                             Request,
     
425.                             EvtRequestWriteCompletionRoutine,
     
426.                             pipe);
     
427. 
     
428.     ret = WdfRequestSend(Request,
     
429.                     WdfUsbTargetPipeGetIoTarget(pipe),
     
430.                     WDF_NO_SEND_OPTIONS);
     
431.     if (ret == FALSE) {
     
432.         status = WdfRequestGetStatus(Request);
     
433.         goto Exit;
     
434.     } else {
     
435.         return;
     
436.     }
     
437. 
     
438. Exit:
     
439.     WdfRequestCompleteWithInformation(Request, status, 0);
     
440. 
     
441.     return;
     
442. }
     
443. 
     
444. VOID
     
445. EvtRequestWriteCompletionRoutine(
     
446.     IN WDFREQUEST Request,
     
447.     IN WDFIOTARGET Target,
     
448.     PWDF_REQUEST_COMPLETION_PARAMS CompletionParams,
     
449.     IN WDFCONTEXT Context
     
450.     )
     
451. {
     
452.     NTSTATUS status;
     
453.     size_t bytesWritten = 0;
     
454.     PWDF_USB_REQUEST_COMPLETION_PARAMS usbCompletionParams;
     
455. 
     
456.     UNREFERENCED_PARAMETER(Target);
     
457.     UNREFERENCED_PARAMETER(Context);
     
458. 
     
459.     status = CompletionParams->IoStatus.Status;
     
460. 
     
461.     usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
     
462. 
     
463.     bytesWritten = usbCompletionParams->Parameters.PipeWrite.Length;
     
464. 
     
465.     if (NT_SUCCESS(status)){
     
466.         KdPrint(("Number of bytes written: %I64d\n", (INT64)bytesWritten));
     
467.     } else {
     
468.         KdPrint(("Write failed: request Status %!STATUS! UsbdStatus %!STATUS!\n",
     
469.                 status, usbCompletionParams->UsbdStatus));
     
470.     }
     
471. 
     
472.     WdfRequestCompleteWithInformation(Request, status, bytesWritten);
     
473. 
     
474.     return;
     
475. }