zram: deprecate zram attrs sysfs nodes

Add Documentation/ABI/obsolete/sysfs-block-zram file and list obsolete and
deprecated attributes there.  The patch also adds additional information
to zram documentation and describes the basic strategy:

- the existing RW nodes will be downgraded to WO nodes (in 4.11)
- deprecated RO sysfs nodes will eventually be removed (in 4.11)

Users will be additionally notified about deprecated attr usage by
pr_warn_once() (added to every deprecated attr _show()), as suggested by
Minchan Kim.

User space is advised to use zram<id>/stat, zram<id>/io_stat and
zram<id>/mm_stat files.

Signed-off-by: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
Reported-by: Minchan Kim <minchan@kernel.org>
Cc: Nitin Gupta <ngupta@vflare.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

1 files changed, 119 insertions, 0 deletions

diff --git a/Documentation/ABI/obsolete/sysfs-block-zram b/Documentation/ABI/obsolete/sysfs-block-zram
new file mode 100644
index 000000000000..720ea92cfb2e
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-block-zram
@@ -0,0 +1,119 @@
+What:           /sys/block/zram<id>/num_reads
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The num_reads file is read-only and specifies the number of
+                reads (failed or successful) done on this device.
+                Now accessible via zram<id>/stat node.
+
+What:           /sys/block/zram<id>/num_writes
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The num_writes file is read-only and specifies the number of
+                writes (failed or successful) done on this device.
+                Now accessible via zram<id>/stat node.
+
+What:           /sys/block/zram<id>/invalid_io
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The invalid_io file is read-only and specifies the number of
+                non-page-size-aligned I/O requests issued to this device.
+                Now accessible via zram<id>/io_stat node.
+
+What:           /sys/block/zram<id>/failed_reads
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The failed_reads file is read-only and specifies the number of
+                failed reads happened on this device.
+                Now accessible via zram<id>/io_stat node.
+
+What:           /sys/block/zram<id>/failed_writes
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The failed_writes file is read-only and specifies the number of
+                failed writes happened on this device.
+                Now accessible via zram<id>/io_stat node.
+
+What:           /sys/block/zram<id>/notify_free
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The notify_free file is read-only. Depending on device usage
+                scenario it may account a) the number of pages freed because
+                of swap slot free notifications or b) the number of pages freed
+                because of REQ_DISCARD requests sent by bio. The former ones
+                are sent to a swap block device when a swap slot is freed, which
+                implies that this disk is being used as a swap disk. The latter
+                ones are sent by filesystem mounted with discard option,
+                whenever some data blocks are getting discarded.
+                Now accessible via zram<id>/io_stat node.
+
+What:           /sys/block/zram<id>/zero_pages
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The zero_pages file is read-only and specifies number of zero
+                filled pages written to this disk. No memory is allocated for
+                such pages.
+                Now accessible via zram<id>/mm_stat node.
+
+What:           /sys/block/zram<id>/orig_data_size
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The orig_data_size file is read-only and specifies uncompressed
+                size of data stored in this disk. This excludes zero-filled
+                pages (zero_pages) since no memory is allocated for them.
+                Unit: bytes
+                Now accessible via zram<id>/mm_stat node.
+
+What:           /sys/block/zram<id>/compr_data_size
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The compr_data_size file is read-only and specifies compressed
+                size of data stored in this disk. So, compression ratio can be
+                calculated using orig_data_size and this statistic.
+                Unit: bytes
+                Now accessible via zram<id>/mm_stat node.
+
+What:           /sys/block/zram<id>/mem_used_total
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The mem_used_total file is read-only and specifies the amount
+                of memory, including allocator fragmentation and metadata
+                overhead, allocated for this disk. So, allocator space
+                efficiency can be calculated using compr_data_size and this
+                statistic.
+                Unit: bytes
+                Now accessible via zram<id>/mm_stat node.
+
+What:           /sys/block/zram<id>/mem_used_max
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The mem_used_max file is read/write and specifies the amount
+                of maximum memory zram have consumed to store compressed data.
+                For resetting the value, you should write "0". Otherwise,
+                you could see -EINVAL.
+                Unit: bytes
+                Downgraded to write-only node: so it's possible to set new
+                value only; its current value is stored in zram<id>/mm_stat
+                node.
+
+What:           /sys/block/zram<id>/mem_limit
+Date:           August 2015
+Contact:        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+                The mem_limit file is read/write and specifies the maximum
+                amount of memory ZRAM can use to store the compressed data.
+                The limit could be changed in run time and "0" means disable
+                the limit.  No limit is the initial state.  Unit: bytes
+                Downgraded to write-only node: so it's possible to set new
+                value only; its current value is stored in zram<id>/mm_stat
+                node.