Ninja Tekkaman | b5ced6b | 2012-08-29 12:54:41 +0800 | [diff] [blame] | 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 在与其目录关联的 sysfs_dirent 对象中内部保存一个指向实现 |
| 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。 |