Before we get into the details, it is worth taking a moment to understand how kobjects 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 thinking 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 Section 3.5.1. 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.

This book has presented a number of types with simple mechanisms for initialization 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 memset. 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 kobject'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 actually 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.

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 manipulating 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.

Note that, in many cases, the reference count in the kobject itself may not be sufficient to prevent race conditions. The existence of a kobject (and its containing structure) 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 module that owns it. So cdev_get uses try_module_get to attempt to increment that module'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.

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 reference count in the first place. Even predictable object life cycles become more complicated 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 single, 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);

    /* 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 associated 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 structure 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.

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 function 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. Containment 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 contained 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-1. Bear in mind that:

Figure 14-2. A simple kset hierarchy

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.

A subsystem is a representation for a high-level portion of the kernel as a whole. Subsystems 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 subsystem for every bus type known to the kernel. A driver author almost never needs to create a new subsystem; if you feel tempted to do so, think again. What you probably want, in the end, is to add a new class, as discussed in Section 14.5.

A subsystem is represented by a simple structure:

struct subsystem {
    struct kset kset;
    struct rw_semaphore rwsem;
};

A subsystem, thus, is really just a wrapper around a kset, with a semaphore thrown in.

Every kset must belong to a subsystem. The subsystem membership helps establish the kset's position in the hierarchy, but, more importantly, the subsystem's rwsem semaphore is used to serialize access to a kset's internal-linked list. This membership is represented by the subsys pointer in struct kset. Thus, one can find each kset's containing subsystem from the kset's structure, but one cannot find the multiple ksets contained in a subsystem directly from the subsystem structure.

Subsystems are often declared with a special macro:

decl_subsys(name, struct kobj_type *type, 
            struct kset_hotplug_ops *hotplug_ops);

This macro creates a struct subsystem with a name formed by taking the name given to the macro and appending _subsys to it. The macro also initializes the internal kset with the given type and hotplug_ops. (We discuss hotplug operations later in this chapter.)

Subsystems have the usual list of setup and teardown functions:

void subsystem_init(struct subsystem *subsys);
int subsystem_register(struct subsystem *subsys);
void subsystem_unregister(struct subsystem *subsys);
struct subsystem *subsys_get(struct subsystem *subsys)
void subsys_put(struct subsystem *subsys);

Most of these operations just act upon the subsystem's kset.

As we mentioned, the example source includes a virtual bus implementation called lddbus. This bus sets up its bus_type structure as follows:

struct bus_type ldd_bus_type = {
    .name = "ldd",
    .match = ldd_match,
    .hotplug  = ldd_hotplug,
};

Note that very few of the bus_type fields require initialization; most of that is handled by the device model core. We do have to specify the name of the bus, however, and any methods that go along with it.

Inevitably, a new bus must be registered with the system via a call to bus_register . The lddbus code does so in this way:

ret = bus_register(&ldd_bus_type);
if (ret)
    return ret;

This call can fail, of course, so the return value must always be checked. If it succeeds, the new bus subsystem has been added to the system; it is visible in sysfs under /sys/bus, and it is possible to start adding devices.

Should it be necessary to remove a bus from the system (when the associated module is removed, for example), bus_unregister should be called:

void bus_unregister(struct bus_type *bus);

There are several methods defined for the bus_type structure; they allow the bus code to serve as an intermediary between the device core and individual drivers. The methods defined in the 2.6.10 kernel are:

The lddbus driver has a very simple match function, which simply compares the driver and device names:

static int ldd_match(struct device *dev, struct device_driver *driver)
{
    return !strncmp(dev->bus_id, driver->name, strlen(driver->name));
}

When real hardware is involved, the match function usually makes some sort of comparison between the hardware ID provided by the device itself and the IDs supported by the driver.

The lddbus hotplug method looks like this:

static int ldd_hotplug(struct device *dev, char **envp, int num_envp,
        char *buffer, int buffer_size)
{
    envp[0] = buffer;
    if (snprintf(buffer, buffer_size, "LDDBUS_VERSION=%s",
                Version) >= buffer_size)
        return -ENOMEM;
    envp[1] = NULL;
    return 0;
}

Here, we add in the current revision number of the lddbus source, just in case anybody is curious.

If you are writing bus-level code, you may find yourself having to perform some operation on all devices or drivers that have been registered with your bus. It may be tempting to dig directly into the structures in the bus_type structure, but it is better to use the helper functions that have been provided.

To operate on every device known to the bus, use:

int bus_for_each_dev(struct bus_type *bus, struct device *start, 
                     void *data, int (*fn)(struct device *, void *));

This function iterates over every device on bus, passing the associated device structure to fn, along with the value passed in as data. If start is NULL, the iteration begins with the first device on the bus; otherwise iteration starts with the first device after start. If fn returns a nonzero value, iteration stops and that value is returned from bus_for_each_dev .

There is a similar function for iterating over drivers:

int bus_for_each_drv(struct bus_type *bus, struct device_driver *start, 
                     void *data, int (*fn)(struct device_driver *, void *));

This function works just like bus_for_each_dev, except, of course, that it works with drivers instead.

It should be noted that both of these functions hold the bus subsystem's reader/writer semaphore for the duration of the work. So an attempt to use the two of them together will deadlock—each will be trying to obtain the same semaphore. Operations that modify the bus (such as unregistering devices) will also lock up. So, use the bus_for_each functions with some care.

Almost every layer in the Linux device model provides an interface for the addition of attributes, and the bus layer is no exception. The bus_attribute type is defined in <linux/device.h> as follows:

struct bus_attribute {
    struct attribute attr;
    ssize_t (*show)(struct bus_type *bus, char *buf);
    ssize_t (*store)(struct bus_type *bus, const char *buf, 
                     size_t count);
};

We have already seen struct attribute in Section 14.2.1. The bus_attribute type also includes two methods for displaying and setting the value of the attribute. Most device model layers above the kobject level work this way.

A convenience macro has been provided for the compile-time creation and initialization of bus_attribute structures:

BUS_ATTR(name, mode, show, store);

This macro declares a structure, generating its name by prepending the string bus_attr_ to the given name.

Any attributes belonging to a bus should be created explicitly with bus_create_file:

int bus_create_file(struct bus_type *bus, struct bus_attribute *attr);

Attributes can also be removed with:

void bus_remove_file(struct bus_type *bus, struct bus_attribute *attr);

The lddbus driver creates a simple attribute file containing, once again, the source version number. The show method and bus_attribute structure are set up as follows:

static ssize_t show_bus_version(struct bus_type *bus, char *buf)
{
    return snprintf(buf, PAGE_SIZE, "%s
", Version);
}

static BUS_ATTR(version, S_IRUGO, show_bus_version, NULL);

Creating the attribute file is done at module load time:

if (bus_create_file(&ldd_bus_type, &bus_attr_version))
    printk(KERN_NOTICE "Unable to create version attribute
");

This call creates an attribute file (/sys/bus/ldd/version) containing the revision number for the lddbus code.

The usual set of registration and unregistration functions exists:

int device_register(struct device *dev);
void device_unregister(struct device *dev);

We have seen how the lddbus code registers its bus type. However, an actual bus is a device and must be registered separately. For simplicity, the lddbus module supports only a single virtual bus, so the driver sets up its device at compile time:

static void ldd_bus_release(struct device *dev)
{
    printk(KERN_DEBUG "lddbus release
");
}
    
struct device ldd_bus = {
    .bus_id   = "ldd0",
    .release  = ldd_bus_release
};

This is a top-level bus, so the parent and bus fields are left NULL. We have a simple, no-op release method, and, as the first (and only) bus, its name is ldd0. This bus device is registered with:

ret = device_register(&ldd_bus);
if (ret)
    printk(KERN_NOTICE "Unable to register ldd0
");

Once that call is complete, the new bus can be seen under /sys/devices in sysfs. Any devices added to this bus then shows up under /sys/devices/ldd0/.

Device entries in sysfs can have attributes. The relevant structure is:

struct device_attribute {
    struct attribute attr;
    ssize_t (*show)(struct device *dev, char *buf);
    ssize_t (*store)(struct device *dev, const char *buf, 
                     size_t count);
};

These attribute structures can be set up at compile time with this macro:

DEVICE_ATTR(name, mode, show, store);

The resulting structure is named by prepending dev_attr_ to the given name. The actual management of attribute files is handled with the usual pair of functions:

int device_create_file(struct device *device, 
                       struct device_attribute *entry);
void device_remove_file(struct device *dev, 
                        struct device_attribute *attr);

The dev_attrs field of struct bus_type points to a list of default attributes created for every device added to that bus.

The device structure contains the information that the device model core needs to model the system. Most subsystems, however, track additional information about the devices they host. As a result, it is rare for devices to be represented by bare device structures; instead, that structure, like kobject structures, is usually embedded within a higher-level representation of the device. If you look at the definitions of struct pci_dev or struct usb_device, you will find a struct device buried inside. Usually, low-level drivers are not even aware of that struct device, but there can be exceptions.

The lddbus driver creates its own device type (struct ldd_device) and expects individual device drivers to register their devices using that type. It is a simple structure:

struct ldd_device {
    char *name;
    struct ldd_driver *driver;
    struct device dev;
};

#define to_ldd_device(dev) container_of(dev, struct ldd_device, dev);

This structure allows the driver to provide an actual name for the device (which can be distinct from its bus ID, stored in the device structure) and a pointer to driver information. Structures for real devices usually also contain information about the vendor, device model, device configuration, resources used, and so on. Good examples can be found in struct pci_dev (<linux/pci.h>) or struct usb_device (<linux/usb.h>). A convenience macro (to_ldd_device) is also defined for struct ldd_device to make it easy to turn pointers to the embedded device structure into ldd_device pointers.

The registration interface exported by lddbus looks like this:

int register_ldd_device(struct ldd_device *ldddev)
{
    ldddev->dev.bus = &ldd_bus_type;
    ldddev->dev.parent = &ldd_bus;
    ldddev->dev.release = ldd_dev_release;
    strncpy(ldddev->dev.bus_id, ldddev->name, BUS_ID_SIZE);
    return device_register(&ldddev->dev);
}
EXPORT_SYMBOL(register_ldd_device);

Here, we simply fill in some of the embedded device structure fields (which individual drivers should not need to know about), and register the device with the driver core. If we wanted to add bus-specific attributes to the device, we could do so here.

To show how this interface is used, let us introduce another sample driver, which we have called sculld. It is yet another variant on the scullp driver first introduced in Chapter 8. It implements the usual memory area device, but sculld also works with the Linux device model by way of the lddbus interface.

The sculld driver adds an attribute of its own to its device entry; this attribute, called dev, simply contains the associated device number. This attribute could be used by a module loading the script or the hotplug subsystem to automatically create device nodes when the device is added to the system. The setup for this attribute follows the usual patterns:

static ssize_t sculld_show_dev(struct device *ddev, char *buf)
{
    struct sculld_dev *dev = ddev->driver_data;

    return print_dev_t(buf, dev->cdev.dev);
}

static DEVICE_ATTR(dev, S_IRUGO, sculld_show_dev, NULL);

Then, at initialization time, the device is registered, and the dev attribute is created through the following function:

static void sculld_register_dev(struct sculld_dev *dev, int index)
{
    sprintf(dev->devname, "sculld%d", index);
    dev->ldev.name = dev->devname;
    dev->ldev.driver = &sculld_driver;
    dev->ldev.dev.driver_data = dev;
    register_ldd_device(&dev->ldev);
    device_create_file(&dev->ldev.dev, &dev_attr_dev);
}

Note that we make use of the driver_data field to store the pointer to our own, internal device structure.

As is the case with mos t driver core structures, the device_driver structure is usually found embedded within a higher-level, bus-specific structure. The lddbus subsystem would never go against such a trend, so it has defined its own ldd_driver structure:

struct ldd_driver {
    char *version;
    struct module *module;
    struct device_driver driver;
    struct driver_attribute version_attr;
};

#define to_ldd_driver(drv) container_of(drv, struct ldd_driver, driver);

Here, we require each driver to provide its current software version, and lddbus exports that version string for every driver it knows about. The bus-specific driver registration function is:

int register_ldd_driver(struct ldd_driver *driver)
{
    int ret;
    
    driver->driver.bus = &ldd_bus_type;
    ret = driver_register(&driver->driver);
    if (ret)
        return ret;
    driver->version_attr.attr.name = "version";
    driver->version_attr.attr.owner = driver->module;
    driver->version_attr.attr.mode = S_IRUGO;
    driver->version_attr.show = show_version;
    driver->version_attr.store = NULL;
    return driver_create_file(&driver->driver, &driver->version_attr);
}

The first half of the function simply registers the low-level device_driver structure with the core; the rest sets up the version attribute. Since this attribute is created at runtime, we can't use the DRIVER_ATTR macro; instead, the driver_attribute structure must be filled in by hand. Note that we set the owner of the attribute to the driver module, rather than the lddbus module; the reason for this can be seen in the implementation of the show function for this attribute:

static ssize_t show_version(struct device_driver *driver, char *buf)
{
    struct ldd_driver *ldriver = to_ldd_driver(driver);

    sprintf(buf, "%s
", ldriver->version);
    return strlen(buf);
}

One might think that the attribute owner should be the lddbus module, since the function that implements the attribute is defined there. This function, however, is working with the ldd_driver structure created (and owned) by the driver itself. If that structure were to go away while a user-space process tried to read the version number, things could get messy. Designating the driver module as the owner of the attribute prevents the module from being unloaded, while user-space holds the attribute file open. Since each driver module creates a reference to the lddbus module, we can be sure that lddbus will not be unloaded at an inopportune time.

For completeness, sculld creates its ldd_driver structure as follows:

static struct ldd_driver sculld_driver = {
    .version = "$Revision: 1.1 $",
    .module = THIS_MODULE,
    .driver = {
        .name = "sculld",
    },
};

A simple call to register_ldd_driver adds it to the system. Once initialization is complete, the driver information can be seen in sysfs:

$ tree /sys/bus/ldd/drivers
/sys/bus/ldd/drivers
`-- sculld
    |-- sculld0 -> ../../../../devices/ldd0/sculld0
    |-- sculld1 -> ../../../../devices/ldd0/sculld1
    |-- sculld2 -> ../../../../devices/ldd0/sculld2
    |-- sculld3 -> ../../../../devices/ldd0/sculld3
    `-- version

A class is defined by an instance of struct class:

struct class {
    char *name;
    struct class_attribute *class_attrs;
    struct class_device_attribute *class_dev_attrs;
    int (*hotplug)(struct class_device *dev, char **envp, 
                   int num_envp, char *buffer, int buffer_size);
    void (*release)(struct class_device *dev);
    void (*class_release)(struct class *class);
    /* Some fields omitted */
};

