]>
Commit | Line | Data |
---|---|---|
77c46e9b DS |
1 | |
2 | System Utilities sysfs Library - libsysfs | |
3 | ========================================= | |
4 | ||
5 | Version: 0.4.0 | |
6 | December 16, 2003 | |
7 | ||
8 | Contents | |
9 | -------- | |
10 | 1. Introduction | |
11 | 2. Requirements | |
12 | 3. Definitions | |
13 | 4. Overview | |
14 | 5. Data Structures | |
15 | 5.1 Directory and Attribute Data Structures | |
16 | 5.1.1 Attribute Structure | |
17 | 5.1.2 Link Structure | |
18 | 5.1.3 Directory Structure | |
19 | 5.2 Bus Data Structure | |
20 | 5.3 Class Data Structures | |
21 | 5.4 Root Device Data Structure | |
22 | 5.5 Device Data Structure | |
23 | 5.6 Driver Data Structure | |
24 | 6. Functions | |
25 | 6.1 Utility Functions | |
26 | 6.2 Filesystem Functions | |
27 | 6.2.1 Attribute Functions | |
28 | 6.2.2 Directory Link Functions | |
29 | 6.2.3 Directory Functions | |
30 | 6.3 Bus Functions | |
31 | 6.4 Class Functions | |
32 | 6.5 Device Functions | |
33 | 6.6 Driver Functions | |
34 | 7. Navigating a dlist | |
35 | 8. Usage | |
36 | 9. Conclusion | |
37 | ||
38 | ||
39 | 1. Introduction | |
40 | --------------- | |
41 | ||
42 | Libsysfs' purpose is to provide a consistent and stable interface for | |
43 | querying system device information exposed through the sysfs filesystem. | |
44 | The library implements functions for querying filesystem information, | |
45 | such as reading directories and files. It also contains routines for | |
46 | working with buses, classes, and the device tree. | |
47 | ||
48 | ||
49 | 2. Requirements | |
50 | --------------- | |
51 | ||
52 | The library must satisfy the following requirements: | |
53 | ||
54 | - It must provide a stable programming interfaces that applications can | |
55 | be built upon. | |
56 | ||
57 | - It must provide functions to retrieve device Vital Product Data (VPD) | |
58 | information for Error Log Analysis (ELA) support. ELA will provide | |
59 | device driver and device bus address information. | |
60 | ||
61 | - It must provide access to all system devices and information exposed | |
62 | by sysfs. | |
63 | ||
64 | - It must provide a function to find sysfs' current mount point. | |
65 | ||
66 | - It must provide a function for udev to retrieve a device's major and | |
67 | minor numbers. | |
68 | ||
69 | ||
70 | 3. Definitions | |
71 | -------------- | |
72 | ||
73 | - sysfs: Sysfs is a virtual filesystem in 2.5+ Linux kernels that | |
74 | presents a hierarchical representation of all system physical and | |
75 | virtual devices. It presents system devices by bus, by class, and | |
76 | by topology. Callbacks to device drivers are exposed as files in | |
77 | device directories. Sysfs, for all purposes, is our tree of system | |
78 | devices. For more information, please see: | |
79 | ||
80 | http://www.kernel.org/pub/linux/kernel/people/mochel/doc/ | |
81 | ||
82 | - udev: Udev is Greg Kroah-Hartman's User Space implementation of devfs. | |
83 | Udev creates /dev nodes for devices upon Hotplug events. The Hotplug | |
84 | event provides udev with a sysfs directory location of the device. Udev | |
85 | must use that directory to grab device's major and minor number, which it | |
86 | will use to create the /dev node. For more information, please see: | |
87 | ||
88 | http://www.kernel.org/pub/linux/utils/kernel/hotplug/ | |
89 | ||
90 | ||
91 | 4. Overview | |
92 | ----------- | |
93 | ||
94 | Libsysfs grew from a common need. There are several applications under | |
95 | development that need access to sysfs and system devices. Udev, on a | |
96 | hotplug event, must take a sysfs device path and create a /dev node. Our | |
97 | diagnostic client needs to list all system devices. Finally, our Error | |
98 | Log Analysis piece is required to retrieve VPD information for a | |
99 | failing device. We divided to create a single library interface rather | |
100 | than having these separate applications create their own accesses to | |
101 | sysfs involving reading directories and files. | |
102 | ||
103 | Libsysfs will also provide stability for applications to be built upon. Sysfs | |
104 | currently doesn't enforce any standards for callback or file names. File | |
105 | names change depending on bus or class. Sysfs is also changing, it is | |
106 | currently being developed. Libsysfs will provide a stable interface to | |
107 | applications while allowing sysfs to change underneath it. | |
108 | ||
109 | Like sysfs, the library will provide devices to applications by bus, by | |
110 | class, and by topology. The library will function similar to directories | |
111 | and files that lie underneath it. To query a device on a PCI bus, one would | |
112 | "open" the bus to scan or read devices and "close" the bus when | |
113 | completed. Besides supplying functions to retrieve devices, the library | |
114 | will also provide some utility functions like getting sysfs mount point. | |
115 | ||
116 | ||
117 | 5. Data Structures | |
118 | ------------------ | |
119 | ||
120 | Libsysfs will classify system devices following sysfs' example, dividing | |
121 | them by bus, class, and devices. The library presents this information | |
122 | generically. It doesn't, for example, differentiate between PCI and USB | |
123 | buses. Device attributes are presented with values as they are exposed | |
124 | by sysfs, the values are not formatted. | |
125 | ||
126 | The library will provide standard definitions for working with sysfs | |
127 | and devices, here's some examples: | |
128 | ||
129 | #define SYSFS_FSTYPE_NAME "sysfs" | |
130 | #define SYSFS_PROC_MNTS "/proc/mounts" | |
131 | #define SYSFS_BUS_DIR "/bus" | |
132 | #define SYSFS_BUS_NAME "bus" | |
133 | #define SYSFS_CLASS_DIR "/class" | |
0c17d02d | 134 | #define SYSFS_CLASS_NAME "class" |
77c46e9b DS |
135 | #define SYSFS_BLOCK_DIR "/block" |
136 | #define SYSFS_BLOCK_NAME "block" | |
137 | #define SYSFS_DEVICES_DIR "/devices" | |
138 | #define SYSFS_DEVICES_NAME "devices" | |
139 | #define SYSFS_DRIVERS_DIR "/drivers" | |
140 | #define SYSFS_DRIVERS_NAME "drivers" | |
141 | #define SYSFS_NAME_ATTRIBUTE "name" | |
142 | ||
143 | The library uses some definitions to mark maximum size of a sysfs name or | |
144 | path length: | |
145 | ||
146 | #define SYSFS_PATH_MAX 255 | |
147 | #define SYSFS_NAME_LEN 50 | |
148 | #define SYSFS_BUS_ID_SIZE 20 | |
149 | ||
150 | ||
151 | NOTE: | |
152 | As of release 0.4.0 of libsysfs, a number of changes have been made | |
153 | so that the dlists and "directory" references in all libsysfs's | |
154 | structures are not populated until such time that it is absolutely | |
155 | necessary. Hence, these elements may not contain valid data at all | |
156 | times (as was the case before). | |
157 | ||
158 | 5.1 Directory and Attribute Data Structures | |
159 | ------------------------------------------- | |
160 | ||
161 | The library implements structures to represent sysfs directories, links, | |
162 | and files. | |
163 | ||
164 | ||
165 | 5.1.1 Attribute Structure | |
166 | ------------------------- | |
167 | ||
168 | A file in sysfs represents a device or driver attribute. Attributes can be | |
169 | read only, write only, or read and write. File data can be ASCII and | |
170 | binary. The library has the following structure to represent files: | |
171 | ||
172 | struct sysfs_attribute { | |
173 | unsigned char *value; | |
174 | unsigned short len; /* value length */ | |
175 | unsigned short method; /* show and store */ | |
176 | unsigned char name[SYSFS_NAME_LEN]; | |
177 | unsigned char path[SYSFS_PATH_MAX]; | |
178 | }; | |
179 | ||
180 | Path represents the file/attribute's full path. Value is used when reading | |
181 | from or writing to an attribute. "len" is the length of data in "value". | |
182 | Method is a bitmask for defining if the attribute supports show(read) | |
183 | and/or store(write). | |
184 | ||
185 | ||
186 | 5.1.2 Link Structure | |
187 | -------------------- | |
188 | ||
189 | Symbolic links are used in sysfs to link bus or class views with | |
190 | particular devices. | |
191 | ||
192 | struct sysfs_link { | |
193 | unsigned char name[SYSFS_NAME_LEN]; | |
194 | unsigned char path[SYSFS_PATH_MAX]; | |
195 | unsigned char target[SYSFS_PATH_MAX]; | |
196 | }; | |
197 | ||
198 | Link's name is stored in "name' and it's target stored in "target". Absolute | |
199 | path to the link is stored in "path". | |
200 | ||
201 | ||
202 | 5.1.3 Directory Structure | |
203 | ------------------------- | |
204 | ||
205 | The directory structure represents a sysfs directory: | |
206 | ||
207 | struct sysfs_directory { | |
208 | struct dlist *subdirs; | |
209 | struct dlist *links; | |
210 | struct dlist *attributes; | |
211 | unsigned char name[SYSFS_NAME_LEN]; | |
212 | unsigned char path[SYSFS_PATH_MAX]; | |
213 | }; | |
214 | ||
215 | The sysfs_directory structure includes the list of subdirectories, links and | |
216 | attributes. The "name" and absolute "path" are also stored in the structure. | |
217 | The sysfs_directory structure is intended for use internal to the library. | |
218 | Applications needing access to attributes and links from the directory | |
219 | will need to make appropriate calls (described below) to get the same. | |
220 | ||
221 | ||
222 | 5.2 Bus Data Structure | |
223 | ---------------------- | |
224 | ||
225 | All buses look similar in sysfs including lists of devices and drivers, | |
226 | therefore we use the following structure to represent all sysfs buses: | |
227 | ||
228 | struct sysfs_bus { | |
229 | unsigned char name[SYSFS_NAME_LEN]; | |
230 | unsigned char path[SYSFS_PATH_MAX]; | |
231 | ||
232 | /* internal use only */ | |
233 | struct dlist *drivers; | |
234 | struct dlist *devices; | |
235 | struct sysfs_directory *directory; | |
236 | }; | |
237 | ||
238 | The sysfs_bus structure contains the bus "name", while the "path" to bus | |
239 | directory is also stored. It also contains lists of devices on the bus | |
240 | and drivers that are registered on it. The bus' directory is represented | |
241 | by the sysfs_directory structure and it contains references to all the | |
242 | subdirectories, links, and attributes. The sysfs_directory structure | |
243 | is for internal use only. The following functions may be used by | |
244 | applications to retrieve data from the sysfs_directory structure: | |
245 | ||
246 | struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus) | |
247 | struct sysfs_attribute *sysfs_get_bus_attribute(struct sysfs_bus *bus, | |
248 | unsigned char *attrname) | |
249 | ||
250 | ||
251 | 5.3 Class Data Structures | |
252 | ------------------------- | |
253 | ||
254 | The library uses two data structures to represent classes in sysfs. Sysfs | |
255 | classes contains a class directory like "net" or "scsi_host" and then | |
256 | class devices like "eth0", "lo", or "eth1" for the "net" class. | |
257 | ||
258 | struct sysfs_class { | |
259 | unsigned char name[SYSFS_NAME_LEN]; | |
260 | unsigned char path[SYSFS_PATH_MAX]; | |
261 | ||
262 | /* for internal use only */ | |
263 | struct dlist *devices; | |
264 | struct sysfs_directory *directory; | |
265 | }; | |
266 | ||
267 | The sysfs_class represents device classes in sysfs like "net". It contains | |
268 | the class "name", "path" to the class, a list of class devices and the | |
269 | directory representation (for internal use only). | |
270 | ||
271 | struct sysfs_class_device { | |
272 | unsigned char name[SYSFS_NAME_LEN]; | |
273 | unsigned char classname[SYSFS_NAME_LEN]; | |
274 | unsigned char path[SYSFS_PATH_MAX]; | |
275 | ||
276 | /* for internal use only */ | |
277 | struct sysfs_class_device *parent; | |
278 | struct sysfs_device *sysdevice; /* NULL if virtual */ | |
279 | struct sysfs_driver *driver; /* NULL if not implemented */ | |
280 | struct sysfs_directory *directory; | |
281 | }; | |
282 | ||
283 | A class device isn't the same as a sysfs_device, it's specific to the class in | |
284 | which it belongs. The class device structure contains the name of the class | |
285 | the class device belongs to, its sysfs_device reference and that device's | |
286 | driver reference (if any). It also contains the name of the class device | |
287 | - like "eth0", its parent point (if present) and its sysfs directory | |
288 | information including links and attributes (for internal use only). | |
289 | The following function may be used by applications to retrieve data | |
290 | from the sysfs_directory structure: | |
291 | ||
292 | struct dlist *sysfs_get_classdev_attributes(struct sysfs_class_device *cdev); | |
293 | ||
294 | ||
295 | 5.4 Root Device Data Structure | |
296 | ------------------------------ | |
297 | ||
298 | Device hierarchies in sysfs are represented under the /sys/devices directory | |
299 | structure. Sysfs devices typically spawn off from base devices which are | |
300 | represented by a sysfs_root_device. | |
301 | ||
302 | struct sysfs_root_device { | |
303 | unsigned char name[SYSFS_NAME_LEN]; | |
304 | unsigned char path[SYSFS_PATH_MAX]; | |
305 | ||
306 | /* for internal use only */ | |
307 | struct dlist *devices; | |
308 | struct sysfs_directory *directory; | |
309 | }; | |
310 | ||
311 | The sysfs_root_device structure contains a list of "devices" that spawn off it. | |
312 | The name of the root device as represented under /sys/devices is read into | |
313 | "name" and the absolute path into "path" and its sysfs_directory information | |
314 | intended to be used internal to the library. | |
315 | ||
316 | ||
317 | 5.5 Device Data Structure | |
318 | ------------------------- | |
319 | ||
320 | The sysfs_device structure represents a system device that's exposed | |
321 | in sysfs under the /sys/devices directory structure. | |
322 | ||
323 | struct sysfs_device { | |
324 | unsigned char name[SYSFS_NAME_LEN]; | |
325 | unsigned char bus_id[SYSFS_NAME_LEN]; | |
326 | unsigned char bus[SYSFS_NAME_LEN]; | |
327 | unsigned char driver_name[SYSFS_NAME_LEN]; | |
328 | unsigned char path[SYSFS_PATH_MAX]; | |
329 | ||
330 | /* for internal use only */ | |
331 | struct sysfs_device *parent; | |
332 | struct dlist *children; | |
333 | struct sysfs_directory *directory; | |
334 | }; | |
335 | ||
336 | The sysfs_device structure contains a "parent" pointer, a list of child | |
337 | devices, if any, device's directory, its bus id - which is the name of | |
338 | device's directory, the bus name on which this device is registered and | |
339 | its driver name. The device structure also contains the absolute path | |
340 | to the device and a directory structure, which contains a list of the | |
341 | device's attributes (for internal use only). The following functions | |
342 | may be used to obtain information from sysfs_directory structure: | |
343 | ||
344 | struct sysfs_attribute *sysfs_get_device_attribute(struct sysfs_device *dev, | |
345 | const unsigned char *name) | |
346 | struct dlist *sysfs_get_device_attributes(struct sysfs_device *device) | |
347 | ||
348 | ||
349 | 5.6 Driver Data Structure | |
350 | ------------------------- | |
351 | ||
352 | The sysfs_driver structure represents a device driver. | |
353 | ||
354 | struct sysfs_driver { | |
355 | unsigned char name[SYSFS_NAME_LEN]; | |
356 | unsigned char path[SYSFS_PATH_MAX]; | |
357 | ||
358 | /* for internal use only */ | |
359 | struct dlist *devices; | |
360 | struct sysfs_directory *directory; | |
361 | }; | |
362 | ||
363 | The sysfs_driver structure contains a list of devices that use this driver, | |
364 | the name of the driver, its path, and its directory information, which | |
365 | includes the driver's attributes (for internal use only). The following | |
366 | function may be used to retrieve driver attribute information from the | |
367 | sysfs_directory structure: | |
368 | ||
369 | struct dlist *sysfs_get_driver_attributes(struct sysfs_driver *driver) | |
370 | ||
371 | ||
372 | 6. Functions | |
373 | ------------ | |
374 | ||
375 | Libsysfs will provide functions to access system devices by bus, by class, | |
376 | and by device. Functions will act like accessing directories and files, | |
377 | using "open" and "close". Open returns a structure and close is used | |
378 | to clean that structure up. | |
379 | ||
380 | ||
381 | 6.1 Utility Functions | |
382 | --------------------- | |
383 | ||
384 | The library will provide a few utility functions for working with sysfs. | |
385 | ||
386 | ------------------------------------------------------------------------------- | |
387 | Name: sysfs_get_mnt_path | |
388 | ||
389 | Description: Function finds the mount path for filesystem type "sysfs". | |
390 | ||
391 | Arguments: unsigned char *mnt_path Mount path buffer | |
392 | size_t len Size of mount path buffer | |
393 | ||
394 | Returns: Zero with success. | |
395 | -1 with error. Errno will be set with error: | |
396 | - EINVAL for invalid argument, if buffer is NULL. | |
397 | ||
398 | Prototype: sysfs_get_mnt_path(unsigned char *mnt_path, size_t len); | |
399 | ------------------------------------------------------------------------------- | |
400 | ||
401 | ------------------------------------------------------------------------------- | |
402 | Name: sysfs_get_name_from_path | |
403 | ||
404 | Description: Function returns the last directory or file name from the | |
405 | included path. | |
406 | ||
407 | Arguments: const unsigned char *path Path to parse name from | |
408 | unsigned char *name Buffer to put parsed name into | |
409 | size_t *len Size of name buffer | |
410 | ||
411 | Returns: 0 with success. | |
412 | -1 on Error. Errno will be set with error, returning | |
413 | - EINVAL for invalid arguments | |
414 | ||
415 | Prototype: int sysfs_get_name_from_path(const unsigned char *path, | |
416 | unsigned char *name, size_t *len) | |
417 | ------------------------------------------------------------------------------- | |
418 | ||
419 | ------------------------------------------------------------------------------- | |
420 | Name: sysfs_get_link | |
421 | ||
422 | Description: Sysfs readlink function, reads the link at supplied path | |
423 | and returns its target path. | |
424 | ||
425 | Arguments: const unsigned char *path Link's path | |
426 | unsigned char *target Buffer to place link's target path | |
427 | size_t len Size of target buffer | |
428 | ||
429 | Returns: 0 with success | |
430 | -1 with error. Errno will be set with error, returning | |
431 | - EINVAL for invalid arguments | |
432 | ||
433 | Prototype: int sysfs_get_link(const unsigned char *path, | |
434 | unsigned char *target, size_t len) | |
435 | ------------------------------------------------------------------------------- | |
436 | ||
437 | ------------------------------------------------------------------------------- | |
438 | Name: sysfs_open_subsystem_list | |
439 | ||
440 | Description: Function returns the list of entries for the given subsystem. If | |
441 | the argument is "bus", this function will return a list of buses | |
442 | ("pci", "scsi", etc) supported on the system. | |
443 | ||
444 | sysfs_close_list() has to be called to free the list obtained | |
445 | from this call. | |
446 | ||
447 | Arguments: unsigned char *name Subsystem to open, like "bus".. | |
448 | ||
449 | Returns: dlist of entries for the subsystem on success | |
450 | NULL with error indicating the "name" subsystem is invalid. | |
451 | ||
452 | Prototype: struct dlist *sysfs_open_subsystem_list(unsigned char *name) | |
453 | ------------------------------------------------------------------------------- | |
454 | ||
455 | ------------------------------------------------------------------------------- | |
456 | Name: sysfs_open_bus_devices_list | |
457 | ||
458 | Description: Function returns the list of devices on the given bus. | |
459 | ||
460 | sysfs_close_list() has to be called to free the list obtained | |
461 | from this call. | |
462 | ||
463 | Arguments: unsigned char *name Bus name to open "pci"/"scsi"/"usb".. | |
464 | ||
465 | Returns: dlist of device names for the given bus on success | |
466 | NULL with error indicating the bus is not supported. | |
467 | ||
468 | Prototype: struct dlist *sysfs_open_bus_devices_list(unsigned char *name) | |
469 | ------------------------------------------------------------------------------- | |
470 | ||
471 | ------------------------------------------------------------------------------- | |
472 | Name: sysfs_close_list | |
473 | ||
474 | Description: Closes a given dlist. This can be used as a generic list close | |
475 | routine. | |
476 | ||
477 | Arguments: struct dlist *list List to be closed | |
478 | ||
479 | Prototype: void sysfs_close_list(struct dlist *list) | |
480 | ------------------------------------------------------------------------------- | |
481 | ||
482 | ------------------------------------------------------------------------------- | |
483 | Name: sysfs_path_is_dir | |
484 | ||
485 | Description: Utility function to verify if a given path is to a directory. | |
486 | ||
487 | Arguments: unsigned char *path Path to verify | |
488 | ||
489 | Returns: 0 on success, 1 on error | |
490 | - EINVAL for invalid arguments | |
491 | ||
492 | Prototype: int sysfs_path_is_dir(unsigned char *path) | |
493 | ------------------------------------------------------------------------------- | |
494 | ||
495 | ------------------------------------------------------------------------------- | |
496 | Name: sysfs_path_is_file | |
497 | ||
498 | Description: Utility function to verify if a given path is to a file. | |
499 | ||
500 | Arguments: unsigned char *path Path to verify | |
501 | ||
502 | Returns: 0 on success, 1 on error | |
503 | - EINVAL for invalid arguments | |
504 | ||
505 | Prototype: int sysfs_path_is_file(unsigned char *path) | |
506 | ------------------------------------------------------------------------------- | |
507 | ||
508 | ------------------------------------------------------------------------------- | |
509 | Name: sysfs_path_is_link | |
510 | ||
511 | Description: Utility function to verify if a given path is to a link. | |
512 | ||
513 | Arguments: unsigned char *path Path to verify | |
514 | ||
515 | Returns: 0 on success, 1 on error | |
516 | - EINVAL for invalid arguments | |
517 | ||
518 | Prototype: int sysfs_path_is_link(unsigned char *path) | |
519 | ------------------------------------------------------------------------------- | |
520 | ||
521 | 6.2 Filesystem Functions | |
522 | ------------------------ | |
523 | ||
524 | Libsysfs provides a set of functions to open, read, and close directories | |
525 | and attributes/files in sysfs. These functions mirror their filesystem | |
526 | function counterparts. | |
527 | ||
528 | 6.2.1 Attribute Functions | |
529 | ------------------------- | |
530 | ||
531 | Along with the usual open, read, and close functions, libsysfs provides | |
532 | a couple other functions for accessing attribute values. | |
533 | ||
534 | ------------------------------------------------------------------------------- | |
535 | Name: sysfs_open_attribute | |
536 | ||
537 | Description: Opens up a file in sysfs and creates a sysfs_attribute | |
538 | structure. File isn't read with this function. | |
539 | ||
540 | Arguments: const unsigned char *path File/Attribute's path | |
541 | ||
542 | Returns: struct sysfs_attribute * with success. | |
543 | NULL with error. Errno will be set with error, returning | |
544 | - EINVAL for invalid arguments | |
545 | ||
546 | Prototype: struct sysfs_attribute *sysfs_open_attribute | |
547 | (const unsigned char *path) | |
548 | ------------------------------------------------------------------------------- | |
549 | ||
550 | ------------------------------------------------------------------------------- | |
551 | Name: sysfs_close_attribute | |
552 | ||
553 | Description: Cleans up and closes sysfs_attribute structure. | |
554 | ||
555 | Arguments: struct sysfs_attribute *sysattr Attribute to close | |
556 | ||
557 | Prototype: void sysfs_close_attribute(struct sysfs_attribute *sysattr) | |
558 | ------------------------------------------------------------------------------- | |
559 | ||
560 | ------------------------------------------------------------------------------- | |
561 | Name: sysfs_read_dir_attributes | |
562 | ||
563 | Description: Reads the given sysfs_directory to create a list of attributes. | |
564 | ||
565 | Arguments: struct sysfs_directory *sysdir sysfs_directory whose | |
566 | attributes to read | |
567 | ||
568 | Returns: struct dlist * of attributes on success | |
569 | NULL with error. Errno will be set on error, returning EINVAL | |
570 | for invalid arguments | |
571 | ||
572 | Prototype: struct dlist *sysfs_read_dir_attributes | |
573 | (struct sysfs_directory *sysdir) | |
574 | ------------------------------------------------------------------------------- | |
575 | ||
576 | ------------------------------------------------------------------------------- | |
577 | Name: sysfs_refresh_attributes | |
578 | ||
579 | Description: Given a list of attributes, this function refreshes the values | |
580 | of attributes in the list. | |
581 | ||
582 | Arguments: struct dlist *attrlist list of attributes to refresh | |
583 | ||
584 | Returns: 0 with success. | |
585 | 1 with error. Errno will be set on error, returning EINVAL | |
586 | for invalid arguments | |
587 | ||
588 | Prototype: int sysfs_refresh_attributes(struct dlist *attrlist) | |
589 | ------------------------------------------------------------------------------- | |
590 | ||
591 | ------------------------------------------------------------------------------- | |
592 | Name: sysfs_read_attribute | |
593 | ||
594 | Description: Reads the supplied attribute. Since the maximum transfer | |
595 | from a sysfs attribute is a pagesize, function reads in | |
596 | up to a page from the file and stores it in the "value" | |
597 | field in the attribute. | |
598 | ||
599 | Arguments: struct sysfs_attribute *sysattr Attribute to read | |
600 | ||
601 | Returns: 0 with success. | |
602 | -1 with error. Errno will be set with error, returning | |
603 | - EINVAL for invalid arguments | |
604 | ||
605 | Prototype: int sysfs_read_attribute(struct sysfs_attribute *sysattr) | |
606 | ------------------------------------------------------------------------------- | |
607 | ||
608 | ------------------------------------------------------------------------------- | |
609 | Name: sysfs_write_attribute | |
610 | ||
611 | Description: Writes to the supplied attribute. Function validates if attribute | |
612 | is writable, and writes the new value to the attribute. Value to | |
613 | write as well as its length is user supplied. In case the length | |
614 | written is not equal to the length requested to be written, the | |
615 | original value is restored and an error is returned. | |
616 | ||
617 | Arguments: struct sysfs_attribute *sysattr Attribute to write to | |
618 | const unsigned char *new_value New value for the attribute | |
619 | size_t len Length of "new_value" | |
620 | ||
621 | Returns: 0 with success. | |
622 | -1 with error. Errno will be set with error, returning | |
623 | - EINVAL for invalid arguments | |
624 | ||
625 | Prototype: int sysfs_write_attribute(struct sysfs_attribute *sysattr, | |
626 | const unsigned char *new_value, size_t len) | |
627 | ------------------------------------------------------------------------------- | |
628 | ||
629 | ------------------------------------------------------------------------------- | |
630 | Name: sysfs_read_attribute_value | |
631 | ||
632 | Description: Given a path to a specific attribute, function reads and | |
633 | returns its value to the supplied value buffer. | |
634 | ||
635 | Arguments: const unsigned char *attrpath Attribute path to read | |
636 | unsigned char *value Buffer to place attribute's value | |
637 | size_t vsize Size of buffer | |
638 | ||
639 | Returns: 0 with success. | |
640 | -1 with error. Errno will be set with error, returning | |
641 | - EINVAL for invalid arguments | |
642 | ||
643 | Prototype: int sysfs_read_attribute_value(const unsigned char *attrpath, | |
644 | unsigned char *value, size_t vsize) | |
645 | ------------------------------------------------------------------------------- | |
646 | ||
647 | ------------------------------------------------------------------------------- | |
648 | Name: sysfs_get_value_from_attributes | |
649 | ||
650 | Description: Function takes a single or linked list of sysfs attribute | |
651 | structures and returns the value of the specified attribute | |
652 | name. | |
653 | ||
654 | Arguments: struct sysfs_attribute *attr | |
655 | Attribute list to search through | |
656 | const unsigned char *name Name of attribute to return value | |
657 | ||
658 | Returns: unsigned char * attribute value with success. | |
659 | NULL with error. Errno will be set with error, returning | |
660 | - EINVAL for invalid arguments | |
661 | ||
662 | Prototype: unsigned char *sysfs_get_value_from_attributes | |
663 | (struct sysfs_attribute *attr, const unsigned char * name) | |
664 | ------------------------------------------------------------------------------- | |
665 | ||
666 | ------------------------------------------------------------------------------- | |
667 | Name: sysfs_get_directory_attribute | |
668 | ||
669 | Description: Function walks the list of attributes for the given sysfs | |
670 | directory and returns the sysfs_attribute structure for | |
671 | the specified attribute name. | |
672 | ||
673 | Arguments: struct sysfs_directory *dir Directory in which to search | |
674 | unsigned char *attrname Attribute name to look for | |
675 | ||
676 | Returns: struct sysfs_attribute on success. | |
677 | NULL with error. Errno will be set with error, returning | |
678 | - EINVAL for invalid arguments | |
679 | ||
680 | Prototype: struct sysfs_attribute *sysfs_get_directory_attribute | |
681 | (struct sysfs_directory *dir, unsigned char *attrname) | |
682 | ------------------------------------------------------------------------------- | |
683 | ||
684 | ||
685 | 6.2.2 Link Functions | |
686 | -------------------- | |
687 | ||
688 | Sysfs contains many symbolic links, like bus links to bus devices. Libsysfs | |
689 | treats links differently than directories due to processing differences. A | |
690 | link in the /sys/bus/"busname"/devices/ directory indicates a device in the | |
691 | /sys/devices directory. Through links we give the functionality to know | |
692 | what is and what isn't a link and the ability to query the links target. | |
693 | ||
694 | ------------------------------------------------------------------------------- | |
695 | Name: sysfs_open_link | |
696 | ||
697 | Description: Opens a directory link. | |
698 | ||
699 | Arguments: const unsigned char *linkpath Path to link | |
700 | ||
701 | Returns: struct sysfs_link * with success. | |
702 | NULL with error. Errno will be set with error, returning | |
703 | - EINVAL for invalid arguments | |
704 | ||
705 | Prototype: struct sysfs_link *sysfs_open_link | |
706 | (const unsigned char *linkpath) | |
707 | ------------------------------------------------------------------------------- | |
708 | ||
709 | ------------------------------------------------------------------------------- | |
710 | Name: sysfs_close_link | |
711 | ||
712 | Description: Closes a directory link structure. | |
713 | ||
714 | Arguments: struct sysfs_link *ln Link to close | |
715 | ||
716 | Prototype: void sysfs_close_link(struct sysfs_link *ln) | |
717 | ------------------------------------------------------------------------------- | |
718 | ||
719 | ------------------------------------------------------------------------------- | |
720 | Name: sysfs_read_dir_links | |
721 | ||
722 | Description: Reads the given sysfs_directory to create a list of links. | |
723 | ||
724 | Arguments: struct sysfs_directory *sysdir sysfs_directory whose | |
725 | links to read | |
726 | ||
727 | Returns: struct dlist * of links with success | |
728 | NULL with error. Errno will be set on error, returning EINVAL | |
729 | for invalid arguments | |
730 | ||
731 | Prototype: struct dlist *sysfs_read_dir_links | |
732 | (struct sysfs_directory *sysdir) | |
733 | ------------------------------------------------------------------------------- | |
734 | ||
735 | ------------------------------------------------------------------------------- | |
736 | Name: sysfs_get_directory_link | |
737 | ||
738 | Description: Function walks the list of links for the given sysfs directory | |
739 | and returns the sysfs_link structure for the specified link | |
740 | name. | |
741 | ||
742 | Arguments: struct sysfs_directory *dir Directory in which to search | |
743 | unsigned char *linkname Link name to look for | |
744 | ||
745 | Returns: struct sysfs_link * with success. | |
746 | NULL with error. Errno will be set with error, returning | |
747 | - EINVAL for invalid arguments | |
748 | ||
749 | Prototype: struct sysfs_link *sysfs_get_directory_link | |
750 | (struct sysfs_directory *dir, unsigned char *linkname) | |
751 | ------------------------------------------------------------------------------- | |
752 | ||
753 | ------------------------------------------------------------------------------- | |
754 | Name: sysfs_get_subdirectory_link | |
755 | ||
756 | Description: Function walks the list of links for the given sysfs directory | |
757 | and its subdirectories returns the sysfs_link structure for | |
758 | the specified link name. | |
759 | ||
760 | Arguments: struct sysfs_directory *dir Directory in which to search | |
761 | unsigned char *linkname Link name to look for | |
762 | ||
763 | Returns: struct sysfs_link * with success. | |
764 | NULL with error. Errno will be set with error, returning | |
765 | - EINVAL for invalid arguments | |
766 | ||
767 | Prototype: struct sysfs_link *sysfs_get_subdirectory_link | |
768 | (struct sysfs_directory *dir, unsigned char *linkname) | |
769 | ------------------------------------------------------------------------------- | |
770 | ||
771 | ||
772 | 6.2.3 Directory Functions | |
773 | ------------------------- | |
774 | ||
775 | Sysfs directories can represent every directory under sysfs. The structures | |
776 | keep track of subdirectories, links, and files. Like opendir, readdir, and | |
777 | closedir, libsysfs provides open, read, and close functions for working with | |
778 | sysfs directories. Open creates the sysfs_directory structure. Read reads in | |
779 | its contents - like subdirectories, links, and files. Close cleans it all | |
780 | up. | |
781 | ||
782 | ------------------------------------------------------------------------------- | |
783 | Name: sysfs_open_directory | |
784 | ||
785 | Description: Opens a sysfs directory at a specific path | |
786 | ||
787 | Arguments: const unsigned char *path Directory path to open | |
788 | ||
789 | Returns: struct sysfs_directory * with success. | |
790 | NULL with error. Errno will be set with error, returning | |
791 | - EINVAL for invalid arguments | |
792 | ||
793 | Prototype: struct sysfs_directory *sysfs_open_directory | |
794 | (const unsigned char *path) | |
795 | ------------------------------------------------------------------------------- | |
796 | ||
797 | ------------------------------------------------------------------------------- | |
798 | Name: sysfs_close_directory | |
799 | ||
800 | Description: Closes specific directory, its subdirectories, links, and | |
801 | files. | |
802 | ||
803 | Arguments: struct sysfs_directory *sysdir Directory to close | |
804 | ||
805 | Prototype: void sysfs_close_directory(struct sysfs_directory *sysdir) | |
806 | ------------------------------------------------------------------------------- | |
807 | ||
808 | ------------------------------------------------------------------------------- | |
809 | Name: sysfs_read_dir_subdirs | |
810 | ||
811 | Description: Reads the given sysfs_directory to create a list of subdirs. | |
812 | ||
813 | Arguments: struct sysfs_directory *sysdir sysfs_directory whose | |
814 | subdirs have to be read | |
815 | ||
816 | Returns: struct dlist * of links with success | |
817 | NULL with error. Errno will be set on error, returning EINVAL | |
818 | for invalid arguments | |
819 | ||
820 | Prototype: struct dlist *sysfs_read_dir_subdirs | |
821 | (struct sysfs_directory *sysdir) | |
822 | ------------------------------------------------------------------------------- | |
823 | ||
824 | ------------------------------------------------------------------------------- | |
825 | Name: sysfs_read_directory | |
826 | ||
827 | Description: Read the supplied directory. Reading fills in the directory's | |
828 | contents like subdirectories, links, and attributes. | |
829 | ||
830 | Arguments: struct sysfs_directory *sysdir Directory to read | |
831 | ||
832 | Returns: 0 with success. | |
833 | -1 with error. Errno will be set with error, returning | |
834 | - EINVAL for invalid arguments | |
835 | ||
836 | Prototype: int sysfs_read_directory(struct sysfs_directory *sysdir) | |
837 | ------------------------------------------------------------------------------- | |
838 | ||
839 | ------------------------------------------------------------------------------- | |
840 | Name: sysfs_read_all_subdirs | |
841 | ||
842 | Description: Reads all subdirs under a given supplied directory. | |
843 | ||
844 | Arguments: struct sysfs_directory *sysdir Directory to read | |
845 | ||
846 | Returns: 0 with success. | |
847 | -1 with error. Errno will be set with error, returning | |
848 | - EINVAL for invalid arguments | |
849 | ||
850 | Prototype: int sysfs_read_all_subdirs(struct sysfs_directory *sysdir) | |
851 | ------------------------------------------------------------------------------- | |
852 | ||
853 | ------------------------------------------------------------------------------- | |
854 | Name: sysfs_get_subdirectory | |
855 | ||
856 | Description: Function walks the directory tree for the given directory and | |
857 | returns a sysfs_directory structure for the specified directory | |
858 | name. | |
859 | ||
860 | Arguments: struct sysfs_directory *dir Directory in which to search | |
861 | unsigned char *subname Name of directory to look for | |
862 | ||
863 | Returns: struct sysfs_directory with success. | |
864 | NULL with error. Errno will be set with error, returning | |
865 | - EINVAL for invalid arguments | |
866 | ------------------------------------------------------------------------------- | |
867 | ||
868 | ||
869 | 6.3 Bus Functions | |
870 | ----------------- | |
871 | ||
872 | The library provides a functions for viewing buses represented in sysfs. | |
873 | The sysfs_open_bus opens a bus in the /sys/bus directory, such as "pci", | |
874 | "usb", or "scsi". The open command returns a sysfs_bus structure that | |
875 | contains a list of the bus' devices. The sysfs_close_bus function is | |
876 | used to clean up the bus structure. Given a device or a driver, | |
877 | functions are provided to determine what bus they are on. | |
878 | ||
879 | ------------------------------------------------------------------------------- | |
880 | Name: sysfs_open_bus | |
881 | ||
882 | Description: Function opens up one of the buses represented in sysfs in | |
883 | the /sys/bus directory. It returns a sysfs_bus structure | |
884 | that includes a list of bus devices and drivers. | |
885 | ||
886 | Arguments: const unsigned char *name Bus name to open, like "pci"... | |
887 | ||
888 | Returns: struct sysfs_bus * with success | |
889 | NULL with error. Errno will be set with error, returning | |
890 | - EINVAL for invalid arguments | |
891 | ||
892 | Prototype: struct sysfs_bus *sysfs_open_bus(const unsigned char *name) | |
893 | ------------------------------------------------------------------------------- | |
894 | ||
895 | ------------------------------------------------------------------------------- | |
896 | Name: sysfs_close_bus | |
897 | ||
898 | Description: Function closes up the sysfs_bus structure including its | |
899 | devices, drivers, and directory. | |
900 | ||
901 | Arguments: sysfs_bus *bus Bus structure to close | |
902 | ||
903 | Prototype: void sysfs_close_bus(struct sysfs_bus *bus) | |
904 | ------------------------------------------------------------------------------- | |
905 | ||
906 | ------------------------------------------------------------------------------- | |
907 | Name: sysfs_get_bus_devices | |
908 | ||
909 | Description: Function returns a list of devices that are registered with | |
910 | this bus. | |
911 | ||
912 | Arguments: struct sysfs_bus *bus Bus whose devices list to return | |
913 | ||
914 | Returns: struct dlist * of sysfs_devices on success | |
915 | NULL with error. Errno will be sent with error, returning | |
916 | - EINVAL for invalid arguments | |
917 | ||
918 | Prototype: struct dlist *sysfs_get_bus_devices(struct sysfs_bus *bus) | |
919 | ------------------------------------------------------------------------------- | |
920 | ||
921 | ------------------------------------------------------------------------------- | |
922 | Name: sysfs_get_bus_drivers | |
923 | ||
924 | Description: Function returns a list of drivers that are registered with | |
925 | this bus. | |
926 | ||
927 | Arguments: struct sysfs_bus *bus Bus whose drivers list to return | |
928 | ||
929 | Returns: struct dlist * of sysfs_drivers on success | |
930 | NULL with error. Errno will be sent with error, returning | |
931 | - EINVAL for invalid arguments | |
932 | ||
933 | Prototype: struct dlist *sysfs_get_bus_drivers(struct sysfs_bus *bus) | |
934 | ------------------------------------------------------------------------------- | |
935 | ||
936 | ------------------------------------------------------------------------------- | |
937 | Name: sysfs_get_bus_device | |
938 | ||
939 | Description: Function takes a sysfs_bus structure(obtained on a successful | |
940 | return from a sysfs_open_bus() call) and looks for the given | |
941 | device on this bus. On success, it returns a sysfs_device | |
942 | structure corresponding to the device. | |
943 | ||
944 | Arguments: struct sysfs_bus *bus Bus structure on which to search | |
945 | unsigned char *id Device to look for | |
946 | ||
947 | Returns: struct sysfs_device * with success | |
948 | NULL with error. Errno will be set with error, returning | |
949 | - EINVAL for invalid arguments | |
950 | ||
951 | Prototype: struct sysfs_device *sysfs_get_bus_device | |
952 | (struct sysfs_bus *bus, unsigned char *id) | |
953 | ------------------------------------------------------------------------------- | |
954 | ||
955 | ------------------------------------------------------------------------------- | |
956 | Name: sysfs_get_bus_driver | |
957 | ||
958 | Description: Function takes a sysfs_bus structure (obtained on a successful | |
959 | return from a sysfs_open_bus() call) and looks for the given | |
960 | driver on this bus. On success, it returns a sysfs_driver | |
961 | structure corresponding to the driver. | |
962 | ||
963 | Arguments: struct sysfs_bus *bus Bus structure on which to search | |
964 | unsigned char *drvname Driver to look for | |
965 | ||
966 | Returns: struct sysfs_driver * with success | |
967 | NULL with error. Errno will be set with error, returning | |
968 | - EINVAL for invalid arguments | |
969 | ||
970 | Prototype: struct sysfs_device *sysfs_get_bus_driver | |
971 | (struct sysfs_bus *bus, unsigned char *drvname) | |
972 | ------------------------------------------------------------------------------- | |
973 | ||
974 | ------------------------------------------------------------------------------- | |
975 | Name: sysfs_get_bus_attributes | |
976 | ||
977 | Description: Function takes a sysfs_bus structure and returns a list of | |
978 | attributes for the bus. | |
979 | ||
980 | Arguments: struct sysfs_bus *bus Bus for which attributes are required | |
981 | ||
982 | Returns: struct dlist * of attributes with success | |
983 | NULL with error. Errno will be set with error, returning | |
984 | - EINVAL for invalid arguments | |
985 | ||
986 | Prototype: struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus) | |
987 | ------------------------------------------------------------------------------- | |
988 | ||
989 | ------------------------------------------------------------------------------- | |
990 | Name: sysfs_get_bus_attribute | |
991 | ||
992 | Description: Function takes a sysfs_bus structure and looks for the required | |
993 | attribute on the bus. On success, it returns a sysfs_attribute | |
994 | structure corresponding to the given attribute. | |
995 | ||
996 | Arguments: struct sysfs_bus *bus Bus structure on which to search | |
997 | unsigned char *attrname Attribute to look for | |
998 | ||
999 | Returns: struct sysfs_attribute * with success | |
1000 | NULL with error. Errno will be set with error, returning | |
1001 | - EINVAL for invalid arguments | |
1002 | ||
1003 | Prototype: struct sysfs_attribute *sysfs_get_bus_attribute | |
1004 | (struct sysfs_bus *bus, unsigned char *attrname) | |
1005 | ------------------------------------------------------------------------------- | |
1006 | ||
1007 | ------------------------------------------------------------------------------- | |
1008 | Name: sysfs_open_bus_device | |
1009 | ||
1010 | Description: Given the name of the bus on which to look for, this function | |
1011 | locates a given device on the bus and returns a sysfs_device | |
1012 | structure corresponding to the requested device. | |
1013 | ||
1014 | NOTE: | |
1015 | 1. The sysfs_device structure obtained upon successful return | |
1016 | from this function has to be closed by calling | |
1017 | sysfs_close_device(). | |
1018 | ||
1019 | Arguments: unsigned char *busname Bus on which to search | |
1020 | unsigned char *dev_id Name of the device to look for | |
1021 | ||
1022 | Returns: struct sysfs_device * on success | |
1023 | NULL with error. Errno will be set with error, returning | |
1024 | - EINVAL for invalid arguments | |
1025 | ||
1026 | Prototype: struct sysfs_device *sysfs_open_bus_device | |
1027 | (unsigned char *busname, unsigned char *dev_id) | |
1028 | ------------------------------------------------------------------------------- | |
1029 | ||
1030 | ------------------------------------------------------------------------------- | |
1031 | Name: sysfs_find_driver_bus | |
1032 | ||
1033 | Description: Given the name of a driver, this function finds the name of the | |
1034 | bus the driver is on | |
1035 | ||
1036 | Arguments: const unsigned char *driver Name of the driver to look for | |
1037 | unsigned char *busname Buffer to return the bus name | |
1038 | size_t bsize Size of the "busname" buffer | |
1039 | ||
1040 | Returns: 0 with success. | |
1041 | -1 with error. Errno will be set with error, returning | |
1042 | - EINVAL for invalid arguments | |
1043 | ||
1044 | Prototype: int sysfs_find_driver_bus(const unsigned char *driver, | |
1045 | unsigned char *busname, size_t bsize) | |
1046 | ------------------------------------------------------------------------------- | |
1047 | ||
1048 | ||
1049 | 6.4 Class Functions | |
1050 | ------------------- | |
1051 | ||
1052 | Libsysfs provides functions to open sysfs classes and their class devices. | |
1053 | These functions too operate with open and close, close must be called to | |
1054 | clean up the class structures. Given a class device name, functions are | |
1055 | provided to determine what class they belong to. Once a class device | |
1056 | name and the class it belongs to is known, a function to open the | |
1057 | class device is provided. This method can be used when details of | |
1058 | a single class device is required. | |
1059 | ||
1060 | ------------------------------------------------------------------------------- | |
1061 | Name: sysfs_open_class | |
1062 | ||
1063 | Description: Function opens up one of the classes represented in sysfs in | |
1064 | the /sys/class directory. It returns a sysfs_class structure | |
1065 | that includes a list of class devices. | |
1066 | ||
1067 | Arguments: const unsigned char *name Class name to open, like "net".. | |
1068 | ||
1069 | Returns: struct sysfs_class * with success | |
1070 | NULL with error. Errno will be set with error, returning | |
1071 | - EINVAL for invalid arguments | |
1072 | ||
1073 | Prototype: struct sysfs_class *sysfs_open_class(const unsigned char *name) | |
1074 | ------------------------------------------------------------------------------- | |
1075 | ||
1076 | ------------------------------------------------------------------------------- | |
1077 | Name: sysfs_close_class | |
1078 | ||
1079 | Description: Function closes up the sysfs_class structure including its | |
1080 | class devices. | |
1081 | ||
1082 | Arguments: sysfs_class *class Class structure to close | |
1083 | ||
1084 | Prototype: void sysfs_close_class(struct sysfs_class *class); | |
1085 | ------------------------------------------------------------------------------- | |
1086 | ||
1087 | ------------------------------------------------------------------------------- | |
1088 | Name: sysfs_open_class_device_path | |
1089 | ||
1090 | Description: Function opens up one of the class devices represented in | |
1091 | sysfs in sysfs/class/"class"/ directory. It returns a | |
1092 | sysfs_class_device structure. | |
1093 | ||
1094 | Arguments: const unsigned char *path Path to class device | |
1095 | ||
1096 | Returns: struct sysfs_class_device * with success | |
1097 | NULL with error. Errno will be set with error, returning | |
1098 | - EINVAL for invalid arguments | |
1099 | ||
1100 | Prototype: struct sysfs_class_device *sysfs_open_class_device_path | |
1101 | (const unsigned char *path) | |
1102 | ------------------------------------------------------------------------------- | |
1103 | ||
1104 | ------------------------------------------------------------------------------- | |
1105 | Name: sysfs_close_class_device | |
1106 | ||
1107 | Description: Function closes up the sysfs_class_device structure. | |
1108 | ||
1109 | Arguments: sysfs_class_device *dev Class device structure to close | |
1110 | ||
1111 | Prototype: void sysfs_close_class_device(struct sysfs_class_device *dev) | |
1112 | ------------------------------------------------------------------------------- | |
1113 | ||
1114 | ------------------------------------------------------------------------------- | |
1115 | Name: sysfs_get_class_device | |
1116 | ||
1117 | Description: Function takes a sysfs_class structure(obtained on a successful | |
1118 | return from a sysfs_open_class() call) and looks for the given | |
1119 | device in this class. On success, it returns a sysfs_class_device | |
1120 | structure corresponding to the class device. | |
1121 | ||
1122 | Arguments: struct sysfs_class *class Class on which to search | |
1123 | unsigned_char *name Class device "name" to look for | |
1124 | ||
1125 | Returns: struct sysfs_class_device * with success | |
1126 | NULL with error. Errno will be set with error, returning | |
1127 | - EINVAL for invalid arguments | |
1128 | ||
1129 | Prototype: struct sysfs_class_device *sysfs_get_class_device | |
1130 | (struct sysfs_class *class, unsigned char *name) | |
1131 | ------------------------------------------------------------------------------- | |
1132 | ||
1133 | ------------------------------------------------------------------------------- | |
1134 | Name: sysfs_get_class_devices | |
1135 | ||
1136 | Description: Function returns a list of class devices for the given class. | |
1137 | ||
1138 | Arguments: struct sysfs_class *cls Class whose class device list | |
1139 | is required | |
1140 | ||
1141 | Returns: struct dlist * of sysfs_class_devices on success | |
1142 | NULL with error. Errno will be set with error, returning | |
1143 | - EINVAL for invalid arguments | |
1144 | ||
1145 | Prototype: struct dlist *sysfs_get_class_devices(struct sysfs_class *cls) | |
1146 | ------------------------------------------------------------------------------- | |
1147 | ||
1148 | ------------------------------------------------------------------------------- | |
1149 | Name: sysfs_open_class_device | |
1150 | ||
1151 | Description: Given the name of the class on which to look for, this function | |
1152 | locates a given class device and returns a sysfs_class_device | |
1153 | structure corresponding to the requested class device. | |
1154 | ||
1155 | NOTE: | |
1156 | 1. The sysfs_class_device structure obtained upon successful | |
1157 | return from this function has to be closed by calling | |
1158 | sysfs_close_class_device(). | |
1159 | 2. Class this device belongs to must be known prior to calling | |
1160 | this function. | |
1161 | ||
1162 | Arguments: const unsigned char *classname Class on which to search | |
1163 | unsigned char *name Class device "name" to open | |
1164 | ||
1165 | Returns: struct sysfs_class_device * with success | |
1166 | NULL with error. Errno will be set with error, returning | |
1167 | - EINVAL for invalid arguments | |
1168 | ||
1169 | Prototype: struct sysfs_class_device *sysfs_open_class_device | |
1170 | (const unsigned char *classname, unsigned char *class) | |
1171 | ------------------------------------------------------------------------------- | |
1172 | ||
1173 | ------------------------------------------------------------------------------- | |
1174 | Name: sysfs_get_classdev_device | |
1175 | ||
1176 | Description: Function returns the sysfs_device reference (if present) for the | |
1177 | given class device. | |
1178 | ||
1179 | Arguments: struct sysfs_class_device *clsdev Class device whose | |
1180 | sysfs_device reference | |
1181 | is required | |
1182 | ||
1183 | Returns: struct sysfs_device * on success | |
1184 | NULL with error. Errno will be set with error, returning | |
1185 | - EINVAL for invalid arguments | |
1186 | ||
1187 | Prototype: struct sysfs_device *sysfs_get_classdev_device | |
1188 | (struct sysfs_class_device *clsdev) | |
1189 | ------------------------------------------------------------------------------- | |
1190 | ||
1191 | ------------------------------------------------------------------------------- | |
1192 | Name: sysfs_get_classdev_driver | |
1193 | ||
1194 | Description: Function returns the sysfs_driver reference (if present) for the | |
1195 | given class device. | |
1196 | ||
1197 | Arguments: struct sysfs_class_device *clsdev Class device whose | |
1198 | sysfs_driver reference | |
1199 | is required | |
1200 | ||
1201 | Returns: struct sysfs_driver * on success | |
1202 | NULL with error. Errno will be set with error, returning | |
1203 | - EINVAL for invalid arguments | |
1204 | ||
1205 | Prototype: struct sysfs_driver *sysfs_get_classdev_driver | |
1206 | (struct sysfs_class_device *clsdev) | |
1207 | ------------------------------------------------------------------------------- | |
1208 | ||
1209 | ------------------------------------------------------------------------------- | |
1210 | Name: sysfs_get_classdev_parent | |
1211 | ||
1212 | Description: Function returns the sysfs_class_device reference for the parent | |
1213 | (if present) of the given class device. | |
1214 | ||
1215 | Arguments: struct sysfs_class_device *clsdev Class device whose | |
1216 | parent reference | |
1217 | is required | |
1218 | ||
1219 | Returns: struct sysfs_class_device * on success | |
1220 | NULL with error. Errno will be set with error, returning | |
1221 | - EINVAL for invalid arguments | |
1222 | ||
1223 | Prototype: struct sysfs_class_device *sysfs_get_classdev_parent | |
1224 | (struct sysfs_class_device *clsdev) | |
1225 | ------------------------------------------------------------------------------- | |
1226 | ||
1227 | ------------------------------------------------------------------------------- | |
1228 | Name: sysfs_get_classdev_attributes | |
1229 | ||
1230 | Description: Function takes a sysfs_class_device structure and returns a list | |
1231 | of attributes for the class device. | |
1232 | ||
1233 | Arguments: struct sysfs_class_device *cdev Class device for which | |
1234 | attributes are required | |
1235 | ||
1236 | Returns: struct dlist * of attributes with success | |
1237 | NULL with error. Errno will be set with error, returning | |
1238 | - EINVAL for invalid arguments | |
1239 | ||
1240 | Prototype: struct dlist *sysfs_get_classdev_attributes | |
1241 | (struct sysfs_class_device *cdev) | |
1242 | ------------------------------------------------------------------------------- | |
1243 | ||
1244 | ------------------------------------------------------------------------------- | |
1245 | Name: sysfs_get_classdev_attr | |
1246 | ||
1247 | Description: Searches supplied class device's attributes by name and returns | |
1248 | the attribute. | |
1249 | ||
1250 | Arguments: struct sysfs_class_device *clsdev Device to search | |
1251 | const unsigned char *name Attribute name to find | |
1252 | ||
1253 | Returns: struct sysfs_attribute * with success | |
1254 | NULL with error. Errno will be set with error, returning | |
1255 | - EINVAL for invalid arguments | |
1256 | ||
1257 | Prototype: struct sysfs_attribute *sysfs_get_classdev_attr | |
1258 | (struct sysfs_class_device *clsdev, const unsigned char *name) | |
1259 | ------------------------------------------------------------------------------- | |
1260 | ||
1261 | ------------------------------------------------------------------------------- | |
1262 | Name: sysfs_open_classdev_attr | |
1263 | ||
1264 | Description: Function takes as arguments, a the name of the class, the class | |
1265 | device name and the name of the required attribute. | |
1266 | ||
1267 | NOTE: | |
1268 | 1. The struct sysfs_attribute * obtained upon successful | |
1269 | return from this function has to be closed by making | |
1270 | a call to sysfs_close_attribute() | |
1271 | ||
1272 | Arguments: unsigned char *classname Class name on which to search | |
1273 | unsigned char *dev Name of the class device | |
1274 | unsigned char *attrib Attribute to open | |
1275 | ||
1276 | Returns: struct sysfs_attribute * with success. | |
1277 | NULL with error. Errno will be set with error, returning | |
1278 | - EINVAL for invalid arguments | |
1279 | ||
1280 | Prototype: struct sysfs_attribute *sysfs_write_classdev_attr | |
1281 | (const unsigned char *classname, const unsigned char *dev, | |
1282 | const unsigned char *attrib) | |
1283 | ------------------------------------------------------------------------------- | |
1284 | ||
1285 | ||
1286 | 6.5 Device Functions | |
1287 | -------------------- | |
1288 | ||
1289 | Devices represent everything in sysfs under /sys/devices, which is a | |
1290 | hierarchical view of system devices. Besides the expected open and | |
1291 | close functions, libsysfs provides open and close functions for | |
1292 | root devices. These functions recursively open or close a device | |
1293 | and all of its children. | |
1294 | ||
1295 | ------------------------------------------------------------------------------- | |
1296 | Name: sysfs_open_device_path | |
1297 | ||
1298 | Description: Opens up a device at a specific path. It opens the device's | |
1299 | directory, reads the directory, and returns a sysfs_device | |
1300 | structure. | |
1301 | ||
1302 | Arguments: const unsigned char *path Path to device | |
1303 | ||
1304 | Returns: struct sysfs_device * with success | |
1305 | NULL with error. Errno will be set with error, returning | |
1306 | - EINVAL for invalid arguments | |
1307 | ||
1308 | Prototype: struct sysfs_device *sysfs_open_device_path | |
1309 | (const unsigned char *path) | |
1310 | ------------------------------------------------------------------------------- | |
1311 | ||
1312 | ------------------------------------------------------------------------------- | |
1313 | Name: sysfs_close_device | |
1314 | ||
1315 | Description: Function closes up the sysfs_device structure. | |
1316 | ||
1317 | Arguments: sysfs_device *dev Device structure to close | |
1318 | ||
1319 | Prototype: void sysfs_close_device(struct sysfs_device *dev) | |
1320 | ------------------------------------------------------------------------------- | |
1321 | ||
1322 | ------------------------------------------------------------------------------- | |
1323 | Name: sysfs_open_root_device | |
1324 | ||
1325 | Description: Function opens up one of the root devices represented in sysfs | |
1326 | in the /sys/devices directory. It returns a sysfs_root_device | |
1327 | structure that includes a list of devices in the tree. | |
1328 | ||
1329 | Arguments: const unsigned char *name Name of the root device to open | |
1330 | ||
1331 | Returns: struct sysfs_root_device * with success | |
1332 | NULL with error. Errno will be set with error, returning | |
1333 | - EINVAL for invalid arguments | |
1334 | ||
1335 | Prototype: struct sysfs_device *sysfs_open_root_device | |
1336 | (const unsigned char *name) | |
1337 | ------------------------------------------------------------------------------- | |
1338 | ||
1339 | ------------------------------------------------------------------------------- | |
1340 | Name: sysfs_close_root_device | |
1341 | ||
1342 | Description: Function closes up the sysfs_root_device structure including the | |
1343 | devices in the root device tree. | |
1344 | ||
1345 | Arguments: sysfs_device *root Root device structure to close | |
1346 | ||
1347 | Prototype: void sysfs_close_root_device(struct sysfs_root_device *root) | |
1348 | ------------------------------------------------------------------------------- | |
1349 | ||
1350 | ------------------------------------------------------------------------------- | |
1351 | Name: sysfs_get_device_parent | |
1352 | ||
1353 | Description: Function returns the sysfs_device reference for the parent | |
1354 | (if present) of the given sysfs_device. | |
1355 | ||
1356 | Arguments: struct sysfs_device *dev sysfs_device whose parent | |
1357 | reference is required | |
1358 | ||
1359 | Returns: struct sysfs_device * on success | |
1360 | NULL with error. Errno will be set with error, returning | |
1361 | - EINVAL for invalid arguments | |
1362 | ||
1363 | Prototype: struct sysfs_device *sysfs_get_device_parent | |
1364 | (struct sysfs_device *dev) | |
1365 | ------------------------------------------------------------------------------- | |
1366 | ||
1367 | ------------------------------------------------------------------------------- | |
1368 | Name: sysfs_get_root_devices | |
1369 | ||
1370 | Description: Function returns a list of devices under the given root device. | |
1371 | ||
1372 | Arguments: struct sysfs_root_device *root sysfs_root_device whose devices | |
1373 | list is required | |
1374 | ||
1375 | Returns: struct dlist * of sysfs_devices on success | |
1376 | NULL with error. Errno will be set with error, returning | |
1377 | - EINVAL for invalid arguments | |
1378 | ||
1379 | Prototype: struct dlist *sysfs_get_root_devices | |
1380 | (struct sysfs_root_device *root) | |
1381 | ------------------------------------------------------------------------------- | |
1382 | ||
1383 | ------------------------------------------------------------------------------- | |
1384 | Name: sysfs_get_device_attr | |
1385 | ||
1386 | Description: Searches supplied device's attributes by name and returns | |
1387 | the attribute. | |
1388 | ||
1389 | Arguments: struct sysfs_device *dev Device to search | |
1390 | const unsigned char *name Attribute name to find | |
1391 | ||
1392 | Returns: struct sysfs_attribute * with success | |
1393 | NULL with error. Errno will be set with error, returning | |
1394 | - EINVAL for invalid arguments | |
1395 | ||
1396 | Prototype: struct sysfs_attribute *sysfs_get_device_attr | |
1397 | (struct sysfs_device *dev, const unsigned char *name) | |
1398 | ------------------------------------------------------------------------------- | |
1399 | ||
1400 | ------------------------------------------------------------------------------- | |
1401 | Name: sysfs_get_device_attributes | |
1402 | ||
1403 | Description: Function takes a sysfs_device structure and returns a list | |
1404 | of attributes for the device. | |
1405 | ||
1406 | Arguments: struct sysfs_device *device Device for which | |
1407 | attributes are required | |
1408 | ||
1409 | Returns: struct dlist * of attributes with success | |
1410 | NULL with error. Errno will be set with error, returning | |
1411 | - EINVAL for invalid arguments | |
1412 | ||
1413 | Prototype: struct dlist *sysfs_get_device_attributes | |
1414 | (struct sysfs_device *device) | |
1415 | ------------------------------------------------------------------------------- | |
1416 | ||
1417 | ------------------------------------------------------------------------------- | |
1418 | Name: sysfs_open_device | |
1419 | ||
1420 | Description: Given the name of the bus on which to look for, this function | |
1421 | locates a given device and returns a sysfs_device structure | |
1422 | corresponding to the requested device. | |
1423 | ||
1424 | Arguments: const unsigned char *bus_id Device to look for | |
1425 | const unsigned char *bus Bus on which to search | |
1426 | ||
1427 | Returns: struct sysfs_device * with success | |
1428 | NULL with error. Errno will be set with error, returning | |
1429 | - EINVAL for invalid arguments | |
1430 | ||
1431 | Prototype: struct sysfs_device *sysfs_open_device | |
1432 | (const unsigned char *bus_id, const unsigned char *bus) | |
1433 | ------------------------------------------------------------------------------- | |
1434 | ||
1435 | ------------------------------------------------------------------------------- | |
1436 | Name: sysfs_open_device_attr | |
1437 | ||
1438 | Description: Function takes as arguments, the bus on which to search for a | |
1439 | device, and an attribute of the device to open. | |
1440 | ||
1441 | NOTE: | |
1442 | 1. The struct sysfs_attribute * obtained upon successful | |
1443 | return from this function has to be closed by making | |
1444 | a call to sysfs_close_attribute() | |
1445 | ||
1446 | Arguments: unsigned char *bus Bus on which to search | |
1447 | unsigned char *bus_id Device to look for | |
1448 | unsigned char *attrib Name of the attribute to open | |
1449 | ||
1450 | Returns: struct sysfs_attribute * with success. | |
1451 | NULL with error. Errno will be set with error, returning | |
1452 | - EINVAL for invalid arguments | |
1453 | ||
1454 | Prototype: struct sysfs_attribute *sysfs_open_device_attr | |
1455 | (const unsigned char *bus, const unsigned char *bus_id, | |
1456 | const unsigned char *attrib) | |
1457 | ------------------------------------------------------------------------------- | |
1458 | ||
1459 | ||
1460 | 6.6 Driver Functions | |
1461 | -------------------- | |
1462 | ||
1463 | Drivers are represented in sysfs under the /sys/bus/xxx/drivers (xxx being | |
1464 | the bus type, such as "pci", "usb, and so on). Functions are provided to | |
1465 | open and close drivers. | |
1466 | ||
1467 | ------------------------------------------------------------------------------- | |
1468 | Name: sysfs_open_driver_path | |
1469 | ||
1470 | Description: Opens driver at specific path. | |
1471 | ||
1472 | Arguments: const unsigned char *path Path to driver | |
1473 | ||
1474 | Returns: struct sysfs_driver * with success | |
1475 | NULL with error. Errno will be set with error, returning | |
1476 | - EINVAL for invalid arguments | |
1477 | ||
1478 | Prototype: struct sysfs_driver *sysfs_open_driver_path | |
1479 | (const unsigned char *path) | |
1480 | ------------------------------------------------------------------------------- | |
1481 | ||
1482 | ------------------------------------------------------------------------------- | |
1483 | Name: sysfs_close_driver | |
1484 | ||
1485 | Description: Closes and cleans up sysfs_driver structure. | |
1486 | ||
1487 | Arguments: sysfs_driver *driver Driver structure to close | |
1488 | ||
1489 | Prototype: void sysfs_close_driver(struct sysfs_driver *driver) | |
1490 | ------------------------------------------------------------------------------- | |
1491 | ||
1492 | ------------------------------------------------------------------------------- | |
1493 | Name: sysfs_get_driver_devices | |
1494 | ||
1495 | Description: Function returns a list of devices that use this driver. | |
1496 | ||
1497 | Arguments: struct sysfs_driver *driver Driver whose devices list is | |
1498 | required | |
1499 | ||
1500 | Returns: struct dlist * of sysfs_devices on success | |
1501 | NULL with error. Errno will be set with error, returning | |
1502 | - EINVAL for invalid arguments | |
1503 | ||
1504 | Prototype: struct dlist *sysfs_get_driver_devices | |
1505 | (struct sysfs_driver *driver) | |
1506 | ------------------------------------------------------------------------------- | |
1507 | ||
1508 | ------------------------------------------------------------------------------- | |
1509 | Name: sysfs_get_driver_device | |
1510 | ||
1511 | Description: Function returns a sysfs_device reference for the device with | |
1512 | "name" that uses this driver | |
1513 | ||
1514 | Arguments: struct sysfs_driver *driver Driver on which to search | |
1515 | const unsigned char *name Name of the device to look for | |
1516 | ||
1517 | Returns: struct sysfs_device * corresponding to "name" on success | |
1518 | NULL with error. Errno will be set with error, returning | |
1519 | - EINVAL for invalid arguments | |
1520 | ||
1521 | Prototype: struct dlist *sysfs_get_driver_device | |
1522 | (struct sysfs_driver *driver, const unsigned char *name) | |
1523 | ------------------------------------------------------------------------------- | |
1524 | ||
1525 | ------------------------------------------------------------------------------- | |
1526 | Name: sysfs_get_driver_attr | |
1527 | ||
1528 | Description: Searches supplied driver's attributes by name and returns | |
1529 | the attribute. | |
1530 | ||
1531 | Arguments: struct sysfs_driver *drv Driver to search | |
1532 | const unsigned char *name Attribute name to find | |
1533 | ||
1534 | Returns: struct sysfs_attribute * with success | |
1535 | NULL with error. Errno will be set with error, returning | |
1536 | - EINVAL for invalid arguments | |
1537 | ||
1538 | Prototype: struct sysfs_attribute *sysfs_get_driver_attr | |
1539 | (struct sysfs_driver *drv, const unsigned char *name) | |
1540 | ------------------------------------------------------------------------------- | |
1541 | ||
1542 | ------------------------------------------------------------------------------- | |
1543 | Name: sysfs_get_driver_attributes | |
1544 | ||
1545 | Description: Function takes a sysfs_driver structure and returns a list | |
1546 | of attributes for the driver. | |
1547 | ||
1548 | Arguments: struct sysfs_driver *driver Driver for which | |
1549 | attributes are required | |
1550 | ||
1551 | Returns: struct dlist * of attributes with success | |
1552 | NULL with error. Errno will be set with error, returning | |
1553 | - EINVAL for invalid arguments | |
1554 | ||
1555 | Prototype: struct dlist *sysfs_get_driver_attributes | |
1556 | (struct sysfs_driver *driver) | |
1557 | ------------------------------------------------------------------------------- | |
1558 | ||
1559 | ------------------------------------------------------------------------------- | |
1560 | Name: sysfs_open_driver | |
1561 | ||
1562 | Description: Given the name of the bus on which to look for, this function | |
1563 | locates a given driver and returns a sysfs_driver structure | |
1564 | corresponding to the requested device. | |
1565 | ||
1566 | NOTE: | |
1567 | 1. The sysfs_driver structure obtained upon successful return | |
1568 | from this function has to be closed by calling | |
1569 | sysfs_close_driver_by_name(). | |
1570 | 2. Bus on which to look for this driver should be known prior | |
1571 | to calling this function. Use sysfs_find_driver_bus() | |
1572 | to determine this. | |
1573 | ||
1574 | Arguments: const unsigned char *drv_name Driver to look for | |
1575 | const unsigned char *bus Bus on which to search | |
1576 | size_t bsize Size of "bus" | |
1577 | ||
1578 | Returns: struct sysfs_driver * with success | |
1579 | NULL with error. Errno will be set with error, returning | |
1580 | - EINVAL for invalid arguments | |
1581 | ||
1582 | Prototype: struct sysfs_driver *sysfs_open_driver | |
1583 | (const unsigned char *drv_name, | |
1584 | const unsigned char *bus, size_t bsize) | |
1585 | ------------------------------------------------------------------------------- | |
1586 | ||
1587 | ------------------------------------------------------------------------------- | |
1588 | Name: sysfs_get_driver_links | |
1589 | ||
1590 | Description: Function returns a list of links for a given driver | |
1591 | ||
1592 | Arguments: struct sysfs_driver *driver Driver to get links from | |
1593 | ||
1594 | Returns: struct dlist * of links on success | |
1595 | NULL with error | |
1596 | ||
1597 | Prototype: struct dlist *sysfs_get_driver_links | |
1598 | (struct sysfs_driver *driver) | |
1599 | ------------------------------------------------------------------------------- | |
1600 | ||
1601 | ------------------------------------------------------------------------------- | |
1602 | Name: sysfs_open_driver_attr | |
1603 | ||
1604 | Description: Function takes as arguments, the bus the driver is registered | |
1605 | on, the driver name and the name of the attribute to open. | |
1606 | ||
1607 | NOTE: | |
1608 | 1. The struct sysfs_attribute * obtained upon successful | |
1609 | return from this function has to be closed by making | |
1610 | a call to sysfs_close_attribute() | |
1611 | ||
1612 | Arguments: unsigned char *bus Bus on which driver is present | |
1613 | unsigned char *drv Driver to look for | |
1614 | unsigned char *attrib Name of the attribute to open | |
1615 | ||
1616 | Returns: struct sysfs_attribute * with success. | |
1617 | NULL with error. Errno will be set with error, returning | |
1618 | - EINVAL for invalid arguments | |
1619 | ||
1620 | Prototype: struct sysfs_attribute *sysfs_open_driver_attr | |
1621 | (const unsigned char *bus, const unsigned char *drv, | |
1622 | const unsigned char *attrib) | |
1623 | ------------------------------------------------------------------------------- | |
1624 | ||
1625 | ||
1626 | 7. Navigating a dlist | |
1627 | --------------------- | |
1628 | ||
1629 | Libsysfs uses (yet another) list implementation thanks to Eric J Bohm. | |
1630 | ||
1631 | Some library functions return a dlist of devices/drivers/attributes, etc. | |
1632 | To navigate the list returned the macro "dlist_for_each_data" is to be used. | |
1633 | ||
1634 | ------------------------------------------------------------------------------ | |
1635 | Function/Macro name: dlist_for_each_data | |
1636 | ||
1637 | Description: Walk the given list, returning a known data type/ | |
1638 | structure in each iteration. | |
1639 | ||
1640 | Arguments: struct dlist *list List pointer | |
1641 | data_iterator Data type/structure variable | |
1642 | contained in the list | |
1643 | datatype Data type/structure contained | |
1644 | in the list | |
1645 | ||
1646 | Returns: On each iteration, "data_iterator" will contain a list | |
1647 | element of "datatype" | |
1648 | ||
1649 | Usage example: The function sysfs_get_classdev_attributes() returns a | |
1650 | dlist of attributes. To navigate the list: | |
1651 | ||
1652 | struct sysfs_attribute *attr = NULL; | |
1653 | struct dlist *attrlist = NULL; | |
1654 | . | |
1655 | . | |
1656 | . | |
1657 | attrlist = sysfs_get_classdev_attributes | |
1658 | (struct sysfs_class_device *cdev) | |
1659 | if (attrlist != NULL) { | |
1660 | dlist_for_each_data(attrlist, attr, | |
1661 | struct sysfs_attribute) { | |
1662 | . | |
1663 | . | |
1664 | . | |
1665 | } | |
1666 | } | |
1667 | ------------------------------------------------------------------------------- | |
1668 | ||
1669 | ||
1670 | 8. Usage | |
1671 | -------- | |
1672 | ||
1673 | Accessing devices through libsysfs is supposed to mirror accessing devices | |
1674 | in the filesystem it represents. Here's a typical order of operation: | |
1675 | ||
1676 | - get sysfs mount point | |
1677 | - "open" sysfs category, ie. bus, class, or device | |
1678 | - work with category | |
1679 | - "close" sysfs category | |
1680 | ||
1681 | ||
1682 | 9. Conclusion | |
1683 | ------------- | |
1684 | ||
1685 | Libsysfs is meant to provide a stable application programming interface to | |
1686 | sysfs. Applications can depend upon the library to access system devices | |
1687 | and functions exposed through sysfs. |