docs: filesystems: convert sysfs.txt to ReST

- Add a SPDX header;
- Add a document title;
- Adjust document and section titles;
- use :field: markup;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/5c480dcb467315b5df6e25372a65e473b585c36d.1581955849.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/filesystems/index.rst

@@ -87,5 +87,6 @@ Documentation for filesystem implementations.
    relay
    romfs
    squashfs
+   sysfs
    virtiofs
    vfat

Documentation/filesystems/sysfs.txt → Documentation/filesystems/sysfs.rst

+.. SPDX-License-Identifier: GPL-2.0
 
-sysfs - _The_ filesystem for exporting kernel objects. 
+=====================================================
+sysfs - _The_ filesystem for exporting kernel objects
+=====================================================
 
 Patrick Mochel	<mochel@osdl.org>
+
 Mike Murphy <mamurph@cs.clemson.edu>
 
-Revised:    16 August 2011
-Original:   10 January 2003
+:Revised:    16 August 2011
+:Original:   10 January 2003
 
 
 What it is:
@@ -24,7 +28,7 @@ Using sysfs
 ~~~~~~~~~~~
 
 sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
-it by doing:
+it by doing::
 
     mount -t sysfs sysfs /sys
 
@@ -65,17 +69,17 @@ formatting of data is heavily frowned upon. Doing these things may get
 you publicly humiliated and your code rewritten without notice.
 
 
-An attribute definition is simply:
+An attribute definition is simply::
 
-struct attribute {
+    struct attribute {
 	    char                    * name;
 	    struct module		*owner;
 	    umode_t                 mode;
-};
+    };
 
 
-int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
-void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
+    int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
+    void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
 
 
 A bare attribute contains no means to read or write the value of the
@@ -83,38 +87,38 @@ attribute. Subsystems are encouraged to define their own attribute
 structure and wrapper functions for adding and removing attributes for
 a specific object type.
 
-For example, the driver model defines struct device_attribute like:
+For example, the driver model defines struct device_attribute like::
 
-struct device_attribute {
+    struct device_attribute {
 	    struct attribute	attr;
 	    ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 			    char *buf);
 	    ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 			    const char *buf, size_t count);
-};
+    };
 
-int device_create_file(struct device *, const struct device_attribute *);
-void device_remove_file(struct device *, const struct device_attribute *);
+    int device_create_file(struct device *, const struct device_attribute *);
+    void device_remove_file(struct device *, const struct device_attribute *);
 
-It also defines this helper for defining device attributes: 
+It also defines this helper for defining device attributes::
 
-#define DEVICE_ATTR(_name, _mode, _show, _store) \
-struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
+    #define DEVICE_ATTR(_name, _mode, _show, _store) \
+    struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
 
-For example, declaring
+For example, declaring::
 
-static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
+    static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
 
-is equivalent to doing:
+is equivalent to doing::
 
-static struct device_attribute dev_attr_foo = {
+    static struct device_attribute dev_attr_foo = {
 	    .attr = {
 		    .name = "foo",
 		    .mode = S_IWUSR | S_IRUGO,
 	    },
 	    .show = show_foo,
 	    .store = store_foo,
-};
+    };
 
 Note as stated in include/linux/kernel.h "OTHER_WRITABLE?  Generally
 considered a bad idea." so trying to set a sysfs file writable for
@@ -127,15 +131,21 @@ readable. The above case could be shortened to:
 static struct device_attribute dev_attr_foo = __ATTR_RW(foo);
 
 the list of helpers available to define your wrapper function is:
-__ATTR_RO(name): assumes default name_show and mode 0444
-__ATTR_WO(name): assumes a name_store only and is restricted to mode
+
+__ATTR_RO(name):
+		 assumes default name_show and mode 0444
+__ATTR_WO(name):
+		 assumes a name_store only and is restricted to mode
                  0200 that is root write access only.
-__ATTR_RO_MODE(name, mode): fore more restrictive RO access currently
+__ATTR_RO_MODE(name, mode):
+	         fore more restrictive RO access currently
                  only use case is the EFI System Resource Table
                  (see drivers/firmware/efi/esrt.c)
-__ATTR_RW(name): assumes default name_show, name_store and setting
+__ATTR_RW(name):
+	         assumes default name_show, name_store and setting
                  mode to 0644.
-__ATTR_NULL: which sets the name to NULL and is used as end of list
+__ATTR_NULL:
+	         which sets the name to NULL and is used as end of list
                  indicator (see: kernel/workqueue.c)
 
 Subsystem-Specific Callbacks
@@ -143,12 +153,12 @@ Subsystem-Specific Callbacks
 
 When a subsystem defines a new attribute type, it must implement a
 set of sysfs operations for forwarding read and write calls to the
-show and store methods of the attribute owners. 
+show and store methods of the attribute owners::
 
-struct sysfs_ops {
+    struct sysfs_ops {
 	    ssize_t (*show)(struct kobject *, struct attribute *, char *);
 	    ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
-};
+    };
 
 [ Subsystems should have already defined a struct kobj_type as a
 descriptor for this type, which is where the sysfs_ops pointer is
@@ -160,14 +170,14 @@ and struct attribute pointers to the appropriate pointer types, and
 calls the associated methods.
 
 
-To illustrate:
+To illustrate::
 
-#define to_dev(obj) container_of(obj, struct device, kobj)
-#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
+    #define to_dev(obj) container_of(obj, struct device, kobj)
+    #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
 
-static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
+    static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
 				char *buf)
