diff options
Diffstat (limited to 'libsysfs')
| -rw-r--r-- | libsysfs/libsysfs.txt | 1954 |
1 files changed, 1954 insertions, 0 deletions
diff --git a/libsysfs/libsysfs.txt b/libsysfs/libsysfs.txt new file mode 100644 index 0000000000..b877cb8030 --- /dev/null +++ b/libsysfs/libsysfs.txt @@ -0,0 +1,1954 @@ + + System Utilities sysfs Library - libsysfs + ========================================= + +Version: 1.2.0 +September 13, 2004 + +Contents +-------- +1. Introduction +2. Requirements +3. Definitions +4. Overview +5. Data Structures + 5.1 Directory and Attribute Data Structures + 5.1.1 Attribute Structure + 5.1.2 Link Structure + 5.1.3 Directory Structure + 5.2 Bus Data Structure + 5.3 Class Data Structures + 5.4 Root Device Data Structure + 5.5 Device Data Structure + 5.6 Driver Data Structure +6. Functions + 6.1 Calling Conventions in Libsysfs + 6.2 Utility Functions + 6.3 Filesystem Functions + 6.3.1 Attribute Functions + 6.3.2 Directory Link Functions + 6.3.3 Directory Functions + 6.4 Bus Functions + 6.5 Class Functions + 6.6 Device Functions + 6.7 Driver Functions +7. Dlists + 7.1 Navigating a dlist + 7.2 Custom sorting using dlist_sort_custom() +8. Usage +9. Testsuite +10. Conclusion + + +1. Introduction +--------------- + +Libsysfs' purpose is to provide a consistent and stable interface for +querying system device information exposed through the sysfs filesystem. +The library implements functions for querying filesystem information, +such as reading directories and files. It also contains routines for +working with buses, classes, and the device tree. + + +2. Requirements +--------------- + +The library must satisfy the following requirements: + +- It must provide a stable programming interfaces that applications can + be built upon. + +- It must provide functions to retrieve device Vital Product Data (VPD) + information for Error Log Analysis (ELA) support. ELA will provide + device driver and device bus address information. + +- It must provide access to all system devices and information exposed + by sysfs. + +- It must provide a function to find sysfs' current mount point. + +- It must provide a function for udev to retrieve a device's major and + minor numbers. + + +3. Definitions +-------------- + +- sysfs: Sysfs is a virtual filesystem in 2.5+ Linux kernels that + presents a hierarchical representation of all system physical and + virtual devices. It presents system devices by bus, by class, and + by topology. Callbacks to device drivers are exposed as files in + device directories. Sysfs, for all purposes, is our tree of system + devices. For more information, please see: + + http://www.kernel.org/pub/linux/kernel/people/mochel/doc/ + +- udev: Udev is Greg Kroah-Hartman's User Space implementation of devfs. + Udev creates /dev nodes for devices upon Hotplug events. The Hotplug + event provides udev with a sysfs directory location of the device. Udev + must use that directory to grab device's major and minor number, which it + will use to create the /dev node. For more information, please see: + + http://www.kernel.org/pub/linux/utils/kernel/hotplug/ + + Udev provides persistent device naming based on a set of user specified + rules. The rules a device name is based on could one or a combination of a + number of parameters such as the bus the device is on, the serial number + of the device (in case of USB), the vendor name (in case of SCSI) and so + on. Udev uses Libsysfs to retrieve relevent information to appropriately + name devices. + + +4. Overview +----------- + +Libsysfs grew from a common need. There are several applications under +development that need access to sysfs and system devices. Udev, on a +hotplug event, must take a sysfs device path and create a /dev node. Our +diagnostic client needs to list all system devices. Finally, our Error +Log Analysis piece is required to retrieve VPD information for a +failing device. We divided to create a single library interface rather +than having these separate applications create their own accesses to +sysfs involving reading directories and files. + +Libsysfs will also provide stability for applications to be built upon. Sysfs +currently doesn't enforce any standards for callback or file names. File +names change depending on bus or class. Sysfs is also changing, it is +currently being developed. Libsysfs will provide a stable interface to +applications while allowing sysfs to change underneath it. + +Like sysfs, the library will provide devices to applications by bus, by +class, and by topology. The library will function similar to directories +and files that lie underneath it. To query a device on a PCI bus, one would +"open" the bus to scan or read devices and "close" the bus when +completed. Besides supplying functions to retrieve devices, the library +will also provide some utility functions like getting sysfs mount point. + +A paper on Libsysfs was presented at Linux.Conf.Au 2004 (Adelaide, January +2004). The paper is available online at: + +http://oss.software.ibm.com/linux/papers/libsysfs/libsysfs-linuxconfau2004.pdf + + +5. Data Structures +------------------ + +Libsysfs will classify system devices following sysfs' example, dividing +them by bus, class, and devices. The library presents this information +generically. It doesn't, for example, differentiate between PCI and USB +buses. Device attributes are presented with values as they are exposed +by sysfs, the values are not formatted. + +The library will provide standard definitions for working with sysfs +and devices, here's some examples: + +#define SYSFS_FSTYPE_NAME "sysfs" +#define SYSFS_PROC_MNTS "/proc/mounts" +#define SYSFS_BUS_NAME "bus" +#define SYSFS_CLASS_NAME "class" +#define SYSFS_BLOCK_NAME "block" +#define SYSFS_DEVICES_NAME "devices" +#define SYSFS_DRIVERS_NAME "drivers" +#define SYSFS_NAME_ATTRIBUTE "name" + +The library uses some definitions to mark maximum size of a sysfs name or +path length: + +#define SYSFS_PATH_MAX 255 +#define SYSFS_NAME_LEN 50 +#define SYSFS_BUS_ID_SIZE 20 + + +NOTE: + a. As of release 0.4.0 of sysfsutils, a number of changes have been + made so that the dlists and "directory" references in all libsysfs's + structures are not populated until such time that it is absolutely + necessary. Hence, these elements may not contain valid data at all + times (as was the case before). + b. As of release 1.0.0 of sysfsutils, all dlists in the library are + sorted in alphabetical order. It is now a requirement that the + "name" and "path" be the first two elements of all libsysfs + structures. + + +5.1 Directory and Attribute Data Structures +------------------------------------------- + +The library implements structures to represent sysfs directories, links, +and files. + + +5.1.1 Attribute Structure +------------------------- + +A file in sysfs represents a device or driver attribute. Attributes can be +read only, write only, or read and write. File data can be ASCII and +binary. The library has the following structure to represent files: + +struct sysfs_attribute { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + char *value; + unsigned short len; /* value length */ + unsigned short method; /* show and store */ +}; + +Path represents the file/attribute's full path. Value is used when reading +from or writing to an attribute. "len" is the length of data in "value". +Method is a bitmask for defining if the attribute supports show(read) +and/or store(write). + + +5.1.2 Link Structure +-------------------- + +Symbolic links are used in sysfs to link bus or class views with +particular devices. + +struct sysfs_link { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + char target[SYSFS_PATH_MAX]; +}; + +Link's name is stored in "name' and it's target stored in "target". Absolute +path to the link is stored in "path". + + +5.1.3 Directory Structure +------------------------- + +The directory structure represents a sysfs directory: + +struct sysfs_directory { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + + /* Private: for internal use only */ + struct dlist *subdirs; + struct dlist *links; + struct dlist *attributes; +}; + +The sysfs_directory structure includes the list of subdirectories, links and +attributes. The "name" and absolute "path" are also stored in the structure. +The sysfs_directory structure is intended for use internal to the library. +Applications needing access to attributes and links from the directory +will need to make appropriate calls (described below) to get the same. + + +5.2 Bus Data Structure +---------------------- + +All buses look similar in sysfs including lists of devices and drivers, +therefore we use the following structure to represent all sysfs buses: + +struct sysfs_bus { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + + /* Private: for internal use only */ + struct dlist *drivers; + struct dlist *devices; + struct sysfs_directory *directory; +}; + +The sysfs_bus structure contains the bus "name", while the "path" to bus +directory is also stored. It also contains lists of devices on the bus +and drivers that are registered on it. The bus' directory is represented +by the sysfs_directory structure and it contains references to all the +subdirectories, links, and attributes. The sysfs_directory structure +is for internal use only. The following functions may be used by +applications to retrieve data from the sysfs_directory structure: + +struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus) +struct sysfs_attribute *sysfs_get_bus_attribute(struct sysfs_bus *bus, + char *attrname) + + +5.3 Class Data Structures +------------------------- + +The library uses two data structures to represent classes in sysfs. Sysfs +classes contains a class directory like "net" or "scsi_host" and then +class devices like "eth0", "lo", or "eth1" for the "net" class. + +struct sysfs_class { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + + /* Private: for internal use only */ + struct dlist *devices; + struct sysfs_directory *directory; +}; + +The sysfs_class represents device classes in sysfs like "net". It contains +the class "name", "path" to the class, a list of class devices and the +directory representation (for internal use only). + +struct sysfs_class_device { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + char classname[SYSFS_NAME_LEN]; + + /* Private: for internal use only */ + struct sysfs_class_device *parent; + struct sysfs_device *sysdevice; /* NULL if virtual */ + struct sysfs_driver *driver; /* NULL if not implemented */ + struct sysfs_directory *directory; +}; + +A class device isn't the same as a sysfs_device, it's specific to the class in +which it belongs. The class device structure contains the name of the class +the class device belongs to, its sysfs_device reference and that device's +driver reference (if any). It also contains the name of the class device +- like "eth0", its parent point (if present) and its sysfs directory +information including links and attributes (for internal use only). +The following function may be used by applications to retrieve data +from the sysfs_directory structure: + +struct dlist *sysfs_get_classdev_attributes(struct sysfs_class_device *cdev); + + +5.4 Root Device Data Structure +------------------------------ + +Device hierarchies in sysfs are represented under the /sys/devices directory +structure. Sysfs devices typically spawn off from base devices which are +represented by a sysfs_root_device. + +struct sysfs_root_device { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + + /* Private: for internal use only */ + struct dlist *devices; + struct sysfs_directory *directory; +}; + +The sysfs_root_device structure contains a list of "devices" that spawn off it. +The name of the root device as represented under /sys/devices is read into +"name" and the absolute path into "path" and its sysfs_directory information +intended to be used internal to the library. + + +5.5 Device Data Structure +------------------------- + +The sysfs_device structure represents a system device that's exposed +in sysfs under the /sys/devices directory structure. + +struct sysfs_device { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + char bus_id[SYSFS_NAME_LEN]; + char bus[SYSFS_NAME_LEN]; + char driver_name[SYSFS_NAME_LEN]; + + /* Private: for internal use only */ + struct sysfs_device *parent; + struct dlist *children; + struct sysfs_directory *directory; +}; + +The sysfs_device structure contains a "parent" pointer, a list of child +devices, if any, device's directory, its bus id - which is the name of +device's directory, the bus name on which this device is registered and +its driver name. The device structure also contains the absolute path +to the device and a directory structure, which contains a list of the +device's attributes (for internal use only). The following functions +may be used to obtain information from sysfs_directory structure: + +struct sysfs_attribute *sysfs_get_device_attribute(struct sysfs_device *dev, + const char *name) +struct dlist *sysfs_get_device_attributes(struct sysfs_device *device) + + +5.6 Driver Data Structure +------------------------- + +The sysfs_driver structure represents a device driver. + +struct sysfs_driver { + char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + + /* Private: for internal use only */ + struct dlist *devices; + struct sysfs_directory *directory; +}; + +The sysfs_driver structure contains a list of devices that use this driver, +the name of the driver, its path, and its directory information, which +includes the driver's attributes (for internal use only). The following +function may be used to retrieve driver attribute information from the +sysfs_directory structure: + +struct dlist *sysfs_get_driver_attributes(struct sysfs_driver *driver) + + +6. Functions +------------ + +Libsysfs will provide functions to access system devices by bus, by class, +and by device. Functions will act like accessing directories and files, +using "open" and "close". Open returns a structure and close is used +to clean that structure up. + + +6.1 Calling Conventions in Libsysfs +----------------------------------- + +Libsysfs uses a simple API calling convention. APIs are classified to be +one of "open", "get", "close" types. The convention is as follows: + + a. All "open" APIs have a corresponding "close" API. + b. References obtained using "get" calls should not be closed + explicitly. + c. All "opened" references have to be closed with a call to + their corresponding "close" call. This takes care of + freeing structure references obtained with "get" calls. + + +6.2 Utility Functions +--------------------- + +The library will provide a few utility functions for working with sysfs. + +------------------------------------------------------------------------------- +Name: sysfs_get_mnt_path + +Description: Function finds the mount path for filesystem type "sysfs". + +Arguments: char *mnt_path Mount path buffer + size_t len Size of mount path buffer + +Returns: Zero with success. + -1 with error. Errno will be set with error: + - EINVAL for invalid argument, if buffer is NULL or + if len is zero + +Prototype: sysfs_get_mnt_path(char *mnt_path, size_t len); +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_name_from_path + +Description: Function returns the last directory or file name from the + included path. + +Arguments: const char *path Path to parse name from + char *name Buffer to put parsed name into + size_t *len Size of name buffer + +Returns: 0 with success. + -1 on Error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_get_name_from_path(const char *path, + char *name, size_t *len) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_link + +Description: Sysfs readlink function, reads the link at supplied path + and returns its target path. + +Arguments: const char *path Link's path + char *target Buffer to place link's target + size_t len Size of target buffer + +Returns: 0 with success + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_get_link(const char *path, char *target, size_t len) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_subsystem_list + +Description: Function returns the list of entries for the given subsystem. If + the argument is "bus", this function will return a list of buses + ("pci", "scsi", etc) supported on the system. + + sysfs_close_list() has to be called to free the list obtained + from this call. + +Arguments: char *name Subsystem to open, like "bus".. + +Returns: dlist of entries for the subsystem on success + NULL with error indicating the "name" subsystem is invalid. + +Prototype: struct dlist *sysfs_open_subsystem_list(char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_bus_devices_list + +Description: Function returns the list of devices on the given bus. + + sysfs_close_list() has to be called to free the list obtained + from this call. + +Arguments: char *name Bus name to open "pci"/"scsi"/"usb".. + +Returns: dlist of device names for the given bus on success + NULL with error indicating the bus is not supported. + +Prototype: struct dlist *sysfs_open_bus_devices_list(char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_list + +Description: Closes a given dlist. This can be used as a generic list close + routine. + +Arguments: struct dlist *list List to be closed + +Prototype: void sysfs_close_list(struct dlist *list) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_path_is_dir + +Description: Utility function to verify if a given path is to a directory. + +Arguments: const char *path Path to verify + +Returns: 0 on success, 1 on error + - EINVAL for invalid arguments + +Prototype: int sysfs_path_is_dir(const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_path_is_file + +Description: Utility function to verify if a given path is to a file. + +Arguments: const char *path Path to verify + +Returns: 0 on success, 1 on error + - EINVAL for invalid arguments + +Prototype: int sysfs_path_is_file(const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_path_is_link + +Description: Utility function to verify if a given path is to a link. + +Arguments: const char *path Path to verify + +Returns: 0 on success, 1 on error + - EINVAL for invalid arguments + +Prototype: int sysfs_path_is_link(const char *path) +------------------------------------------------------------------------------- + + +6.3 Filesystem Functions +------------------------ + +Libsysfs provides a set of functions to open, read, and close directories +and attributes/files in sysfs. These functions mirror their filesystem +function counterparts. + + +6.3.1 Attribute Functions +------------------------- + +Along with the usual open, read, and close functions, libsysfs provides +a couple other functions for accessing attribute values. + +------------------------------------------------------------------------------- +Name: sysfs_open_attribute + +Description: Opens up a file in sysfs and creates a sysfs_attribute + structure. File isn't read with this function. + +Arguments: const char *path File/Attribute's path + +Returns: struct sysfs_attribute * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_open_attribute(const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_attribute + +Description: Cleans up and closes sysfs_attribute structure. + +Arguments: struct sysfs_attribute *sysattr Attribute to close + +Prototype: void sysfs_close_attribute(struct sysfs_attribute *sysattr) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_read_dir_attributes + +Description: Reads the given sysfs_directory to create a list of attributes. + +Arguments: struct sysfs_directory *sysdir sysfs_directory whose + attributes to read + +Returns: struct dlist * of attributes on success + NULL with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: struct dlist *sysfs_read_dir_attributes + (struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_dir_attributes + +Description: Given a list sysfs_directory, this function refreshes the list + of attributes for the given directory. + +Arguments: struct sysfs_directory *sysdir sysfs_ directory whose + attributes list to refresh + +Returns: 0 with success. + 1 with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: int sysfs_refresh_dir_attributes(struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_dir_attributes + +Description: Returns a list of attributes for the given sysfs_directory. + +Arguments: struct sysfs_directory *sysdir sysfs_directory whose + attributes list to return + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: struct dlist *sysfs_read_dir_attributes + (struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_read_attribute + +Description: Reads the supplied attribute. Since the maximum transfer + from a sysfs attribute is a pagesize, function reads in + up to a page from the file and stores it in the "value" + field in the attribute. + +Arguments: struct sysfs_attribute *sysattr Attribute to read + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_read_attribute(struct sysfs_attribute *sysattr) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_write_attribute + +Description: Writes to the supplied attribute. Function validates if the + given attribute is writable, and writes the new value to the + attribute. Value to write as well as its length is user + supplied. In case the length written is not equal to the + length requested to be written, the original value is + restored and an error is returned. + +Arguments: struct sysfs_attribute *sysattr Attribute to write to + const char *new_value sysattr's new value + size_t len Length of "new_value" + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_write_attribute(struct sysfs_attribute *sysattr, + const char *new_value, size_t len) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_read_attribute_value + +Description: Given a path to a specific attribute, function reads and + returns its value to the supplied value buffer. + +Arguments: const char *attrpath Attribute path to read + char *value Buffer to read in attribute's value + size_t vsize Size of buffer + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_read_attribute_value(const char *attrpath, + char *value, size_t vsize) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_value_from_attributes + +Description: Function takes a single or linked list of sysfs attribute + structures and returns the value of the specified attribute + name. + +Arguments: struct dlist *attr Attribute list to search through + const char *name Name of attribute whose value + to retrieve + +Returns: char * attribute value with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: char *sysfs_get_value_from_attributes + (struct sysfs_attribute *attr, const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_directory_attribute + +Description: Function walks the list of attributes for the given sysfs + directory and returns the sysfs_attribute structure for + the specified attribute name. + +Arguments: struct sysfs_directory *dir Directory in which to search + char *attrname Attribute name to look for + +Returns: struct sysfs_attribute on success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_get_directory_attribute + (struct sysfs_directory *dir, char *attrname) +------------------------------------------------------------------------------- + + +6.3.2 Link Functions +-------------------- + +Sysfs contains many symbolic links, like bus links to bus devices. Libsysfs +treats links differently than directories due to processing differences. A +link in the /sys/bus/"busname"/devices/ directory indicates a device in the +/sys/devices directory. Through links we give the functionality to know +what is and what isn't a link and the ability to query the links target. + +------------------------------------------------------------------------------- +Name: sysfs_open_link + +Description: Opens a directory link. + +Arguments: const char *linkpath Path to link + +Returns: struct sysfs_link * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_link *sysfs_open_link(const char *linkpath) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_link + +Description: Closes a directory link structure. + +Arguments: struct sysfs_link *ln Link to close + +Prototype: void sysfs_close_link(struct sysfs_link *ln) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_read_dir_links + +Description: Reads the given sysfs_directory to create a list of links. + +Arguments: struct sysfs_directory *sysdir sysfs_directory whose + links to read + +Returns: struct dlist * of links with success + NULL with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: struct dlist *sysfs_read_dir_links + (struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_dir_links + +Description: Returns a list of links for the given sysfs_directory. + +Arguments: struct sysfs_directory *sysdir sysfs_directory whose + list of links to return + +Returns: struct dlist * of links with success + NULL with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: struct dlist *sysfs_read_dir_links + (struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_directory_link + +Description: Function walks the list of links for the given sysfs directory + and returns the sysfs_link structure for the specified link + name. + +Arguments: struct sysfs_directory *dir Directory in which to search + char *linkname Link name to look for + +Returns: struct sysfs_link * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_link *sysfs_get_directory_link + (struct sysfs_directory *dir, char *linkname) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_subdirectory_link + +Description: Function walks the list of links for the given sysfs directory + and its subdirectories returns the sysfs_link structure for + the specified link name. + +Arguments: struct sysfs_directory *dir Directory in which to search + char *linkname Link name to look for + +Returns: struct sysfs_link * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_link *sysfs_get_subdirectory_link + (struct sysfs_directory *dir, char *linkname) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_dir_links + +Description: Given a list sysfs_directory, this function refreshes the list + of links under the given directory. + +Arguments: struct sysfs_directory *sysdir sysfs_ directory whose + links list to refresh + +Returns: 0 with success. + 1 with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: int sysfs_refresh_dir_links(struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + + +6.3.3 Directory Functions +------------------------- + +Sysfs directories can represent every directory under sysfs. The structures +keep track of subdirectories, links, and files. Like opendir, readdir, and +closedir, libsysfs provides open, read, and close functions for working with +sysfs directories. Open creates the sysfs_directory structure. Read reads in +its contents - like subdirectories, links, and files. Close cleans it all +up. + +------------------------------------------------------------------------------- +Name: sysfs_open_directory + +Description: Opens a sysfs directory at a specific path + +Arguments: const char *path Directory path to open + +Returns: struct sysfs_directory * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_directory *sysfs_open_directory(const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_directory + +Description: Closes specific directory, its subdirectories, links, and + files. + +Arguments: struct sysfs_directory *sysdir Directory to close + +Prototype: void sysfs_close_directory(struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_read_dir_subdirs + +Description: Reads the given sysfs_directory to create a list of subdirs. + +Arguments: struct sysfs_directory *sysdir sysfs_directory whose + subdirs have to be read + +Returns: struct dlist * of links with success + NULL with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: struct dlist *sysfs_read_dir_subdirs + (struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_read_directory + +Description: Read the supplied directory. Reading fills in the directory's + contents like subdirectories, links, and attributes. + +Arguments: struct sysfs_directory *sysdir Directory to read + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_read_directory(struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_read_all_subdirs + +Description: Reads all subdirs under a given supplied directory. + +Arguments: struct sysfs_directory *sysdir Directory to read + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_read_all_subdirs(struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_subdirectory + +Description: Function walks the directory tree for the given directory and + returns a sysfs_directory structure for the specified directory + name. + +Arguments: struct sysfs_directory *dir Directory in which to search + char *subname Name of directory to look for + +Returns: struct sysfs_directory with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_directory *sysfs_get_subdirectory + (struct sysfs_directory *dir, char *subname) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_dir_subdirs + +Description: Returns a list of subdirs for the given sysfs_directory. + +Arguments: struct sysfs_directory *sysdir sysfs_directory whose + subdirectories list to return + +Returns: struct dlist * of directories with success + NULL with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: struct dlist *sysfs_read_dir_subdirs + (struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_dir_subdirs + +Description: Given a list sysfs_directory, this function refreshes the list + of subdirectories under the given directory. + +Arguments: struct sysfs_directory *sysdir sysfs_ directory whose + subdirs list to refresh + +Returns: 0 with success. + 1 with error. Errno will be set on error, returning EINVAL + for invalid arguments + +Prototype: int sysfs_refresh_dir_subdirs(struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + + +6.4 Bus Functions +----------------- + +The library provides a functions for viewing buses represented in sysfs. +The sysfs_open_bus opens a bus in the /sys/bus directory, such as "pci", +"usb", or "scsi". The open command returns a sysfs_bus structure that +contains a list of the bus' devices. The sysfs_close_bus function is +used to clean up the bus structure. Given a device or a driver, +functions are provided to determine what bus they are on. + +------------------------------------------------------------------------------- +Name: sysfs_open_bus + +Description: Function opens up one of the buses represented in sysfs in + the /sys/bus directory. It returns a sysfs_bus structure + that includes a list of bus devices and drivers. + +Arguments: const char *name Bus name to open, like "pci"... + +Returns: struct sysfs_bus * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_bus *sysfs_open_bus(const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_bus + +Description: Function closes up the sysfs_bus structure including its + devices, drivers, and directory. + +Arguments: sysfs_bus *bus Bus structure to close + +Prototype: void sysfs_close_bus(struct sysfs_bus *bus) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_bus_devices + +Description: Function returns a list of devices that are registered with + this bus. + +Arguments: struct sysfs_bus *bus Bus whose devices list to return + +Returns: struct dlist * of sysfs_devices on success + NULL with error. Errno will be sent with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_bus_devices(struct sysfs_bus *bus) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_bus_drivers + +Description: Function returns a list of drivers that are registered with + this bus. + +Arguments: struct sysfs_bus *bus Bus whose drivers list to return + +Returns: struct dlist * of sysfs_drivers on success + NULL with error. Errno will be sent with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_bus_drivers(struct sysfs_bus *bus) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_bus_device + +Description: Function takes a sysfs_bus structure(obtained on a successful + return from a sysfs_open_bus() call) and looks for the given + device on this bus. On success, it returns a sysfs_device + structure corresponding to the device. + +Arguments: struct sysfs_bus *bus Bus structure on which to search + char *id Device to look for + +Returns: struct sysfs_device * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_get_bus_device + (struct sysfs_bus *bus, char *id) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_bus_driver + +Description: Function takes a sysfs_bus structure (obtained on a successful + return from a sysfs_open_bus() call) and looks for the given + driver on this bus. On success, it returns a sysfs_driver + structure corresponding to the driver. + +Arguments: struct sysfs_bus *bus Bus structure on which to search + char *drvname Driver to look for + +Returns: struct sysfs_driver * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_get_bus_driver + (struct sysfs_bus *bus, char *drvname) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_bus_attributes + +Description: Function takes a sysfs_bus structure and returns a list of + attributes for the bus. + +Arguments: struct sysfs_bus *bus Bus for which attributes are required + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_bus_attribute + +Description: Function takes a sysfs_bus structure and looks for the required + attribute on the bus. On success, it returns a sysfs_attribute + structure corresponding to the given attribute. + +Arguments: struct sysfs_bus *bus Bus structure on which to search + char *attrname Attribute to look for + +Returns: struct sysfs_attribute * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_get_bus_attribute + (struct sysfs_bus *bus, char *attrname) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_bus_attributes + +Description: Function refreshes the list of attributes for a given sysfs_bus + +Arguments: struct sysfs_bus *bus Bus whose attributes list to refresh + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_find_driver_bus + +Description: Given the name of a driver, this function finds the name of the + bus the driver is on + +Arguments: const char *driver Name of the driver to look for + char *busname Buffer to return the bus name + size_t bsize Size of the "busname" buffer + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_find_driver_bus(const char *driver, + char *busname, size_t bsize) +------------------------------------------------------------------------------- + + +6.5 Class Functions +------------------- + +Libsysfs provides functions to open sysfs classes and their class devices. +These functions too operate with open and close, close must be called to +clean up the class structures. Given a class device name, functions are +provided to determine what class they belong to. Once a class device +name and the class it belongs to is known, a function to open the +class device is provided. This method can be used when details of +a single class device is required. + +------------------------------------------------------------------------------- +Name: sysfs_open_class + +Description: Function opens up one of the classes represented in sysfs in + the /sys/class directory. It returns a sysfs_class structure + that includes a list of class devices. + +Arguments: const char *name Class name to open, like "net".. + +Returns: struct sysfs_class * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_class *sysfs_open_class(const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_class + +Description: Function closes up the sysfs_class structure including its + class devices. + +Arguments: sysfs_class *cls Class structure to close + +Prototype: void sysfs_close_class(struct sysfs_class *cls); +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_class_device_path + +Description: Function opens up one of the class devices represented in + sysfs in sysfs/class/"class"/ directory. It returns a + sysfs_class_device structure. + +Arguments: const char *path Path to class device + +Returns: struct sysfs_class_device * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_class_device *sysfs_open_class_device_path + (const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_class_device + +Description: Function closes up the sysfs_class_device structure. + +Arguments: sysfs_class_device *dev Class device structure to close + +Prototype: void sysfs_close_class_device(struct sysfs_class_device *dev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_class_device + +Description: Function takes a sysfs_class structure(obtained on a successful + return from a sysfs_open_class() call) and looks for the given + device in this class. On success, it returns a sysfs_class_device + structure corresponding to the class device. + +Arguments: struct sysfs_class *cls Class on which to search + char *name Class device "name" to look for + +Returns: struct sysfs_class_device * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_class_device *sysfs_get_class_device + (struct sysfs_class *cls, char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_class_devices + +Description: Function returns a list of class devices for the given class. + +Arguments: struct sysfs_class *cls Class whose class device list + is required + +Returns: struct dlist * of sysfs_class_devices on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_class_devices(struct sysfs_class *cls) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_class_device + +Description: Given the name of the class on which to look for, this function + locates a given class device and returns a sysfs_class_device + structure corresponding to the requested class device. + + NOTE: + 1. The sysfs_class_device structure obtained upon successful + return from this function has to be closed by calling + sysfs_close_class_device(). + 2. Class this device belongs to must be known prior to calling + this function. + +Arguments: const char *classname Class on which to search + char *name Class device "name" to open + +Returns: struct sysfs_class_device * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_class_device *sysfs_open_class_device + (const char *classname, char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_classdev_device + +Description: Function returns the sysfs_device reference (if present) for the + given class device. + +Arguments: struct sysfs_class_device *clsdev Class device whose + sysfs_device reference + is required + +Returns: struct sysfs_device * on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_get_classdev_device + (struct sysfs_class_device *clsdev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_classdev_driver + +Description: Function returns the sysfs_driver reference (if present) for + the given class device. + +Arguments: struct sysfs_class_device *clsdev Class device whose + sysfs_driver reference + is required + +Returns: struct sysfs_driver * on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_driver *sysfs_get_classdev_driver + (struct sysfs_class_device *clsdev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_classdev_parent + +Description: Function returns the sysfs_class_device reference for the + parent (if present) of the given class device. + +Arguments: struct sysfs_class_device *clsdev Class device whose + parent reference + is required + +Returns: struct sysfs_class_device * on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_class_device *sysfs_get_classdev_parent + (struct sysfs_class_device *clsdev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_classdev_attributes + +Description: Function takes a sysfs_class_device structure and returns a + list of attributes for the class device. + +Arguments: struct sysfs_class_device *cdev Class device for which + attributes are required + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_classdev_attributes + (struct sysfs_class_device *cdev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_classdev_attr + +Description: Searches supplied class device's attributes by name and returns + the attribute. + +Arguments: struct sysfs_class_device *clsdev Device to search + const char *name Attribute name to find + +Returns: struct sysfs_attribute * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_get_classdev_attr + (struct sysfs_class_device *clsdev, const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_classdev_attributes + +Description: Function refreshes the list of attributes for a given + sysfs_class_device. + +Arguments: struct sysfs_class_device *cdev Class device whose attributes + list to refresh + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_classdev_attributes + (struct sysfs_class_device *cdev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_classdev_attr + +Description: Function takes as arguments, a the name of the class, the class + device name and the name of the required attribute. + + NOTE: + 1. The struct sysfs_attribute * obtained upon successful + return from this function has to be closed by making + a call to sysfs_close_attribute() + +Arguments: char *classname Class name on which to search + char *dev Name of the class device + char *attrib Attribute to open + +Returns: struct sysfs_attribute * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_write_classdev_attr + (const char *classname, const char *dev, + const char *attrib) +------------------------------------------------------------------------------- + + +6.6 Device Functions +-------------------- + +Devices represent everything in sysfs under /sys/devices, which is a +hierarchical view of system devices. Besides the expected open and +close functions, libsysfs provides open and close functions for +root devices. These functions recursively open or close a device +and all of its children. + +------------------------------------------------------------------------------- +Name: sysfs_open_device_path + +Description: Opens up a device at a specific path. It opens the device's + directory, reads the directory, and returns a sysfs_device + structure. + +Arguments: const char *path Path to device + +Returns: struct sysfs_device * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_open_device_path(const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_device + +Description: Function closes up the sysfs_device structure. + +Arguments: sysfs_device *dev Device structure to close + +Prototype: void sysfs_close_device(struct sysfs_device *dev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_root_device + +Description: Function opens up one of the root devices represented in sysfs + in the /sys/devices directory. It returns a sysfs_root_device + structure that includes a list of devices in the tree. + +Arguments: const char *name Name of the root device to open + +Returns: struct sysfs_root_device * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_open_root_device(const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_root_device + +Description: Function closes up the sysfs_root_device structure including the + devices in the root device tree. + +Arguments: sysfs_device *root Root device structure to close + +Prototype: void sysfs_close_root_device(struct sysfs_root_device *root) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_device_tree + +Description: Function opens up the device tree at the specified path. + +Arguments: const char *path Path at which to open the device tree + +Returns: struct sysfs_device * with success + NULL with error, Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_open_device_tree(const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_device_tree + +Description: Function closes the device tree originating at the given + sysfs_device. + +Arguments: struct sysfs_device *devroot Device from which the device + tree has to be closed + +Prototype: void sysfs_close_device_tree(struct sysfs_device *devroot) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_device_parent + +Description: Function returns the sysfs_device reference for the parent + (if present) of the given sysfs_device. + +Arguments: struct sysfs_device *dev sysfs_device whose parent + reference is required + +Returns: struct sysfs_device * on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_get_device_parent + (struct sysfs_device *dev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_root_devices + +Description: Function returns a list of devices under the given root device. + +Arguments: struct sysfs_root_device *root sysfs_root_device whose devices + list is required + +Returns: struct dlist * of sysfs_devices on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_root_devices + (struct sysfs_root_device *root) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_device_attr + +Description: Searches supplied device's attributes by name and returns + the attribute. + +Arguments: struct sysfs_device *dev Device to search + const char *name Attribute name to find + +Returns: struct sysfs_attribute * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_get_device_attr + (struct sysfs_device *dev, const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_device_attributes + +Description: Function takes a sysfs_device structure and returns a list + of attributes for the device. + +Arguments: struct sysfs_device *device Device for which + attributes are required + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_device_attributes + (struct sysfs_device *device) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_device_attributes + +Description: Function refreshes the list of attributes for a given + sysfs_device. + +Arguments: struct sysfs_device *device Device whose attributes list + to refresh + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_refresh_device_attributes + (struct sysfs_device *device) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_device + +Description: Given the name of the bus on which to look for, this function + locates a given device and returns a sysfs_device structure + corresponding to the requested device. + +Arguments: const char *bus Bus on which to search + const char *bus_id Device to look for + +Returns: struct sysfs_device * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_device *sysfs_open_device + (const char *bus, const char *bus_id) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_device_bus + +Description: Given a sysfs_device, this function fills in the bus this + device is on in the sysfs_device->bus field. + +Arguments: struct sysfs_device *dev Device whose bus name to find + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_get_device_bus(struct sysfs_device *dev) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_device_attr + +Description: Function takes as arguments, the bus on which to search for a + device, and an attribute of the device to open. + + NOTE: + 1. The struct sysfs_attribute * obtained upon successful + return from this function has to be closed by making + a call to sysfs_close_attribute() + +Arguments: char *bus Bus on which to search + char *bus_id Device to look for + char *attrib Name of the attribute to open + +Returns: struct sysfs_attribute * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_open_device_attr + (const char *bus, const char *bus_id, const char *attrib) +------------------------------------------------------------------------------- + + +6.7 Driver Functions +-------------------- + +Drivers are represented in sysfs under the /sys/bus/xxx/drivers (xxx being +the bus type, such as "pci", "usb, and so on). Functions are provided to +open and close drivers. + +------------------------------------------------------------------------------- +Name: sysfs_open_driver_path + +Description: Opens driver at specific path. + +Arguments: const char *path Path to driver + +Returns: struct sysfs_driver * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_driver *sysfs_open_driver_path(const char *path) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_close_driver + +Description: Closes and cleans up sysfs_driver structure. + +Arguments: sysfs_driver *driver Driver structure to close + +Prototype: void sysfs_close_driver(struct sysfs_driver *driver) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_driver_devices + +Description: Function returns a list of devices that use this driver. + +Arguments: struct sysfs_driver *driver Driver whose devices list is + required + +Returns: struct dlist * of sysfs_devices on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_driver_devices + (struct sysfs_driver *driver) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_driver_devices + +Description: Function refreshes the list of devices that use this driver. + +Arguments: struct sysfs_driver *driver Driver whose devices list is + required to be refreshed + +Returns: struct dlist * of sysfs_devices on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_refresh_driver_devices + (struct sysfs_driver *driver) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_driver_device + +Description: Function returns a sysfs_device reference for the device with + "name" that uses this driver + +Arguments: struct sysfs_driver *driver Driver on which to search + const char *name Name of the device to look for + +Returns: struct sysfs_device * corresponding to "name" on success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_driver_device + (struct sysfs_driver *driver, const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_driver_attr + +Description: Searches supplied driver's attributes by name and returns + the attribute. + +Arguments: struct sysfs_driver *drv Driver to search + const char *name Attribute name to find + +Returns: struct sysfs_attribute * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_get_driver_attr + (struct sysfs_driver *drv, const char *name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_driver_attributes + +Description: Function takes a sysfs_driver structure and returns a list + of attributes for the driver. + +Arguments: struct sysfs_driver *driver Driver for which attributes + are required + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_get_driver_attributes + (struct sysfs_driver *driver) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_refresh_driver_attributes + +Description: Function refreshes the list of attributes for a given + sysfs_driver. + +Arguments: struct sysfs_driver *driver Driver whose attributes list + to refresh + +Returns: struct dlist * of attributes with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct dlist *sysfs_refresh_driver_attributes + (struct sysfs_driver *driver) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_driver + +Description: Given the name of the bus on which to look for, this function + locates a given driver and returns a sysfs_driver structure + corresponding to the requested device. + + NOTE: + 1. The sysfs_driver structure obtained upon successful return + from this function has to be closed by calling + sysfs_close_driver_by_name(). + 2. Bus on which to look for this driver should be known prior + to calling this function. Use sysfs_find_driver_bus() + to determine this. + +Arguments: const char *bus_name Bus on which to search + const char *drv_name Driver name to look for + +Returns: struct sysfs_driver * with success + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_driver *sysfs_open_driver(const char *bus_name, + const char *drv_name) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_get_driver_links + +Description: Function returns a list of links for a given driver + +Arguments: struct sysfs_driver *driver Driver to get links from + +Returns: struct dlist * of links on success + NULL with error + +Prototype: struct dlist *sysfs_get_driver_links + (struct sysfs_driver *driver) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +Name: sysfs_open_driver_attr + +Description: Function takes as arguments, the bus the driver is registered + on, the driver name and the name of the attribute to open. + + NOTE: + 1. The struct sysfs_attribute * obtained upon successful + return from this function has to be closed by making + a call to sysfs_close_attribute() + +Arguments: char *bus Bus on which driver is present + char *drv Driver to look for + char *attrib Name of the attribute to open + +Returns: struct sysfs_attribute * with success. + NULL with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: struct sysfs_attribute *sysfs_open_driver_attr + (const char *bus, const char *drv, const char *attrib) +------------------------------------------------------------------------------- + + +7 Dlists +-------- + +Libsysfs uses (yet another) list implementation thanks to Eric J Bohm. + + +7.1 Navigating a dlist +---------------------- + +Some library functions return a dlist of devices/drivers/attributes, etc. +To navigate the list returned the macro "dlist_for_each_data" is to be used. + +------------------------------------------------------------------------------ +Function/Macro name: dlist_for_each_data + +Description: Walk the given list, returning a known data type/ + structure in each iteration. + +Arguments: struct dlist *list List pointer + data_iterator Data type/structure variable + contained in the list + datatype Data type/structure contained + in the list + +Returns: On each iteration, "data_iterator" will contain a list + element of "datatype" + +Usage example: The function sysfs_get_classdev_attributes() returns a + dlist of attributes. To navigate the list: + + struct sysfs_attribute *attr = NULL; + struct dlist *attrlist = NULL; + . + . + . + attrlist = sysfs_get_classdev_attributes + (struct sysfs_class_device *cdev) + if (attrlist != NULL) { + dlist_for_each_data(attrlist, attr, + struct sysfs_attribute) { + . + . + . + } + } +------------------------------------------------------------------------------- + + +7.2 Custom sorting using dlist_sort_custom() +-------------------------------------------- + +As of release 1.2.0, libsysfs provides a new interface for custom sorting +of dlists. The API dlist_sort_custom() has been added for this purpose. +Applications that would like to define their own sorter function can now +make use of this API. + +The sorter function must conform to the following prototype: + + int compare(void *a, void*b) + +dlist_sort_custom() expects that the compare function will: + return >0 for a before b + return <0 for b before a + return 0 for a == b + + +8. Usage +-------- + +Accessing devices through libsysfs is supposed to mirror accessing devices +in the filesystem it represents. Here's a typical order of operation: + + - get sysfs mount point + - "open" sysfs category, ie. bus, class, or device + - work with category + - "close" sysfs category + + +9. Testsuite +------------ + +Version 1.0.0 of sysfsutils ships with a comprehensive testsuite. The testsuite +shipped as part of the "test" directory of the sysfsutils source package, +results in an executable "testlibsysfs" which will be installed in the +/usr/local/bin directory. Some of the salient features of the testsuite are: + +a. Tests _every_ API exported by the library. +b. Tests are performed for all possible combinations of input parameters. +c. Detailed output is provided for the correct case. +d. Facility to redirect output of the tests to a normal file. +e. Number of iterations of tests can be specified. + +The testsuite comes with its own configuration file "libsysfs.conf" in the +"test" directory. This file is used to generate a header file at the time +the tests are built. + +To use the testsuite: + +a. Modify the variables libsysfs.conf file to appropriate values for your + system. (The libsysfs.conf file contains comments describing what each + variable stands for and, in some cases, how to determine an appropriate + value for the system under test). + +b. Build and install the testsuite. + +c. Run the testsuite: + + testlibsysfs <number of iterations> <logfile> + +The default logfile is stdout. + +NOTE: If the libsysfs.conf file is changed, make sure to run "make clean" in +the test directory and then a "make" for the changes to take effect. + + +10. Conclusion +-------------- + +Libsysfs is meant to provide a stable application programming interface to +sysfs. Applications can depend upon the library to access system devices +and functions exposed through sysfs. |