sysfs - 用于导出内核对象的_The_文件系统

Patrick Mochel <mochel@osdl.org>

Mike Murphy <mamurph@cs.clemson.edu>

修订:

2011 年 8 月 16 日

原始:

2003 年 1 月 10 日

它是什么

sysfs 是一个基于 RAM 的文件系统,最初基于 ramfs。它提供了一种将内核数据结构、它们的属性以及它们之间的链接导出到用户空间的方法。

sysfs 本质上与 kobject 基础设施相关联。请阅读 您一直不想知道的关于 kobject、kset 和 ktype 的一切 以获取有关 kobject 接口的更多信息。

使用 sysfs

如果定义了 CONFIG_SYSFS,则始终编译 sysfs。您可以通过执行以下操作来访问它

mount -t sysfs sysfs /sys

目录创建

对于每个向系统注册的 kobject,都会在 sysfs 中为其创建一个目录。该目录是作为 kobject 父目录的子目录创建的,从而向用户空间表达了内部对象层次结构。sysfs 中的顶级目录表示对象层次结构的公共祖先;即对象所属的子系统。

sysfs 在内部存储一个指向 kobject 的指针,该 kobject 在与目录关联的 kernfs_node 对象中实现了目录。过去,每当文件打开或关闭时,sysfs 都使用此 kobject 指针直接对 kobject 进行引用计数。使用当前的 sysfs 实现,kobject 引用计数仅由函数 sysfs_schedule_callback() 直接修改。

属性

属性可以以文件系统中常规文件的形式导出为 kobject。sysfs 将文件 I/O 操作转发到为属性定义的方法,从而提供了一种读取和写入内核属性的方法。

属性应该是 ASCII 文本文件,最好每个文件只有一个值。需要注意的是,每个文件只包含一个值可能效率不高,因此表达相同类型的数组是可以接受的。

混合类型、表达多行数据以及对数据进行花哨的格式化会受到严重谴责。做这些事情可能会让你公开受辱,并且你的代码会在不通知的情况下被重写。

属性定义很简单

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


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

裸属性不包含读取或写入属性值的方法。鼓励子系统定义自己的属性结构和包装函数,以便为特定对象类型添加和删除属性。

例如,驱动程序模型定义 struct device_attribute

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

int device_create_file(struct device *, const struct device_attribute *);
void device_remove_file(struct device *, const struct device_attribute *);

它还定义了这个用于定义设备属性的助手

#define DEVICE_ATTR(_name, _mode, _show, _store) \
struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)

例如,声明

static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);

相当于做

static struct device_attribute dev_attr_foo = {
        .attr = {
                .name = "foo",
                .mode = S_IWUSR | S_IRUGO,
        },
        .show = show_foo,
        .store = store_foo,
};

请注意,正如 include/linux/kernel.h 中所述的“OTHER_WRITABLE?通常被认为是一个坏主意。”,因此尝试将 sysfs 文件设置为每个人都可写将失败,从而恢复为“其他”的 RO 模式。

对于常见情况,sysfs.h 提供了方便的宏,使定义属性更容易,并使代码更简洁易读。以上情况可以缩短为

static struct device_attribute dev_attr_foo = __ATTR_RW(foo);

可用于定义包装函数的助手列表为

__ATTR_RO(name)

假定默认的 name_show 和 mode 0444

__ATTR_WO(name)

仅假定 name_store 并且仅限于 mode 0200,即仅 root 写入访问。

__ATTR_RO_MODE(name, mode)

用于更严格的 RO 访问;目前唯一的用例是 EFI 系统资源表(参见 drivers/firmware/efi/esrt.c)

__ATTR_RW(name)

假定默认的 name_show、name_store 并将模式设置为 0644。

__ATTR_NULL

这将名称设置为 NULL,并用作列表结束指示符(参见:kernel/workqueue.c)

子系统特定回调

当子系统定义新的属性类型时,它必须实现一组 sysfs 操作,以便将读取和写入调用转发到属性所有者的 show 和 store 方法

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

[ 子系统应该已经定义了一个 struct kobj_type 作为此类型的描述符,sysfs_ops 指针存储在该类型中。有关更多信息,请参见 kobject 文档。]

当读取或写入文件时,sysfs 会调用该类型的适当方法。然后,该方法将通用的 struct kobject 和 struct attribute 指针转换为适当的指针类型,并调用关联的方法。

为了说明

#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)

static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
                            char *buf)
{
        struct device_attribute *dev_attr = to_dev_attr(attr);
        struct device *dev = kobj_to_dev(kobj);
        ssize_t ret = -EIO;

        if (dev_attr->show)
                ret = dev_attr->show(dev, dev_attr, buf);
        if (ret >= (ssize_t)PAGE_SIZE) {
                printk("dev_attr_show: %pS returned bad count\n",
                                dev_attr->show);
        }
        return ret;
}

读取/写入属性数据

要读取或写入属性,在声明属性时必须指定 show() 或 store() 方法。方法类型应与为设备属性定义的那些方法一样简单

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

也就是说,它们应该只接受一个对象、一个属性和一个缓冲区作为参数。