-{
+    {
 	    struct device_attribute *dev_attr = to_dev_attr(attr);
 	    struct device *dev = to_dev(kobj);
 	    ssize_t ret = -EIO;
@@ -179,7 +189,7 @@ static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
 				    dev_attr->show);
 	    }
 	    return ret;
-}
+    }
 
 
 
@@ -188,10 +198,10 @@ Reading/Writing Attribute Data
 
 To read or write attributes, show() or store() methods must be
 specified when declaring the attribute. The method types should be as
-simple as those defined for device attributes:
+simple as those defined for device attributes::
 
-ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
-ssize_t (*store)(struct device *dev, struct device_attribute *attr,
+    ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
+    ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 		    const char *buf, size_t count);
 
 IOW, they should take only an object, an attribute, and a buffer as parameters.
@@ -251,23 +261,23 @@ Other notes:
   sure to have a way to check this, if necessary.
 
 
-A very simple (and naive) implementation of a device attribute is:
+A very simple (and naive) implementation of a device attribute is::
 
-static ssize_t show_name(struct device *dev, struct device_attribute *attr,
+    static ssize_t show_name(struct device *dev, struct device_attribute *attr,
 			    char *buf)
-{
+    {
 	    return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
-}
+    }
 
-static ssize_t store_name(struct device *dev, struct device_attribute *attr,
+    static ssize_t store_name(struct device *dev, struct device_attribute *attr,
 			    const char *buf, size_t count)
-{
+    {
 	    snprintf(dev->name, sizeof(dev->name), "%.*s",
 		    (int)min(count, sizeof(dev->name) - 1), buf);
 	    return count;
-}
+    }
 
-static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
+    static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
 
 
 (Note that the real implementation doesn't allow userspace to set the
@@ -280,23 +290,23 @@ Top Level Directory Layout
 The sysfs directory arrangement exposes the relationship of kernel
 data structures.
 
-The top level sysfs directory looks like:
+The top level sysfs directory looks like::
 
-block/
-bus/
-class/
-dev/
-devices/
-firmware/
-net/
-fs/
+    block/
+    bus/
+    class/
+    dev/
+    devices/
+    firmware/
+    net/
+    fs/
 
 devices/ contains a filesystem representation of the device tree. It maps
 directly to the internal kernel device tree, which is a hierarchy of
 struct device.
 
 bus/ contains flat directory layout of the various bus types in the
-kernel. Each bus's directory contains two subdirectories:
+kernel. Each bus's directory contains two subdirectories::
 
 	devices/
 	drivers/
@@ -331,71 +341,71 @@ Current Interfaces
 The following interface layers currently exist in sysfs:
 
 
-- devices (include/linux/device.h)
-----------------------------------
-Structure:
+devices (include/linux/device.h)
+--------------------------------
+Structure::
 
-struct device_attribute {
+    struct device_attribute {
 	    struct attribute	attr;
 	    ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 			    char *buf);
 	    ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 			    const char *buf, size_t count);
-};
+    };
 
-Declaring:
+Declaring::
 
-DEVICE_ATTR(_name, _mode, _show, _store);
+    DEVICE_ATTR(_name, _mode, _show, _store);
 
-Creation/Removal:
+Creation/Removal::
 
-int device_create_file(struct device *dev, const struct device_attribute * attr);
-void device_remove_file(struct device *dev, const struct device_attribute * attr);
+    int device_create_file(struct device *dev, const struct device_attribute * attr);
+    void device_remove_file(struct device *dev, const struct device_attribute * attr);
 
 
-- bus drivers (include/linux/device.h)
---------------------------------------
-Structure:
+bus drivers (include/linux/device.h)
+------------------------------------
+Structure::
 
-struct bus_attribute {
+    struct bus_attribute {
 	    struct attribute        attr;
 	    ssize_t (*show)(struct bus_type *, char * buf);
 	    ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
-};
+    };
 
-Declaring:
+Declaring::
 
-static BUS_ATTR_RW(name);
-static BUS_ATTR_RO(name);
-static BUS_ATTR_WO(name);
+    static BUS_ATTR_RW(name);
+    static BUS_ATTR_RO(name);
+    static BUS_ATTR_WO(name);
 
-Creation/Removal:
+Creation/Removal::
 
-int bus_create_file(struct bus_type *, struct bus_attribute *);
-void bus_remove_file(struct bus_type *, struct bus_attribute *);
+    int bus_create_file(struct bus_type *, struct bus_attribute *);
+    void bus_remove_file(struct bus_type *, struct bus_attribute *);
 
 
-- device drivers (include/linux/device.h)
------------------------------------------
+device drivers (include/linux/device.h)
+---------------------------------------
 
-Structure:
+Structure::
 
-struct driver_attribute {
+    struct driver_attribute {
 	    struct attribute        attr;
 	    ssize_t (*show)(struct device_driver *, char * buf);
 	    ssize_t (*store)(struct device_driver *, const char * buf,
 			    size_t count);
-};
+    };
 
-Declaring:
+Declaring::
 
-DRIVER_ATTR_RO(_name)
-DRIVER_ATTR_RW(_name)
+    DRIVER_ATTR_RO(_name)
+    DRIVER_ATTR_RW(_name)
 
-Creation/Removal:
+Creation/Removal::
 
-int driver_create_file(struct device_driver *, const struct driver_attribute *);
-void driver_remove_file(struct device_driver *, const struct driver_attribute *);
+    int driver_create_file(struct device_driver *, const struct driver_attribute *);
+    void driver_remove_file(struct device_driver *, const struct driver_attribute *);
 
 
 Documentation