1zram: Compressed RAM based block devices
2----------------------------------------
3
4* Introduction
5
6The zram module creates RAM based block devices named /dev/zram<id>
7(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
8in memory itself. These disks allow very fast I/O and compression provides
9good amounts of memory savings. Some of the usecases include /tmp storage,
10use as swap disks, various caches under /var and maybe many more :)
11
12Statistics for individual zram devices are exported through sysfs nodes at
13/sys/block/zram<id>/
14
15* Usage
16
17Following shows a typical sequence of steps for using zram.
18
191) Load Module:
20	modprobe zram num_devices=4
21	This creates 4 devices: /dev/zram{0,1,2,3}
22	(num_devices parameter is optional. Default: 1)
23
242) Set max number of compression streams
25	Compression backend may use up to max_comp_streams compression streams,
26	thus allowing up to max_comp_streams concurrent compression operations.
27	By default, compression backend uses single compression stream.
28
29	Examples:
30	#show max compression streams number
31	cat /sys/block/zram0/max_comp_streams
32
33	#set max compression streams number to 3
34	echo 3 > /sys/block/zram0/max_comp_streams
35
36Note:
37In order to enable compression backend's multi stream support max_comp_streams
38must be initially set to desired concurrency level before ZRAM device
39initialisation. Once the device initialised as a single stream compression
40backend (max_comp_streams equals to 1), you will see error if you try to change
41the value of max_comp_streams because single stream compression backend
42implemented as a special case by lock overhead issue and does not support
43dynamic max_comp_streams. Only multi stream backend supports dynamic
44max_comp_streams adjustment.
45
463) Select compression algorithm
47	Using comp_algorithm device attribute one can see available and
48	currently selected (shown in square brackets) compression algortithms,
49	change selected compression algorithm (once the device is initialised
50	there is no way to change compression algorithm).
51
52	Examples:
53	#show supported compression algorithms
54	cat /sys/block/zram0/comp_algorithm
55	lzo [lz4]
56
57	#select lzo compression algorithm
58	echo lzo > /sys/block/zram0/comp_algorithm
59
604) Set Disksize
61        Set disk size by writing the value to sysfs node 'disksize'.
62        The value can be either in bytes or you can use mem suffixes.
63        Examples:
64            # Initialize /dev/zram0 with 50MB disksize
65            echo $((50*1024*1024)) > /sys/block/zram0/disksize
66
67            # Using mem suffixes
68            echo 256K > /sys/block/zram0/disksize
69            echo 512M > /sys/block/zram0/disksize
70            echo 1G > /sys/block/zram0/disksize
71
72Note:
73There is little point creating a zram of greater than twice the size of memory
74since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
75size of the disk when not in use so a huge zram is wasteful.
76
775) Set memory limit: Optional
78	Set memory limit by writing the value to sysfs node 'mem_limit'.
79	The value can be either in bytes or you can use mem suffixes.
80	In addition, you could change the value in runtime.
81	Examples:
82	    # limit /dev/zram0 with 50MB memory
83	    echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
84
85	    # Using mem suffixes
86	    echo 256K > /sys/block/zram0/mem_limit
87	    echo 512M > /sys/block/zram0/mem_limit
88	    echo 1G > /sys/block/zram0/mem_limit
89
90	    # To disable memory limit
91	    echo 0 > /sys/block/zram0/mem_limit
92
936) Activate:
94	mkswap /dev/zram0
95	swapon /dev/zram0
96
97	mkfs.ext4 /dev/zram1
98	mount /dev/zram1 /tmp
99
1007) Stats:
101Per-device statistics are exported as various nodes under /sys/block/zram<id>/
102
103A brief description of exported device attritbutes. For more details please
104read Documentation/ABI/testing/sysfs-block-zram.
105
106Name            access            description
107----            ------            -----------
108disksize          RW    show and set the device's disk size
109initstate         RO    shows the initialization state of the device
110reset             WO    trigger device reset
111num_reads         RO    the number of reads
112failed_reads      RO    the number of failed reads
113num_write         RO    the number of writes
114failed_writes     RO    the number of failed writes
115invalid_io        RO    the number of non-page-size-aligned I/O requests
116max_comp_streams  RW    the number of possible concurrent compress operations
117comp_algorithm    RW    show and change the compression algorithm
118notify_free       RO    the number of notifications to free pages (either
119                        slot free notifications or REQ_DISCARD requests)
120zero_pages        RO    the number of zero filled pages written to this disk
121orig_data_size    RO    uncompressed size of data stored in this disk
122compr_data_size   RO    compressed size of data stored in this disk
123mem_used_total    RO    the amount of memory allocated for this disk
124mem_used_max      RW    the maximum amount memory zram have consumed to
125                        store compressed data
126mem_limit         RW    the maximum amount of memory ZRAM can use to store
127                        the compressed data
128num_migrated      RO    the number of objects migrated migrated by compaction
129
130
131WARNING
132=======
133per-stat sysfs attributes are considered to be deprecated.
134The basic strategy is:
135-- the existing RW nodes will be downgraded to WO nodes (in linux 4.11)
136-- deprecated RO sysfs nodes will eventually be removed (in linux 4.11)
137
138The list of deprecated attributes can be found here:
139Documentation/ABI/obsolete/sysfs-block-zram
140
141Basically, every attribute that has its own read accessible sysfs node
142(e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat
143or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated.
144
145User space is advised to use the following files to read the device statistics.
146
147File /sys/block/zram<id>/stat
148
149Represents block layer statistics. Read Documentation/block/stat.txt for
150details.
151
152File /sys/block/zram<id>/io_stat
153
154The stat file represents device's I/O statistics not accounted by block
155layer and, thus, not available in zram<id>/stat file. It consists of a
156single line of text and contains the following stats separated by
157whitespace:
158	failed_reads
159	failed_writes
160	invalid_io
161	notify_free
162
163File /sys/block/zram<id>/mm_stat
164
165The stat file represents device's mm statistics. It consists of a single
166line of text and contains the following stats separated by whitespace:
167	orig_data_size
168	compr_data_size
169	mem_used_total
170	mem_limit
171	mem_used_max
172	zero_pages
173	num_migrated
174
1758) Deactivate:
176	swapoff /dev/zram0
177	umount /dev/zram1
178
1799) Reset:
180	Write any positive value to 'reset' sysfs node
181	echo 1 > /sys/block/zram0/reset
182	echo 1 > /sys/block/zram1/reset
183
184	This frees all the memory allocated for the given device and
185	resets the disksize to zero. You must set the disksize again
186	before reusing the device.
187
188Nitin Gupta
189ngupta@vflare.org
190