The Linux Device Model

The Linux Device Model

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. 362 Chapter 14 CHAPTER 14 The Linux Device Model One of the stated goals for the 2.5 development cycle was the creation of a unified device model for the kernel. Previous kernels had no single data structure to which they could turn to obtain information about how the system is put together. Despite this lack of information, things worked well for some time. The demands of newer systems, with their more complicated topologies and need to support features such as power management, made it clear, however, that a general abstraction describing the structure of the system was needed.

The 2.6 device model provides that abstraction. It is now used within the kernel to support a wide variety of tasks, including: Power management and system shutdown These require an understanding of the system’s structure. For example, a USB host adaptor cannot be shut down before dealing with all of the devices con- nected to that adaptor. The device model enables a traversal of the system’s hardware in the right order. Communications with user space The implementation of the sysfs virtual filesystem is tightly tied into the device model and exposes the structure represented by it. The provision of information about the system to user space and knobs for changing operating parameters is increasingly done through sysfs and, therefore, through the device model.

Hotpluggable devices Computer hardware is increasingly dynamic; peripherals can come and go at the whim of the user. The hotplug mechanism used within the kernel to handle and (especially) communicate with user space about the plugging and unplugging of devices is managed through the device model.

Device classes Many parts of the system have little interest in how devices are connected, but they need to know what kinds of devices are available. The device model includes a mechanism for assigning devices to classes, which describe those ,ch14.12359 Page 362 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. The Linux Device Model | 363 devices at a higher, functional level and allow them to be discovered from user space. Object lifecycles Many of the functions described above, including hotplug support and sysfs, complicate the creation and manipulation of objects created within the kernel.

The implementation of the device model required the creation of a set of mecha- nisms for dealing with object lifecycles, their relationships to each other, and their representation in user space.

The Linux device model is a complex data structure. For example, consider Figure 14-1, which shows (in simplified form) a tiny piece of the device model struc- ture associated with a USB mouse. Down the center of the diagram, we see the part of the core “devices” tree that shows how the mouse is connected to the system. The “bus” tree tracks what is connected to each bus, while the subtree under “classes” concerns itself with the functions provided by the devices, regardless of how they are connected. The device model tree on even a simple system contains hundreds of nodes like those shown in the diagram; it is a difficult data structure to visualize as a whole.

For the most part, the Linux device model code takes care of all these considerations without imposing itself upon driver authors. It sits mostly in the background; direct interaction with the device model is generally handled by bus-level logic and various other kernel subsystems. As a result, many driver authors can ignore the device model entirely, and trust it to take care of itself. There are times, however, when an understanding of the device model is a good thing to have. There are times when the device model “leaks out” from behind the other layers; for example, the generic DMA code (which we encounter in Figure 14-1.

A small piece of the device model Buses Devices Classes Input devs Mouse 1 pci() dev 0:10 usb 2 port 1 dev 1:1-0 usb drivers devices usb- hid ,ch14.12359 Page 363 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. 364 | Chapter 14: The Linux Device Model Chapter 15) works with struct device. You may want to use some of the capabili- ties provided by the device model, such as the reference counting and related fea- tures provided by kobjects. Communication with user space via sysfs is also a device model function; this chapter explains how that communication works. We start, however, with a bottom-up presentation of the device model. The com- plexity of the device model makes it hard to understand by starting with a high-level view.

Our hope is that, by showing how the low-level device components work, we can prepare you for the challenge of grasping how those components are used to build the larger structure.

For many readers, this chapter can be treated as advanced material that need not be read the first time through. Those who are interested in how the Linux device model works are encouraged to press ahead, however, as we get into the low-level details. Kobjects, Ksets, and Subsystems The kobject is the fundamental structure that holds the device model together. It was initially conceived as a simple reference counter, but its responsibilities have grown over time, and so have its fields. The tasks handled by struct kobject and its sup- porting code now include: Reference counting of objects Often, when a kernel object is created, there is no way to know just how long it will exist.

