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
17There are several ways to configure and manage zram device(-s):
18a) using zram and zram_control sysfs attributes
19b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
20
21In this document we will describe only 'manual' zram configuration steps,
22IOW, zram and zram_control sysfs attributes.
23
24In order to get a better idea about zramctl please consult util-linux
25documentation, zramctl man-page or `zramctl --help'. Please be informed
26that zram maintainers do not develop/maintain util-linux or zramctl, should
27you have any questions please contact util-linux@vger.kernel.org
28
29Following shows a typical sequence of steps for using zram.
30
31WARNING
32=======
33For the sake of simplicity we skip error checking parts in most of the
34examples below. However, it is your sole responsibility to handle errors.
35
36zram sysfs attributes always return negative values in case of errors.
37The list of possible return codes:
38-EBUSY	-- an attempt to modify an attribute that cannot be changed once
39the device has been initialised. Please reset device first;
40-ENOMEM	-- zram was not able to allocate enough memory to fulfil your
41needs;
42-EINVAL	-- invalid input has been provided.
43
44If you use 'echo', the returned value that is changed by 'echo' utility,
45and, in general case, something like:
46
47	echo 3 > /sys/block/zram0/max_comp_streams
48	if [ $? -ne 0 ];
49		handle_error
50	fi
51
52should suffice.
53
541) Load Module:
55	modprobe zram num_devices=4
56	This creates 4 devices: /dev/zram{0,1,2,3}
57
58num_devices parameter is optional and tells zram how many devices should be
59pre-created. Default: 1.
60
612) Set max number of compression streams
62	Compression backend may use up to max_comp_streams compression streams,
63	thus allowing up to max_comp_streams concurrent compression operations.
64	By default, compression backend uses single compression stream.
65
66	Examples:
67	#show max compression streams number
68	cat /sys/block/zram0/max_comp_streams
69
70	#set max compression streams number to 3
71	echo 3 > /sys/block/zram0/max_comp_streams
72
73Note:
74In order to enable compression backend's multi stream support max_comp_streams
75must be initially set to desired concurrency level before ZRAM device
76initialisation. Once the device initialised as a single stream compression
77backend (max_comp_streams equals to 1), you will see error if you try to change
78the value of max_comp_streams because single stream compression backend
79implemented as a special case by lock overhead issue and does not support
80dynamic max_comp_streams. Only multi stream backend supports dynamic
81max_comp_streams adjustment.
82
833) Select compression algorithm
84	Using comp_algorithm device attribute one can see available and
85	currently selected (shown in square brackets) compression algorithms,
86	change selected compression algorithm (once the device is initialised
87	there is no way to change compression algorithm).
88
89	Examples:
90	#show supported compression algorithms
91	cat /sys/block/zram0/comp_algorithm
92	lzo [lz4]
93
94	#select lzo compression algorithm
95	echo lzo > /sys/block/zram0/comp_algorithm
96
974) Set Disksize
98        Set disk size by writing the value to sysfs node 'disksize'.
99        The value can be either in bytes or you can use mem suffixes.
100        Examples:
101            # Initialize /dev/zram0 with 50MB disksize
102            echo $((50*1024*1024)) > /sys/block/zram0/disksize
103
104            # Using mem suffixes
105            echo 256K > /sys/block/zram0/disksize
106            echo 512M > /sys/block/zram0/disksize
107            echo 1G > /sys/block/zram0/disksize
108
109Note:
110There is little point creating a zram of greater than twice the size of memory
111since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
112size of the disk when not in use so a huge zram is wasteful.
113
1145) Set memory limit: Optional
115	Set memory limit by writing the value to sysfs node 'mem_limit'.
116	The value can be either in bytes or you can use mem suffixes.
117	In addition, you could change the value in runtime.
118	Examples:
119	    # limit /dev/zram0 with 50MB memory
120	    echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
121
122	    # Using mem suffixes
123	    echo 256K > /sys/block/zram0/mem_limit
124	    echo 512M > /sys/block/zram0/mem_limit
125	    echo 1G > /sys/block/zram0/mem_limit
126
127	    # To disable memory limit
128	    echo 0 > /sys/block/zram0/mem_limit
129
1306) Activate:
131	mkswap /dev/zram0
132	swapon /dev/zram0
133
134	mkfs.ext4 /dev/zram1
135	mount /dev/zram1 /tmp
136
1377) Add/remove zram devices
138
139zram provides a control interface, which enables dynamic (on-demand) device
140addition and removal.
141
142In order to add a new /dev/zramX device, perform read operation on hot_add
143attribute. This will return either new device's device id (meaning that you
144can use /dev/zram<id>) or error code.
145
146Example:
147	cat /sys/class/zram-control/hot_add
148	1
149
150To remove the existing /dev/zramX device (where X is a device id)
151execute
152	echo X > /sys/class/zram-control/hot_remove
153
1548) Stats:
155Per-device statistics are exported as various nodes under /sys/block/zram<id>/
156
157A brief description of exported device attributes. For more details please
158read Documentation/ABI/testing/sysfs-block-zram.
159
160Name            access            description
161----            ------            -----------
162disksize          RW    show and set the device's disk size
163initstate         RO    shows the initialization state of the device
164reset             WO    trigger device reset
165num_reads         RO    the number of reads
166failed_reads      RO    the number of failed reads
167num_write         RO    the number of writes
168failed_writes     RO    the number of failed writes
169invalid_io        RO    the number of non-page-size-aligned I/O requests
170max_comp_streams  RW    the number of possible concurrent compress operations
171comp_algorithm    RW    show and change the compression algorithm
172notify_free       RO    the number of notifications to free pages (either
173                        slot free notifications or REQ_DISCARD requests)
174zero_pages        RO    the number of zero filled pages written to this disk
175orig_data_size    RO    uncompressed size of data stored in this disk
176compr_data_size   RO    compressed size of data stored in this disk
177mem_used_total    RO    the amount of memory allocated for this disk
178mem_used_max      RW    the maximum amount of memory zram have consumed to
179                        store the data (to reset this counter to the actual
180                        current value, write 1 to this attribute)
181mem_limit         RW    the maximum amount of memory ZRAM can use to store
182                        the compressed data
183pages_compacted   RO    the number of pages freed during compaction
184                        (available only via zram<id>/mm_stat node)
185compact           WO    trigger memory compaction
186
187WARNING
188=======
189per-stat sysfs attributes are considered to be deprecated.
190The basic strategy is:
191-- the existing RW nodes will be downgraded to WO nodes (in linux 4.11)
192-- deprecated RO sysfs nodes will eventually be removed (in linux 4.11)
193
194The list of deprecated attributes can be found here:
195Documentation/ABI/obsolete/sysfs-block-zram
196
197Basically, every attribute that has its own read accessible sysfs node
198(e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat
199or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated.
200
201User space is advised to use the following files to read the device statistics.
202
203File /sys/block/zram<id>/stat
204
205Represents block layer statistics. Read Documentation/block/stat.txt for
206details.
207
208File /sys/block/zram<id>/io_stat
209
210The stat file represents device's I/O statistics not accounted by block
211layer and, thus, not available in zram<id>/stat file. It consists of a
212single line of text and contains the following stats separated by
213whitespace:
214	failed_reads
215	failed_writes
216	invalid_io
217	notify_free
218
219File /sys/block/zram<id>/mm_stat
220
221The stat file represents device's mm statistics. It consists of a single
222line of text and contains the following stats separated by whitespace:
223	orig_data_size
224	compr_data_size
225	mem_used_total
226	mem_limit
227	mem_used_max
228	zero_pages
229	num_migrated
230
2319) Deactivate:
232	swapoff /dev/zram0
233	umount /dev/zram1
234
23510) Reset:
236	Write any positive value to 'reset' sysfs node
237	echo 1 > /sys/block/zram0/reset
238	echo 1 > /sys/block/zram1/reset
239
240	This frees all the memory allocated for the given device and
241	resets the disksize to zero. You must set the disksize again
242	before reusing the device.
243
244Nitin Gupta
245ngupta@vflare.org
246