1Device Driver Architecture 2================================================== 3 4This document tries to give you a short introduction into the new device 5manager, and how to write drivers for it. Haiku still supports the 6legacy device driver architecture introduced with BeOS. 7 8The new device driver architecture of Haiku is still a moving target, 9although most of its details are already specificed. 10 111. The Basics 12------------- 13 14The device manager functionality builds upon *device_node* objects. 15Every driver in the system publishes one or more of such nodes, building 16a tree of device nodes. This tree is in theory a dynamic representation 17of the current hardware devices in the system, but in practice will also 18contain implementation specific details; since every node comes with an 19API specific to that node, you'll find device nodes that only come with 20a number of support functions for a certain class of drivers. 21 22Structurally, a *device_node* is a set of a module, attributes, and 23resources, as well as a parent and children. At a minimum, a node must 24have a module, all other components are optional. 25 26TODO: picture of the device node tree 27 28When the system starts, there is only a root node registered. Only 29primary hardware busses register with the root node, such as PCI, and 30ISA on x86. Since the PCI bus is an intelligent bus, it knows what 31hardware is installed, and registers a child node for each device on the 32bus. 33 34Every driver can also publish a device in */dev* for communication with 35userland applications. All drivers and devices are kernel modules. 36 372. Exploring the Device Tree 38---------------------------- 39 40So how does it all work? When building the initial device tree, the 41system only explores a minimum of device drivers only, resulting in a 42tree that basically only shows the hardware found in the computer. 43 44Now, if the system requires disk access, it will scan the device file 45system for a driver that provides such functionality, in this case, it 46will look for drivers under "/dev/disk/". The device manager has a set 47of built-in rules for how to translate a device path into a device node, 48and vice versa: every node representing a device of an intelligent bus 49(such as PCI) will also contain device type information following the 50PCI definitions. In this case, the "disk" sub-path will translate into 51the *PCI_mass_storage* type, and hence, the device manager will then 52completely explore all device nodes of that type. 53 54It will also use that path information to only ask drivers that actually 55are in a matching module directory. In the above example of a disk 56driver, this would be either in "busses/scsi", "busses/ide", 57"drivers/disk", ... 58 59For untyped or generic busses, it will use the context information 60gained from the devfs query directly, and will search for drivers in 61that sub directory only. The only exception to this rule are the devfs 62directories "disk", "ports", and "bus", which will also allow to search 63matching drivers in "busses". While this is relatively limited, it is a 64good way to cut down the number of drivers to be loaded. 65 663. Writing a Driver 67------------------- 68 69The device manager assumes the following API from a driver module: 70 71- **supports_device()** 72 Determines wether or not the driver supports a given parent device 73 node, that is the hardware device it represents (if any), and the API 74 the node exports. 75- **register_device()** 76 The driver should register its device node here. The parent driver is 77 always initialized at this point. When registering the node, the 78 driver can also attach certain I/O resources (like I/O ports, or 79 memory ranges) to the node -- the device manager will make sure that 80 only one node can claim these resources. 81- **init_driver()** 82 Any initialization necessary to get the driver going. For most 83 drivers, this will be reduced to the creation of a private data 84 structure that is going to be used for all of the following 85 functions. 86- **uninit_driver()** 87 Uninitializes resources acquired by **init_driver()**. 88- **register_child_devices()** 89 If the driver wants to register any child device nodes or to publish 90 any devices, it should do so here. This function is called only 91 during the initial registration process of the device node. 92- **rescan_child_devices()** 93 Is called whenever a manual rescan is triggered. 94- **device_removed()** Is called when the device node is about to be 95 unregistered when its device is gone, for example when a USB device 96 is unplugged. 97- **suspend()** 98 Enters different sleep modes. 99- **resume()** 100 Resumes a device from a previous sleep mode. 101 102To ensure that a module exports this API, it **must** end its module 103name with "driver_v1" to denote the version of the API it supports. Note 104that **suspend()** and **resume()** are currently never called, as Haiku 105has no power management implemented yet. 106 107If your driver can give the device it is attached to a nice name that 108can be presented to the user, it should add the **B_DEVICE_PRETTY_NAME** 109attribute to the device node. 110 111The **B_DEVICE_UNIQUE_ID** should be used in case the device has a 112unique ID that can be used to identify it, and also differentiate it 113from other devices of the same model and vendor. This information will 114be added to the file system attributes of all devices published by your 115driver, so that user applications can identify, say, a USB printer no 116matter what USB slot it is attached to, and assign it additional data, 117like paper configuration, or recognize it as the default printer. 118 119If your driver implements an API that is used by a support or bus 120module, you will usually use the **B_DEVICE_FIXED_CHILD** attribute to 121specify exactly which child device node you will be talking to. If you 122support several child nodes, you may want to have a closer look at the 123section explaining `how to write a bus driver <#bus_driver>`__. 124 125In addition to the child nodes a driver registers itself, a driver can 126either have dynamic children or fixed children, never both. Also, fixed 127children are registered before **register_child_devices()** is called, 128while dynamic children are registered afterwards. 129 1304. Publishing a Device 131---------------------- 132 133To publish a device entry in the device file system under */dev*, all 134your driver has to do is to call the 135 136:: 137 138 publish_device(device_node *node, const char *path, 139 const char *deviceModuleName); 140 141function the device manager module exports. The *path* is the path 142component that follows "/dev", for example "net/ipro1000/0". The 143*deviceModuleName* is the module exporting the device functionality. It 144should end with "device_v1" to show the device manager which protocol it 145supports. If the device node your device belongs to is removed, your 146device is removed automatically with it. On the other hand, you are 147allowed to unpublish the device at any point using the 148**unpublish_device()** function the device manager delivers for this. 149 150A device module must export the following API: 151 152- **init_device()** 153 This is called when the open() is called on this device for the first 154 time. You may want to create a private data structure that is passed 155 on to all subsequent calls of the **open()** function that your 156 device exports. 157- **uninit_device()** 158 Is called when the last file descriptor to the device had been 159 closed. 160- **device_removed()** 161 When the device node your device belongs to is going to be removed, 162 you're notified about this in this function. 163- **open()** 164 Called whenever your device is opened. 165- **close()** 166- **free()** 167 Free the private data structure you allocated in **open()**. 168- **read()** 169- **write()** 170- **io()** 171 This is a replacement for the **read()**, and **write()** calls, and 172 allows, among other things, for asynchronous I/O. This functionality 173 has not yet been implemented, though (see below). 174- **control()** 175- **select()** 176- **deselect()** 177 1785. Writing a Bus Driver 179----------------------- 180 181A bus driver is a driver that represents a bus where one or more 182arbitrary devices can be attached to. 183 184There are two basic types of busses: intelligent busses like PCI or USB 185that know a lot about the devices attached to it, like a generic device 186type, as well as device and vendor ID information, and simple 187untyped/generic busses that either have not all the information (like 188device type) or don't even know what and if any devices are attached. 189The device manager has been written in such a way that device 190exploration makes use of additional information the bus can provide in 191order to find a responsible device driver faster, and with less 192overhead. 193 1945.1. Writing an Intelligent Bus Driver 195^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 196 197If your bus knows what type of device is attached to, and also has 198vendor and device ID information about that device, it is considered to 199be an intelligent bus. The bus driver is supposed to have one parent 200node representing the bus, and to create a child node for each device 201attached to the bus. 202 203The additional information you have about the devices are attached to 204the device node in the following attributes: 205 206- **B_DEVICE_VENDOR_ID** 207 The vendor ID - this ID has only to be valid in the namespace of your 208 bus. 209- **B_DEVICE_ID** 210 The device ID. 211- **B_DEVICE_TYPE** 212 The device type as defined by the PCI class base information. 213- **B_DEVICE_SUB_TYPE** 214 The device sub type as defined by the PCI sub class information. 215- **B_DEVICE_INTERFACE** 216 The device interface type as defined by the PCI class API 217 information. 218 219You can use the **B_DEVICE_FLAGS** attribute to define how the device 220manager finds the children of the devices you exported. For this kind of 221bus drivers, you will usually only want to specify 222**B_FIND_CHILD_ON_DEMAND** here, which causes the driver only to be 223searched when the system asks for it. 224 2255.2. Writing a Simple Bus Driver 226^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 227 228A bus can be simple in a number of ways: 229 230#. It may not know how many or if any devices are attached to it 231#. It cannot retrieve any type information about the devices it has, but 232 knows all devices that are attached to it 233 234An example of the latter would be the Zorro bus of the Amiga - it only 235has information about the vendor and device ID, but no type information. 236It should be implemented like an intelligent bus, though, with the type 237information simply omitted. 238 239Therefore, this section is about the former case, that is, a simple bus 240like the ISA bus. Since it doesn't know anything about its children, it 241does not publish any child nodes, instead, it will just specify the 242B_FIND_MULTIPLE_CHILDREN and B_FIND_CHILD_ON_DEMAND flags for its device 243node. Since there is no additional information about this bus, the 244device manager will assume a simple bus, and will try to find drivers on 245demand only. 246 247The generic bus 248--------------- 249 250Some devices are not tied to a specific bus. This is the case for all 251drivers that do not relate to a physical device: /dev/null, /dev/zero, 252/dev/random, etc. A "generic" bus has been added, and these drivers can 253attach to it. 254 2556. Open Issues 256-------------- 257 258While most of the new device manager is fledged out, there are some 259areas that could use improvements or are problematic under certain 260requirements. Also, some parts just haven't been written yet. 261 2626.1. generic/simple busses 263^^^^^^^^^^^^^^^^^^^^^^^^^^ 264 2656.2. Unpublishing 266^^^^^^^^^^^^^^^^^ 267 2686.4. Versioning 269^^^^^^^^^^^^^^^ 270 271The way the device manager works, it makes versioning of modules (which 272are supposed to be one of the strong points of the module system) much 273harder or even impossible. While the device manager could introduce a 274new API and could translate between a "driver_v1", and a "driver_v2" API 275on the fly, it's not yet possible for a PCI sub module to do the same 276thing. 277 278**Proposed Solution:** Add attribute **B_DEVICE_ALTERNATE_VERSION** that 279specifies alternate versions of the module API this device node 280supports. We would then need a **request_version()** or 281**set_version()** function (to be called from **supports_device()**) 282that allows to specify the version of the parent node this device node 283wants to talk to. 284 2856.5. Unregistering Nodes 286^^^^^^^^^^^^^^^^^^^^^^^^ 287 2886.6. Support for generic drivers is missing 289^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 290 291This should probably be done by simply adding a simple bus driver named 292"generic" that generic drivers need to ask for. 293 2946.7. Mappings, And Other Optimizations 295^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 296 297Due to the way the device tree is built, the device manager could 298remember which driver served a given device node. That way, it wouldn't 299need to search for a driver anymore, but could just pick it up. 300Practically, the device manager should cache the type (and/or 301vendor/device) information of a node, and assign one or more drivers 302(via module name) to this information. It should also remember negative 303outcome, that is if there is no driver supporting the hardware. 304 305This way, only the first boot would require an actual search for 306drivers, as subsequent boots would reuse the type-driver assignments. If 307a new driver is installed, the cached assignments would need to be 308updated immediately. If a driver has been installed outside of the 309running system, the device manager might want to create a hash per 310module directory to see if anything changed to flush the cache. 311Alternatively or additionally, the boot loader could have a menu causing 312the cache to be ignored. 313 314It would be nice to find a way for generic and simple busses to reduce 315the amount of searching necessary for them. One way would be to remember 316which driver supports which bus - but this information is currently only 317accessible derived from what the driver does, and is therefore not 318reliable or complete. A separately exported information would be 319necessary for this. 320 321Also, when looking for a generic or simple bus driver, actual 322directories could be omitted; currently, driver search is always 323recursive, as that's how the module mechanism is working. Eventually, we 324might want to extend the open_module_list_etc() call a bit more to 325accomplish that. 326