One way of tracking the lifecycle of such objects is through reference counting. When no code in the kernel holds a reference to a given object, that object has finished its useful life and can be deleted. Sysfs representation Every object that shows up in sysfs has, underneath it, a kobject that interacts with the kernel to create its visible representation.

Data structure glue The device model is, in its entirety, a fiendishly complicated data structure made up of multiple hierarchies with numerous links between them. The kobject implements this structure and holds it together. Hotplug event handling The kobject subsystem handles the generation of events that notify user space about the comings and goings of hardware on the system. One might conclude from the preceding list that the kobject is a complicated struc- ture. One would be right. By looking at one piece at a time, however, it is possible to understand this structure and how it works.

,ch14.12359 Page 364 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. Kobjects, Ksets, and Subsystems | 365 Kobject Basics A kobject has the type struct kobject; it is defined in . That file also includes declarations for a number of other structures related to kobjects and, of course, a long list of functions for manipulating them. Embedding kobjects Before we get into the details, it is worth taking a moment to understand how kob- jects are used. If you look back at the list of functions handled by kobjects, you see that they are all services performed on behalf of other objects.

A kobject, in other words, is of little interest on its own; it exists only to tie a higher-level object into the device model.

Thus, it is rare (even unknown) for kernel code to create a standalone kobject; instead, kobjects are used to control access to a larger, domain-specific object. To this end, kobjects are found embedded in other structures. If you are used to think- ing of things in object-oriented terms, kobjects can be seen as a top-level, abstract class from which other classes are derived. A kobject implements a set of capabilities that are not particularly useful by themselves but that are nice to have in other objects. The C language does not allow for the direct expression of inheritance, so other techniques—such as embedding one structure in another—must be used.

As an example, let’s look back at struct cdev, which we encountered in Chapter 3. That structure, as found in the 2.6.10 kernel, looks like this: struct cdev { struct kobject kobj; struct module *owner; struct file_operations *ops; struct list_head list; dev_t dev; unsigned int count; }; As we can see, the cdev structure has a kobject embedded within it. If you have one of these structures, finding its embedded kobject is just a matter of using the kobj field. Code that works with kobjects often has the opposite problem, however: given a struct kobject pointer, what is the pointer to the containing structure? You should avoid tricks (such as assuming that the kobject is at the beginning of the structure), and, instead, use the container_of macro (introduced in the section “The open Method” in Chapter 3).

So the way to convert a pointer to a struct kobject called kp embedded within a struct cdev would be: struct cdev *device = container_of(kp, struct cdev, kobj); Programmers often define a simple macro for “back-casting” kobject pointers to the containing type.

,ch14.12359 Page 365 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. 366 | Chapter 14: The Linux Device Model Kobject initialization This book has presented a number of types with simple mechanisms for initializa- tion at compile or runtime. The initialization of a kobject is a bit more complicated, especially when all of its functions are used. Regardless of how a kobject is used, however, a few steps must be performed. The first of those is to simply set the entire kobject to 0, usually with a call to mem- set.

Often this initialization happens as part of the zeroing of the structure into which the kobject is embedded. Failure to zero out a kobject often leads to very strange crashes further down the line; it is not a step you want to skip. The next step is to set up some of the internal fields with a call to kobject_init( ): void kobject_init(struct kobject *kobj); Among other things, kobject_init sets the kobject’s reference count to one. Calling kobject_init is not sufficient, however. Kobject users must, at a minimum, set the name of the kobject; this is the name that is used in sysfs entries.

If you dig through the kernel source, you can find the code that copies a string directly into the kob- ject’s name field, but that approach should be avoided. Instead, use: int kobject_set_name(struct kobject *kobj, const char *format ) ; This function takes a printk-style variable argument list. Believe it or not, it is actu- ally possible for this operation to fail (it may try to allocate memory); conscientious code should check the return value and react accordingly.

The other kobject fields that should be set, directly or indirectly, by the creator are ktype, kset, and parent. We will get to these later in this chapter. Reference count manipulation One of the key functions of a kobject is to serve as a reference counter for the object in which it is embedded. As long as references to the object exist, the object (and the code that supports it) must continue to exist. The low-level functions for manipulat- ing a kobject’s reference counts are: struct kobject *kobject_get(struct kobject *kobj); void kobject_put(struct kobject *kobj); A successful call to kobject_get increments the kobject’s reference counter and returns a pointer to the kobject.

