zram: add set_max_streams knob

[mirror_ubuntu-zesty-kernel.git] / Documentation / blockdev / zram.txt

zram: Compressed RAM based block devices
----------------------------------------

* Introduction

The zram module creates RAM based block devices named /dev/zram<id>
(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
in memory itself. These disks allow very fast I/O and compression provides
good amounts of memory savings. Some of the usecases include /tmp storage,
use as swap disks, various caches under /var and maybe many more :)

Statistics for individual zram devices are exported through sysfs nodes at
/sys/block/zram<id>/

* Usage

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)

2) Set max number of compression streams
	Compression backend may use up to max_comp_streams compression streams,
	thus allowing up to max_comp_streams concurrent compression operations.
	By default, compression backend uses single compression stream.

	Examples:
	#show max compression streams number
	cat /sys/block/zram0/max_comp_streams

	#set max compression streams number to 3
	echo 3 > /sys/block/zram0/max_comp_streams

Note:
In order to enable compression backend's multi stream support max_comp_streams
must be initially set to desired concurrency level before ZRAM device
initialisation. Once the device initialised as a single stream compression
backend (max_comp_streams equals to 0) changing the value of max_comp_streams
will not take any effect, because single stream compression backend implemented
as a special case and does not support dynamic max_comp_streams. Only multi
stream backend supports dynamic max_comp_streams adjustment.

3) Set Disksize
        Set disk size by writing the value to sysfs node 'disksize'.
        The value can be either in bytes or you can use mem suffixes.
        Examples:
            # Initialize /dev/zram0 with 50MB disksize
            echo $((50*1024*1024)) > /sys/block/zram0/disksize

            # Using mem suffixes
            echo 256K > /sys/block/zram0/disksize
            echo 512M > /sys/block/zram0/disksize
            echo 1G > /sys/block/zram0/disksize

Note:
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.

4) Activate:
	mkswap /dev/zram0
	swapon /dev/zram0

	mkfs.ext4 /dev/zram1
	mount /dev/zram1 /tmp

5) Stats:
	Per-device statistics are exported as various nodes under
	/sys/block/zram<id>/
		disksize
		num_reads
		num_writes
		failed_reads
		failed_writes
		invalid_io
		notify_free
		zero_pages
		orig_data_size
		compr_data_size
		mem_used_total

6) Deactivate:
	swapoff /dev/zram0
	umount /dev/zram1

7) Reset:
	Write any positive value to 'reset' sysfs node
	echo 1 > /sys/block/zram0/reset
	echo 1 > /sys/block/zram1/reset

	This frees all the memory allocated for the given device and
	resets the disksize to zero. You must set the disksize again
	before reusing the device.

Nitin Gupta
ngupta@vflare.org