About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / sysfs.txt




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.

1	
2	sysfs - _The_ filesystem for exporting kernel objects. 
3	
4	Patrick Mochel	<mochel@osdl.org>
5	Mike Murphy <mamurph@cs.clemson.edu>
6	
7	Revised:    16 August 2011
8	Original:   10 January 2003
9	
10	
11	What it is:
12	~~~~~~~~~~~
13	
14	sysfs is a ram-based filesystem initially based on ramfs. It provides
15	a means to export kernel data structures, their attributes, and the 
16	linkages between them to userspace. 
17	
18	sysfs is tied inherently to the kobject infrastructure. Please read
19	Documentation/kobject.txt for more information concerning the kobject
20	interface. 
21	
22	
23	Using sysfs
24	~~~~~~~~~~~
25	
26	sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
27	it by doing:
28	
29	    mount -t sysfs sysfs /sys 
30	
31	
32	Directory Creation
33	~~~~~~~~~~~~~~~~~~
34	
35	For every kobject that is registered with the system, a directory is
36	created for it in sysfs. That directory is created as a subdirectory
37	of the kobject's parent, expressing internal object hierarchies to
38	userspace. Top-level directories in sysfs represent the common
39	ancestors of object hierarchies; i.e. the subsystems the objects
40	belong to. 
41	
42	Sysfs internally stores a pointer to the kobject that implements a
43	directory in the kernfs_node object associated with the directory. In
44	the past this kobject pointer has been used by sysfs to do reference
45	counting directly on the kobject whenever the file is opened or closed.
46	With the current sysfs implementation the kobject reference count is
47	only modified directly by the function sysfs_schedule_callback().
48	
49	
50	Attributes
51	~~~~~~~~~~
52	
53	Attributes can be exported for kobjects in the form of regular files in
54	the filesystem. Sysfs forwards file I/O operations to methods defined
55	for the attributes, providing a means to read and write kernel
56	attributes.
57	
58	Attributes should be ASCII text files, preferably with only one value
59	per file. It is noted that it may not be efficient to contain only one
60	value per file, so it is socially acceptable to express an array of
61	values of the same type. 
62	
63	Mixing types, expressing multiple lines of data, and doing fancy
64	formatting of data is heavily frowned upon. Doing these things may get
65	you publicly humiliated and your code rewritten without notice. 
66	
67	
68	An attribute definition is simply:
69	
70	struct attribute {
71	        char                    * name;
72	        struct module		*owner;
73	        umode_t                 mode;
74	};
75	
76	
77	int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
78	void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
79	
80	
81	A bare attribute contains no means to read or write the value of the
82	attribute. Subsystems are encouraged to define their own attribute
83	structure and wrapper functions for adding and removing attributes for
84	a specific object type. 
85	
86	For example, the driver model defines struct device_attribute like:
87	
88	struct device_attribute {
89		struct attribute	attr;
90		ssize_t (*show)(struct device *dev, struct device_attribute *attr,
91				char *buf);
92		ssize_t (*store)(struct device *dev, struct device_attribute *attr,
93				 const char *buf, size_t count);
94	};
95	
96	int device_create_file(struct device *, const struct device_attribute *);
97	void device_remove_file(struct device *, const struct device_attribute *);
98	
99	It also defines this helper for defining device attributes: 
100	
101	#define DEVICE_ATTR(_name, _mode, _show, _store) \
102	struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
103	
104	For example, declaring
105	
106	static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
107	
108	is equivalent to doing:
109	
110	static struct device_attribute dev_attr_foo = {
111		.attr = {
112			.name = "foo",
113			.mode = S_IWUSR | S_IRUGO,
114		},
115		.show = show_foo,
116		.store = store_foo,
117	};
118	
119	
120	Subsystem-Specific Callbacks
121	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122	
123	When a subsystem defines a new attribute type, it must implement a
124	set of sysfs operations for forwarding read and write calls to the
125	show and store methods of the attribute owners. 
126	
127	struct sysfs_ops {
128	        ssize_t (*show)(struct kobject *, struct attribute *, char *);
129	        ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
130	};
131	
132	[ Subsystems should have already defined a struct kobj_type as a
133	descriptor for this type, which is where the sysfs_ops pointer is
134	stored. See the kobject documentation for more information. ]
135	
136	When a file is read or written, sysfs calls the appropriate method
137	for the type. The method then translates the generic struct kobject
138	and struct attribute pointers to the appropriate pointer types, and
139	calls the associated methods. 
140	
141	
142	To illustrate:
143	
144	#define to_dev(obj) container_of(obj, struct device, kobj)
145	#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
146	
147	static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
148	                             char *buf)
149	{
150	        struct device_attribute *dev_attr = to_dev_attr(attr);
151	        struct device *dev = to_dev(kobj);
152	        ssize_t ret = -EIO;
153	
154	        if (dev_attr->show)
155	                ret = dev_attr->show(dev, dev_attr, buf);
156	        if (ret >= (ssize_t)PAGE_SIZE) {
157	                print_symbol("dev_attr_show: %s returned bad count\n",
158	                                (unsigned long)dev_attr->show);
159	        }
160	        return ret;
161	}
162	
163	
164	
165	Reading/Writing Attribute Data
166	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167	
168	To read or write attributes, show() or store() methods must be
169	specified when declaring the attribute. The method types should be as
170	simple as those defined for device attributes:
171	
172	ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
173	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
174	                 const char *buf, size_t count);
175	
176	IOW, they should take only an object, an attribute, and a buffer as parameters.
177	
178	
179	sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
180	method. Sysfs will call the method exactly once for each read or
181	write. This forces the following behavior on the method
182	implementations: 
183	
184	- On read(2), the show() method should fill the entire buffer. 
185	  Recall that an attribute should only be exporting one value, or an
186	  array of similar values, so this shouldn't be that expensive. 
187	
188	  This allows userspace to do partial reads and forward seeks
189	  arbitrarily over the entire file at will. If userspace seeks back to
190	  zero or does a pread(2) with an offset of '0' the show() method will
191	  be called again, rearmed, to fill the buffer.
192	
193	- On write(2), sysfs expects the entire buffer to be passed during the
194	  first write. Sysfs then passes the entire buffer to the store() method.
195	  A terminating null is added after the data on stores. This makes
196	  functions like sysfs_streq() safe to use.
197	
198	  When writing sysfs files, userspace processes should first read the
199	  entire file, modify the values it wishes to change, then write the
200	  entire buffer back. 
201	
202	  Attribute method implementations should operate on an identical
203	  buffer when reading and writing values. 
204	
205	Other notes:
206	
207	- Writing causes the show() method to be rearmed regardless of current
208	  file position.
209	
210	- The buffer will always be PAGE_SIZE bytes in length. On i386, this
211	  is 4096. 
212	
213	- show() methods should return the number of bytes printed into the
214	  buffer. This is the return value of scnprintf().
215	
216	- show() must not use snprintf() when formatting the value to be
217	  returned to user space. If you can guarantee that an overflow
218	  will never happen you can use sprintf() otherwise you must use
219	  scnprintf().
220	
221	- store() should return the number of bytes used from the buffer. If the
222	  entire buffer has been used, just return the count argument.
223	
224	- show() or store() can always return errors. If a bad value comes
225	  through, be sure to return an error.
226	
227	- The object passed to the methods will be pinned in memory via sysfs
228	  referencing counting its embedded object. However, the physical 
229	  entity (e.g. device) the object represents may not be present. Be 
230	  sure to have a way to check this, if necessary. 
231	
232	
233	A very simple (and naive) implementation of a device attribute is:
234	
235	static ssize_t show_name(struct device *dev, struct device_attribute *attr,
236	                         char *buf)
237	{
238		return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
239	}
240	
241	static ssize_t store_name(struct device *dev, struct device_attribute *attr,
242	                          const char *buf, size_t count)
243	{
244	        snprintf(dev->name, sizeof(dev->name), "%.*s",
245	                 (int)min(count, sizeof(dev->name) - 1), buf);
246		return count;
247	}
248	
249	static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
250	
251	
252	(Note that the real implementation doesn't allow userspace to set the 
253	name for a device.)
254	
255	
256	Top Level Directory Layout
257	~~~~~~~~~~~~~~~~~~~~~~~~~~
258	
259	The sysfs directory arrangement exposes the relationship of kernel
260	data structures. 
261	
262	The top level sysfs directory looks like:
263	
264	block/
265	bus/
266	class/
267	dev/
268	devices/
269	firmware/
270	net/
271	fs/
272	
273	devices/ contains a filesystem representation of the device tree. It maps
274	directly to the internal kernel device tree, which is a hierarchy of
275	struct device. 
276	
277	bus/ contains flat directory layout of the various bus types in the
278	kernel. Each bus's directory contains two subdirectories:
279	
280		devices/
281		drivers/
282	
283	devices/ contains symlinks for each device discovered in the system
284	that point to the device's directory under root/.
285	
286	drivers/ contains a directory for each device driver that is loaded
287	for devices on that particular bus (this assumes that drivers do not
288	span multiple bus types).
289	
290	fs/ contains a directory for some filesystems.  Currently each
291	filesystem wanting to export attributes must create its own hierarchy
292	below fs/ (see ./fuse.txt for an example).
293	
294	dev/ contains two directories char/ and block/. Inside these two
295	directories there are symlinks named <major>:<minor>.  These symlinks
296	point to the sysfs directory for the given device.  /sys/dev provides a
297	quick way to lookup the sysfs interface for a device from the result of
298	a stat(2) operation.
299	
300	More information can driver-model specific features can be found in
301	Documentation/driver-model/. 
302	
303	
304	TODO: Finish this section.
305	
306	
307	Current Interfaces
308	~~~~~~~~~~~~~~~~~~
309	
310	The following interface layers currently exist in sysfs:
311	
312	
313	- devices (include/linux/device.h)
314	----------------------------------
315	Structure:
316	
317	struct device_attribute {
318		struct attribute	attr;
319		ssize_t (*show)(struct device *dev, struct device_attribute *attr,
320				char *buf);
321		ssize_t (*store)(struct device *dev, struct device_attribute *attr,
322				 const char *buf, size_t count);
323	};
324	
325	Declaring:
326	
327	DEVICE_ATTR(_name, _mode, _show, _store);
328	
329	Creation/Removal:
330	
331	int device_create_file(struct device *dev, const struct device_attribute * attr);
332	void device_remove_file(struct device *dev, const struct device_attribute * attr);
333	
334	
335	- bus drivers (include/linux/device.h)
336	--------------------------------------
337	Structure:
338	
339	struct bus_attribute {
340	        struct attribute        attr;
341	        ssize_t (*show)(struct bus_type *, char * buf);
342	        ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
343	};
344	
345	Declaring:
346	
347	BUS_ATTR(_name, _mode, _show, _store)
348	
349	Creation/Removal:
350	
351	int bus_create_file(struct bus_type *, struct bus_attribute *);
352	void bus_remove_file(struct bus_type *, struct bus_attribute *);
353	
354	
355	- device drivers (include/linux/device.h)
356	-----------------------------------------
357	
358	Structure:
359	
360	struct driver_attribute {
361	        struct attribute        attr;
362	        ssize_t (*show)(struct device_driver *, char * buf);
363	        ssize_t (*store)(struct device_driver *, const char * buf,
364	                         size_t count);
365	};
366	
367	Declaring:
368	
369	DRIVER_ATTR(_name, _mode, _show, _store)
370	
371	Creation/Removal:
372	
373	int driver_create_file(struct device_driver *, const struct driver_attribute *);
374	void driver_remove_file(struct device_driver *, const struct driver_attribute *);
375	
376	
377	Documentation
378	~~~~~~~~~~~~~
379	
380	The sysfs directory structure and the attributes in each directory define an
381	ABI between the kernel and user space. As for any ABI, it is important that
382	this ABI is stable and properly documented. All new sysfs attributes must be
383	documented in Documentation/ABI. See also Documentation/ABI/README for more
384	information.
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.