Each class needs a unique name, which is how this class appears under /sys/class. When the class is registered, all of the attributes listed in the (NULL-terminated) array pointed to by class_attrs is created. There is also a set of default attributes for every device added to the class; class_dev_attrs points to those. There is the usual hotplug function for adding variables to the environment when events are generated. There are also two release methods: release is called whenever a device is removed from the class, while class_release is called when the class itself is released.

The registration functions are:

int class_register(struct class *cls);
void class_unregister(struct class *cls);

The interface for working with attributes should not surprise anybody at this point:

struct class_attribute {
    struct attribute attr;
    ssize_t (*show)(struct class *cls, char *buf);
    ssize_t (*store)(struct class *cls, const char *buf, size_t count);
};

CLASS_ATTR(name, mode, show, store);

int class_create_file(struct class *cls, 
                      const struct class_attribute *attr);
void class_remove_file(struct class *cls, 
                       const struct class_attribute *attr);

The real purpose of a class is to serve as a container for the devices that are members of that class. A member is represented by struct class_device:

struct class_device {
    struct kobject kobj;
    struct class *class;
    struct device *dev;
    void *class_data;
    char class_id[BUS_ID_SIZE];
};

The class_id field holds the name of this device as it appears in sysfs. The class pointer should point to the class holding this device, and dev should point to the associated device structure. Setting dev is optional; if it is non-NULL, it is used to create a symbolic link from the class entry to the corresponding entry under /sys/devices, making it easy to find the device entry in user space. The class can use class_data to hold a private pointer.