If, however, the kobject is already in the process of being destroyed, the operation fails, and kobject_get returns NULL. This return value must always be tested, or no end of unpleasant race conditions could result. When a reference is released, the call to kobject_put decrements the reference count and, possibly, frees the object. Remember that kobject_init sets the reference count to one; so when you create a kobject, you should make sure that the corresponding kobject_put call is made when that initial reference is no longer needed. ,ch14.12359 Page 366 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. Kobjects, Ksets, and Subsystems | 367 Note that, in many cases, the reference count in the kobject itself may not be suffi- cient to prevent race conditions. The existence of a kobject (and its containing struc- ture) may well, for example, require the continued existence of the module that created that kobject. It would not do to unload that module while the kobject is still being passed around. That is why the cdev structure we saw above contains a struct module pointer. Reference counting for struct cdev is implemented as follows: struct kobject *cdev_get(struct cdev *p) { struct module *owner = p->owner; struct kobject *kobj; if (owner && !try_module_get(owner)) return NULL; kobj = kobject_get(&p->kobj); if (!kobj) module_put(owner); return kobj; } Creating a reference to a cdev structure requires creating a reference also to the mod- ule that owns it.

So cdev_get uses try_module_get to attempt to increment that mod- ule’s usage count. If that operation succeeds, kobject_get is used to increment the kobject’s reference count as well. That operation could fail, of course, so the code checks the return value from kobject_get and releases its reference to the module if things don’t work out.

Release functions and kobject types One important thing still missing from the discussion is what happens to a kobject when its reference count reaches 0. The code that created the kobject generally does not know when that will happen; if it did, there would be little point in using a refer- ence count in the first place. Even predictable object life cycles become more compli- cated when sysfs is brought in; user-space programs can keep a reference to a kobject (by keeping one of its associated sysfs files open) for an arbitrary period of time. The end result is that a structure protected by a kobject cannot be freed at any sin- gle, predictable point in the driver’s lifecycle, but in code that must be prepared to run at whatever moment the kobject’s reference count goes to 0.

The reference count is not under the direct control of the code that created the kobject. So that code must be notified asynchronously whenever the last reference to one of its kobjects goes away.

