sysfs

gcslinux

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


本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u1/37445/showart_303455.html