The usual registration functions have been provided:

int class_device_register(struct class_device *cd);
void class_device_unregister(struct class_device *cd);

The class device interface also allows the renaming of an already registered entry:

int class_device_rename(struct class_device *cd, char *new_name);

Class device entries have attributes:

struct class_device_attribute {
   struct attribute attr;
   ssize_t (*show)(struct class_device *cls, char *buf);
   ssize_t (*store)(struct class_device *cls, const char *buf, 
                    size_t count);
};

CLASS_DEVICE_ATTR(name, mode, show, store);

int class_device_create_file(struct class_device *cls, 
                             const struct class_device_attribute *attr);
void class_device_remove_file(struct class_device *cls, 
                              const struct class_device_attribute *attr);

A default set of attributes, in the class's class_dev_attrs field, is created when the class device is registered; class_device_create_file may be used to create additional attributes. Attributes may also be added to class devices created with the class_simple interface.

The class subsystem has an additional concept not found in other parts of the Linux device model. This mechanism is called an interface, but it is, perhaps, best thought of as a sort of trigger mechanism that can be used to get notification when devices enter or leave the class.

An interface is represented by:

struct class_interface {
    struct class *class;
    int (*add) (struct class_device *cd);
    void (*remove) (struct class_device *cd);
};

Interfaces can be registered and unregistered with:

