Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/s390/linux

[firefly-linux-kernel-4.4.55.git] / Documentation / blockdev / zram.txt

diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.txt
index 971765ed5ac13b70f3b7e81154a0749debb56b09..c4de576093affed9a5877bfb484c75c67246ab96 100644 (file)
--- a/Documentation/blockdev/zram.txt
+++ b/Documentation/blockdev/zram.txt
@@ -19,7 +19,9 @@ Following shows a typical sequence of steps for using zram.
 1) Load Module:
        modprobe zram num_devices=4
        This creates 4 devices: /dev/zram{0,1,2,3}
-       (num_devices parameter is optional. Default: 1)
+
+num_devices parameter is optional and tells zram how many devices should be
+pre-created. Default: 1.
 
 2) Set max number of compression streams
        Compression backend may use up to max_comp_streams compression streams,
@@ -97,7 +99,24 @@ size of the disk when not in use so a huge zram is wasteful.
        mkfs.ext4 /dev/zram1
        mount /dev/zram1 /tmp
 
-7) Stats:
+7) Add/remove zram devices
+
+zram provides a control interface, which enables dynamic (on-demand) device
+addition and removal.
+
+In order to add a new /dev/zramX device, perform read operation on hot_add
+attribute. This will return either new device's device id (meaning that you
+can use /dev/zram<id>) or error code.
+
+Example:
+       cat /sys/class/zram-control/hot_add
+       1
+
+To remove the existing /dev/zramX device (where X is a device id)
+execute
+       echo X > /sys/class/zram-control/hot_remove
+
+8) Stats:
 Per-device statistics are exported as various nodes under /sys/block/zram<id>/
 
 A brief description of exported device attritbutes. For more details please
@@ -126,18 +145,57 @@ mem_used_max      RW    the maximum amount memory zram have consumed to
 mem_limit         RW    the maximum amount of memory ZRAM can use to store
                         the compressed data
 num_migrated      RO    the number of objects migrated migrated by compaction
+compact           WO    trigger memory compaction
+
+WARNING
+=======
+per-stat sysfs attributes are considered to be deprecated.
+The basic strategy is:
+-- the existing RW nodes will be downgraded to WO nodes (in linux 4.11)
+-- deprecated RO sysfs nodes will eventually be removed (in linux 4.11)
+
+The list of deprecated attributes can be found here:
+Documentation/ABI/obsolete/sysfs-block-zram
+
+Basically, every attribute that has its own read accessible sysfs node
+(e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat
+or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated.
 
+User space is advised to use the following files to read the device statistics.
 
 File /sys/block/zram<id>/stat
 
 Represents block layer statistics. Read Documentation/block/stat.txt for
 details.
 
-8) Deactivate:
+File /sys/block/zram<id>/io_stat
+
+The stat file represents device's I/O statistics not accounted by block
+layer and, thus, not available in zram<id>/stat file. It consists of a
+single line of text and contains the following stats separated by
+whitespace:
+       failed_reads
+       failed_writes
+       invalid_io
+       notify_free
+
+File /sys/block/zram<id>/mm_stat
+
+The stat file represents device's mm statistics. It consists of a single
+line of text and contains the following stats separated by whitespace:
+       orig_data_size
+       compr_data_size
+       mem_used_total
+       mem_limit
+       mem_used_max
+       zero_pages
+       num_migrated
+
+9) Deactivate:
        swapoff /dev/zram0
        umount /dev/zram1
 
-9) Reset:
+10) Reset:
        Write any positive value to 'reset' sysfs node
        echo 1 > /sys/block/zram0/reset
        echo 1 > /sys/block/zram1/reset