Overview of the Linux sysfs System

Linux sysfs System

1. Overview: What is sysfs?

/sys directory is a virtual file system provided by the kernel through the sysfs file system. It was introduced in the 2.6 kernel and is similar to procfs (/proc) but has different design purposes:

• Purpose: To display the hierarchy of kernel objects (kobject), along with their attributes and relationships.
• Content: It provides a structured view of information about devices, drivers, modules, kernel subsystems, etc.
• Function:

• Export kernel data to user space: Allows user space programs (like udev, utility scripts) to view and sometimes configure kernel parameters.
• Foundation of the device model: Provides a unified model for device management (hotplugging, power management, device discovery).
• Replace the chaotic /proc: Moves device-related information out of the unstructured /proc, allowing /proc to focus more on process information.

A typical /sys directory contains the following subdirectories:

• block/: All block devices
• bus/: All bus types in the system (e.g., pci, usb, i2c)
• class/: Device classes categorized by function (e.g., net, sound, graphics)
• devices/: Physical hierarchy of all devices in the system
• fs/: Information related to file systems
• kernel/: Kernel configuration and status information
• module/: Information about loaded modules

2. Core Implementation Principles: kobject, kset, ktype

The implementation of sysfs is built on three core data structures that together form the foundation of the Linux device model.

a. kobject (Kernel Object)

• What is it: struct kobject is the most basic structure in the device model. It does not have an actual “device” meaning but serves primarily as a glue and reference counting base structure.
• Responsibilities:

1. Reference counting: Implemented through kref, tracks the lifecycle of the object. When the reference count drops to 0, the object is released.
2. Representation in sysfs: Each kobject corresponds to a directory in sysfs.
3. Provides parent pointer: Used to establish hierarchy (directory structure) in sysfs.
4. Belonging relationship: Belongs to a certain kset (set).

b. kset (Kernel Object Set)

• What is it: struct kset is a collection of kobjects. It is also a kobject.
• Responsibilities:

1. Aggregate kobject: Groups kobjects with common characteristics together (e.g., all PCI devices form a set).
2. Manage sysfs directory: A kset also corresponds to a directory in sysfs, and all kobject directories it contains are sub-items of this directory. For example, /sys/bus/pci/devices/ is a kset that contains all PCI device kobjects.
3. Support hotplug events: When a kobject is added to or removed from a kset, the kset is responsible for sending a uevent (hotplug event) to user space.

c. ktype (Kernel Object Type)

• What is it: struct kobj_type describes the behavior of a class of kobjects. Kobjects of the same type share the same set of operations.
• Responsibilities:

1. Release function: Defines how to release the memory occupied by a kobject when its reference count is 0. This is mandatory.
2. Default attributes: Provides the attribute files that this type of kobject has by default in sysfs (i.e., the show and store operations).
3. sysfs operations: Points to the sysfs_ops structure, which contains the generic show and store methods for this type of kobject.

Summary of the relationships among the three:

• A kobject belongs to a kset.
• A kobject has a ktype.
• A kset also contains a kobject (thus it also has a directory in sysfs), and its internal kobjects can point to the same ktype (but this is not mandatory).

3. Code Framework and Key APIs

a. Creating and Initializing kobject

Typically, kobject is not used directly but is embedded in larger structures (like struct device, struct device_driver).

#include <linux/kobject.h>

/* 1. Initialize an already allocated kobject */
void kobject_init(struct kobject *kobj, struct kobj_type *ktype);

/* 2. Register the kobject in the system and create its directory in sysfs */
int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);

/* 3. Usually combine initialization and addition into one function */
int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
                         struct kobject *parent, const char *fmt, ...);

/* 4. Decrease reference count; when the count is 0, the object will be cleaned up */
void kobject_put(struct kobject *kobj);

/* Example code snippet */
struct my_device {
    struct kobject kobj;
    // ... other device-specific fields ...
};

static struct kobj_type my_ktype = {
    .release = my_device_release,
    .sysfs_ops = &my_sysfs_ops,
    .default_attrs = my_default_attrs,
};

