1/*
2 *	Version 3 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_V3_H_
9#define _USB_V3_H_
10
11#include <KernelExport.h>
12#include <bus_manager.h>
13#include <iovec.h>
14
15#include <USB_spec.h>
16#include <USB_isochronous.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22typedef struct usb_module_info usb_module_info;
23
24typedef uint32 usb_id;
25typedef usb_id usb_device;
26typedef usb_id usb_interface;
27typedef usb_id usb_pipe;
28
29typedef struct usb_endpoint_info usb_endpoint_info;
30typedef struct usb_interface_info usb_interface_info;
31typedef struct usb_interface_list usb_interface_list;
32typedef struct usb_configuration_info usb_configuration_info;
33
34typedef struct usb_notify_hooks {
35	status_t		(*device_added)(usb_device device, void **cookie);
36	status_t		(*device_removed)(void *cookie);
37} usb_notify_hooks;
38
39typedef struct usb_support_descriptor {
40	uint8						dev_class;
41	uint8						dev_subclass;
42	uint8						dev_protocol;
43	uint16						vendor;
44	uint16						product;
45} usb_support_descriptor;
46
47struct usb_endpoint_info {
48	usb_endpoint_descriptor		*descr;			/* descriptor and handle */
49	usb_pipe					handle;			/* of this endpoint/pipe */
50};
51
52struct usb_interface_info {
53	usb_interface_descriptor	*descr;			/* descriptor and handle */
54	usb_interface				handle;			/* of this interface */
55
56	size_t						endpoint_count;	/* count and list of endpoints */
57	usb_endpoint_info			*endpoint;		/* in this interface */
58
59	size_t						generic_count;	/* unparsed descriptors in */
60	usb_descriptor				**generic;		/* this interface */
61};
62
63struct usb_interface_list {
64	size_t						alt_count;		/* count and list of alternate */
65	usb_interface_info			*alt;			/* interfaces available */
66
67	usb_interface_info			*active;		/* currently active alternate */
68};
69
70struct usb_configuration_info {
71	usb_configuration_descriptor *descr;		/* descriptor of this config */
72
73	size_t						interface_count;/* interfaces in this config */
74	usb_interface_list			*interface;
75};
76
77// Flags for queue_isochronous
78#define	USB_ISO_ASAP	0x01
79
80typedef void (*usb_callback_func)(void *cookie, status_t status, void *data,
81	size_t actualLength);
82
83
84/* The usb_module_info represents the public API of the USB Stack. */
85struct usb_module_info {
86	bus_manager_info				binfo;
87
88	/*
89	 *	Use register_driver() to inform the Stack of your interest to support
90	 *	USB devices. Support descriptors are used to indicate support for a
91	 *	specific device class/subclass/protocol or vendor/product.
92	 *	A value of 0 can be used as a wildcard for all fields.
93	 *
94	 *	Would you like to be notified about all added hubs (class 0x09) you
95	 *	would use a support descriptor like this for register_driver:
96	 *		usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 };
97	 *
98	 *	If you intend to support just any device, or you at least want to be
99	 *	notified about any device, just pass NULL as the supportDescriptor and
100	 *	0 as the supportDescriptorCount to register_driver.
101	 */
102	status_t						(*register_driver)(const char *driverName,
103										const usb_support_descriptor *supportDescriptors,
104										size_t supportDescriptorCount,
105										const char *optionalRepublishDriverName);
106
107	/*
108	 *	Install notification hooks using your registered driverName. The
109	 *	device_added hook will be called for every device that matches the
110	 *	support descriptors you provided in register_driver.
111	 *	When first installing the hooks you will receive a notification about
112	 *	any already present matching device. If you return B_OK in this hook,
113	 *	you can use the id that is provided. If the hook indicates an error,
114	 *	the resources will be deallocated and you may not use the usb_device
115	 *	that is provided. In this case you will not receive a device_removed
116	 *	notification for the device either.
117	 */
118	status_t						(*install_notify)(const char *driverName,
119										const usb_notify_hooks *hooks);
120	status_t						(*uninstall_notify)(const char *driverName);
121
122	/* Get the device descriptor of a device. */
123	const usb_device_descriptor		*(*get_device_descriptor)(usb_device device);
124
125	/* Get the nth supported configuration of a device*/
126	const usb_configuration_info	*(*get_nth_configuration)(usb_device device,
127										uint32 index);
128
129	/* Get the current configuration */
130	const usb_configuration_info	*(*get_configuration)(usb_device device);
131
132	/* Set the current configuration */
133	status_t						(*set_configuration)(usb_device device,
134										const usb_configuration_info *configuration);
135
136	status_t						(*set_alt_interface)(usb_device device,
137										const usb_interface_info *interface);
138
139	/*
140	 *	Standard device requests - convenience functions
141	 *	The provided handle may be a usb_device, usb_pipe or usb_interface
142	 */
143	status_t						(*set_feature)(usb_id handle, uint16 selector);
144	status_t						(*clear_feature)(usb_id handle, uint16 selector);
145	status_t						(*get_status)(usb_id handle, uint16 *status);
146
147	status_t						(*get_descriptor)(usb_device device,
148										uint8 descriptorType, uint8 index,
149										uint16 languageID, void *data,
150										size_t dataLength,
151										size_t *actualLength);
152
153	/* Generic device request function - synchronous */
154	status_t						(*send_request)(usb_device device,
155										uint8 requestType, uint8 request,
156										uint16 value, uint16 index,
157										uint16 length, void *data,
158										size_t *actualLength);
159
160	/*
161	 *	Asynchronous request queueing. These functions return immediately
162	 *	and the return code only tells whether the _queuing_ of the request
163	 *	was successful or not. It doesn't indicate transfer success or error.
164	 *
165	 *	When the transfer is finished, the provided callback function is
166	 *	called with the transfer status, a pointer to the data buffer and
167	 *	the actually transfered length as well as with the callbackCookie
168	 *	that was used when queuing the request.
169	 */
170	status_t						(*queue_interrupt)(usb_pipe pipe,
171										void *data, size_t dataLength,
172										usb_callback_func callback,
173										void *callbackCookie);
174
175	status_t						(*queue_bulk)(usb_pipe pipe,
176										void *data, size_t dataLength,
177										usb_callback_func callback,
178										void *callbackCookie);
179
180	status_t						(*queue_bulk_v)(usb_pipe pipe,
181										iovec *vector, size_t vectorCount,
182										usb_callback_func callback,
183										void *callbackCookie);
184
185	status_t						(*queue_bulk_v_physical)(usb_pipe pipe,
186										physical_entry *vectors, size_t vectorCount,
187										usb_callback_func callback,
188										void *callbackCookie);
189
190	status_t						(*queue_isochronous)(usb_pipe pipe,
191										void *data, size_t dataLength,
192										usb_iso_packet_descriptor *packetDesc,
193										uint32 packetCount,
194										uint32 *startingFrameNumber,
195										uint32 flags,
196										usb_callback_func callback,
197										void *callbackCookie);
198
199	status_t						(*queue_request)(usb_device device,
200										uint8 requestType, uint8 request,
201										uint16 value, uint16 index,
202										uint16 length, void *data,
203										usb_callback_func callback,
204										void *callbackCookie);
205
206	status_t						(*set_pipe_policy)(usb_pipe pipe,
207										uint8 maxNumQueuedPackets,
208										uint16 maxBufferDurationMS,
209										uint16 sampleSize);
210
211	/* Cancel all pending async requests in a pipe */
212	status_t						(*cancel_queued_transfers)(usb_pipe pipe);
213
214	/* Cancel all pending async requests in a device control pipe */
215	status_t						(*cancel_queued_requests)(usb_device device);
216
217	/* Tuning, configuration of timeouts, etc */
218	status_t						(*usb_ioctl)(uint32 opcode, void *buffer,
219										size_t bufferSize);
220
221	/*
222	 * Enumeration of device topology - With these commands you can enumerate
223	 * the roothubs and enumerate child devices of hubs. Note that the index
224	 * provided to get_nth_child does not map to the port where the child
225	 * device is attached to. To get this information you would call
226	 * get_device_parent which provides you with the parent hub and the port
227	 * index of a device. To test whether an enumerated child is a hub you
228	 * can either examine the device descriptor or you can call get_nth_child
229	 * and check the returned status. A value of B_OK indicates that the call
230	 * succeeded and the returned info is valid, B_ENTRY_NOT_FOUND indicates
231	 * that you have reached the last index. Any other error indicates that
232	 * the provided arguments are invalid (i.e. not a hub or invalid pointers)
233	 * or an internal error occured. Note that there are no guarantees that
234	 * the device handle you get stays valid while you are using it. If it gets
235	 * invalid any further use will simply return an error. You should install
236	 * notify hooks to avoid such situations.
237	 */
238	status_t						(*get_nth_roothub)(uint32 index,
239										usb_device *rootHub);
240	status_t						(*get_nth_child)(usb_device hub,
241										uint8 index, usb_device *childDevice);
242	status_t						(*get_device_parent)(usb_device device,
243										usb_device *parentHub,
244										uint8 *portIndex);
245
246	/*
247	 * Hub interaction - These commands are only valid when used with a hub
248	 * device handle. Use reset_port to trigger a reset of the port with index
249	 * portIndex. This will cause a disconnect event for the attached device.
250	 * With disable_port you can specify that the port at portIndex shall be
251	 * disabled. This will also cause a disconnect event for the attached
252	 * device. Use reset_port to reenable a previously disabled port.
253	 */
254	status_t						(*reset_port)(usb_device hub,
255										uint8 portIndex);
256	status_t						(*disable_port)(usb_device hub,
257										uint8 portIndex);
258};
259
260
261#define	B_USB_MODULE_NAME		"bus_managers/usb/v3.1"
262
263
264#ifdef __cplusplus
265}
266#endif
267
268#endif /* !_USB_V3_H_ */
269