summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormananth <mananth>2003-08-29 11:36:20 +0000
committermananth <mananth>2003-08-29 11:36:20 +0000
commit03fe4dcdc8b3e69ca7853474d4c812b36a187431 (patch)
treed0a62a7bb00795cb61265c969809e2c5ad69433a
parent293fac7445f27c20ee3f2b7d3d2b6f183a0d2656 (diff)
downloadsysfsutils-03fe4dcdc8b3e69ca7853474d4c812b36a187431.tar.gz
Removed "bus_name" from sysfs_device.
Updated docs/libsysfs.txt, TODO, NEWS files
-rw-r--r--ChangeLog4
-rw-r--r--NEWS11
-rw-r--r--TODO23
-rw-r--r--docs/libsysfs.txt281
-rw-r--r--include/libsysfs.h1
-rw-r--r--lib/sysfs_device.c1
6 files changed, 201 insertions, 120 deletions
diff --git a/ChangeLog b/ChangeLog
index 6b5917a..6c8c26d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,8 @@
+08/29/2003 - Ananth Mavinakayanahalli <ananth@in.ibm.com>
+ * Removed "bus_name" from struct sysfs_device
+ * Updated NEWS, TODO and docs/libsysfs.txt files
+
08/28/2003 - Ananth Mavinakayanahalli <ananth@in.ibm.com>
* Added more utility functions to sysfsutils
* Modified commands to make use of the new functions
diff --git a/NEWS b/NEWS
index c0cafb5..f8ba2c5 100644
--- a/NEWS
+++ b/NEWS
@@ -1,8 +1,15 @@
Version History:
---------------
- 0.2.0 - Current Development Branch
- * ADded autoconf configuration support
+ 0.2.0 - Released August 28, 2003
+ * Added autoconf configuration support.
+ * Added Eric J Bohm's dlist patch.
+ * Changed the library structures and routines to use dlists.
+ * Added Guo Min's sysfs_write_attribute patch
+ * Added sysfs_root_device for use with /sys/devices subsystem
+ * Added lots of "find"/utility functions.
+ * Modified commands to make use of new API.
+ * Added functions to get lists of specific subsystems.
0.1.1 - Released August 1, 2003
* Created NEWS file for Version History.
diff --git a/TODO b/TODO
index 9f32242..89522c8 100644
--- a/TODO
+++ b/TODO
@@ -1,14 +1,10 @@
Library:
--------
-- Implement a better device tree, so we can eventually walk the tree.
-- Add write attribute write commands:
- sysfs_write_attribute()
- sysfs_write_attribute_value()
-- Possibly add abstract data list to make device tree easier and to
- give calling applications a means to easily manage large lists
- of devices.
- Make bus lists of devices using topology.
+- Rework debugging error messages and look into better logging on error.
- Need to properly set errno.
+- Add more "find"/utility functions.
+- Add subsystem specific support for PCI, SCSI, USB, etc
Commands:
---------
@@ -16,3 +12,16 @@ Commands:
- Add topology tree view.
- Need to clean up error messages.
- Clean up how attribute values are printed.
+- Add capability to use of attribute "write" functions.
+- Use sysfs_root_device as the base structure for listing from the
+ devices subsystem.
+- Add subsystem specific support. Commands can, for example, do PCI id lookup.
+
+Docs:
+-----
+- Update libsysfs.txt with changes/additions to the library.
+- Create man pages for commands and for library.
+
+Test:
+-----
+- Design and implement test suites for the library.
diff --git a/docs/libsysfs.txt b/docs/libsysfs.txt
index c38d74d..6415373 100644
--- a/docs/libsysfs.txt
+++ b/docs/libsysfs.txt
@@ -2,8 +2,8 @@
System Utilities sysfs Library - libsysfs
=========================================
-Version: 0.1.0
-June 30, 2003
+Version: 0.2.0
+August 29, 2003
Contents
--------
@@ -18,8 +18,9 @@ Contents
5.1.3 Directory Structure
5.2 Bus Data Structure
5.3 Class Data Structures
- 5.4 Device Data Structure
- 5.5 Driver Data Structure
+ 5.4 Root Device Data Structure
+ 5.5 Device Data Structure
+ 5.6 Driver Data Structure
6. Functions
6.1 Utility Functions
6.2 Filesystem Functions
@@ -157,16 +158,17 @@ 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 {
- struct sysfs_attribute *next;
- char path[SYSFS_PATH_MAX];
- char *value;
- int method; /* show and store */
+ unsigned char *value;
+ unsigned short len; /* value length */
+ unsigned short method; /* show and store */
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
};
-The library links attributes together using the "next" pointer. Path
-represents the file/attribute's full path. Value is used when reading
-from or writing to an attribute. Method is a bitmask for defining if
-the attribute supports show(read) and/or store(write).
+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
@@ -176,13 +178,13 @@ Symbolic links are used in sysfs to link bus or class views with
particular devices.
struct sysfs_link {
- struct sysfs_link *next;
- char name[SYSFS_NAME_LEN];
- char target[SYSFS_NAME_LEN];
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
+ unsigned char target[SYSFS_PATH_MAX];
};
-The "next" pointer is for linking links together. Link's name is stored
-in name and it's target stored in target.
+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
@@ -191,16 +193,18 @@ in name and it's target stored in target.
The directory structure represents a sysfs directory:
struct sysfs_directory {
- struct sysfs_directory *next;
- char path[SYSFS_PATH_MAX];
- struct sysfs_directory *subdirs;
- struct sysfs_link *links;
- struct sysfs_attribute *attributes;
+ struct dlist *subdirs;
+ struct dlist *links;
+ struct dlist *attributes;
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
};
-The directory structure includes a "next" pointer for linking directories
-together. It also includes the directory's full path and links to
-subdirectories, links, and 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
@@ -210,19 +214,26 @@ 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 {
- struct sysfs_bus *next;
- char name[SYSFS_NAME_LEN];
+ struct dlist *drivers;
+ struct dlist *devices;
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
+
+ /* internal use only */
struct sysfs_directory *directory;
- struct sysfs_driver *drivers;
- struct sysfs_device *devices;
};
-The "next" pointer, as with other structures, is used for linking buses
-together. The bus name, like "pci" or "usb", is stored in the name field.
-The bus' directory is represented by the sysfs_directory structure and
-it contains references to all the subdirectories, links, and attributes
-associated with the bus. Finally, the bus contains lists of those
-devices on the bus and their drivers.
+The sysfs_bus structure contains lists of those devices on the bus and their
+drivers. The bus name, like "pci" or "usb", is stored in the name field, while
+the "path" to bus directory is also stored. 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,
+ unsigned char *attrname)
5.3 Class Data Structures
@@ -233,67 +244,111 @@ 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 {
- struct sysfs_class *next;
- char name[SYSFS_NAME_LEN];
+ struct dlist *devices;
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
+
+ /* for internal use only */
struct sysfs_directory *directory;
- struct sysfs_class_device *devices;
};
-The sysfs_class represents device classes in sysfs like "net". It contains
-a "next" pointer for list management, the class name, and the directory
-representation. Finally, it contains a linked list of class devices.
+The sysfs_class represents device classes in sysfs like "net". It contains a
+list of class devices, the class name, "path" to the class and the directory
+representation (for internal use only).
struct sysfs_class_device {
- struct sysfs_class_device *next;
- char name[SYSFS_NAME_LEN];
- struct sysfs_directory *directory;
struct sysfs_device *sysdevice; /* NULL if virtual */
struct sysfs_driver *driver; /* NULL if not implemented */
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
+
+ /* for internal use only */
+ 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 a "next"
-pointer for list management, the name of the class device - like "eth0",
-its sysfs directory information including links and attributes, and
-finally the sysfs_device reference and that device's driver reference.
+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 sysfs_device
+reference and that device's driver reference (if any). It also contains
+the name of the class device - like "eth0", 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 heirarchies 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 {
+ struct dlist *devices;
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
-5.4 Device Data Structure
+ /* for internal use only */
+ 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 {
- struct sysfs_device *next;
- char name[SYSFS_NAME_LEN];
- char bus_id[SYSFS_NAME_LEN];
- struct sysfs_driver *driver;
+ struct sysfs_device *parent;
+ struct dlist *children;
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char bus_id[SYSFS_NAME_LEN];
+ unsigned char driver_name[SYSFS_NAME_LEN];
+
+ /* for internal use only */
struct sysfs_directory *directory;
- struct sysfs_device *children;
};
-The sysfs_device structure contains a "next" pointer for linking a list
-of devices together, its name as read from the "name" attribute in the
-device's directory, its bus id - which is the name of device's directory,
-and a reference to its driver. The device structure also contains a
-directory structure, which contains a list of the device's attributes,
-and a list of its child devices, if it has any.
+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, and a its driver name. The device structure also
+contains 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 unsigned char *name)
+struct dlist *sysfs_get_device_attributes(struct sysfs_device *device)
-5.5 Driver Data Structure
+5.6 Driver Data Structure
-------------------------
The sysfs_driver structure represents a device driver.
struct sysfs_driver {
- struct sysfs_driver *next;
- char name[SYSFS_NAME_LEN];
+ struct dlist *devices;
+ unsigned char name[SYSFS_NAME_LEN];
+ unsigned char path[SYSFS_PATH_MAX];
+
+ /* for internal use only */
struct sysfs_directory *directory;
};
-It contains a "next" pointer, the name of the driver, and its directory
-information, which includes the driver's attributes.
+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
@@ -315,14 +370,14 @@ Name: sysfs_get_mnt_path
Description: Function finds the mount path for filesystem type "sysfs".
-Arguments: chat *mnt_path Mount path buffer
- size_t len Size of mount path buffer
+Arguments: unsigned 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.
-Prototype: sysfs_get_mnt_path(char *mnt_path, size_t len);
+Prototype: sysfs_get_mnt_path(unsigned char *mnt_path, size_t len);
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -331,16 +386,16 @@ Name: sysfs_get_name_from_path
Description: Function returns the last directory or file name from the
included path.
-Arguments: char *path Path to parse name from
- char *name Buffer to put parsed name into
- size_t *len Size of name buffer
+Arguments: const unsigned char *path Path to parse name from
+ unsigned 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(char *path, char *name,
- size_t *len)
+Prototype: int sysfs_get_name_from_path(const unsigned char *path,
+ unsigned char *name, size_t *len)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -349,15 +404,16 @@ Name: sysfs_get_link
Description: Sysfs realink 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 path
- size_t len Size of target buffer
+Arguments: const unsigned char *path Link's path
+ unsigned char *target Buffer to place link's target path
+ 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)
+Prototype: int sysfs_get_link(const unsigned char *path,
+ unsigned char *target, size_t len)
-------------------------------------------------------------------------------
@@ -382,13 +438,14 @@ 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: char *path File/Attribute's path
+Arguments: const unsigned 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(char *path)
+Prototype: struct sysfs_attribute *sysfs_open_attribute
+ (const unsigned char *path)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -424,16 +481,16 @@ 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: char *attrpath Attribute path to read
- char *value Buffer to place attribute's value
- size_t vsize Size of buffer
+Arguments: const unsigned char *attrpath Attribute path to read
+ unsigned char *value Buffer to place 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(char *attrpath, char *value,
- size_t vsize)
+Prototype: int sysfs_read_attribute_value(const unsigned char *attrpath,
+ unsigned char *value, size_t vsize)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -444,15 +501,15 @@ Description: Function takes a single or linked list of sysfs attribute
name.
Arguments: struct sysfs_attribute *attr
- Attribute list to search through
- char *name Name of attribute to return value
+ Attribute list to search through
+ const unsigned char *name Name of attribute to return value
-Returns: char * attribute value with success.
+Returns: unsigned 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, char * name)
+Prototype: unsigned char *sysfs_get_value_from_attributes
+ (struct sysfs_attribute *attr, const unsigned char * name)
-------------------------------------------------------------------------------
@@ -470,13 +527,14 @@ Name: sysfs_open_link
Description: Opens a directory link.
-Arguments: char *linkpath Path to link
+Arguments: const unsigned 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(char *linkpath)
+Prototype: struct sysfs_link *sysfs_open_link
+ (const unsigned char *linkpath)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -505,13 +563,14 @@ Name: sysfs_open_directory
Description: Opens a sysfs directory at a specific path
-Arguments: char *path Directory path to open
+Arguments: const unsigned 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(char *path)
+Prototype: struct sysfs_directory *sysfs_open_directory
+ (const unsigned char *path)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -557,13 +616,13 @@ 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: char *name Bus name to open, like "pci"....
+Arguments: const unsigned 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(char *name)
+Prototype: struct sysfs_bus *sysfs_open_bus(const unsigned char *name)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -592,13 +651,13 @@ 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: char *name Class name to open, like "net"....
+Arguments: const unsigned 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(char *name)
+Prototype: struct sysfs_class *sysfs_open_class(const unsigned char *name)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -619,13 +678,14 @@ Description: Function opens up one of the class devices represented in
sysfs in sysfs/class/"class"/ directory. It retunrs a
sysfs_class_device structure.
-Arguments: char *path Path to class device
+Arguments: const unsigned 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(char *path)
+Prototype: struct sysfs_class_device *sysfs_open_class_device
+ (const unsigned char *path)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -655,13 +715,14 @@ 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: char *path Path to device
+Arguments: const unsigned 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(char *path)
+Prototype: struct sysfs_device *sysfs_open_device
+ (const unsigned char *path)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -669,7 +730,7 @@ Name: sysfs_close_device
Description: Function closes up the sysfs_device structure.
-Arguments: sysfs_device *dev Device structure to close
+Arguments: sysfs_device *dev Device structure to close
Prototype: void sysfs_close_device(struct sysfs_device *dev)
-------------------------------------------------------------------------------
@@ -681,13 +742,14 @@ Description: Same as sysfs_open_device except it recursively opens
children devices and adds them to the tree. Returns root
tree.
-Arguments: char *path Path to device
+Arguments: const unsigned 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_tree(char *path)
+Prototype: struct sysfs_device *sysfs_open_device_tree
+ (const unsigned char *path)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
@@ -708,14 +770,14 @@ Description: Searches supplied device's attributes by name and returns
the attribute.
Arguments: struct sysfs_device *dev Device to search
- char *name Attribute name to find
+ const unsigned 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, char *name)
+ (struct sysfs_device *dev, const unsigned char *name)
-------------------------------------------------------------------------------
@@ -729,13 +791,14 @@ Name: sysfs_open_driver
Description: Opens driver at specific path.
-Arguments: char *path Path to driver
+Arguments: const unsigned 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(char *path)
+Prototype: struct sysfs_driver *sysfs_open_driver
+ (const unsigned char *path)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
diff --git a/include/libsysfs.h b/include/libsysfs.h
index 9a3eb66..8a0fb4d 100644
--- a/include/libsysfs.h
+++ b/include/libsysfs.h
@@ -83,7 +83,6 @@ struct sysfs_device {
struct dlist *children;
unsigned char name[SYSFS_NAME_LEN];
unsigned char bus_id[SYSFS_NAME_LEN];
- unsigned char bus_name[SYSFS_NAME_LEN];
unsigned char driver_name[SYSFS_NAME_LEN];
/* for internal use only */
diff --git a/lib/sysfs_device.c b/lib/sysfs_device.c
index 7e18e23..593dbf9 100644
--- a/lib/sysfs_device.c
+++ b/lib/sysfs_device.c
@@ -126,7 +126,6 @@ struct sysfs_device *sysfs_open_device(const unsigned char *path)
}
dev->directory = sdir;
strcpy(dev->bus_id, sdir->name);
- sysfs_find_device_bus_name(dev->bus_id, dev->bus_name, SYSFS_NAME_LEN);
/* get device name */
p = sysfs_get_value_from_attributes(sdir->attributes,