Commit | Line | Data |
---|---|---|
b5ced6b3 NT |
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 | ||
390b421c | 64 | Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现 |
b5ced6b3 NT |
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。 |