Based on kernel version 4.9. Page generated on 2016-12-21 14:37 EST.
1 Chinese translated version of Documentation/filesystems/sysfs.txt 2 3 If you have any comment or update to the content, please contact the 4 original document maintainer directly. However, if you have a problem 5 communicating in English you can also ask the Chinese maintainer for 6 help. Contact the Chinese maintainer if this translation is outdated 7 or if there is a problem with the translation. 8 9 Maintainer: Patrick Mochel <mochel@osdl.org> 10 Mike Murphy <mamurph@cs.clemson.edu> 11 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> 12 --------------------------------------------------------------------- 13 Documentation/filesystems/sysfs.txt 的中文翻译 14 15 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 16 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 17 译存在问题，请联系中文版维护者。 18 英文版维护者： Patrick Mochel <mochel@osdl.org> 19 Mike Murphy <mamurph@cs.clemson.edu> 20 中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 21 中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 22 中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 23 24 25 以下为正文 26 --------------------------------------------------------------------- 27 sysfs - 用于导出内核对象(kobject)的文件系统 28 29 Patrick Mochel <mochel@osdl.org> 30 Mike Murphy <mamurph@cs.clemson.edu> 31 32 修订: 16 August 2011 33 原始版本: 10 January 2003 34 35 36 sysfs 简介: 37 ~~~~~~~~~~ 38 39 sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导出内核 40 数据结构及其属性，以及它们之间的关联到用户空间的方法。 41 42 sysfs 始终与 kobject 的底层结构紧密相关。请阅读 43 Documentation/kobject.txt 文档以获得更多关于 kobject 接口的 44 信息。 45 46 47 使用 sysfs 48 ~~~~~~~~~~~ 49 50 只要内核配置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你可 51 通过以下命令挂载它: 52 53 mount -t sysfs sysfs /sys 54 55 56 创建目录 57 ~~~~~~~~ 58 59 任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个 60 目录是作为该 kobject 的父对象所在目录的子目录创建的，以准确地传递 61 内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的 62 共同祖先；例如：某些对象属于某个子系统。 63 64 Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现 65 目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于 66 kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject 67 引用计数只能通过 sysfs_schedule_callback() 函数直接修改。 68 69 70 属性 71 ~~~~ 72 73 kobject 的属性可在文件系统中以普通文件的形式导出。Sysfs 为属性定义 74 了面向文件 I/O 操作的方法，以提供对内核属性的读写。 75 76 77 属性应为 ASCII 码文本文件。以一个文件只存储一个属性值为宜。但一个 78 文件只包含一个属性值可能影响效率，所以一个包含相同数据类型的属性值 79 数组也被广泛地接受。 80 81 混合类型、表达多行数据以及一些怪异的数据格式会遭到强烈反对。这样做是 82 很丢脸的,而且其代码会在未通知作者的情况下被重写。 83 84 85 一个简单的属性结构定义如下: 86 87 struct attribute { 88 char * name; 89 struct module *owner; 90 umode_t mode; 91 }; 92 93 94 int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); 95 void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); 96 97 98 一个单独的属性结构并不包含读写其属性值的方法。子系统最好为增删特定 99 对象类型的属性定义自己的属性结构体和封装函数。 100 101 例如:驱动程序模型定义的 device_attribute 结构体如下: 102 103 struct device_attribute { 104 struct attribute attr; 105 ssize_t (*show)(struct device *dev, struct device_attribute *attr, 106 char *buf); 107 ssize_t (*store)(struct device *dev, struct device_attribute *attr, 108 const char *buf, size_t count); 109 }; 110 111 int device_create_file(struct device *, const struct device_attribute *); 112 void device_remove_file(struct device *, const struct device_attribute *); 113 114 为了定义设备属性，同时定义了一下辅助宏: 115 116 #define DEVICE_ATTR(_name, _mode, _show, _store) \ 117 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) 118 119 例如:声明 120 121 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); 122 123 等同于如下代码： 124 125 static struct device_attribute dev_attr_foo = { 126 .attr = { 127 .name = "foo", 128 .mode = S_IWUSR | S_IRUGO, 129 .show = show_foo, 130 .store = store_foo, 131 }, 132 }; 133 134 135 子系统特有的回调函数 136 ~~~~~~~~~~~~~~~~~~~ 137 138 当一个子系统定义一个新的属性类型时，必须实现一系列的 sysfs 操作， 139 以帮助读写调用实现属性所有者的显示和储存方法。 140 141 struct sysfs_ops { 142 ssize_t (*show)(struct kobject *, struct attribute *, char *); 143 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); 144 }; 145 146 [子系统应已经定义了一个 struct kobj_type 结构体作为这个类型的 147 描述符，并在此保存 sysfs_ops 的指针。更多的信息参见 kobject 的 148 文档] 149 150 sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会 151 将一般的kobject 和 attribute 结构体指针转换为适当的指针类型后 152 调用相关联的函数。 153 154 155 示例: 156 157 #define to_dev(obj) container_of(obj, struct device, kobj) 158 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) 159 160 static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, 161 char *buf) 162 { 163 struct device_attribute *dev_attr = to_dev_attr(attr); 164 struct device *dev = to_dev(kobj); 165 ssize_t ret = -EIO; 166 167 if (dev_attr->show) 168 ret = dev_attr->show(dev, dev_attr, buf); 169 if (ret >= (ssize_t)PAGE_SIZE) { 170 print_symbol("dev_attr_show: %s returned bad count\n", 171 (unsigned long)dev_attr->show); 172 } 173 return ret; 174 } 175 176 177 178 读写属性数据 179 ~~~~~~~~~~~~ 180 181 在声明属性时，必须指定 show() 或 store() 方法，以实现属性的 182 读或写。这些方法的类型应该和以下的设备属性定义一样简单。 183 184 ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); 185 ssize_t (*store)(struct device *dev, struct device_attribute *attr, 186 const char *buf, size_t count); 187 188 也就是说,他们应只以一个处理对象、一个属性和一个缓冲指针作为参数。 189 190 sysfs 会分配一个大小为 (PAGE_SIZE) 的缓冲区并传递给这个方法。 191 Sysfs 将会为每次读写操作调用一次这个方法。这使得这些方法在执行时 192 会出现以下的行为: 193 194 - 在读方面（read(2)），show() 方法应该填充整个缓冲区。回想属性 195 应只导出了一个属性值或是一个同类型属性值的数组，所以这个代价将 196 不会不太高。 197 198 这使得用户空间可以局部地读和任意的向前搜索整个文件。如果用户空间 199 向后搜索到零或使用‘0’偏移执行一个pread(2)操作，show()方法将 200 再次被调用，以重新填充缓存。 201 202 - 在写方面（write(2)），sysfs 希望在第一次写操作时得到整个缓冲区。 203 之后 Sysfs 传递整个缓冲区给 store() 方法。 204 205 当要写 sysfs 文件时，用户空间进程应首先读取整个文件，修该想要 206 改变的值，然后回写整个缓冲区。 207 208 在读写属性值时，属性方法的执行应操作相同的缓冲区。 209 210 注记: 211 212 - 写操作导致的 show() 方法重载，会忽略当前文件位置。 213 214 - 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。 215 216 - show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的 217 返回值。 218 219 - show() 应始终使用 snprintf()。 220 221 - store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回 222 count 参数。 223 224 - show() 或 store() 可以返回错误值。当得到一个非法值，必须返回一个 225 错误值。 226 227 - 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在 228 内存中。尽管如此，对象代表的物理实体(如设备)可能已不存在。如有必要， 229 应该实现一个检测机制。 230 231 一个简单的(未经实验证实的)设备属性实现如下： 232 233 static ssize_t show_name(struct device *dev, struct device_attribute *attr, 234 char *buf) 235 { 236 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); 237 } 238 239 static ssize_t store_name(struct device *dev, struct device_attribute *attr, 240 const char *buf, size_t count) 241 { 242 snprintf(dev->name, sizeof(dev->name), "%.*s", 243 (int)min(count, sizeof(dev->name) - 1), buf); 244 return count; 245 } 246 247 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); 248 249 250 （注意：真正的实现不允许用户空间设置设备名。） 251 252 顶层目录布局 253 ~~~~~~~~~~~~ 254 255 sysfs 目录的安排显示了内核数据结构之间的关系。 256 257 顶层 sysfs 目录如下: 258 259 block/ 260 bus/ 261 class/ 262 dev/ 263 devices/ 264 firmware/ 265 net/ 266 fs/ 267 268 devices/ 包含了一个设备树的文件系统表示。他直接映射了内部的内核 269 设备树，反映了设备的层次结构。 270 271 bus/ 包含了内核中各种总线类型的平面目录布局。每个总线目录包含两个 272 子目录: 273 274 devices/ 275 drivers/ 276 277 devices/ 包含了系统中出现的每个设备的符号链接，他们指向 root/ 下的 278 设备目录。 279 280 drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序的目录(这里 281 假定驱动没有跨越多个总线类型)。 282 283 fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须 284 在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.txt)。 285 286 dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以 287 <major>:<minor> 格式命名的符号链接。这些符号链接指向 sysfs 目录 288 中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找 289 设备 sysfs 接口快捷的方法。 290 291 更多有关 driver-model 的特性信息可以在 Documentation/driver-model/ 292 中找到。 293 294 295 TODO: 完成这一节。 296 297 298 当前接口 299 ~~~~~~~~ 300 301 以下的接口层普遍存在于当前的sysfs中: 302 303 - 设备 (include/linux/device.h) 304 ---------------------------------- 305 结构体: 306 307 struct device_attribute { 308 struct attribute attr; 309 ssize_t (*show)(struct device *dev, struct device_attribute *attr, 310 char *buf); 311 ssize_t (*store)(struct device *dev, struct device_attribute *attr, 312 const char *buf, size_t count); 313 }; 314 315 声明: 316 317 DEVICE_ATTR(_name, _mode, _show, _store); 318 319 增/删属性: 320 321 int device_create_file(struct device *dev, const struct device_attribute * attr); 322 void device_remove_file(struct device *dev, const struct device_attribute * attr); 323 324 325 - 总线驱动程序 (include/linux/device.h) 326 -------------------------------------- 327 结构体: 328 329 struct bus_attribute { 330 struct attribute attr; 331 ssize_t (*show)(struct bus_type *, char * buf); 332 ssize_t (*store)(struct bus_type *, const char * buf, size_t count); 333 }; 334 335 声明: 336 337 BUS_ATTR(_name, _mode, _show, _store) 338 339 增/删属性: 340 341 int bus_create_file(struct bus_type *, struct bus_attribute *); 342 void bus_remove_file(struct bus_type *, struct bus_attribute *); 343 344 345 - 设备驱动程序 (include/linux/device.h) 346 ----------------------------------------- 347 348 结构体: 349 350 struct driver_attribute { 351 struct attribute attr; 352 ssize_t (*show)(struct device_driver *, char * buf); 353 ssize_t (*store)(struct device_driver *, const char * buf, 354 size_t count); 355 }; 356 357 声明: 358 359 DRIVER_ATTR(_name, _mode, _show, _store) 360 361 增/删属性： 362 363 int driver_create_file(struct device_driver *, const struct driver_attribute *); 364 void driver_remove_file(struct device_driver *, const struct driver_attribute *); 365 366 367 文档 368 ~~~~ 369 370 sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。 371 对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs 372 属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。