Home | History | Annotate | Download | only in api
      1 /*
      2  * Copyright (C) 2009 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_API_ADB_API_LEGACY_H_
     18 #define ANDROID_USB_API_ADB_API_LEGACY_H_
     19 /** \file
     20   This file consists of declarations of constants and structures required
     21   for supporting communications of this API with a legacy (custom) USB
     22   driver.
     23 */
     24 
     25 // Enables compillation for "straight" C
     26 #ifdef __cplusplus
     27   #define EXTERN_C    extern "C"
     28 #else
     29   #define EXTERN_C    extern
     30   typedef int bool;
     31   #define true  1
     32   #define false 0
     33 #endif
     34 
     35 /// Name for the default bulk read pipe
     36 #define DEVICE_BULK_READ_PIPE_NAME  L"BulkRead"
     37 
     38 /// Name for the default bulk write pipe
     39 #define DEVICE_BULK_WRITE_PIPE_NAME L"BulkWrite"
     40 
     41 /// Prefix for an index-based pipe name
     42 #define DEVICE_PIPE_NAME_PREFIX     L"PIPE_"
     43 
     44 /** \name IOCTL codes for the driver
     45 */
     46 ///@{
     47 
     48 /// Control code for IOCTL that gets USB_DEVICE_DESCRIPTOR
     49 #define ADB_CTL_GET_USB_DEVICE_DESCRIPTOR         10
     50 
     51 /// Control code for IOCTL that gets USB_CONFIGURATION_DESCRIPTOR
     52 #define ADB_CTL_GET_USB_CONFIGURATION_DESCRIPTOR  11
     53 
     54 /// Control code for IOCTL that gets USB_INTERFACE_DESCRIPTOR
     55 #define ADB_CTL_GET_USB_INTERFACE_DESCRIPTOR      12
     56 
     57 /// Control code for IOCTL that gets endpoint information
     58 #define ADB_CTL_GET_ENDPOINT_INFORMATION          13
     59 
     60 /// Control code for bulk read IOCTL
     61 #define ADB_CTL_BULK_READ                         14
     62 
     63 /// Control code for bulk write IOCTL
     64 #define ADB_CTL_BULK_WRITE                        15
     65 
     66 /// Control code for IOCTL that gets device serial number
     67 #define ADB_CTL_GET_SERIAL_NUMBER                 16
     68 
     69 /// IOCTL that gets USB_DEVICE_DESCRIPTOR
     70 #define ADB_IOCTL_GET_USB_DEVICE_DESCRIPTOR \
     71               CTL_CODE(FILE_DEVICE_UNKNOWN, \
     72                        ADB_CTL_GET_USB_DEVICE_DESCRIPTOR, \
     73                        METHOD_BUFFERED, \
     74                        FILE_READ_ACCESS)
     75 
     76 /// IOCTL that gets USB_CONFIGURATION_DESCRIPTOR
     77 #define ADB_IOCTL_GET_USB_CONFIGURATION_DESCRIPTOR \
     78               CTL_CODE(FILE_DEVICE_UNKNOWN, \
     79                        ADB_CTL_GET_USB_CONFIGURATION_DESCRIPTOR, \
     80                        METHOD_BUFFERED, \
     81                        FILE_READ_ACCESS)
     82 
     83 /// IOCTL that gets USB_INTERFACE_DESCRIPTOR
     84 #define ADB_IOCTL_GET_USB_INTERFACE_DESCRIPTOR \
     85               CTL_CODE(FILE_DEVICE_UNKNOWN, \
     86                        ADB_CTL_GET_USB_INTERFACE_DESCRIPTOR, \
     87                        METHOD_BUFFERED, \
     88                        FILE_READ_ACCESS)
     89 
     90 /// IOCTL that gets endpoint information
     91 #define ADB_IOCTL_GET_ENDPOINT_INFORMATION \
     92               CTL_CODE(FILE_DEVICE_UNKNOWN, \
     93                        ADB_CTL_GET_ENDPOINT_INFORMATION, \
     94                        METHOD_BUFFERED, \
     95                        FILE_READ_ACCESS)
     96 
     97 /// Bulk read IOCTL
     98 #define ADB_IOCTL_BULK_READ \
     99               CTL_CODE(FILE_DEVICE_UNKNOWN, \
    100                        ADB_CTL_BULK_READ, \
    101                        METHOD_OUT_DIRECT, \
    102                        FILE_READ_ACCESS)
    103 
    104 // For bulk write IOCTL we send request data in the form of AdbBulkTransfer
    105 // structure and output buffer is just ULONG that receives number of bytes
    106 // actually written. Since both of these are tiny we can use buffered I/O
    107 // for this IOCTL.
    108 /// Bulk write IOCTL
    109 #define ADB_IOCTL_BULK_WRITE \
    110               CTL_CODE(FILE_DEVICE_UNKNOWN, \
    111                        ADB_CTL_BULK_WRITE, \
    112                        METHOD_BUFFERED, \
    113                        FILE_WRITE_ACCESS)
    114 
    115 /// IOCTL that gets device serial number
    116 #define ADB_IOCTL_GET_SERIAL_NUMBER \
    117               CTL_CODE(FILE_DEVICE_UNKNOWN, \
    118                        ADB_CTL_GET_SERIAL_NUMBER, \
    119                        METHOD_BUFFERED, \
    120                        FILE_READ_ACCESS)
    121 
    122 ///@}
    123 
    124 /** Structure AdbQueryEndpointInformation formats input for
    125   ADB_IOCTL_GET_ENDPOINT_INFORMATION IOCTL request
    126 */
    127 struct AdbQueryEndpointInformation {
    128   /// Zero-based endpoint index for which information is queried.
    129   /// See ADB_QUERY_BULK_xxx_ENDPOINT_INDEX for shortcuts.
    130   UCHAR endpoint_index;
    131 };
    132 
    133 /** Structure AdbBulkTransfer formats parameters for ADB_CTL_BULK_READ and
    134   ADB_CTL_BULK_WRITE IOCTL requests.
    135 */
    136 struct AdbBulkTransfer {
    137   /// Time in milliseconds to complete this request
    138   ULONG time_out;
    139 
    140   /// Size of the data to transfer. This parameter is used only for
    141   /// ADB_CTL_BULK_WRITE request. For ADB_CTL_BULK_READ requests transfer
    142   /// size is defined by the output buffer size.
    143   ULONG transfer_size;
    144 
    145   /// Initializes statically allocated structure
    146   __forceinline AdbBulkTransfer() {
    147     time_out = 0;
    148     transfer_size = 0;
    149     for_x64 = 0;
    150   }
    151 
    152   /// Provides access to protected write_buffer field
    153   void* GetWriteBuffer() {
    154     return write_buffer;
    155   }
    156 
    157   /// Provides access to protected write_buffer field
    158   const void* GetWriteBuffer() const {
    159     return write_buffer;
    160   }
    161 
    162   /// Sets write_buffer field.
    163   void SetWriteBuffer(void* buffer) {
    164     // For 32-bit we must zero out high 32 bit of the address, so 64-bit
    165     // driver will see valid address when accessing 64-bit write_buffer.
    166     for_x64 = 0;
    167     write_buffer = buffer;
    168   }
    169 
    170 protected:
    171   /// Pointer to the actual buffer for ADB_CTL_BULK_WRITE request. This field
    172   /// is not used in ADB_CTL_BULK_READ request. Note that in order to support
    173   /// compatibility between 32-bit and 64-bit versions of both, driver and
    174   /// application we must sizeof this field to the max pointer sizeof (which
    175   /// is 64 bit in our case). The idea is that if IOCTL was issued by a 64-bit
    176   /// process to a 64-bit driver, write_buffer will be valid 64-bit pointer to
    177   /// the write buffer. Same is true for 32-bit app talking to 32-bit driver.
    178   /// If, however, a 32-bit app is talking to 64-bit driver, then write_buffer
    179   /// initialized by 32-bit app will contain 32-bit address, which will be
    180   /// correctly picked up ("extended") by 64-bit driver. Since when setting
    181   /// this field by a 32-bit app requires some extra work (see SetWriteBuffer)
    182   /// we hide this field, making it accessible only throug the accessor
    183   /// methods (Get/SetWriteBuffer).
    184   union {
    185     void* write_buffer;
    186     __int64 for_x64;
    187   };
    188 };
    189 
    190 #endif  // ANDROID_USB_API_ADB_API_LEGACY_H_
    191