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 */ 8 9 10/*! 11 \page usb_modules Writing drivers for USB devices 12 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. 19 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. 26 27 \section usb_modules_scope The Scope of this Document 28 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 it's own interface for drivers, and so does Haiku. 35 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. 44 45 \section usb_modules_structure Structure of the Stack 46 47 This section will outline how Haiku's USB stack is structured, and how you 48 can interact with this stack. 49 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. 60 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. 72 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. 79 80 \section usb_modules_registration Initial Steps: Driver Registration 81 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. 85 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. 89 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. 93 94\code 95// Global variables and constants 96usb_module_info *gUsb; 97const char *kDriverName = "usb_hid"; 98 99static usb_support_descriptor sSupportedDevices[1] = { 100 { USB_HID_DEVICE_CLASS, 0, 0, 0, 0 }, 101}; 102 103// Prototype for the hooks that are called when devices are added or removed 104static status_t hid_device_added(const usb_device *dev, void **cookie); 105static status_t hid_device_removed(void *cookie); 106 107static usb_notify_hooks sNotifyHooks = { 108 hid_device_added, 109 hid_device_removed 110}; 111 112// Driver initialization, called by the kernel when the driver is loaded 113status_t 114init_driver(void) 115{ 116 if (get_module(B_USB_MODULE_NAME, (module_info **)&gUsb) != B_OK) 117 return B_ERROR; 118 119 gUsb->register_driver(kDriverName, sSupportedDevices, 120 1, NULL); 121 gUsb->install_notify(kDriverName, &sNotifyHooks); 122 123 return B_OK; 124} 125\endcode 126 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. 131 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 it's 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. 140 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. 149 150 \section usb_modules_changes Handling Device Changes 151 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. 156 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. 163 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). 170 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. 175 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. 185 186 \section usb_modules_standard Standard USB Operations 187 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. 193 194 \subsection usb_modules_standard_descriptors Configurations, Interfaces and Descriptors 195 196 Many standard USB operations have to do with configurations, interfaces and 197 descriptors. All these operations are accessible by convenience functions. 198 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. 203 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(). 209 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. 215 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. 226 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. 231 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. 239 240 \subsection usb_modules_standard_features Features 241 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). 247 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 . 251 252 \subsection usb_modules_standard_other Other Standard Calls 253 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. 256 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. 260 261 \section usb_modules_transfers Data Transfers 262 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. 266 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. 274 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. 282 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. 289 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. 296 297 \subsection usb_modules_transfers_control Control Requests 298 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. 306 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: 311 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. 316 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 323 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. 331 332 \subsection usb_modules_transfers_interrupt Interrupt 333 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. 337 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. 344 345 \subsection usb_modules_transfers_bulk Bulk 346 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. 353 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. 359 360 \subsection usb_modules_transfers_isochronous Isochronous 361 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. 364 365 \section usb_modules_cleanup Cleaning Up 366 367 This section describes how to gracefully leave the stack after your driver is 368 requested to shut down. 369 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. 374 375\code 376void 377uninit_driver(void) 378{ 379 usb->uninstall_notify(kDriverName); 380 put_module(B_USB_MODULE_NAME); 381} 382\endcode 383 384 \section usb_modules_resources More Resources 385 386 This section should list more resources on the web. 387*/ 388