About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / zh_CN / filesystems / sysfs.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:41 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 在与其目录关联的 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。
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.