0001 Chinese translated version of Documentation/filesystems/sysfs.rst
0002
0003 If you have any comment or update to the content, please contact the
0004 original document maintainer directly. However, if you have a problem
0005 communicating in English you can also ask the Chinese maintainer for
0006 help. Contact the Chinese maintainer if this translation is outdated
0007 or if there is a problem with the translation.
0008
0009 Maintainer: Patrick Mochel <mochel@osdl.org>
0010 Mike Murphy <mamurph@cs.clemson.edu>
0011 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
0012 ---------------------------------------------------------------------
0013 Documentation/filesystems/sysfs.rst 的中文翻译
0014
0015 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
0016 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
0017 译存在问题，请联系中文版维护者。
0018 英文版维护者： Patrick Mochel <mochel@osdl.org>
0019 Mike Murphy <mamurph@cs.clemson.edu>
0020 中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
0021 中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
0022 中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
0023
0024
0025 以下为正文
0026 ---------------------------------------------------------------------
0027 sysfs - 用于导出内核对象(kobject)的文件系统
0028
0029 Patrick Mochel <mochel@osdl.org>
0030 Mike Murphy <mamurph@cs.clemson.edu>
0031
0032 修订: 16 August 2011
0033 原始版本: 10 January 2003
0034
0035
0036 sysfs 简介:
0037 ~~~~~~~~~~
0038
0039 sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导出内核
0040 数据结构及其属性，以及它们之间的关联到用户空间的方法。
0041
0042 sysfs 始终与 kobject 的底层结构紧密相关。请阅读
0043 Documentation/core-api/kobject.rst 文档以获得更多关于 kobject 接口的
0044 信息。
0045
0046
0047 使用 sysfs
0048 ~~~~~~~~~~~
0049
0050 只要内核配置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你可
0051 通过以下命令挂载它:
0052
0053 mount -t sysfs sysfs /sys
0054
0055
0056 创建目录
0057 ~~~~~~~~
0058
0059 任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个
0060 目录是作为该 kobject 的父对象所在目录的子目录创建的，以准确地传递
0061 内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的
0062 共同祖先；例如：某些对象属于某个子系统。
0063
0064 Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现
0065 目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于
0066 kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject
0067 引用计数只能通过 sysfs_schedule_callback() 函数直接修改。
0068
0069
0070 属性
0071 ~~~~
0072
0073 kobject 的属性可在文件系统中以普通文件的形式导出。Sysfs 为属性定义
0074 了面向文件 I/O 操作的方法，以提供对内核属性的读写。
0075
0076
0077 属性应为 ASCII 码文本文件。以一个文件只存储一个属性值为宜。但一个
0078 文件只包含一个属性值可能影响效率，所以一个包含相同数据类型的属性值
0079 数组也被广泛地接受。
0080
0081 混合类型、表达多行数据以及一些怪异的数据格式会遭到强烈反对。这样做是
0082 很丢脸的,而且其代码会在未通知作者的情况下被重写。
0083
0084
0085 一个简单的属性结构定义如下:
0086
0087 struct attribute {
0088 char * name;
0089 struct module *owner;
0090 umode_t mode;
0091 };
0092
0093
0094 int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
0095 void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
0096
0097
0098 一个单独的属性结构并不包含读写其属性值的方法。子系统最好为增删特定
0099 对象类型的属性定义自己的属性结构体和封装函数。
0100
0101 例如:驱动程序模型定义的 device_attribute 结构体如下:
0102
0103 struct device_attribute {
0104 struct attribute attr;
0105 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
0106 char *buf);
0107 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
0108 const char *buf, size_t count);
0109 };
0110
0111 int device_create_file(struct device *, const struct device_attribute *);
0112 void device_remove_file(struct device *, const struct device_attribute *);
0113
0114 为了定义设备属性，同时定义了一下辅助宏:
0115
0116 #define DEVICE_ATTR(_name, _mode, _show, _store) \
0117 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
0118
0119 例如:声明
0120
0121 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
0122
0123 等同于如下代码：
0124
0125 static struct device_attribute dev_attr_foo = {
0126 .attr = {
0127 .name = "foo",
0128 .mode = S_IWUSR | S_IRUGO,
0129 .show = show_foo,
0130 .store = store_foo,
0131 },
0132 };
0133
0134
0135 子系统特有的回调函数
0136 ~~~~~~~~~~~~~~~~~~~
0137
0138 当一个子系统定义一个新的属性类型时，必须实现一系列的 sysfs 操作，
0139 以帮助读写调用实现属性所有者的显示和储存方法。
0140
0141 struct sysfs_ops {
0142 ssize_t (*show)(struct kobject *, struct attribute *, char *);
0143 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
0144 };
0145
0146 [子系统应已经定义了一个 struct kobj_type 结构体作为这个类型的
0147 描述符，并在此保存 sysfs_ops 的指针。更多的信息参见 kobject 的
0148 文档]
0149
0150 sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会
0151 将一般的kobject 和 attribute 结构体指针转换为适当的指针类型后
0152 调用相关联的函数。
0153
0154
0155 示例:
0156
0157 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
0158
0159 static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
0160 char *buf)
0161 {
0162 struct device_attribute *dev_attr = to_dev_attr(attr);
0163 struct device *dev = kobj_to_dev(kobj);
0164 ssize_t ret = -EIO;
0165
0166 if (dev_attr->show)
0167 ret = dev_attr->show(dev, dev_attr, buf);
0168 if (ret >= (ssize_t)PAGE_SIZE) {
0169 printk("dev_attr_show: %pS returned bad count\n",
0170 dev_attr->show);
0171 }
0172 return ret;
0173 }
0174
0175
0176
0177 读写属性数据
0178 ~~~~~~~~~~~~
0179
0180 在声明属性时，必须指定 show() 或 store() 方法，以实现属性的
0181 读或写。这些方法的类型应该和以下的设备属性定义一样简单。
0182
0183 ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
0184 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
0185 const char *buf, size_t count);
0186
0187 也就是说,他们应只以一个处理对象、一个属性和一个缓冲指针作为参数。
0188
0189 sysfs 会分配一个大小为 (PAGE_SIZE) 的缓冲区并传递给这个方法。
0190 Sysfs 将会为每次读写操作调用一次这个方法。这使得这些方法在执行时
0191 会出现以下的行为:
0192
0193 - 在读方面（read(2)），show() 方法应该填充整个缓冲区。回想属性
0194 应只导出了一个属性值或是一个同类型属性值的数组，所以这个代价将
0195 不会不太高。
0196
0197 这使得用户空间可以局部地读和任意的向前搜索整个文件。如果用户空间
0198 向后搜索到零或使用‘0’偏移执行一个pread(2)操作，show()方法将
0199 再次被调用，以重新填充缓存。
0200
0201 - 在写方面（write(2)），sysfs 希望在第一次写操作时得到整个缓冲区。
0202 之后 Sysfs 传递整个缓冲区给 store() 方法。
0203
0204 当要写 sysfs 文件时，用户空间进程应首先读取整个文件，修该想要
0205 改变的值，然后回写整个缓冲区。
0206
0207 在读写属性值时，属性方法的执行应操作相同的缓冲区。
0208
0209 注记:
0210
0211 - 写操作导致的 show() 方法重载，会忽略当前文件位置。
0212
0213 - 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。
0214
0215 - show() 方法应该返回写入缓冲区的字节数，也就是 scnprintf()的
0216 返回值。
0217
0218 - show() 方法在将格式化返回值返回用户空间的时候，禁止使用snprintf()。
0219 如果可以保证不会发生缓冲区溢出，可以使用sprintf()，否则必须使用
0220 scnprintf()。
0221
0222 - store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回
0223 count 参数。
0224
0225 - show() 或 store() 可以返回错误值。当得到一个非法值，必须返回一个
0226 错误值。
0227
0228 - 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在
0229 内存中。尽管如此，对象代表的物理实体(如设备)可能已不存在。如有必要，
0230 应该实现一个检测机制。
0231
0232 一个简单的(未经实验证实的)设备属性实现如下：
0233
0234 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
0235 char *buf)
0236 {
0237 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
0238 }
0239
0240 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
0241 const char *buf, size_t count)
0242 {
0243 snprintf(dev->name, sizeof(dev->name), "%.*s",
0244 (int)min(count, sizeof(dev->name) - 1), buf);
0245 return count;
0246 }
0247
0248 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
0249
0250
0251 （注意：真正的实现不允许用户空间设置设备名。）
0252
0253 顶层目录布局
0254 ~~~~~~~~~~~~
0255
0256 sysfs 目录的安排显示了内核数据结构之间的关系。
0257
0258 顶层 sysfs 目录如下:
0259
0260 block/
0261 bus/
0262 class/
0263 dev/
0264 devices/
0265 firmware/
0266 net/
0267 fs/
0268
0269 devices/ 包含了一个设备树的文件系统表示。他直接映射了内部的内核
0270 设备树，反映了设备的层次结构。
0271
0272 bus/ 包含了内核中各种总线类型的平面目录布局。每个总线目录包含两个
0273 子目录:
0274
0275 devices/
0276 drivers/
0277
0278 devices/ 包含了系统中出现的每个设备的符号链接，他们指向 root/ 下的
0279 设备目录。
0280
0281 drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序的目录(这里
0282 假定驱动没有跨越多个总线类型)。
0283
0284 fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须
0285 在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.rst)。
0286
0287 dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以
0288 <major>:<minor> 格式命名的符号链接。这些符号链接指向 sysfs 目录
0289 中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找
0290 设备 sysfs 接口快捷的方法。
0291
0292 更多有关 driver-model 的特性信息可以在 Documentation/driver-api/driver-model/
0293 中找到。
0294
0295
0296 TODO: 完成这一节。
0297
0298
0299 当前接口
0300 ~~~~~~~~
0301
0302 以下的接口层普遍存在于当前的sysfs中:
0303
0304 - 设备 (include/linux/device.h)
0305 ----------------------------------
0306 结构体:
0307
0308 struct device_attribute {
0309 struct attribute attr;
0310 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
0311 char *buf);
0312 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
0313 const char *buf, size_t count);
0314 };
0315
0316 声明:
0317
0318 DEVICE_ATTR(_name, _mode, _show, _store);
0319
0320 增/删属性:
0321
0322 int device_create_file(struct device *dev, const struct device_attribute * attr);
0323 void device_remove_file(struct device *dev, const struct device_attribute * attr);
0324
0325
0326 - 总线驱动程序 (include/linux/device.h)
0327 --------------------------------------
0328 结构体:
0329
0330 struct bus_attribute {
0331 struct attribute attr;
0332 ssize_t (*show)(struct bus_type *, char * buf);
0333 ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
0334 };
0335
0336 声明:
0337
0338 BUS_ATTR(_name, _mode, _show, _store)
0339
0340 增/删属性:
0341
0342 int bus_create_file(struct bus_type *, struct bus_attribute *);
0343 void bus_remove_file(struct bus_type *, struct bus_attribute *);
0344
0345
0346 - 设备驱动程序 (include/linux/device.h)
0347 -----------------------------------------
0348
0349 结构体:
0350
0351 struct driver_attribute {
0352 struct attribute attr;
0353 ssize_t (*show)(struct device_driver *, char * buf);
0354 ssize_t (*store)(struct device_driver *, const char * buf,
0355 size_t count);
0356 };
0357
0358 声明:
0359
0360 DRIVER_ATTR(_name, _mode, _show, _store)
0361
0362 增/删属性：
0363
0364 int driver_create_file(struct device_driver *, const struct driver_attribute *);
0365 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
0366
0367
0368 文档
0369 ~~~~
0370
0371 sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。
0372 对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs
0373 属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。
