Provide a simple documentation for pages_per_pool_page ZRAM
device attribute.

Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
---
 Documentation/admin-guide/blockdev/zram.rst | 38 ++++++++++++++++-----
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst
index 010fb05a5999..4cb287520d45 100644
--- a/Documentation/admin-guide/blockdev/zram.rst
+++ b/Documentation/admin-guide/blockdev/zram.rst
@@ -112,7 +112,29 @@ to list all of them using, for instance, /proc/crypto or any other
 method. This, however, has an advantage of permitting the usage of
 custom crypto compression modules (implementing S/W or H/W compression).
 
-4) Set Disksize
+4) Set pages per-pool page limit: Optional
+==========================================
+
+zsmalloc pages can consist of up to ZS_DEFAULT_PAGES_PER_ZSPAGE (single)
+physical pages. The exact number is calculated for each zsmalloc size
+class during zsmalloc pool creation. ZRAM provides pages_per_pool_page
+device attribute that lets one adjust that limit (maximum possible value
+is ZS_MAX_PAGES_PER_ZSPAGE). The default limit is considered to be good
+enough, so tweak this value only when the changes in zsmalloc size classes
+characteristics are beneficial for your data patterns. The limit on the
+pages per zspages (currently) should be in [1,16] range; default value
+is 4.
+
+Examples::
+
+	#show current zsmalloc pages per-pool page limit
+	cat /sys/block/zramX/pages_per_pool_page
+	4
+
+	#set zsmalloc pages per-pool page limit
+	echo 8 > /sys/block/zramX/pages_per_pool_page
+
+5) Set Disksize
 ===============
 
 Set disk size by writing the value to sysfs node 'disksize'.
@@ -132,7 +154,7 @@ There is little point creating a zram of greater than twice the size of memory
 since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
 size of the disk when not in use so a huge zram is wasteful.
 
-5) Set memory limit: Optional
+6) Set memory limit: Optional
 =============================
 
 Set memory limit by writing the value to sysfs node 'mem_limit'.
@@ -151,7 +173,7 @@ Examples::
 	# To disable memory limit
 	echo 0 > /sys/block/zram0/mem_limit
 
-6) Activate
+7) Activate
 ===========
 
 ::
@@ -162,7 +184,7 @@ Examples::
 	mkfs.ext4 /dev/zram1
 	mount /dev/zram1 /tmp
 
-7) Add/remove zram devices
+8) Add/remove zram devices
 ==========================
 
 zram provides a control interface, which enables dynamic (on-demand) device
@@ -182,7 +204,7 @@ execute::
 
 	echo X > /sys/class/zram-control/hot_remove
 
-8) Stats
+9) Stats
 ========
 
 Per-device statistics are exported as various nodes under /sys/block/zram<id>/
@@ -283,15 +305,15 @@ a single line of text and contains the following stats separated by whitespace:
 		Unit: 4K bytes
  ============== =============================================================
 
-9) Deactivate
-=============
+10) Deactivate
+==============
 
 ::
 
 	swapoff /dev/zram0
 	umount /dev/zram1
 
-10) Reset
+11) Reset
 =========
 
 	Write any positive value to 'reset' sysfs node::
-- 
2.38.1.273.g43a17bfeac-goog

On Mon, Oct 31, 2022 at 02:41:07PM +0900, Sergey Senozhatsky wrote:
> Provide a simple documentation for pages_per_pool_page ZRAM
> device attribute.
> 
> Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> ---
>  Documentation/admin-guide/blockdev/zram.rst | 38 ++++++++++++++++-----
>  1 file changed, 30 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst
> index 010fb05a5999..4cb287520d45 100644
> --- a/Documentation/admin-guide/blockdev/zram.rst
> +++ b/Documentation/admin-guide/blockdev/zram.rst
> @@ -112,7 +112,29 @@ to list all of them using, for instance, /proc/crypto or any other
>  method. This, however, has an advantage of permitting the usage of
>  custom crypto compression modules (implementing S/W or H/W compression).
>  
> -4) Set Disksize
> +4) Set pages per-pool page limit: Optional
> +==========================================
> +
> +zsmalloc pages can consist of up to ZS_DEFAULT_PAGES_PER_ZSPAGE (single)
> +physical pages. The exact number is calculated for each zsmalloc size
> +class during zsmalloc pool creation. ZRAM provides pages_per_pool_page
> +device attribute that lets one adjust that limit (maximum possible value
> +is ZS_MAX_PAGES_PER_ZSPAGE). The default limit is considered to be good
> +enough, so tweak this value only when the changes in zsmalloc size classes
> +characteristics are beneficial for your data patterns. The limit on the
> +pages per zspages (currently) should be in [1,16] range; default value
> +is 4.

I think we need to introudce pros and cons for user to decide it since
it's not familiar with admin. I think It would need more explanation about
zsmalloc internal(especailly zspage and size classes)

On (22/11/10 18:20), Minchan Kim wrote:
> > diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst
> > index 010fb05a5999..4cb287520d45 100644
> > --- a/Documentation/admin-guide/blockdev/zram.rst
> > +++ b/Documentation/admin-guide/blockdev/zram.rst
> > @@ -112,7 +112,29 @@ to list all of them using, for instance, /proc/crypto or any other
> >  method. This, however, has an advantage of permitting the usage of
> >  custom crypto compression modules (implementing S/W or H/W compression).
> >  
> > -4) Set Disksize
> > +4) Set pages per-pool page limit: Optional
> > +==========================================
> > +
> > +zsmalloc pages can consist of up to ZS_DEFAULT_PAGES_PER_ZSPAGE (single)
> > +physical pages. The exact number is calculated for each zsmalloc size
> > +class during zsmalloc pool creation. ZRAM provides pages_per_pool_page
> > +device attribute that lets one adjust that limit (maximum possible value
> > +is ZS_MAX_PAGES_PER_ZSPAGE). The default limit is considered to be good
> > +enough, so tweak this value only when the changes in zsmalloc size classes
> > +characteristics are beneficial for your data patterns. The limit on the
> > +pages per zspages (currently) should be in [1,16] range; default value
> > +is 4.
> 
> I think we need to introudce pros and cons for user to decide it since
> it's not familiar with admin. I think It would need more explanation about
> zsmalloc internal(especailly zspage and size classes)

OK, agreed. I have quite a bit of info in the 0002 commit messages.
I can copy-paste some of those bits and edit them. We also have
some info the internal doc, which I can also use as a "source of
inspiration".