sysfs 分配一个大小为 (PAGE_SIZE) 的缓冲区并将其传递给该方法。sysfs 将对每次读取或写入调用该方法一次。这强制对方法实现执行以下行为

  • 在 read(2) 上,show() 方法应填充整个缓冲区。回想一下,属性应该只导出一个值,或一个相似值的数组,因此这不应该太昂贵。

    这允许用户空间执行部分读取并在整个文件上随意转发查找。如果用户空间查找回零或使用偏移量“0”执行 pread(2),则将再次调用 show() 方法,重新准备,以填充缓冲区。

  • 在 write(2) 上,sysfs 希望在第一次写入期间传递整个缓冲区。然后,sysfs 将整个缓冲区传递给 store() 方法。在存储时,数据后会添加一个终止空字符。这使得像 sysfs_streq() 这样的函数可以安全使用。

    在写入 sysfs 文件时,用户空间进程应首先读取整个文件,修改它希望更改的值,然后将整个缓冲区写回。

    属性方法实现应在读取和写入值时操作相同的缓冲区。

其他说明

  • 无论当前文件位置如何,写入都会重新准备 show() 方法。

  • 缓冲区的长度始终为 PAGE_SIZE 字节。在 x86 上,这是 4096。

  • show() 方法应返回打印到缓冲区中的字节数。

  • show() 应该只使用 sysfs_emit()sysfs_emit_at() 来格式化要返回给用户空间的值。

  • store() 应返回缓冲区中使用的字节数。如果已使用整个缓冲区,则只需返回计数参数。

  • show() 或 store() 始终可以返回错误。如果出现错误值,请务必返回错误。

  • 通过 sysfs 引用计数其嵌入对象,传递给方法的对象将被固定在内存中。但是,该对象表示的物理实体(例如设备)可能不存在。如有必要,请务必有一种方法来检查这一点。

设备属性的一个非常简单(且幼稚)的实现是

static ssize_t show_name(struct device *dev, struct device_attribute *attr,
                        char *buf)
{
        return sysfs_emit(buf, "%s\n", dev->name);
}

static ssize_t store_name(struct device *dev, struct device_attribute *attr,
                        const char *buf, size_t count)
{
        snprintf(dev->name, sizeof(dev->name), "%.*s",
                (int)min(count, sizeof(dev->name) - 1), buf);
        return count;
}

static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);

(请注意,实际实现不允许用户空间设置设备的名称。)

顶层目录布局

sysfs 目录排列公开了内核数据结构的关系。

顶层 sysfs 目录如下所示

block/
bus/
class/
dev/
devices/
firmware/
fs/
hypervisor/
kernel/
module/
net/
power/

devices/ 包含设备树的文件系统表示形式。它直接映射到内部内核设备树,该树是 struct device 的层次结构。

bus/ 包含内核中各种总线类型的平面目录布局。每个总线的目录包含两个子目录

devices/
drivers/

devices/ 包含系统中发现的每个设备的符号链接,这些链接指向根目录下的设备目录。

drivers/ 包含为该特定总线上的设备加载的每个设备驱动程序的目录(这假定驱动程序不跨越多种总线类型)。

fs/ 包含一些文件系统的目录。目前,每个想要导出属性的文件系统都必须在 fs/ 下创建自己的层次结构(有关示例,请参见 ./fuse.rst)。

module/ 包含所有已加载的系统模块(包括内置模块和可加载模块)的参数值和状态信息。

dev/ 包含两个目录:char/ 和 block/。在这两个目录中,都有名为 <major>:<minor> 的符号链接。这些符号链接指向给定设备的 sysfs 目录。/sys/dev 提供了一种从 stat(2) 操作的结果中快速查找设备 sysfs 接口的方法。

有关驱动程序模型特定功能的更多信息,请参见 Documentation/driver-api/driver-model/。

TODO:完成此部分。

当前接口

sysfs 中目前存在以下接口层。

设备 (include/linux/device.h)

结构

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

声明

DEVICE_ATTR(_name, _mode, _show, _store);

创建/删除

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

总线驱动程序 (include/linux/device.h)

结构

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

声明

static BUS_ATTR_RW(name);
static BUS_ATTR_RO(name);
static BUS_ATTR_WO(name);

创建/删除

int bus_create_file(struct bus_type *, struct bus_attribute *);
void bus_remove_file(struct bus_type *, struct bus_attribute *);

设备驱动程序 (include/linux/device.h)

结构

struct driver_attribute {
        struct attribute        attr;
        ssize_t (*show)(struct device_driver *, char * buf);
        ssize_t (*store)(struct device_driver *, const char * buf,
                        size_t count);
};

声明

DRIVER_ATTR_RO(_name)
DRIVER_ATTR_RW(_name)

创建/删除

int driver_create_file(struct device_driver *, const struct driver_attribute *);
void driver_remove_file(struct device_driver *, const struct driver_attribute *);

文档

sysfs 目录结构和每个目录中的属性定义了内核与用户空间之间的 ABI。对于任何 ABI,重要的是此 ABI 是稳定的并已正确记录。所有新的 sysfs 属性必须记录在 Documentation/ABI 中。另请参见 Documentation/ABI/README 以获取更多信息。