int class_interface_register(struct class_interface *intf);
void class_interface_unregister(struct class_interface *intf);

The functioning of an interface is straightforward. Whenever a class device is added to the class specified in the class_interface structure, the interface's add function is called. That function can perform any additional setup required for that device; this setup often takes the form of adding more attributes, but other applications are possible. When the device is removed from the class, the remove method is called to perform any required cleanup.

Multiple interfaces can be registered for a class.

Any devices on the IEEE1394 bus, also known as Firewire, have the /sbin/hotplug parameter name and the SUBSYSTEM environment variable set to the value ieee1394. The ieee1394 subsystem also always adds the following four environment variables:

All network devices create a hotplug event when the device is registered or unregistered in the kernel. The /sbin/hotplug call has the parameter name and the SUBSYSTEM environment variable set to the value net, and just adds the following environment variable:

Any devices on the PCI bus have the parameter name and the SUBSYSTEM environment variable set to the value pci. The PCI subsystem also always adds the following four environment variables:

For all input devices (mice, keyboards, joysticks, etc.), a hotplug event is generated when the device is added and removed from the kernel. The /sbin/hotplug parameter and the SUBSYSTEM environment variable are set to the value input. The input subsystem also always adds the following environment variable:

The following environment variables may be present, if the device supports it:

