[PATCHv2] zram: update documentation

[PATCHv2] zram: update documentation

[Sergey Senozhatsky]

From: Sergey SENOZHATSKY <sergey.senozhatsky@gmail.com>

Several documentation changes.

First, we never mentioned any errors and never required any
error checks in documentation.

Second, mention that there is another way to configure and
manage zram devices -- zramctl, provided by util-linux.

Third, add a bit of clarification on why `mem_used_max' attr
is RW and correct some typos.

Signed-off-by: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
---
 Documentation/blockdev/zram.txt | 44 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 4 deletions(-)

diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.txt
index 62435bb..5bda503 100644
--- a/Documentation/blockdev/zram.txt
+++ b/Documentation/blockdev/zram.txt
@@ -14,8 +14,43 @@ Statistics for individual zram devices are exported through sysfs nodes at
 
 * Usage
 
+There are several ways to configure and manage zram device(-s):
+a) using zram and zram_control sysfs attributes
+b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
+
+In this document we will describe only 'manual' zram configuration steps,
+IOW, zram and zram_control sysfs attributes.
+
+In order to get a better idea about zramctl please consult util-linux
+documentation, zramctl man-page or `zramctl --help'. Please be informed
+that zram maintainers do not develop/maintain util-linux or zramctl, should
+you have any questions please contact util-linux@vger.kernel.org
+
 Following shows a typical sequence of steps for using zram.
 
+WARNING
+=======
+For the sake of simplicity we skip error checking parts in most of the
+examples below. However, it is your sole responsibility to handle errors.
+
+zram sysfs attributes always return negative values in case of errors.
+The list of possible return codes:
+-EBUSY	-- an attempt to modify an attribute that cannot be changed once
+the device has been initialised. Please reset device first;
+-ENOMEM	-- zram was not able to allocate enough memory to fulfil your
+needs;
+-EINVAL	-- invalid input has been provided.
+
+If you use 'echo', the returned value that is changed by 'echo' utility,
+and, in general case, something like:
+
+	echo 3 > /sys/block/zram0/max_comp_streams
+	if [ $? -ne 0 ];
+		handle_error
+	fi
+
+should suffice.
+
 1) Load Module:
 	modprobe zram num_devices=4
 	This creates 4 devices: /dev/zram{0,1,2,3}
@@ -47,7 +82,7 @@ max_comp_streams adjustment.
 
 3) Select compression algorithm
 	Using comp_algorithm device attribute one can see available and
-	currently selected (shown in square brackets) compression algortithms,
+	currently selected (shown in square brackets) compression algorithms,
 	change selected compression algorithm (once the device is initialised
 	there is no way to change compression algorithm).
 
@@ -119,7 +154,7 @@ execute
 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
+A brief description of exported device attributes. For more details please
 read Documentation/ABI/testing/sysfs-block-zram.
 
 Name            access            description
@@ -140,8 +175,9 @@ zero_pages        RO    the number of zero filled pages written to this disk
 orig_data_size    RO    uncompressed size of data stored in this disk
 compr_data_size   RO    compressed size of data stored in this disk
 mem_used_total    RO    the amount of memory allocated for this disk
-mem_used_max      RW    the maximum amount memory zram have consumed to
-                        store compressed data
+mem_used_max      RW    the maximum amount of memory zram have consumed to
+                        store the data (to reset this counter to the actual
+                        current value, write 1 to this attribute)
 mem_limit         RW    the maximum amount of memory ZRAM can use to store
                         the compressed data
 pages_compacted   RO    the number of pages freed during compaction
-- 
2.5.3

Re: [PATCHv2] zram: update documentation

[Jonathan Corbet]

On Thu, 24 Sep 2015 18:56:41 +0900
Sergey Senozhatsky <sergey.senozhatsky@gmail.com> wrote:

> Several documentation changes.
> 
> First, we never mentioned any errors and never required any
> error checks in documentation.
> 
> Second, mention that there is another way to configure and
> manage zram devices -- zramctl, provided by util-linux.
> 
> Third, add a bit of clarification on why `mem_used_max' attr
> is RW and correct some typos.

You didn't send this to the docs maintainer (me), but it looks like an
improvement, so I'll stash it into the docs tree anyway.

Thanks,

jon

Re: [PATCHv2] zram: update documentation

[Sergey Senozhatsky]

On (09/24/15 15:39), Jonathan Corbet wrote:
> On Thu, 24 Sep 2015 18:56:41 +0900
> Sergey Senozhatsky <sergey.senozhatsky@gmail.com> wrote:
> 
> > Several documentation changes.
> > 
> > First, we never mentioned any errors and never required any
> > error checks in documentation.
> > 
> > Second, mention that there is another way to configure and
> > manage zram devices -- zramctl, provided by util-linux.
> > 
> > Third, add a bit of clarification on why `mem_used_max' attr
> > is RW and correct some typos.
> 
> You didn't send this to the docs maintainer (me), but it looks like an
> improvement, so I'll stash it into the docs tree anyway.

Oh, sorry. Not sure I've ever Cc-ed you on zram Documentation patches.
Will keep in mind.

	-ss

Re: [PATCHv2] zram: update documentation

[Minchan Kim]

On Thu, Sep 24, 2015 at 06:56:41PM +0900, Sergey Senozhatsky wrote:
> From: Sergey SENOZHATSKY <sergey.senozhatsky@gmail.com>
> 
> Several documentation changes.
> 
> First, we never mentioned any errors and never required any
> error checks in documentation.
> 
> Second, mention that there is another way to configure and
> manage zram devices -- zramctl, provided by util-linux.
> 
> Third, add a bit of clarification on why `mem_used_max' attr
> is RW and correct some typos.
> 
> Signed-off-by: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>

Acked-by: Minchan Kim <minchan@kernel.org>

Thanks, Sergey!