This notification is done through a kobject’s release method. Usually, this method has a form such as: void my_object_release(struct kobject *kobj) { struct my_object *mine = container_of(kobj, struct my_object, kobj); ,ch14.12359 Page 367 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. 368 | Chapter 14: The Linux Device Model /* Perform any additional cleanup on this object, then * / kfree(mine); } One important point cannot be overstated: every kobject must have a release method, and the kobject must persist (in a consistent state) until that method is called.

If these constraints are not met, the code is flawed. It risks freeing the object when it is still in use, or it fails to release the object after the last reference is returned.

Interestingly, the release method is not stored in the kobject itself; instead, it is asso- ciated with the type of the structure that contains the kobject. This type is tracked with a structure of type struct kobj_type, often simply called a “ktype.” This struc- ture looks like the following: struct kobj_type { void (*release)(struct kobject *); struct sysfs_ops *sysfs_ops; struct attribute **default_attrs; }; The release field in struct kobj_type is, of course, a pointer to the release method for this type of kobject. We will come back to the other two fields (sysfs_ops and default_attrs) later in this chapter.

Every kobject needs to have an associated kobj_type structure. Confusingly, the pointer to this structure can be found in two different places. The kobject structure itself contains a field (called ktype) that can contain this pointer. If, however, this kobject is a member of a kset, the kobj_type pointer is provided by that kset instead. (We will look at ksets in the next section.) Meanwhile, the macro: struct kobj_type *get_ktype(struct kobject *kobj); finds the kobj_type pointer for a given kobject. Kobject Hierarchies, Ksets, and Subsystems The kobject structure is often used to link together objects into a hierarchical struc- ture that matches the structure of the subsystem being modeled.

There are two sepa- rate mechanisms for this linking: the parent pointer and ksets. The parent field in struct kobject is a pointer to another kobject—the one repre- senting the next level up in the hierarchy. If, for example, a kobject represents a USB device, its parent pointer may indicate the object representing the hub into which the device is plugged.

The main use for the parent pointer is to position the object in the sysfs hierarchy. We’ll see how this works in the section “Low-Level Sysfs Operations.” ,ch14.12359 Page 368 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. Kobjects, Ksets, and Subsystems | 369 Ksets In many ways, a kset looks like an extension of the kobj_type structure; a kset is a collection of kobjects embedded within structures of the same type. However, while struct kobj_type concerns itself with the type of an object, struct kset is concerned with aggregation and collection.

The two concepts have been separated so that objects of identical type can appear in distinct sets. Therefore, the main function of a kset is containment; it can be thought of as the top-level container class for kobjects. In fact, each kset contains its own kobject internally, and it can, in many ways, be treated the same way as a kobject. It is worth noting that ksets are always represented in sysfs; once a kset has been set up and added to the system, there will be a sysfs directory for it. Kobjects do not necessarily show up in sysfs, but every kobject that is a member of a kset is represented there.

Adding a kobject to a kset is usually done when the object is created; it is a two-step process. The kobject’s kset field must be pointed at the kset of interest; then the kobject should be passed to: int kobject_add(struct kobject *kobj); As always, programmers should be aware that this function can fail (in which case it returns a negative error code) and respond accordingly. There is a convenience func- tion provided by the kernel: extern int kobject_register(struct kobject *kobj); This function is simply a combination of kobject_init and kobject_add. When a kobject is passed to kobject_add, its reference count is incremented.

Con- tainment within the kset is, after all, a reference to the object. At some point, the kobject will probably have to be removed from the kset to clear that reference; that is done with: void kobject_del(struct kobject *kobj); There is also a kobject_unregister function, which is a combination of kobject_del and kobject_put.

A kset keeps its children in a standard kernel linked list. In almost all cases, the con- tained kobjects also have pointers to the kset (or, strictly, its embedded kobject) in their parent’s fields. So, typically, a kset and its kobjects look something like what you see in Figure 14-2. Bear in mind that: • All of the contained kobjects in the diagram are actually embedded within some other type, possibly even other ksets. • It is not required that a kobject’s parent be the containing kset (although any other organization would be strange and rare).

,ch14.12359 Page 369 Tuesday, January 25, 2005 1:54 PM

This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. 370 | Chapter 14: The Linux Device Model Operations on ksets For initialization and setup, ksets have an interface very similar to that of kobjects. The following functions exist: void kset_init(struct kset *kset); int kset_add(struct kset *kset); int kset_register(struct kset *kset); void kset_unregister(struct kset *kset); For the most part, these functions just call the analogous kobject_ function on the kset’s embedded kobject.

To manage the reference counts of ksets, the situation is about the same: struct kset *kset_get(struct kset *kset); void kset_put(struct kset *kset); A kset also has a name, which is stored in the embedded kobject.

So, if you have a kset called my_set, you would set its name with: kobject_set_name(&my_set->kobj, "The name"); Ksets also have a pointer (in the ktype field) to the kobj_type structure describing the kobjects it contains. This type is used in preference to the ktype field in a kobject itself. As a result, in typical usage, the ktype field in struct kobject is left NULL, because the same field within the kset is the one actually used. Finally, a kset contains a subsystem pointer (called subsys). So it’s time to talk about subsystems.

Subsystems A subsystem is a representation for a high-level portion of the kernel as a whole. Sub- systems usually (but not always) show up at the top of the sysfs hierarchy. Some example subsystems in the kernel include block_subsys (/sys/block, for block devices), devices_subsys (/sys/devices, the core device hierarchy), and a specific sub- system for every bus type known to the kernel. A driver author almost never needs to Figure 14-2. A simple kset hierarchy kobject kobject kobject kobject kobject->parent kobject->kset ksetchildlist ,ch14.12359 Page 370 Tuesday, January 25, 2005 1:54 PM