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
AdbBulkTransferAdbBulkTransfer146   __forceinline AdbBulkTransfer() {
147     time_out = 0;
148     transfer_size = 0;
149     for_x64 = 0;
150   }
151 
152   /// Provides access to protected write_buffer field
GetWriteBufferAdbBulkTransfer153   void* GetWriteBuffer() {
154     return write_buffer;
155   }
156 
157   /// Provides access to protected write_buffer field
GetWriteBufferAdbBulkTransfer158   const void* GetWriteBuffer() const {
159     return write_buffer;
160   }
161 
162   /// Sets write_buffer field.
SetWriteBufferAdbBulkTransfer163   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