1/*
2 *	Version 2 USB Device Driver API
3 *
4 *	Copyright 2006, Haiku Inc. All Rights Reserved.
5 *	Distributed under the terms of the MIT License.
6 */
7
8#ifndef _USB_V2_H_
9#define _USB_V2_H_
10
11#include <KernelExport.h>
12#include <bus_manager.h>
13
14#include <USB_spec.h>
15#include <USB_rle.h>
16
17#ifdef __cplusplus
18extern "C" {
19#endif
20
21typedef struct usb_module_info usb_module_info;
22
23/* these are opaque handles to internal stack objects */
24typedef struct usb_device usb_device;
25typedef struct usb_interface usb_interface;
26typedef struct usb_pipe usb_pipe;
27
28typedef struct usb_endpoint_info usb_endpoint_info;
29typedef struct usb_interface_info usb_interface_info;
30typedef struct usb_interface_list usb_interface_list;
31typedef struct usb_configuration_info usb_configuration_info;
32
33typedef struct usb_notify_hooks {
34	status_t		(*device_added)(const usb_device *device, void **cookie);
35	status_t		(*device_removed)(void *cookie);
36} usb_notify_hooks;
37
38typedef struct usb_support_descriptor {
39	uint8						dev_class;
40	uint8						dev_subclass;
41	uint8						dev_protocol;
42	uint16						vendor;
43	uint16						product;
44} usb_support_descriptor;
45
46struct usb_endpoint_info {
47	usb_endpoint_descriptor		*descr;			/* descriptor and handle */
48	usb_pipe					*handle;		/* of this endpoint/pipe */
49};
50
51struct usb_interface_info {
52	usb_interface_descriptor	*descr;			/* descriptor and handle */
53	usb_interface				*handle;		/* of this interface */
54
55	size_t						endpoint_count;	/* count and list of endpoints */
56	usb_endpoint_info			*endpoint;		/* in this interface */
57
58	size_t						generic_count;	/* unparsed descriptors in */
59	usb_descriptor				**generic;		/* this interface */
60};
61
62struct usb_interface_list {
63	size_t						alt_count;		/* count and list of alternate */
64	usb_interface_info			*alt;			/* interfaces available */
65
66	usb_interface_info			*active;		/* currently active alternate */
67};
68
69struct usb_configuration_info {
70	usb_configuration_descriptor *descr;		/* descriptor of this config */
71
72	size_t						interface_count;/* interfaces in this config */
73	usb_interface_list			*interface;
74};
75
76typedef void (*usb_callback_func)(void *cookie, status_t status, void *data,
77	size_t actualLength);
78
79
80/* The usb_module_info represents the public API of the USB Stack. */
81struct usb_module_info {
82	bus_manager_info				binfo;
83
84	/*
85	 *	Use register_driver() to inform the Stack of your interest to support
86	 *	USB devices. Support descriptors are used to indicate support for a
87	 *	specific device class/subclass/protocol or vendor/product.
88	 *	A value of 0 can be used as a wildcard for all fields.
89	 *
90	 *	Would you like to be notified about all added hubs (class 0x09) you
91	 *	would a support descriptor like this to register_driver:
92	 *		usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 };
93	 *
94	 *	If you intend to support just any device, or you at least want to be
95	 *	notified about any device, just pass NULL as the supportDescriptor and
96	 *	0 as the supportDescriptorCount to register_driver.
97	 */
98	status_t						(*register_driver)(const char *driverName,
99										const usb_support_descriptor *supportDescriptors,
100										size_t supportDescriptorCount,
101										const char *optionalRepublishDriverName);
102
103	/*
104	 *	Install notification hooks using your registered driverName. The
105	 *	device_added hook will be called for every device that matches the
106	 *	support descriptors you provided in register_driver.
107	 *	When first installing the hooks you will receive a notification about
108	 *	any already present matching device. If you return B_OK in this hook,
109	 *	you can use the id that is provided. If the hook indicates an error,
110	 *	the resources will be deallocated and you may not use the usb_device
111	 *	that is provided. In this case you will not receive a device_removed
112	 *	notification for the device either.
113	 */
114	status_t						(*install_notify)(const char *driverName,
115										const usb_notify_hooks *hooks);
116	status_t						(*uninstall_notify)(const char *driverName);
117
118	/* Get the device descriptor of a device. */
119	const usb_device_descriptor		*(*get_device_descriptor)(const usb_device *device);
120
121	/* Get the nth supported configuration of a device*/
122	const usb_configuration_info	*(*get_nth_configuration)(const usb_device *device,
123										uint index);
124
125	/* Get the current configuration */
126	const usb_configuration_info	*(*get_configuration)(const usb_device *device);
127
128	/* Set the current configuration */
129	status_t						(*set_configuration)(const usb_device *device,
130										const usb_configuration_info *configuration);
131
132	status_t						(*set_alt_interface)(const usb_device *device,
133										const usb_interface_info *interface);
134
135	/*
136	 *	Standard device requests - convenience functions
137	 *	The provided object may be a usb_device, usb_pipe or usb_interface
138	 */
139	status_t						(*set_feature)(const void *object, uint16 selector);
140	status_t						(*clear_feature)(const void *object, uint16 selector);
141	status_t						(*get_status)(const void *object, uint16 *status);
142
143	status_t						(*get_descriptor)(const usb_device *device,
144										uint8 descriptorType, uint8 index,
145										uint16 languageID, void *data,
146										size_t dataLength,
147										size_t *actualLength);
148
149	/* Generic device request function - synchronous */
150	status_t						(*send_request)(const usb_device *device,
151										uint8 requestType, uint8 request,
152										uint16 value, uint16 index,
153										uint16 length, void *data,
154										size_t dataLength,
155										size_t *actualLength);
156
157	/*
158	 *	Asynchronous request queueing. These functions return immediately
159	 *	and the return code only tells whether the _queuing_ of the request
160	 *	was successful or not. It doesn't indicate transfer success or error.
161	 *
162	 *	When the transfer is finished, the provided callback function is
163	 *	called with the transfer status, a pointer to the data buffer and
164	 *	the actually transfered length as well as with the callbackCookie
165	 *	that was used when queuing the request.
166	 */
167	status_t						(*queue_interrupt)(const usb_pipe *pipe,
168										void *data, size_t dataLength,
169										usb_callback_func callback,
170										void *callbackCookie);
171
172	status_t						(*queue_bulk)(const usb_pipe *pipe,
173										void *data, size_t dataLength,
174										usb_callback_func callback,
175										void *callbackCookie);
176
177	status_t						(*queue_isochronous)(const usb_pipe *pipe,
178										void *data, size_t dataLength,
179										rlea *rleArray,
180										uint16 bufferDurationMS,
181										usb_callback_func callback,
182										void *callbackCookie);
183
184	status_t						(*queue_request)(const usb_device *device,
185										uint8 requestType, uint8 request,
186										uint16 value, uint16 index,
187										uint16 length, void *data,
188										size_t dataLength,
189										usb_callback_func callback,
190										void *callbackCookie);
191
192	status_t						(*set_pipe_policy)(const usb_pipe *pipe,
193										uint8 maxNumQueuedPackets,
194										uint16 maxBufferDurationMS,
195										uint16 sampleSize);
196
197	/* Cancel all pending async requests in a pipe */
198	status_t						(*cancel_queued_transfers)(const usb_pipe *pipe);
199
200	/* tuning, timeouts, etc */
201	status_t						(*usb_ioctl)(uint32 opcode, void *buffer,
202										size_t bufferSize);
203};
204
205
206#define	B_USB_MODULE_NAME		"bus_managers/usb/v2"
207
208
209#ifdef __cplusplus
210}
211#endif
212
213#endif /* !_USB_V2_H_ */
214