headers/bsd: Add sys/queue.h.
[haiku.git] / docs / user / drivers / usb_modules.dox
blob9a99df015f056e880ddf1849a32375575399fa65
1 /*
2  * Copyright 2007 Haiku Inc. All rights reserved.
3  * Distributed under the terms of the MIT License.
4  *
5  * Authors:
6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
7  */
10 /*!
11         \page usb_modules Writing drivers for USB devices
13         The introduction of USB standardized the way many devices connected to a
14         whole range of different computers and operating systems. It introduced a
15         standard that was capable of getting rid of all the legacy systems, such as
16         the LPT, the PS/2 and serial ports. The plug and play nature of the standard
17         was revolutionary at the time of its introduction, and it changed the way
18         which operating systems interacted with devices.
20         With the grand standard that USB has become, Haiku has an implementation
21         of it. It supports both the USB 1.1 and USB 2.0 specifications, and when
22         Haiku R1 is released, it will support the three host controller standards:
23         UHCI, OHCI and EHCI. The modularized design of Haiku's USB stack also paves
24         the way for easy implementation of any future specifications, such as
25         Wireless USB.
27         \section usb_modules_scope The Scope of this Document
29         This document is written for driver developers that need to interact with
30         USB devices. The USB specification standardizes the communication between
31         the host controller and the devices, and how devices should transfer data,
32         but it does not prescribe a standard environment that Operating Systems
33         should provide to the driver interfaces. As such, every operating system has
34         its own interface for drivers, and so does Haiku.
36         This document will point driver developers to relevant parts of the USB
37         module API and give a general impression of the workings of the USB stack.
38         This document will not give information on the basics of writing drivers, or
39         on how to use modules. Have a look elsewhere in this documentation for that.
40         This document also assumes a basic knowledge of the USB specification, and on
41         how you are supposed to interact with devices. See \ref usb_modules_resources
42         for tutorials on the web if you are looking for a basic introduction on
43         communication with the USB protocol.
45         \section usb_modules_structure Structure of the Stack
47         This section will outline how Haiku's USB stack is structured, and how you
48         can interact with this stack.
50         The goal of the USB stack is to provide a few basic features for drivers
51         interacting with USB devices. It is important that the stack maintains a
52         continually updated device grid, so that the driver modules are always
53         aware of the latest status. The stack should also facilitate communication
54         between drivers and the devices, by abstracting the actual transferring of
55         bits via the host controller hardware in the computer. The stack therefore
56         should implement a intuitive interface to give driver developers access to
57         all features and possibilities the USB specification offers, and at the same
58         time it should abstract many of the small requirements and peculiarities of
59         that specification.
61         The stack internally can be divided into two parts. The first part is the
62         core module. This module, called \c usb_busmanager, performs all the
63         operations required by the USB specification. For example, it performs the
64         necessary low-level initialization when new devices are connected, or all the
65         requirements when it comes to performing transfers. The core module also
66         is the module that provides the abstractions to driver developers. The other
67         part of the USB stack are the individual modules that control the different
68         host controllers. Haiku supports the three types in existence: UHCI, OHCI
69         and EHCI. These modules perform the communication between the core module
70         and the hardware. As driver developer, you won't have to interact with these
71         modules: the core module provides all the abstractions you need.
73         Thus, as a driver developer you are interfacing with the \c usb_busmanager
74         module. On Haiku, this module implements two API's. The \c v2 API, identical
75         to the API offered by BeOS R5, can be found in the \c USB2.h file. However,
76         for new drivers, or for ports, the recommended API is the \c v3 API, defined
77         in the USB3.h file. This API is identical to the one provided by Zeta. The
78         \c v2 API should be considered to be deprecated.
80         \section usb_modules_registration Initial Steps: Driver Registration
82         In order to be able to start using the USB stack to communicate with your
83         devices, you will need to perform some actions. This section will outline
84         those actions and will point you to their appropriate locations. 
86         \note The code examples are based on the \c usb_hid driver written by
87                 Jerome Duval. Have a look at this driver for a complete working
88                 example.
90         The following example gives an overview of the requirements to open the 
91         USB module, and to start your driver registration in order to receive
92         connect and disconnect events. 
94 \code
95 // Global variables and constants
96 usb_module_info *gUsb;
97 const char *kDriverName = "usb_hid";
99 static usb_support_descriptor sSupportedDevices[1] = {
100     { USB_HID_DEVICE_CLASS, 0, 0, 0, 0 },
103 // Prototype for the hooks that are called when devices are added or removed
104 static status_t hid_device_added(const usb_device *dev, void **cookie);
105 static status_t hid_device_removed(void *cookie);
107 static usb_notify_hooks sNotifyHooks = {
108         hid_device_added,
109         hid_device_removed
112 // Driver initialization, called by the kernel when the driver is loaded
113 status_t 
114 init_driver(void)
116     if (get_module(B_USB_MODULE_NAME, (module_info **)&gUsb) != B_OK)
117         return B_ERROR;
119     gUsb->register_driver(kDriverName, sSupportedDevices, 
120         1, NULL);
121     gUsb->install_notify(kDriverName, &sNotifyHooks);
123     return B_OK;
125 \endcode
127         Basically, this boils down to three steps. The first step is to acquire the
128         usb_module_info module. This struct contains a set of function pointers that
129         you use to communicate with the stack. You can retrieve it like you would
130         retrieve any other module.
132         As soon as you have done that you can start registering your driver in the
133         stack. What you do is you pass a unique identifier to identify your driver,
134         zero or more \link usb_support_descriptor support descriptors \endlink
135         to provide the stack with information on which devices you support, and the
136         number of support descriptors you provided. The stack is very flexible with
137         what patterns it accepts, so even the most complex driver will be able to
138         pass its credentials. Have a look at the \c usb_support_descriptor struct
139         and the \c usb_module_info::register_driver() call for all the details.
141         The last step in initialization is to provide the stack with notification
142         hooks. These are functions in your driver that the stack should call as soon
143         as a device is attached or removed. Please perform this call after your
144         internal driver data structures are initialized, because as soon as you
145         perform this call, the usb stack will start searching for already attached
146         devices that match the credentials. Have a look at
147         \c usb_module_info::install_notify() and the structure \c usb_notify_hooks
148         for the details on the signatures of your hooks.
150         \section usb_modules_changes Handling Device Changes
152         The USB stack will notify you of device connects and disconnects when they
153         occur. You will receive notifications as soon as you have supplied the hooks
154         to the stack, using \c usb_module_info::install_notify() . This section will
155         explain some of the details when it comes to handling device changes.
157         When a device is added, your supplied usb_notify_hooks::device_added() hook
158         will be called if its credentials matches one of your support descriptors.
159         Because the stack runs through all the registered drivers, it could be that
160         two or more drivers operate on the same device. The stack does not provide
161         a locking mechanism to prevent two conflicting drivers to get in each others
162         way. It is up to the device maker to have supplied such a mechanism.
164         \note In reality, it is very likely that your device will match at least one
165         other driver, because Haiku supplies the \c usb_raw driver. This driver
166         provides userland access to the usb devices and therefore it has a blank
167         support descriptor that matches everything. The \c usb_raw driver will
168         not conflict with your device interaction though (except when there is an
169         userland application that tries to meddle with your device).
171         If your driver is willing to accept the supplied device, and your 
172         device_added() hook returns B_OK, the USB stack will ask the kernel to reload
173         your published devices, so that your device is visible in userspace in the
174         \c /dev tree.
176         The other event that the stack reports, device disconnection, should be
177         handled by your \c usb_notify_hooks::device_removed() hook. Because "plug and
178         play" also means "unplug and leave", you should make sure your driver is 
179         capable of cleaning up in the likely event that the user removes their
180         device, even during transfers. In your hook function, you have the ability to
181         do clean up whatever there is to clean up, however, make sure that you cancel
182         all the pending transfers. Use the usb_module_info::cancel_queued_transfers()
183         call for that end. Also, don't forget to free the cookie you supplied in your
184         device_added() hook. 
186         \section usb_modules_standard Standard USB Operations
188         One of the many conveniences of the Haiku USB API is the fact that many of
189         the standard operations can be performed by simple function calls. As such,
190         you won't have to build many of the standard requests the USB specification
191         defines by hand. This section will outline all the different conveniences and
192         will point you to where to look if you do need something more advanced.
194         \subsection usb_modules_standard_descriptors Configurations, Interfaces and Descriptors
196         Many standard USB operations have to do with configurations, interfaces and
197         descriptors. All these operations are accessible by convenience functions.
199         The device descriptor is one of the first things you will be interested in if
200         you want to check out a device. The device descriptor can be retrieved quite
201         easily using the \c usb_module_info::get_device_descriptor() call. The
202         retrieved descriptor complies to the one dictated by the USB standard.
204         Also important are configurations. Since every device has at least one
205         configuration, you should be able to retrieve and manipulate configurations.
206         You can use \c usb_module_info::get_nth_configuration() to get them. To set
207         a configuration, you should use \c usb_module_info::set_configuration(). To
208         get the active configuration, use \c usb_module_info::get_configuration().
210         \attention By default, Haiku's stack will set the configuration at offset
211         zero, which is according to the standard, the default configuration.
212         Do not rely on that if you first get the device, that the currently active
213         configuration is the default configuration though. Another driver might
214         have manipulated this device already.
216         Every configuration has associated interfaces. To make life easier, the stack
217         automatically gets the interface descriptors (and their associated
218         endpoints), and stores them in the \c usb_configuration_info structure. This
219         structure has a member called \link usb_configuration_info::interface
220         \c interface \endlink which is of the type \c usb_interface_list. That object
221         containts all the interfaces, including a pointer to the interface that is
222         currently active. Each interface is described as a \c usb_interface_info,
223         which is a container for the interface, its associated endpoints and any
224         unparsed descriptors. In order to change the active interface, you can use
225         the stack's \c usb_module_info::set_alt_interface() call. 
227         Endpoints, the basic units with which you can communicate, are stored as
228         \c usb_endpoint_info structures. Each of these structures carries the actual
229         endpoint descriptor, and the accompanying usb_pipe handle that you can use to
230         actually send and receive data.
232         The last point of interest are descriptors. As you have seen, Haiku caches
233         all the relevant descriptors itself, however, you might want to retrieve any
234         other type of descriptor that could be relevant for your device. The
235         convenience function to use in such a case is the 
236         \c usb_module_info::get_descriptor() call. This function takes all the
237         parameters needed to build the actual descriptor, and performs the request
238         over the default control pipe.
240         \subsection usb_modules_standard_features Features
242         Another one of the building blocks of USB are features. Every device should
243         provide for a number of standard features, but the USB specification also
244         leaves the option to using custom device specific features. Feature requests
245         can be performed on devices, interfaces and pipes (which are tied to
246         endpoints). 
248         To set a feature, you can use the \c usb_module_info::set_feature() call. To
249         clear a feature, use the \c usb_module_info::clear_feature() call. One of the
250         most used feature calls is the call to clear a \c USB_FEATURE_ENDPOINT_HALT .
252         \subsection usb_modules_standard_other Other Standard Calls
254         To get the status of a device, an interface or an endpoint, you can use the
255         \c usb_module_info::get_status() call.
257         If you are using isochronous transfers, you can use the
258         \c usb_module_info::set_pipe_policy() to set the properties of the
259         isochronous pipe. 
261         \section usb_modules_transfers Data Transfers
263         Transfering data is one of the basic building blocks of the USB protocol.
264         This section will demonstrate how to perform transfers via the four different
265         protocols the USB stack offers.
267         But first it is essential to show how to perform the transfers using the
268         \c usb_module_info interface. The interface provides five \c queue_*
269         functions, with the asterix being one of the following: \c bulk, \c bulk_v
270         (bulk transfers using a vector), \c interrupt, \c isochronous or \c request
271         (over the standard control pipe). These five functions work asynchronously,
272         which means that your driver is called back from a different thread when your
273         transfer is finished. 
275         The five functions share some arguments. The first argument is always the
276         pipe that is associated with the endpoint (except for control transfers,
277         these only work on the device in general). All of the functions accept a data
278         buffer, and the length of that   buffer. All of the functions require a
279         \c #usb_callback_func, a function in your driver that can be called in case a
280         transfer is finished. The functions also require a cookie that is provided to
281         the callback function. 
283         The working order is as follows: first you queue a transfer, then you handle
284         the result in the callback function when it's done. The callback function
285         will be called with a \a status argument, in which you can check whether or
286         not the transfer actually succeeded. See this \link #usb_callback_func 
287         description \endlink for how your callback function should behave and what
288         kind of status there might have been.
290         Finally, before going into the different transfer types, a note on buffer
291         ownership. The usb stack keeps the internal buffers tidy, but the buffer you
292         provide to the \c queue_* functions are yours. You are responsible for
293         allocating and freeing them, and you may do with them whatever you like,
294         \e except between queueing your transfer and the callback. During that period
295         you should consider the USB stack the owner of the buffer.
297         \subsection usb_modules_transfers_control Control Requests
299         Control requests are done over the device wide control pipe which is provided
300         by every device. Haiku's stack has two functions that you can use to perform
301         custom requests (opposed to many of the \ref usb_modules_standard
302         "standard operations"). Control transfers are the only transfers that you can
303         perform synchronously as well as asynchronously. The functions you can use
304         are \c usb_module_info::send_request() for synchronous requests and
305         \c usb_module_info::queue_request() for asynchronous requests. 
307         Many of the constants that you should use when performing can be found in
308         the USB_spec.h file which is automatically included if you include the main
309         USB header. Have a look of how to use these constants in the following
310         example:
312 \code
313     // Send a request that is defined by the standard of this class. We retrieve
314     // a report from the device on one of its interfaces.
315     // This request is specified by the HID specification.
317     status = usb->send_request(dev,
318         USB_REQTYPE_INTERFACE_IN | USB_REQTYPE_CLASS,
319         USB_REQUEST_HID_GET_REPORT, 0x0100 | report_id,
320         interfaceNumber, device->total_report_size,
321         device->buffer, &actual);
322 \endcode
324         \warning Both the \link usb_module_info::send_request() \a send_request()
325         \endlink and \link usb_module_info::queue_request() \a queue_request()
326         \endlink functions can be used to perform standard usb requests. Avoid
327         low-level operations, because the stack needs to keep its internal
328         data structures consistent. If you need to perform one of the 
329         \ref usb_modules_standard "standard operations", use the provided
330         convenience functions.
332         \subsection usb_modules_transfers_interrupt Interrupt
334         Interrupt transfers apply to endpoints that receive data, or that can be
335         polled in several instances of time. The intervals are determined by the
336         endpoint descriptor.
338         To schedule a transfer, use usb_module_info::queue_interrupt(). You only have
339         to supply a buffer, the stack schedule the transfer in such a way that it
340         will be performed within a certain timeframe. To create a continuous
341         interrupt system, you should queue the next transfer in the callback function
342         of the previous. The stack will make sure that the new transfer will be
343         performed exactly after the required interval. 
345         \subsection usb_modules_transfers_bulk Bulk
347         Bulk transfers are very similar to control transfers. They will be performed
348         as soon as possible without stalling other transfers, and they transfer data.
349         Bulk transfers are designed to transfer up to large amounts of data as
350         efficiently as possible. Performing bulk transfers isn't difficult, you
351         merely supply a buffer and the endpoint that should execute the request, and
352         you're set. 
354         Bulk transfers come in two flavours. The first is 
355         usb_module_info::queue_bulk(), which takes a standard data buffer. The second
356         flavour is the usb_module_info::queue_bulk_v() function, which is designed to
357         operate on (an array of) POSIX vectors. These functions only differ in the
358         buffer they accept, they function in exactly the same way.
360         \subsection usb_modules_transfers_isochronous Isochronous
362         Isochronous transfers are not implemented on Haiku yet. As soon as they are,
363         this section should contain information on how to queue them.
365         \section usb_modules_cleanup Cleaning Up
367         This section describes how to gracefully leave the stack after your driver is
368         requested to shut down.
370         There are truely only two simple actions to perform. The first is to
371         uninstall your notification hooks, using 
372         \c usb_module_info::uninstall_notify(). The second action is to 'put' the
373         module.
375 \code
376 void
377 uninit_driver(void)
379     usb->uninstall_notify(kDriverName);
380     put_module(B_USB_MODULE_NAME);
382 \endcode
384         \section usb_modules_resources More Resources
386         This section should list more resources on the web.