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_DEFINES_H__ 18 #define ANDROID_USB_DRIVER_DEFINES_H__ 19 /** \file 20 This file consists of constants, types and macros used (and useful) in driver 21 development. 22 */ 23 24 /** \name IRQL assertions 25 These assertions help to verify that code is running at expected IRQL 26 */ 27 ///@{ 28 29 /// Asserts that current IRQL is less than provided level 30 #define ASSERT_IRQL_LESS(irql_level) ASSERT(KeGetCurrentIrql() < irql_level) 31 /// Asserts that current IRQL is less or equal than provided level 32 #define ASSERT_IRQL_LESS_OR_EQUAL(irql_level) ASSERT(KeGetCurrentIrql() <= irql_level) 33 /// Asserts that current IRQL is the same as provided level 34 #define ASSERT_IRQL_IS(irql_level) ASSERT(irql_level == KeGetCurrentIrql()) 35 /// Asserts that current IRQL is less than DISPATCH_LEVEL 36 #define ASSERT_IRQL_LOW() ASSERT_IRQL_LESS(DISPATCH_LEVEL) 37 /// Asserts that current IRQL is above APC_LEVEL 38 #define ASSERT_IRQL_HIGH() ASSERT(KeGetCurrentIrql() >= DISPATCH_LEVEL) 39 /// Asserts that current IRQL is at PASSIVE_LEVEL 40 #define ASSERT_IRQL_PASSIVE() ASSERT_IRQL_IS(PASSIVE_LEVEL) 41 /// Asserts that current IRQL is at APC_LEVEL 42 #define ASSERT_IRQL_APC() ASSERT_IRQL_IS(APC_LEVEL) 43 /// Asserts that current IRQL is at DISPATCH_LEVEL 44 #define ASSERT_IRQL_DISPATCH() ASSERT_IRQL_IS(DISPATCH_LEVEL) 45 /// Asserts that current IRQL is at APC or DISPATCH_LEVEL 46 #define ASSERT_IRQL_APC_OR_DISPATCH() \ 47 ASSERT((KeGetCurrentIrql() == APC_LEVEL) || (KeGetCurrentIrql() == DISPATCH_LEVEL)) 48 /// Asserts that current IRQL is less or equal DISPATCH_LEVEL 49 #define ASSERT_IRQL_LOW_OR_DISPATCH() \ 50 ASSERT_IRQL_LESS_OR_EQUAL(DISPATCH_LEVEL) 51 52 ///@} 53 54 #if DBG 55 /** \brief Overrides DbgPrint to make sure that nothing gets printed 56 to debug output in release build. 57 */ 58 ULONG __cdecl GoogleDbgPrint(char* format, ...); 59 #else 60 #define GoogleDbgPrint(Arg) NOTHING 61 #endif 62 63 /// Invalid UCHAR value 64 #define INVALID_UCHAR (static_cast<UCHAR>(0xFF)) 65 66 /// Invalid ULONG value 67 #define INVALID_ULONG (static_cast<ULONG>(-1)) 68 69 /** Enum AndroidUsbWdfObjectType enumerates types of KMDF objects that 70 we extend in our driver. 71 */ 72 enum AndroidUsbWdfObjectType { 73 // We start enum with 1 insetead of 0 to protect orselves from a dangling 74 // or uninitialized context structures because KMDF will zero our extension 75 // when it gets created. 76 77 /// Device object context 78 AndroidUsbWdfObjectTypeDevice = 1, 79 80 /// File object context 81 AndroidUsbWdfObjectTypeFile, 82 83 /// Request object context 84 AndroidUsbWdfObjectTypeRequest, 85 86 /// Workitem object context 87 AndroidUsbWdfObjectTypeWorkitem, 88 89 /// Illegal (maximum) context id 90 AndroidUsbWdfObjectTypeMax 91 }; 92 93 /** Structure AndroidUsbWdfObjectContext represents our context that extends 94 every KMDF object (device, file, pipe, etc). 95 */ 96 typedef struct TagAndroidUsbWdfObjectContext { 97 /// KMDF object type that is extended with this context 98 AndroidUsbWdfObjectType object_type; 99 100 /// Instance of the class that extends KMDF object with this context 101 class AndroidUsbWdfObject* wdf_object_ext; 102 } AndroidUsbWdfObjectContext; 103 104 // KMDF woodoo to register our extension and implement accessor method 105 WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(AndroidUsbWdfObjectContext, 106 GetAndroidUsbWdfObjectContext) 107 108 /** Structure AndroidUsbWdfRequestContext represents our context that is 109 associated with every request recevied by the driver. 110 */ 111 typedef struct TagAndroidUsbWdfRequestContext { 112 /// KMDF object type that is extended with this context 113 /// (must be AndroidUsbWdfObjectTypeRequest) 114 AndroidUsbWdfObjectType object_type; 115 116 /// System time request has been first scheduled 117 // (time of the first WdfRequestSend is called for it) 118 LARGE_INTEGER sent_at; 119 120 /// KMDF descriptor for the memory allocated for URB 121 WDFMEMORY urb_mem; 122 123 /// MDL describing the transfer buffer 124 PMDL transfer_mdl; 125 126 /// Private MDL that we build in order to perform the transfer 127 PMDL mdl; 128 129 // Virtual address for the current segment of transfer. 130 void* virtual_address; 131 132 /// Number of bytes remaining to transfer 133 ULONG length; 134 135 /// Number of bytes requested to transfer 136 ULONG transfer_size; 137 138 /// Accummulated number of bytes transferred 139 ULONG num_xfer; 140 141 /// Initial timeout (in millisec) set for this request 142 ULONG initial_time_out; 143 144 // Read / Write selector 145 bool is_read; 146 147 // IOCTL selector 148 bool is_ioctl; 149 } AndroidUsbWdfRequestContext; 150 151 // KMDF woodoo to register our extension and implement accessor method 152 WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(AndroidUsbWdfRequestContext, 153 GetAndroidUsbWdfRequestContext) 154 155 /** Structure AndroidUsbWorkitemContext represents our context that is 156 associated with workitems created by our driver. 157 */ 158 typedef struct TagAndroidUsbWorkitemContext { 159 /// KMDF object type that is extended with this context 160 /// (must be AndroidUsbWdfObjectTypeWorkitem) 161 AndroidUsbWdfObjectType object_type; 162 163 /// Pipe file object extension that enqueued this work item 164 class AndroidUsbPipeFileObject* pipe_file_ext; 165 } AndroidUsbWorkitemContext; 166 167 // KMDF woodoo to register our extension and implement accessor method 168 WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(AndroidUsbWorkitemContext, 169 GetAndroidUsbWorkitemContext) 170 171 #endif // ANDROID_USB_DRIVER_DEFINES_H__ 172