Documentation / zh_CN / filesystems / sysfs.txt

Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:17 EST.

	Chinese translated version of Documentation/filesystems/sysfs.txt
	
	If you have any comment or update to the content, please contact the
	original document maintainer directly.  However, if you have a problem
	communicating in English you can also ask the Chinese maintainer for
	help.  Contact the Chinese maintainer if this translation is outdated
	or if there is a problem with the translation.
	
	Maintainer: Patrick Mochel	<mochel@osdl.org>
			Mike Murphy <mamurph@cs.clemson.edu>
	Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
	---------------------------------------------------------------------
	Documentation/filesystems/sysfs.txt 的中文翻译
	
	如果想评论或更新本文的内容，请直接�系原文档的维护者。如果你使用英文
	交�有困难的�，也�以�中文版维护者求助。如果本翻译更新��时或者翻
	译存在问题，请�系中文版维护者。
	英文版维护者： Patrick Mochel	<mochel@osdl.org>
			Mike Murphy <mamurph@cs.clemson.edu>
	中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	
	
	以下为正文
	---------------------------------------------------------------------
	sysfs - 用于导出内核对象(kobject)的文件系统
	
	Patrick Mochel	<mochel@osdl.org>
	Mike Murphy <mamurph@cs.clemson.edu>
	
	修订:    16 August 2011
	原始版本:   10 January 2003
	
	
	sysfs 简介:
	~~~~~~~~~~
	
	sysfs 是一个最�基于 ramfs 且�于内存的文件系统。它�供导出内核
	数�结构�其属性，以�它们之间的关�到用户空间的方法。
	
	sysfs 始终与 kobject 的底层结构紧密相关。请阅读
	Documentation/kobject.txt 文档以获得更多关于 kobject 接�的
	信�。
	
	
	使用 sysfs
	~~~~~~~~~~~
	
	��内核�置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你�
	通过以下命令挂载它:
	
	    mount -t sysfs sysfs /sys
	
	
	创建目录
	~~~~~~~~
	
	任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个
	目录是作为该 kobject 的父对象所在目录的�目录创建的，以准确地传递
	内核的对象层次到用户空间。sysfs 中的顶层目录代表�内核对象层次的
	共�祖先；例如：�些对象属于�个�系统。
	
	Sysfs 在与其目录关�的 sysfs_dirent 对象中内部�存一个指�实现
	目录的 kobject 的指针。以�，这个 kobject 指针被 sysfs 直接用于
	kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject
	引用计数�能通过 sysfs_schedule_callback() 函数直接修改。
	
	
	属性
	~~~~
	
	kobject 的属性�在文件系统中以普通文件的形�导出。Sysfs 为属性定义
	了��文件 I/O �作的方法，以�供对内核属性的读写。
	
	
	属性应为 ASCII �文本文件。以一个文件�存储一个属性值为宜。但一个
	文件�包�一个属性值�能影�效率，所以一个包�相�数�类型的属性值
	数组也被广泛地接�。
	
	混�类型�表达多行数�以�一些怪异的数�格�会�到强烈�对。这样�是
	很丢脸的,而且其代�会在未通知作者的情况下被�写。
	
	
	一个简�的属性结构定义如下:
	
	struct attribute {
	        char                    * name;
	        struct module		*owner;
	        umode_t                 mode;
	};
	
	
	int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
	void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
	
	
	一个�独的属性结构并�包�读写其属性值的方法。�系统最好为增删特定
	对象类型的属性定义自己的属性结构体和�装函数。
	
	例如:驱动程�模型定义的 device_attribute 结构体如下:
	
	struct device_attribute {
		struct attribute	attr;
		ssize_t (*show)(struct device *dev, struct device_attribute *attr,
				char *buf);
		ssize_t (*store)(struct device *dev, struct device_attribute *attr,
				 const char *buf, size_t count);
	};
	
	int device_create_file(struct device *, const struct device_attribute *);
	void device_remove_file(struct device *, const struct device_attribute *);
	
	为了定义设备属性，�时定义了一下辅助�:
	
	#define DEVICE_ATTR(_name, _mode, _show, _store) \
	struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
	
	例如:声明
	
	static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
	
	等�于如下代�：
	
	static struct device_attribute dev_attr_foo = {
	       .attr	= {
			.name = "foo",
			.mode = S_IWUSR | S_IRUGO,
			.show = show_foo,
			.store = store_foo,
		},
	};
	
	
	�系统特有的回调函数
	~~~~~~~~~~~~~~~~~~~
	
	当一个�系统定义一个新的属性类型时，必须实现一系列的 sysfs �作，
	以帮助读写调用实现属性所有者的显示和储存方法。
	
	struct sysfs_ops {
	        ssize_t (*show)(struct kobject *, struct attribute *, char *);
	        ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
	};
	
	[�系统应已�定义了一个 struct kobj_type 结构体作为这个类型的
	�述符，并在此�存 sysfs_ops 的指针。更多的信��� kobject 的
	文档]
	
	sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会
	将一般的kobject 和 attribute 结构体指针转�为适当的指针类型�
	调用相关�的函数。
	
	
	示例:
	
	#define to_dev(obj) container_of(obj, struct device, kobj)
	#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
	
	static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
	                             char *buf)
	{
	        struct device_attribute *dev_attr = to_dev_attr(attr);
	        struct device *dev = to_dev(kobj);
	        ssize_t ret = -EIO;
	
	        if (dev_attr->show)
	                ret = dev_attr->show(dev, dev_attr, buf);
	        if (ret >= (ssize_t)PAGE_SIZE) {
	                print_symbol("dev_attr_show: %s returned bad count\n",
	                                (unsigned long)dev_attr->show);
	        }
	        return ret;
	}
	
	
	
	读写属性数�
	~~~~~~~~~~~~
	
	在声明属性时，必须指定 show() 或 store() 方法，以实现属性的
	读或写。这些方法的类型应该和以下的设备属性定义一样简�。
	
	ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
	                 const char *buf, size_t count);
	
	也就是说,他们应�以一个处�对象�一个属性和一个缓冲指针作为�数。
	
	sysfs 会分�一个大�为 (PAGE_SIZE) 的缓冲区并传递给这个方法。
	Sysfs 将会为�次读写�作调用一次这个方法。这使得这些方法在执行时
	会出现以下的行为:
	
	- 在读方�（read(2)），show() 方法应该填充整个缓冲区。回想属性
	  应�导出了一个属性值或是一个�类型属性值的数组，所以这个代价将
	  �会�太高。
	
	  这使得用户空间�以局部地读和任�的���索整个文件。如果用户空间
	  ���索到零或使用‘0’�移执行一个pread(2)�作，show()方法将
	  �次被调用，以�新填充缓存。
	
	- 在写方�（write(2)），sysfs 希望在第一次写�作时得到整个缓冲区。
	  之� Sysfs 传递整个缓冲区给 store() 方法。
	
	  当�写 sysfs 文件时，用户空间进程应首先读�整个文件，修该想�
	  改�的值，然�回写整个缓冲区。
	
	  在读写属性值时，属性方法的执行应�作相�的缓冲区。
	
	注记:
	
	- 写�作导致的 show() 方法�载，会忽略当�文件�置。
	
	- 缓冲区应总是 PAGE_SIZE 大�。对于i386，这个值为4096。
	
	- show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的
	  返回值。
	
	- show() 应始终使用 snprintf()。
	
	- store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，�需返回
	  count �数。
	
	- show() 或 store() �以返回错误值。当得到一个�法值，必须返回一个
	  错误值。
	
	- 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在
	  内存中。尽管如此，对象代表的物�实体(如设备)�能已�存在。如有必�，
	  应该实现一个检测机制。
	
	一个简�的(未�实验�实的)设备属性实现如下：
	
	static ssize_t show_name(struct device *dev, struct device_attribute *attr,
	                         char *buf)
	{
		return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
	}
	
	static ssize_t store_name(struct device *dev, struct device_attribute *attr,
	                          const char *buf, size_t count)
	{
	        snprintf(dev->name, sizeof(dev->name), "%.*s",
	                 (int)min(count, sizeof(dev->name) - 1), buf);
		return count;
	}
	
	static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
	
	
	（注�：真正的实现��许用户空间设置设备�。）
	
	顶层目录布局
	~~~~~~~~~~~~
	
	sysfs 目录的安排显示了内核数�结构之间的关系。
	
	顶层 sysfs 目录如下:
	
	block/
	bus/
	class/
	dev/
	devices/
	firmware/
	net/
	fs/
	
	devices/ 包�了一个设备树的文件系统表示。他直接映射了内部的内核
	设备树，�映了设备的层次结构。
	
	bus/ 包�了内核中��总线类型的平�目录布局。�个总线目录包�两个
	�目录:
	
		devices/
		drivers/
	
	devices/ 包�了系统中出现的�个设备的符�链接，他们指� root/ 下的
	设备目录。
	
	drivers/ 包�了�个已为特定总线上的设备而挂载的驱动程�的目录(这里
	�定驱动没有跨越多个总线类型)。
	
	fs/ 包�了一个为文件系统设立的目录。现在�个想�导出属性的文件系统必须
	在 fs/ 下创建自己的层次结构(��Documentation/filesystems/fuse.txt)。
	
	dev/ 包�两个�目录： char/ 和 block/。在这两个�目录中，有以
	<major>:<minor> 格�命�的符�链接。这些符�链接指� sysfs 目录
	中相应的设备。/sys/dev �供一个通过一个 stat(2) �作结果，查找
	设备 sysfs 接�快�的方法。
	
	更多有关 driver-model 的特性信��以在 Documentation/driver-model/
	中找到。
	
	
	TODO: 完�这一节。
	
	
	当�接�
	~~~~~~~~
	
	以下的接�层普�存在于当�的sysfs中:
	
	- 设备 (include/linux/device.h)
	----------------------------------
	结构体:
	
	struct device_attribute {
		struct attribute	attr;
		ssize_t (*show)(struct device *dev, struct device_attribute *attr,
				char *buf);
		ssize_t (*store)(struct device *dev, struct device_attribute *attr,
				 const char *buf, size_t count);
	};
	
	声明:
	
	DEVICE_ATTR(_name, _mode, _show, _store);
	
	增/删属性:
	
	int device_create_file(struct device *dev, const struct device_attribute * attr);
	void device_remove_file(struct device *dev, const struct device_attribute * attr);
	
	
	- 总线驱动程� (include/linux/device.h)
	--------------------------------------
	结构体:
	
	struct bus_attribute {
	        struct attribute        attr;
	        ssize_t (*show)(struct bus_type *, char * buf);
	        ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
	};
	
	声明:
	
	BUS_ATTR(_name, _mode, _show, _store)
	
	增/删属性:
	
	int bus_create_file(struct bus_type *, struct bus_attribute *);
	void bus_remove_file(struct bus_type *, struct bus_attribute *);
	
	
	- 设备驱动程� (include/linux/device.h)
	-----------------------------------------
	
	结构体:
	
	struct driver_attribute {
	        struct attribute        attr;
	        ssize_t (*show)(struct device_driver *, char * buf);
	        ssize_t (*store)(struct device_driver *, const char * buf,
	                         size_t count);
	};
	
	声明:
	
	DRIVER_ATTR(_name, _mode, _show, _store)
	
	增/删属性：
	
	int driver_create_file(struct device_driver *, const struct driver_attribute *);
	void driver_remove_file(struct device_driver *, const struct driver_attribute *);
	
	
	文档
	~~~~
	
	sysfs 目录结构以�其中包�的属性定义了一个内核与用户空间之间的 ABI。
	对于任何 ABI，其自身的稳定和适当的文档是�常��的。所有新的 sysfs
	属性必须在 Documentation/ABI 中有文档。详� Documentation/ABI/README。

• [ filesystems ]
• sysfs.txt
•