struct my_device *dev = kzalloc(sizeof(*dev), GFP_KERNEL);
if (!dev) return -ENOMEM;

// Initialize and add to sysfs, parent object is kernel_kobj (/sys/kernel/)
ret = kobject_init_and_add(&dev->kobj, &my_ktype, kernel_kobj, "my_device");
if (ret) {
    kobject_put(&dev->kobj);
    return ret;
}
// Increase reference count to avoid accidental release
kobject_get(&dev->kobj);

b. Creating Attributes – Creating Files in sysfs

Attribute files are the interface for user space to interact with the kernel in sysfs.

There are two ways:

1. Default attributes: Provided through the default_attrs field of ktype (these files are automatically created every time a kobject is created).
2. Custom attributes: Dynamically created at runtime.

Attribute definition:

/* An attribute corresponds to a file in sysfs */
struct attribute {
    const char *name;  // File name
    umode_t mode;      // Permissions (e.g., 0644)
};

/* Usually use a richer attribute structure that includes read/write methods */
struct kobj_attribute {
    struct attribute attr;
    ssize_t (*show)(struct kobject *kobj, struct kobj_attribute *attr, char *buf);
    ssize_t (*store)(struct kobject *kobj, struct kobj_attribute *attr, const char *buf, size_t count);
};

Creating and Destroying Attribute Files:

/* Create/remove an attribute file in the kobject's directory */
int sysfs_create_file(struct kobject *kobj, const struct attribute *attr);
void sysfs_remove_file(struct kobject *kobj, const struct attribute *attr);

Show and Store Methods:

/* show: Read data from the kernel to user space (called when cat the file) */
static ssize_t my_attr_show(struct kobject *kobj, struct kobj_attribute *attr, char *buf)
{
    // ... fill data into buf ...
    return strlen(buf);
}

/* store: Write data from user space to the kernel (called when echo > file) */
static ssize_t my_attr_store(struct kobject *kobj, struct kobj_attribute *attr, const char *buf, size_t count)
{
    unsigned long value;
    int ret;

    ret = kstrtoul(buf, 10, &value);
    if (ret < 0)
        return ret;
    // ... use value ...
    return count;
}

/* Define an attribute macro */
static struct kobj_attribute my_attr = __ATTR(my_value, 0664, my_attr_show, my_attr_store);

// Create it in the initialization code
sysfs_create_file(&dev->kobj, &my_attr.attr);

4. Implementation Process Summary (Using Virtual Device as an Example)

1. Define data structure: Create a structure that includes struct kobject.
2. Define ktype: Implement the release method, sysfs_ops, and optional default_attrs.
3. Allocate and initialize: Allocate memory for the structure and call kobject_init_and_add.
4. Create attribute files: Use sysfs_create_file or automatically create through default_attrs.
5. User space interaction: User space interacts with sysfs files through cat and echo, triggering the show and store functions in the kernel.
6. Cleanup: Reduce the reference count through kobject_put, triggering the release method to free resources and automatically remove the directory from sysfs.

5. Interaction with User Space: uevent

When the device state changes (such as adding or removing), the kernel sends a uevent notification to user space (like udevd).udevd will dynamically create/delete device nodes (/dev/) based on these events and the information in /sys.

• Trigger: kobject_uevent(&kobj, KOBJ_ADD) or KOBJ_REMOVE.
• Information source: Information in the uevent environment variables (like device path DEVPATH) mainly comes from the path of the kobject in sysfs.

Summary

| Kernel Concept | Sysfs Representation | Function || :— | :— | :— ||kobject|Directory| Basic building block, provides reference counting and hierarchy ||kset|Directory containing multiple subdirectories| Collection management, hotplug event distribution ||ktype|File operations in the directory| Defines the behavior of object types (release, default attributes) ||attribute|File in the directory| Data interface, allows user space to read/write kernel data |

The entire implementation of sysfs is an excellent example of object-oriented design, which presents the complex relationships among devices, buses, and drivers within the kernel in a clear directory tree format to user space through the three core structures: kobject, kset, and ktype.