kobjects and sysfs

To use the functions described below, you will need to include both <linux/kobject.h> and <linux/sysfs.h> in your source files.

How kobjects get sysfs entries

The name of the directory will be the same as the name given to the kobject itself. The location within sysfs will reflect the kobject's position in the hierarchy you have created. In short: the kobject's directory will be found in its parent's directory, as determined by the kobject's parent field. If you have not explicitly set the parent field, but you have set its kset pointer, then the kset will become the kobject's parent. If there is no parent and no kset, the kobject's directory will become a top-level directory within sysfs, which is rarely what you really want.

Populating a kobject's directory

The key to sysfs attributes is the kobject's kobj_type pointer. When we looked at kobject types before, we passed over a couple of sysfs-related entries. One, called default_attrs, describes the attributes that all kobjects of this type should have; it is a pointer to an array of pointers to attribute structures:

    struct attribute {
	char			*name;
	struct module 		*owner;
	mode_t			mode;
    };

In this structure, name is the name of the attribute (as it will appear within sysfs), owner is a pointer to the module (if any) which is responsible for the implementation of this attribute, and mode is the protection bits which are to be applied to this attribute. The mode is usually S_IRUGO for read-only attributes; if the attribute is writable, you can toss in S_IWUSR to give write access to root only. The last entry in the default_attrs list must be NULL.

The default_attrs array says what the attributes are, but does not tell sysfs how to actually implement those attributes. That task falls to the kobj_type->sysfs_ops field, which points to a structure defined as:

    struct sysfs_ops {
	ssize_t	(*show)(struct kobject *kobj, struct attribute *attr, 
                        char *buffer);
	ssize_t	(*store)(struct kobject *kobj, struct attribute *attr, 
			const char *buffer, size_t size);
    };

These functions will be called for each read and write operation, respectively, on an attribute of a kobject of the given type. In each case, kobj is the kobject whose attribute is being accessed, attr is the struct attribute for the specific attribute, and buffer is a one-page buffer for attribute data.

The show() function should encode the attribute's full value into buffer, being sure not to overrun PAGE_SIZE. Remember that the sysfs convention requires that attributes contain single values or, at most, an array of similar values, so the one-page limit should never be a problem. The return value is, of course, the number of bytes of data actually put into buffer or a negative error code.

The store() function has a similar interface; the additional size parameter gives the length of the data received from user space. Never forget that buffer contains unchecked, user-supplied data; treat it carefully and be sure that it fits whatever format you require. The return value should normally be the same as size, unless something has gone wrong.

As you can see, sysfs requires the use of a single set of show() and store() functions for all attributes of kobjects of the same type. Those functions will, usually, maintain their own array of attribute information to enable them to find the real function charged with implementing each attribute.

Non-default attributes

    int sysfs_create_file(struct kobject *kobj, struct attribute *attr);

If all goes well, the file will be created with the name given in the attribute structure and the return value will be zero; otherwise, the usual negative error code is returned.

Note that the same show() and store() functions will be called to implement operations on the new attribute. Before you add a new, non-default attribute to a kobject, you should take whatever steps are necessary to ensure that those functions know how to implement that attribute.

To remove an attribute, call:

    int sysfs_remove_file(struct kobject *kobj, struct attribute *attr);

After the call, the attribute will no longer appear in the kobject's sysfs entry. Do be aware, however, that a user-space process could have an open file descriptor for that attribute, and that show() and store() calls are still possible after the attribute has been removed.

Symbolic links

Creating a symbolic link within sysfs is easy:

    int sysfs_create_link(struct kobject *kobj, 
			  struct kobject *target,
			  char *name);

This function will create a link (called name) pointing to target's sysfs entry as an attribute of kobj. It will be a relative link, so it works regardless of where sysfs is mounted on any particular system.

The link will persist even if target is removed from the system. If you are creating symbolic links to other kobjects, you should probably have a way of knowing about changes to those kobjects, or some sort of assurance that the target kobjects will not disappear. The consequences (dead symbolic links within sysfs) are not particularly grave, but they would not do much to create confidence in the proper functioning of the system either.

Symbolic links can be removed with:

    void sysfs_remove_link(struct kobject *kobj, char *name);

Binary attributes

Binary attributes are described with a bin_attribute structure:

    struct bin_attribute {
	struct attribute attr;
	size_t size;
	ssize_t (*read)(struct kobject *kobj, char *buffer, 
			loff_t pos, size_t size);
	ssize_t (*write)(struct kobject *kobj, char *buffer, 
			loff_t pos, size_t size);
    };

Here, attr is an attribute structure giving the name, owner, and permissions for the binary attribute, and size is the maximum size of the binary attribute (or zero if there is no maximum). The read() and write() functions work similarly to the normal char driver equivalents; they can be called multiple times for a single load with a maximum of one page worth of data in each call. There is no way for sysfs to signal the last of a set of write operations, so code implementing a binary attribute must be able to determine that some other way.

Binary attributes must be created explicitly; they cannot be set up as default attributes. To create a binary attribute, call:

    int sysfs_create_bin_file(struct kobject *kobj, 
			      struct bin_attribute *attr);

Binary attributes can be removed with:

    int sysfs_remove_bin_file(struct kobject *kobj, 
			      struct bin_attribute *attr);

Last notes