Home | History | Annotate | Download | only in driver 
      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