aboutsummaryrefslogtreecommitdiff
path: root/lib/libusb/libusb20.h
blob: 89cb75eaa999217abba5116fb3f926a64e7935ee (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
/* $FreeBSD$ */
/*-
 * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
 * Copyright (c) 2007-2008 Daniel Drake.  All rights reserved.
 * Copyright (c) 2001 Johannes Erdfelt.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifndef _LIBUSB20_H_
#define	_LIBUSB20_H_

#include <stdint.h>
#include <time.h>
#include <string.h>

#include <sys/time.h>
#include <sys/types.h>
#include <sys/endian.h>

#ifdef __cplusplus
extern	"C" {
#endif
#if 0
};					/* style */

#endif

/** \ingroup misc
 * Error codes. Most libusb20 functions return 0 on success or one of
 * these codes on failure.
 */
enum libusb20_error {
	/** Success (no error) */
	LIBUSB20_SUCCESS = 0,

	/** Input/output error */
	LIBUSB20_ERROR_IO = -1,

	/** Invalid parameter */
	LIBUSB20_ERROR_INVALID_PARAM = -2,

	/** Access denied (insufficient permissions) */
	LIBUSB20_ERROR_ACCESS = -3,

	/** No such device (it may have been disconnected) */
	LIBUSB20_ERROR_NO_DEVICE = -4,

	/** Entity not found */
	LIBUSB20_ERROR_NOT_FOUND = -5,

	/** Resource busy */
	LIBUSB20_ERROR_BUSY = -6,

	/** Operation timed out */
	LIBUSB20_ERROR_TIMEOUT = -7,

	/** Overflow */
	LIBUSB20_ERROR_OVERFLOW = -8,

	/** Pipe error */
	LIBUSB20_ERROR_PIPE = -9,

	/** System call interrupted (perhaps due to signal) */
	LIBUSB20_ERROR_INTERRUPTED = -10,

	/** Insufficient memory */
	LIBUSB20_ERROR_NO_MEM = -11,

	/** Operation not supported or unimplemented on this platform */
	LIBUSB20_ERROR_NOT_SUPPORTED = -12,

	/** Other error */
	LIBUSB20_ERROR_OTHER = -99,
};

/** \ingroup asyncio
 * libusb20_tr_get_status() values */
enum libusb20_transfer_status {
	/** Transfer completed without error. Note that this does not
	 * indicate that the entire amount of requested data was
	 * transferred. */
	LIBUSB20_TRANSFER_COMPLETED,

	/** Callback code to start transfer */
	LIBUSB20_TRANSFER_START,

	/** Drain complete callback code */
	LIBUSB20_TRANSFER_DRAINED,

	/** Transfer failed */
	LIBUSB20_TRANSFER_ERROR,

	/** Transfer timed out */
	LIBUSB20_TRANSFER_TIMED_OUT,

	/** Transfer was cancelled */
	LIBUSB20_TRANSFER_CANCELLED,

	/** For bulk/interrupt endpoints: halt condition detected
	 * (endpoint stalled). For control endpoints: control request
	 * not supported. */
	LIBUSB20_TRANSFER_STALL,

	/** Device was disconnected */
	LIBUSB20_TRANSFER_NO_DEVICE,

	/** Device sent more data than requested */
	LIBUSB20_TRANSFER_OVERFLOW,
};

/** \ingroup asyncio
 * libusb20_tr_set_flags() values */
enum libusb20_transfer_flags {
	/** Report a short frame as error */
	LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK = 0x0001,

	/** Multiple short frames are not allowed */
	LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK = 0x0002,

	/** All transmitted frames are short terminated */
	LIBUSB20_TRANSFER_FORCE_SHORT = 0x0004,

	/** Will do a clear-stall before xfer */
	LIBUSB20_TRANSFER_DO_CLEAR_STALL = 0x0008,
};

/** \ingroup misc
 * libusb20_dev_get_mode() values
 */
enum libusb20_device_mode {
	LIBUSB20_MODE_HOST,		/* default */
	LIBUSB20_MODE_DEVICE,
};

/** \ingroup misc
 * libusb20_dev_get_speed() values
 */
enum {
	LIBUSB20_SPEED_UNKNOWN,		/* default */
	LIBUSB20_SPEED_LOW,
	LIBUSB20_SPEED_FULL,
	LIBUSB20_SPEED_HIGH,
	LIBUSB20_SPEED_VARIABLE,
	LIBUSB20_SPEED_SUPER,
};

/** \ingroup misc
 * libusb20_dev_set_power() values
 */
enum {
	LIBUSB20_POWER_OFF,
	LIBUSB20_POWER_ON,
	LIBUSB20_POWER_SAVE,
	LIBUSB20_POWER_SUSPEND,
	LIBUSB20_POWER_RESUME,
};

struct usb2_device_info;
struct libusb20_transfer;
struct libusb20_backend;
struct libusb20_backend_methods;
struct libusb20_device;
struct libusb20_device_methods;
struct libusb20_config;
struct LIBUSB20_CONTROL_SETUP_DECODED;
struct LIBUSB20_DEVICE_DESC_DECODED;

typedef void (libusb20_tr_callback_t)(struct libusb20_transfer *xfer);

struct libusb20_quirk {
	uint16_t vid;			/* vendor ID */
	uint16_t pid;			/* product ID */
	uint16_t bcdDeviceLow;		/* low revision value, inclusive */
	uint16_t bcdDeviceHigh;		/* high revision value, inclusive */
	uint16_t reserved[2];		/* for the future */
	/* quirk name, UQ_XXX, including terminating zero */
	char	quirkname[64 - 12];
};

/* USB transfer operations */

int	libusb20_tr_close(struct libusb20_transfer *xfer);
int	libusb20_tr_open(struct libusb20_transfer *xfer, uint32_t max_buf_size, uint32_t max_frame_count, uint8_t ep_no);
struct libusb20_transfer *libusb20_tr_get_pointer(struct libusb20_device *pdev, uint16_t tr_index);
uint16_t libusb20_tr_get_time_complete(struct libusb20_transfer *xfer);
uint32_t libusb20_tr_get_actual_frames(struct libusb20_transfer *xfer);
uint32_t libusb20_tr_get_actual_length(struct libusb20_transfer *xfer);
uint32_t libusb20_tr_get_max_frames(struct libusb20_transfer *xfer);
uint32_t libusb20_tr_get_max_packet_length(struct libusb20_transfer *xfer);
uint32_t libusb20_tr_get_max_total_length(struct libusb20_transfer *xfer);
uint8_t	libusb20_tr_get_status(struct libusb20_transfer *xfer);
uint8_t	libusb20_tr_pending(struct libusb20_transfer *xfer);
void	libusb20_tr_callback_wrapper(struct libusb20_transfer *xfer);
void	libusb20_tr_clear_stall_sync(struct libusb20_transfer *xfer);
void	libusb20_tr_drain(struct libusb20_transfer *xfer);
void	libusb20_tr_set_buffer(struct libusb20_transfer *xfer, void *buffer, uint16_t fr_index);
void	libusb20_tr_set_callback(struct libusb20_transfer *xfer, libusb20_tr_callback_t *cb);
void	libusb20_tr_set_flags(struct libusb20_transfer *xfer, uint8_t flags);
void	libusb20_tr_set_length(struct libusb20_transfer *xfer, uint32_t length, uint16_t fr_index);
void	libusb20_tr_set_priv_sc0(struct libusb20_transfer *xfer, void *sc0);
void	libusb20_tr_set_priv_sc1(struct libusb20_transfer *xfer, void *sc1);
void	libusb20_tr_set_timeout(struct libusb20_transfer *xfer, uint32_t timeout);
void	libusb20_tr_set_total_frames(struct libusb20_transfer *xfer, uint32_t nFrames);
void	libusb20_tr_setup_bulk(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
void	libusb20_tr_setup_control(struct libusb20_transfer *xfer, void *psetup, void *pbuf, uint32_t timeout);
void	libusb20_tr_setup_intr(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint32_t timeout);
void	libusb20_tr_setup_isoc(struct libusb20_transfer *xfer, void *pbuf, uint32_t length, uint16_t fr_index);
void	libusb20_tr_start(struct libusb20_transfer *xfer);
void	libusb20_tr_stop(struct libusb20_transfer *xfer);
void	libusb20_tr_submit(struct libusb20_transfer *xfer);
void   *libusb20_tr_get_priv_sc0(struct libusb20_transfer *xfer);
void   *libusb20_tr_get_priv_sc1(struct libusb20_transfer *xfer);


/* USB device operations */

const char *libusb20_dev_get_backend_name(struct libusb20_device *pdev);
const char *libusb20_dev_get_desc(struct libusb20_device *pdev);
int	libusb20_dev_claim_interface(struct libusb20_device *pdev, uint8_t iface_index);
int	libusb20_dev_close(struct libusb20_device *pdev);
int	libusb20_dev_detach_kernel_driver(struct libusb20_device *pdev, uint8_t iface_index);
int	libusb20_dev_set_config_index(struct libusb20_device *pdev, uint8_t configIndex);
int	libusb20_dev_get_debug(struct libusb20_device *pdev);
int	libusb20_dev_get_fd(struct libusb20_device *pdev);
int	libusb20_dev_kernel_driver_active(struct libusb20_device *pdev, uint8_t iface_index);
int	libusb20_dev_open(struct libusb20_device *pdev, uint16_t transfer_max);
int	libusb20_dev_process(struct libusb20_device *pdev);
int	libusb20_dev_release_interface(struct libusb20_device *pdev, uint8_t iface_index);
int	libusb20_dev_request_sync(struct libusb20_device *pdev, struct LIBUSB20_CONTROL_SETUP_DECODED *setup, void *data, uint16_t *pactlen, uint32_t timeout, uint8_t flags);
int	libusb20_dev_req_string_sync(struct libusb20_device *pdev, uint8_t index, uint16_t langid, void *ptr, uint16_t len);
int	libusb20_dev_req_string_simple_sync(struct libusb20_device *pdev, uint8_t index, void *ptr, uint16_t len);
int	libusb20_dev_reset(struct libusb20_device *pdev);
int	libusb20_dev_set_power_mode(struct libusb20_device *pdev, uint8_t power_mode);
uint8_t	libusb20_dev_get_power_mode(struct libusb20_device *pdev);
int	libusb20_dev_set_alt_index(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index);
int	libusb20_dev_get_info(struct libusb20_device *pdev, struct usb2_device_info *pinfo);
int	libusb20_dev_get_iface_desc(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len);

struct LIBUSB20_DEVICE_DESC_DECODED *libusb20_dev_get_device_desc(struct libusb20_device *pdev);
struct libusb20_config *libusb20_dev_alloc_config(struct libusb20_device *pdev, uint8_t config_index);
struct libusb20_device *libusb20_dev_alloc(void);
uint8_t	libusb20_dev_get_address(struct libusb20_device *pdev);
uint8_t	libusb20_dev_get_bus_number(struct libusb20_device *pdev);
uint8_t	libusb20_dev_get_mode(struct libusb20_device *pdev);
uint8_t	libusb20_dev_get_speed(struct libusb20_device *pdev);
uint8_t	libusb20_dev_get_config_index(struct libusb20_device *pdev);
void	libusb20_dev_free(struct libusb20_device *pdev);
void	libusb20_dev_set_debug(struct libusb20_device *pdev, int debug);
void	libusb20_dev_wait_process(struct libusb20_device *pdev, int timeout);

/* USB global operations */

int	libusb20_be_get_dev_quirk(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
int	libusb20_be_get_quirk_name(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq);
int	libusb20_be_add_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);
int	libusb20_be_remove_dev_quirk(struct libusb20_backend *pbe, struct libusb20_quirk *pq);

/* USB backend operations */

struct libusb20_backend *libusb20_be_alloc(const struct libusb20_backend_methods *methods);
struct libusb20_backend *libusb20_be_alloc_default(void);
struct libusb20_backend *libusb20_be_alloc_freebsd(void);
struct libusb20_backend *libusb20_be_alloc_linux(void);
struct libusb20_backend *libusb20_be_alloc_ugen20(void);
struct libusb20_device *libusb20_be_device_foreach(struct libusb20_backend *pbe, struct libusb20_device *pdev);
void	libusb20_be_dequeue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
void	libusb20_be_enqueue_device(struct libusb20_backend *pbe, struct libusb20_device *pdev);
void	libusb20_be_free(struct libusb20_backend *pbe);

#if 0
{					/* style */
#endif
#ifdef __cplusplus
}

#endif

#endif					/* _LIBUSB20_H_ */