Gitiles
Code Review Sign In
review.blissroms.org / platform_bionic / adab51aefdd00b65d631f64e6e313713d7dd9564 / . / libc / kernel / uapi / linux / usb / cdc.h
blob: 17278e15207cf40d6d362d5a13d070cd245a9e36 [file] [log] [blame]
Ben Cheng655a7c02013-10-16 16:09:24 -0700[diff] [blame]1/****************************************************************************
2 ****************************************************************************
3 ***
4 *** This header was automatically generated from a Linux kernel header
5 *** of the same name, to make information necessary for userspace to
6 *** call into the kernel available to libc. It contains only constants,
7 *** structures, and macros generated from the original header, and thus,
8 *** contains no copyrightable information.
9 ***
10 *** To edit the content of this header, modify the corresponding
11 *** source file (e.g. under external/kernel-headers/original/) then
12 *** run bionic/libc/kernel/tools/update_all.py
13 ***
14 *** Any manual change here will be lost the next time this script will
15 *** be run. You've been warned!
16 ***
17 ****************************************************************************
18 ****************************************************************************/
19#ifndef __LINUX_USB_CDC_H
20#define __LINUX_USB_CDC_H
21#include <linux/types.h>
22#define USB_CDC_SUBCLASS_ACM 0x02
23/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
24#define USB_CDC_SUBCLASS_ETHERNET 0x06
25#define USB_CDC_SUBCLASS_WHCM 0x08
26#define USB_CDC_SUBCLASS_DMM 0x09
27#define USB_CDC_SUBCLASS_MDLM 0x0a
28/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
29#define USB_CDC_SUBCLASS_OBEX 0x0b
30#define USB_CDC_SUBCLASS_EEM 0x0c
31#define USB_CDC_SUBCLASS_NCM 0x0d
32#define USB_CDC_SUBCLASS_MBIM 0x0e
33/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
34#define USB_CDC_PROTO_NONE 0
35#define USB_CDC_ACM_PROTO_AT_V25TER 1
36#define USB_CDC_ACM_PROTO_AT_PCCA101 2
37#define USB_CDC_ACM_PROTO_AT_PCCA101_WAKE 3
38/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
39#define USB_CDC_ACM_PROTO_AT_GSM 4
40#define USB_CDC_ACM_PROTO_AT_3G 5
41#define USB_CDC_ACM_PROTO_AT_CDMA 6
42#define USB_CDC_ACM_PROTO_VENDOR 0xff
43/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
44#define USB_CDC_PROTO_EEM 7
45#define USB_CDC_NCM_PROTO_NTB 1
46#define USB_CDC_MBIM_PROTO_NTB 2
47#define USB_CDC_HEADER_TYPE 0x00
48/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
49#define USB_CDC_CALL_MANAGEMENT_TYPE 0x01
50#define USB_CDC_ACM_TYPE 0x02
51#define USB_CDC_UNION_TYPE 0x06
52#define USB_CDC_COUNTRY_TYPE 0x07
53/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
54#define USB_CDC_NETWORK_TERMINAL_TYPE 0x0a
55#define USB_CDC_ETHERNET_TYPE 0x0f
56#define USB_CDC_WHCM_TYPE 0x11
57#define USB_CDC_MDLM_TYPE 0x12
58/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
59#define USB_CDC_MDLM_DETAIL_TYPE 0x13
60#define USB_CDC_DMM_TYPE 0x14
61#define USB_CDC_OBEX_TYPE 0x15
62#define USB_CDC_NCM_TYPE 0x1a
63/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
64#define USB_CDC_MBIM_TYPE 0x1b
65struct usb_cdc_header_desc {
66 __u8 bLength;
67 __u8 bDescriptorType;
68/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
69 __u8 bDescriptorSubType;
70 __le16 bcdCDC;
71} __attribute__ ((packed));
72struct usb_cdc_call_mgmt_descriptor {
73/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
74 __u8 bLength;
75 __u8 bDescriptorType;
76 __u8 bDescriptorSubType;
77 __u8 bmCapabilities;
78/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
79#define USB_CDC_CALL_MGMT_CAP_CALL_MGMT 0x01
80#define USB_CDC_CALL_MGMT_CAP_DATA_INTF 0x02
81 __u8 bDataInterface;
82} __attribute__ ((packed));
83/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
84struct usb_cdc_acm_descriptor {
85 __u8 bLength;
86 __u8 bDescriptorType;
87 __u8 bDescriptorSubType;
88/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
89 __u8 bmCapabilities;
90} __attribute__ ((packed));
91#define USB_CDC_COMM_FEATURE 0x01
92#define USB_CDC_CAP_LINE 0x02
93/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
94#define USB_CDC_CAP_BRK 0x04
95#define USB_CDC_CAP_NOTIFY 0x08
96struct usb_cdc_union_desc {
97 __u8 bLength;
98/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
99 __u8 bDescriptorType;
100 __u8 bDescriptorSubType;
101 __u8 bMasterInterface0;
102 __u8 bSlaveInterface0;
103/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
104} __attribute__ ((packed));
105struct usb_cdc_country_functional_desc {
106 __u8 bLength;
107 __u8 bDescriptorType;
108/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
109 __u8 bDescriptorSubType;
110 __u8 iCountryCodeRelDate;
111 __le16 wCountyCode0;
112} __attribute__ ((packed));
113/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
114struct usb_cdc_network_terminal_desc {
115 __u8 bLength;
116 __u8 bDescriptorType;
117 __u8 bDescriptorSubType;
118/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
119 __u8 bEntityId;
120 __u8 iName;
121 __u8 bChannelIndex;
122 __u8 bPhysicalInterface;
123/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
124} __attribute__ ((packed));
125struct usb_cdc_ether_desc {
126 __u8 bLength;
127 __u8 bDescriptorType;
128/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
129 __u8 bDescriptorSubType;
130 __u8 iMACAddress;
131 __le32 bmEthernetStatistics;
132 __le16 wMaxSegmentSize;
133/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
134 __le16 wNumberMCFilters;
135 __u8 bNumberPowerFilters;
136} __attribute__ ((packed));
137struct usb_cdc_dmm_desc {
138/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
139 __u8 bFunctionLength;
140 __u8 bDescriptorType;
141 __u8 bDescriptorSubtype;
142 __u16 bcdVersion;
143/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
144 __le16 wMaxCommand;
145} __attribute__ ((packed));
146struct usb_cdc_mdlm_desc {
147 __u8 bLength;
148/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
149 __u8 bDescriptorType;
150 __u8 bDescriptorSubType;
151 __le16 bcdVersion;
152 __u8 bGUID[16];
153/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
154} __attribute__ ((packed));
155struct usb_cdc_mdlm_detail_desc {
156 __u8 bLength;
157 __u8 bDescriptorType;
158/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
159 __u8 bDescriptorSubType;
160 __u8 bGuidDescriptorType;
161 __u8 bDetailData[0];
162} __attribute__ ((packed));
163/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
164struct usb_cdc_obex_desc {
165 __u8 bLength;
166 __u8 bDescriptorType;
167 __u8 bDescriptorSubType;
168/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
169 __le16 bcdVersion;
170} __attribute__ ((packed));
171struct usb_cdc_ncm_desc {
172 __u8 bLength;
173/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
174 __u8 bDescriptorType;
175 __u8 bDescriptorSubType;
176 __le16 bcdNcmVersion;
177 __u8 bmNetworkCapabilities;
178/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
179} __attribute__ ((packed));
180struct usb_cdc_mbim_desc {
181 __u8 bLength;
182 __u8 bDescriptorType;
183/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
184 __u8 bDescriptorSubType;
185 __le16 bcdMBIMVersion;
186 __le16 wMaxControlMessage;
187 __u8 bNumberFilters;
188/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
189 __u8 bMaxFilterSize;
190 __le16 wMaxSegmentSize;
191 __u8 bmNetworkCapabilities;
192} __attribute__ ((packed));
193/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
194#define USB_CDC_SEND_ENCAPSULATED_COMMAND 0x00
195#define USB_CDC_GET_ENCAPSULATED_RESPONSE 0x01
196#define USB_CDC_REQ_SET_LINE_CODING 0x20
197#define USB_CDC_REQ_GET_LINE_CODING 0x21
198/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
199#define USB_CDC_REQ_SET_CONTROL_LINE_STATE 0x22
200#define USB_CDC_REQ_SEND_BREAK 0x23
201#define USB_CDC_SET_ETHERNET_MULTICAST_FILTERS 0x40
202#define USB_CDC_SET_ETHERNET_PM_PATTERN_FILTER 0x41
203/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
204#define USB_CDC_GET_ETHERNET_PM_PATTERN_FILTER 0x42
205#define USB_CDC_SET_ETHERNET_PACKET_FILTER 0x43
206#define USB_CDC_GET_ETHERNET_STATISTIC 0x44
207#define USB_CDC_GET_NTB_PARAMETERS 0x80
208/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
209#define USB_CDC_GET_NET_ADDRESS 0x81
210#define USB_CDC_SET_NET_ADDRESS 0x82
211#define USB_CDC_GET_NTB_FORMAT 0x83
212#define USB_CDC_SET_NTB_FORMAT 0x84
213/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
214#define USB_CDC_GET_NTB_INPUT_SIZE 0x85
215#define USB_CDC_SET_NTB_INPUT_SIZE 0x86
216#define USB_CDC_GET_MAX_DATAGRAM_SIZE 0x87
217#define USB_CDC_SET_MAX_DATAGRAM_SIZE 0x88
218/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
219#define USB_CDC_GET_CRC_MODE 0x89
220#define USB_CDC_SET_CRC_MODE 0x8a
221struct usb_cdc_line_coding {
222 __le32 dwDTERate;
223/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
224 __u8 bCharFormat;
225#define USB_CDC_1_STOP_BITS 0
226#define USB_CDC_1_5_STOP_BITS 1
227#define USB_CDC_2_STOP_BITS 2
228/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
229 __u8 bParityType;
230#define USB_CDC_NO_PARITY 0
231#define USB_CDC_ODD_PARITY 1
232#define USB_CDC_EVEN_PARITY 2
233/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
234#define USB_CDC_MARK_PARITY 3
235#define USB_CDC_SPACE_PARITY 4
236 __u8 bDataBits;
237} __attribute__ ((packed));
238/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
239#define USB_CDC_PACKET_TYPE_PROMISCUOUS (1 << 0)
240#define USB_CDC_PACKET_TYPE_ALL_MULTICAST (1 << 1)
241#define USB_CDC_PACKET_TYPE_DIRECTED (1 << 2)
242#define USB_CDC_PACKET_TYPE_BROADCAST (1 << 3)
243/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
244#define USB_CDC_PACKET_TYPE_MULTICAST (1 << 4)
245#define USB_CDC_NOTIFY_NETWORK_CONNECTION 0x00
246#define USB_CDC_NOTIFY_RESPONSE_AVAILABLE 0x01
247#define USB_CDC_NOTIFY_SERIAL_STATE 0x20
248/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
249#define USB_CDC_NOTIFY_SPEED_CHANGE 0x2a
250struct usb_cdc_notification {
251 __u8 bmRequestType;
252 __u8 bNotificationType;
253/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
254 __le16 wValue;
255 __le16 wIndex;
256 __le16 wLength;
257} __attribute__ ((packed));
258/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
259struct usb_cdc_speed_change {
260 __le32 DLBitRRate;
261 __le32 ULBitRate;
262} __attribute__ ((packed));
263/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
264struct usb_cdc_ncm_ntb_parameters {
265 __le16 wLength;
266 __le16 bmNtbFormatsSupported;
267 __le32 dwNtbInMaxSize;
268/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
269 __le16 wNdpInDivisor;
270 __le16 wNdpInPayloadRemainder;
271 __le16 wNdpInAlignment;
272 __le16 wPadding1;
273/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
274 __le32 dwNtbOutMaxSize;
275 __le16 wNdpOutDivisor;
276 __le16 wNdpOutPayloadRemainder;
277 __le16 wNdpOutAlignment;
278/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
279 __le16 wNtbOutMaxDatagrams;
280} __attribute__ ((packed));
281#define USB_CDC_NCM_NTH16_SIGN 0x484D434E
282#define USB_CDC_NCM_NTH32_SIGN 0x686D636E
283/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
284struct usb_cdc_ncm_nth16 {
285 __le32 dwSignature;
286 __le16 wHeaderLength;
287 __le16 wSequence;
288/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
289 __le16 wBlockLength;
290 __le16 wNdpIndex;
291} __attribute__ ((packed));
292struct usb_cdc_ncm_nth32 {
293/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
294 __le32 dwSignature;
295 __le16 wHeaderLength;
296 __le16 wSequence;
297 __le32 dwBlockLength;
298/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
299 __le32 dwNdpIndex;
300} __attribute__ ((packed));
301#define USB_CDC_NCM_NDP16_CRC_SIGN 0x314D434E
302#define USB_CDC_NCM_NDP16_NOCRC_SIGN 0x304D434E
303/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
304#define USB_CDC_NCM_NDP32_CRC_SIGN 0x316D636E
305#define USB_CDC_NCM_NDP32_NOCRC_SIGN 0x306D636E
306#define USB_CDC_MBIM_NDP16_IPS_SIGN 0x00535049
307#define USB_CDC_MBIM_NDP32_IPS_SIGN 0x00737069
308/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
309#define USB_CDC_MBIM_NDP16_DSS_SIGN 0x00535344
310#define USB_CDC_MBIM_NDP32_DSS_SIGN 0x00737364
311struct usb_cdc_ncm_dpe16 {
312 __le16 wDatagramIndex;
313/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
314 __le16 wDatagramLength;
315} __attribute__((__packed__));
316struct usb_cdc_ncm_ndp16 {
317 __le32 dwSignature;
318/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
319 __le16 wLength;
320 __le16 wNextNdpIndex;
321 struct usb_cdc_ncm_dpe16 dpe16[0];
322} __attribute__ ((packed));
323/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
324struct usb_cdc_ncm_dpe32 {
325 __le32 dwDatagramIndex;
326 __le32 dwDatagramLength;
327} __attribute__((__packed__));
328/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
329struct usb_cdc_ncm_ndp32 {
330 __le32 dwSignature;
331 __le16 wLength;
332 __le16 wReserved6;
333/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
334 __le32 dwNextNdpIndex;
335 __le32 dwReserved12;
336 struct usb_cdc_ncm_dpe32 dpe32[0];
337} __attribute__ ((packed));
338/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
339#define USB_CDC_NCM_NDP16_INDEX_MIN 0x000C
340#define USB_CDC_NCM_NDP32_INDEX_MIN 0x0010
341#define USB_CDC_NCM_DATAGRAM_FORMAT_CRC 0x30
342#define USB_CDC_NCM_DATAGRAM_FORMAT_NOCRC 0X31
343/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
344#define USB_CDC_NCM_PROTO_CODE_NO_ENCAP_COMMANDS 0x00
345#define USB_CDC_NCM_PROTO_CODE_EXTERN_PROTO 0xFE
346#define USB_CDC_NCM_NCAP_ETH_FILTER (1 << 0)
347#define USB_CDC_NCM_NCAP_NET_ADDRESS (1 << 1)
348/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
349#define USB_CDC_NCM_NCAP_ENCAP_COMMAND (1 << 2)
350#define USB_CDC_NCM_NCAP_MAX_DATAGRAM_SIZE (1 << 3)
351#define USB_CDC_NCM_NCAP_CRC_MODE (1 << 4)
352#define USB_CDC_NCM_NCAP_NTB_INPUT_SIZE (1 << 5)
353/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
354#define USB_CDC_NCM_NTB16_SUPPORTED (1 << 0)
355#define USB_CDC_NCM_NTB32_SUPPORTED (1 << 1)
356#define USB_CDC_NCM_NDP_ALIGN_MIN_SIZE 0x04
357#define USB_CDC_NCM_NTB_MAX_LENGTH 0x1C
358/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
359#define USB_CDC_NCM_NTB16_FORMAT 0x00
360#define USB_CDC_NCM_NTB32_FORMAT 0x01
361#define USB_CDC_NCM_NTB_MIN_IN_SIZE 2048
362#define USB_CDC_NCM_NTB_MIN_OUT_SIZE 2048
363/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
364struct usb_cdc_ncm_ndp_input_size {
365 __le32 dwNtbInMaxSize;
366 __le16 wNtbInMaxDatagrams;
367 __le16 wReserved;
368/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
369} __attribute__ ((packed));
370#define USB_CDC_NCM_CRC_NOT_APPENDED 0x00
371#define USB_CDC_NCM_CRC_APPENDED 0x01
372#endif
373/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */