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 以获取更多信息。