Any devices on the USB bus have the parameter name and the SUBSYSTEM environment variable set to the value usb. The USB subsystem also always adds the following environment variables:

If the bDeviceClass field is set to 0, the following environment variable is also set:

If the kernel build option, CONFIG_USB_DEVICEFS, which selects the usbfs filesystem to be built in the kernel, is selected, the following environment variable is also set:

All SCSI devices create a hotplug event when the SCSI device is created or removed from the kernel. The /sbin/hotplug call has the parameter name and the SUBSYSTEM environment variable set to the value scsi for every SCSI device that is added or removed from the system. There are no additional environment variables added by the SCSI system, but it is mentioned here because there is a SCSI-specific user-space script that can determine what SCSI drivers (disk, tape, generic, etc.) should be loaded for the specified SCSI device.

If a Plug-and-Play-supported laptop docking station is added or removed from the running Linux system (by inserting the laptop into the station, or removing it), a hotplug event is created. The /sbin/hotplug call has the parameter name and the SUBSYSTEM environment variable set to the value dock. No other environment variables are set.

On the S/390 architecture, the channel bus architecture supports a wide range of hardware, all of which generate /sbin/hotplug events when they are added or removed from the Linux virtual system. These devices all have the /sbin/hotplug parameter name and the SUBSYSTEM environment variable set to the value dasd. No other environment variables are set.

The Linux hotplug scripts started out as the very first user of the /sbin/hotplug call. These scripts look at the different environment variables that the kernel sets to describe the device that was just discovered and then tries to find a kernel module that matches up with that device.

As has been described before, when a driver uses the MODULE_DEVICE_TABLE macro, the program, depmod, takes that information and creates the files located in /lib/module/KERNEL_VERSION/modules.*map. The * is different, depending on the bus type that the driver supports. Currently, the module map files are generated for drivers that work for devices that support the PCI, USB, IEEE1394, INPUT, ISAPNP, and CCW subsystems.

The hotplug scripts use these module map text files to determine what module to try to load to support the device that was recently discovered by the kernel. They load all modules and do not stop at the first match, in order to let the kernel work out what module works best. These scripts do not unload any modules when devices are removed. If they were to try to do that, they could accidentally shut down devices that were also controlled by the same driver of the device that was removed.

