1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_USB_DRIVER_OBJECT_H__ 18 #define ANDROID_USB_DRIVER_OBJECT_H__ 19 /** \file 20 This file consists of declaration of class AndroidUsbDriverObject that 21 encapsulates our driver object. 22 */ 23 24 /// Globally accessible pointer to the driver object 25 extern class AndroidUsbDriverObject* global_driver_object; 26 27 /** AndroidUsbDriverObject class encapsulates driver object and provides 28 overall initialization / cleanup as well as management of globally used 29 resources. We use KMDF framework for this driver because it takes care of 30 most of the USB related "things" (like PnP, power management and other 31 stuff) so we can concentrate more on real functionality. This driver is 32 based on KMDF's usbsamp driver sample available at DDK's src\kmdf\usbsamp 33 directory. Instance of this class (always one) must be allocated from 34 NonPagedPool. 35 */ 36 class AndroidUsbDriverObject { 37 38 public: 39 /** \brief Driver initialization entry point. 40 41 This method is a "gate" to our driver class from main DriverEntry routine. 42 Since this method is called from within DriverEntry only it is placed in 43 "INIT" code segment. 44 This method is called at IRQL PASSIVE_LEVEL. 45 @param drv_object[in] Driver object passed to DriverEntry routine 46 @param reg_path[in] Path to the driver's Registry passed to DriverEntry 47 routine 48 @returns STATUS_SUCCESS on success or an appropriate error code. 49 */ 50 static NTSTATUS DriverEntry(PDRIVER_OBJECT drv_object, 51 PUNICODE_STRING reg_path); 52 53 private: 54 /** \brief Constructs driver object. 55 56 Constructor for driver class must be as light as possible. All 57 initialization that may fail must be deferred to OnDriverEntry method. 58 Since this method is called from within DriverEntry only it is placed in 59 "INIT" code segment. 60 This method is called at IRQL PASSIVE_LEVEL. 61 @param drv_object[in] Driver object passed to DriverEntry routine 62 @param reg_path[in] Path to the driver's Registry passed to DriverEntry 63 routine 64 */ 65 AndroidUsbDriverObject(PDRIVER_OBJECT drv_object, PUNICODE_STRING reg_path); 66 67 /** \brief Destructs driver object. 68 69 Destructor for driver class must be as light as possible. All 70 uninitialization must be done in OnDriverUnload method. 71 This method must be called at PASSIVE IRQL. 72 */ 73 ~AndroidUsbDriverObject(); 74 75 /** \brief Initializes instance of the driver object. 76 77 This method is called immediatelly after driver object has been 78 instantiated to perform actual initialization of the driver. Since this 79 method is called from within DriverEntry only it is placed in 80 "INIT" code segment. 81 This method is called at IRQL PASSIVE_LEVEL. 82 @param drv_object[in] Driver object passed to DriverEntry routine 83 @param reg_path[in] Path to the driver's Registry passed to DriverEntry 84 routine 85 @returns STATUS_SUCCESS on success or an appropriate error code. 86 */ 87 NTSTATUS OnDriverEntry(PDRIVER_OBJECT drv_object, PUNICODE_STRING reg_path); 88 89 /** \brief Actual handler for KMDF's AddDevice event 90 91 This method is called by the framework in response to AddDevice call from 92 the PnP manager. We create and initialize a device object to represent a 93 new instance of the device. 94 This method is called at IRQL PASSIVE_LEVEL. 95 @param device_init[in] A pointer to a framework-allocated WDFDEVICE_INIT 96 structure. 97 @return If the routine succeeds, it returns STATUS_SUCCESS. Otherwise, 98 it returns one of the error status values defined in ntstatus.h. 99 */ 100 NTSTATUS OnAddDevice(PWDFDEVICE_INIT device_init); 101 102 /** \brief Actual driver unload event handler. 103 104 This method is called when driver is being unloaded. 105 This method is called at IRQL PASSIVE_LEVEL. 106 */ 107 void OnDriverUnload(); 108 109 /** \brief KMDF's DeviceAdd event entry point 110 111 This callback is called by the framework in response to AddDevice call from 112 the PnP manager. We create and initialize a device object to represent a 113 new instance of the device. All the software resources should be allocated 114 in this callback. 115 This method is called at IRQL PASSIVE_LEVEL. 116 @param wdf_drv[in] WDF driver handle. 117 @param device_init[in] A pointer to a framework-allocated WDFDEVICE_INIT 118 structure. 119 @return If the routine succeeds, it returns STATUS_SUCCESS. Otherwise, 120 it returns one of the error status values defined in ntstatus.h. 121 */ 122 static NTSTATUS EvtDeviceAddEntry(WDFDRIVER wdf_drv, 123 PWDFDEVICE_INIT device_init); 124 125 /** \brief Driver unload event entry point. 126 127 Framework calls this callback when driver is being unloaded. 128 This method is called at IRQL PASSIVE_LEVEL. 129 */ 130 static VOID EvtDriverUnloadEntry(WDFDRIVER wdf_drv); 131 132 public: 133 134 /// Gets this driver's DRIVER_OBJECT driver_object()135 __forceinline PDRIVER_OBJECT driver_object() const { 136 return driver_object_; 137 } 138 139 /// Gets KMDF driver handle wdf_driver()140 __forceinline WDFDRIVER wdf_driver() const { 141 return wdf_driver_; 142 } 143 144 private: 145 /// This driver's driver object 146 PDRIVER_OBJECT driver_object_; 147 148 /// KMDF driver handle 149 WDFDRIVER wdf_driver_; 150 }; 151 152 #endif // ANDROID_USB_DRIVER_OBJECT_H__ 153