Note, now that the modprobe program can read the MODULE_DEVICE_TABLE information directly from the modules without the need of the module map files, the hotplug scripts might be reduced to a small wrapper around the modprobe program.

One of the main reasons for creating the unified driver model in the kernel was to allow user space to manage the /dev tree in a dynamic fashion. This had previously been done in user space with the implementation of devfs, but that code base has slowly rotted away, due to a lack of an active maintainer and some unfixable core bugs. A number of kernel developers realized that if all device information was exported to user space, it could perform all the necessary management of the /dev tree.

devfs has some very fundamental flaws in its design. It requires every device driver to be modified to support it, and it requires that device driver to specify the name and location within the /dev tree where it is placed. It also does not properly handle dynamic major and minor numbers, and it does not allow user space to override the naming of a device in a simple manner, forcing the device naming policy to reside within the kernel and not in user space. Linux kernel developers really hate having policy within the kernel, and since the devfs naming policy does not follow the Linux Standard Base specification, it really bothers them.

As the Linux kernel started to be installed on huge servers, a lot of users ran into the problem of how to manage very large numbers of devices. Disk drive arrays of over 10,000 unique devices presented the very difficult task of ensuring that a specific disk was always named with the same exact name, no matter where it was placed in the disk array or when it was discovered by the kernel. This same problem also plagued desktop users who tried to plug two USB printers into their system and then realized that they had no way of ensuring that the printer known as /dev/lpt0 would not change and be assigned to the other printer if the system was rebooted.

So, udev was created. It relies on all device information being exported to user space through sysfs and on being notified by /sbin/hotplug that a device was added or removed. Policy decisions, such as what name to give a device, can be specified in user space, outside of the kernel. This ensures that the naming policy is removed from the kernel and allows a large amount of flexibility about the name of each device.

For more information on how to use udev and how to configure it, please see the documentation that comes included with the udev package in your distribution.

All that a device driver needs to do, for udev to work properly with it, is ensure that any major and minor numbers assigned to a device controlled by the driver are exported to user space through sysfs. For any driver that uses a subsystem to assign it a major and minor number, this is already done by the subsystem, and the driver doesn't have to do any work. Examples of subsystems that do this are the tty, misc, usb, input, scsi, block, i2c, network, and frame buffer subsystems. If your driver handles getting a major and minor number on its own, through a call to the cdev_init function or the older register_chrdev function, the driver needs to be modified in order for udev to work properly with it.

udev looks for a file called dev in the /class/ tree of sysfs, in order to determine what major and minor number is assigned to a specific device when it is called by the kernel through the /sbin/hotplug interface. A device driver merely needs to create that file for every device it controls. The class_simple interface is usually the easiest way to do this.

As mentioned in Section 14.5.1 the first step in using the class_simple interface is to create a struct class_simple with a call to the class_simple_create function:

static struct class_simple *foo_class;
...
foo_class = class_simple_create(THIS_MODULE, "foo");
if (IS_ERR(foo_class)) {
    printk(KERN_ERR "Error creating foo class.
");
    goto error;
}

This code creates a directory in sysfs in /sys/class/foo.

Whenever a new device is found by your driver, and you assign it a minor number as described in Chapter 3, the driver should call the class_simple_device_add function:

class_simple_device_add(foo_class, MKDEV(FOO_MAJOR, minor), NULL, "foo%d", minor);

This code causes a subdirectory under /sys/class/foo to be created called fooN, where N is the minor number for this device. There is one file created in this directory, dev, which is exactly what udev needs in order to create a device node for your device.

When your driver is unbound from a device, and you give up the minor number that it was attached to, a call to class_simple_device_remove is needed to remove the sysfs entries for this device:

class_simple_device_remove(MKDEV(FOO_MAJOR, minor));

Later, when your entire driver is being shut down, a call to class_simple_destroy is needed to remove the class that you created originally with the call to class_simple_create:

class_simple_destroy(foo_class);

The dev file that is created by the call to class_simple_device_add consists of the major and minor numbers, separated by a : character. If your driver does not want to use the class_simple interface because you want to provide other files within the class directory for the subsystem, use the print_dev_t function to properly format the major and minor number for the specific device.