]> git.proxmox.com Git - mirror_ubuntu-bionic-kernel.git/blame - Documentation/blockdev/zram.txt
Merge branch 'for-4.15' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/libata
[mirror_ubuntu-bionic-kernel.git] / Documentation / blockdev / zram.txt
CommitLineData
00ac9ba0
NG
1zram: Compressed RAM based block devices
2----------------------------------------
47f9afb3 3
47f9afb3
NG
4* Introduction
5
9b9913d8
NG
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 :)
47f9afb3 11
9b9913d8
NG
12Statistics for individual zram devices are exported through sysfs nodes at
13/sys/block/zram<id>/
47f9afb3
NG
14
15* Usage
16
3657c20d
SS
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
00ac9ba0 29Following shows a typical sequence of steps for using zram.
47f9afb3 30
3657c20d
SS
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
9b9913d8 541) Load Module:
00ac9ba0 55 modprobe zram num_devices=4
9b9913d8 56 This creates 4 devices: /dev/zram{0,1,2,3}
c3cdb40e
SS
57
58num_devices parameter is optional and tells zram how many devices should be
59pre-created. Default: 1.
47f9afb3 60
beca3ec7 612) Set max number of compression streams
69a30a8d
SS
62Regardless the value passed to this attribute, ZRAM will always
63allocate multiple compression streams - one per online CPUs - thus
64allowing several concurrent compression operations. The number of
65allocated compression streams goes down when some of the CPUs
66become offline. There is no single-compression-stream mode anymore,
67unless you are running a UP system or has only 1 CPU online.
68
69To find out how many streams are currently available:
beca3ec7
SS
70 cat /sys/block/zram0/max_comp_streams
71
e46b8a03 723) Select compression algorithm
69a30a8d
SS
73Using comp_algorithm device attribute one can see available and
74currently selected (shown in square brackets) compression algorithms,
75change selected compression algorithm (once the device is initialised
76there is no way to change compression algorithm).
e46b8a03 77
69a30a8d 78Examples:
e46b8a03
SS
79 #show supported compression algorithms
80 cat /sys/block/zram0/comp_algorithm
81 lzo [lz4]
82
83 #select lzo compression algorithm
84 echo lzo > /sys/block/zram0/comp_algorithm
85
69a30a8d
SS
86For the time being, the `comp_algorithm' content does not necessarily
87show every compression algorithm supported by the kernel. We keep this
88list primarily to simplify device configuration and one can configure
89a new device with a compression algorithm that is not listed in
90`comp_algorithm'. The thing is that, internally, ZRAM uses Crypto API
91and, if some of the algorithms were built as modules, it's impossible
92to list all of them using, for instance, /proc/crypto or any other
93method. This, however, has an advantage of permitting the usage of
94custom crypto compression modules (implementing S/W or H/W compression).
415403be 95
e46b8a03 964) Set Disksize
69a30a8d
SS
97Set disk size by writing the value to sysfs node 'disksize'.
98The value can be either in bytes or you can use mem suffixes.
99Examples:
100 # Initialize /dev/zram0 with 50MB disksize
101 echo $((50*1024*1024)) > /sys/block/zram0/disksize
0231c403 102
69a30a8d
SS
103 # Using mem suffixes
104 echo 256K > /sys/block/zram0/disksize
105 echo 512M > /sys/block/zram0/disksize
106 echo 1G > /sys/block/zram0/disksize
47f9afb3 107
e64cd51d
SS
108Note:
109There is little point creating a zram of greater than twice the size of memory
110since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
111size of the disk when not in use so a huge zram is wasteful.
112
9ada9da9 1135) Set memory limit: Optional
69a30a8d
SS
114Set memory limit by writing the value to sysfs node 'mem_limit'.
115The value can be either in bytes or you can use mem suffixes.
116In addition, you could change the value in runtime.
117Examples:
118 # limit /dev/zram0 with 50MB memory
119 echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
120
121 # Using mem suffixes
122 echo 256K > /sys/block/zram0/mem_limit
123 echo 512M > /sys/block/zram0/mem_limit
124 echo 1G > /sys/block/zram0/mem_limit
125
126 # To disable memory limit
127 echo 0 > /sys/block/zram0/mem_limit
9ada9da9
MK
128
1296) Activate:
00ac9ba0
NG
130 mkswap /dev/zram0
131 swapon /dev/zram0
132
133 mkfs.ext4 /dev/zram1
134 mount /dev/zram1 /tmp
47f9afb3 135
6566d1a3
SS
1367) Add/remove zram devices
137
138zram provides a control interface, which enables dynamic (on-demand) device
139addition and removal.
140
141In order to add a new /dev/zramX device, perform read operation on hot_add
142attribute. This will return either new device's device id (meaning that you
143can use /dev/zram<id>) or error code.
144
145Example:
146 cat /sys/class/zram-control/hot_add
147 1
148
149To remove the existing /dev/zramX device (where X is a device id)
150execute
151 echo X > /sys/class/zram-control/hot_remove
152
1538) Stats:
77ba015f
SS
154Per-device statistics are exported as various nodes under /sys/block/zram<id>/
155
3657c20d 156A brief description of exported device attributes. For more details please
77ba015f
SS
157read Documentation/ABI/testing/sysfs-block-zram.
158
159Name access description
160---- ------ -----------
161disksize RW show and set the device's disk size
162initstate RO shows the initialization state of the device
163reset WO trigger device reset
c87d1655
SS
164mem_used_max WO reset the `mem_used_max' counter (see later)
165mem_limit WO specifies the maximum amount of memory ZRAM can use
166 to store the compressed data
77ba015f
SS
167max_comp_streams RW the number of possible concurrent compress operations
168comp_algorithm RW show and change the compression algorithm
3d8ed88b 169compact WO trigger memory compaction
623e47fc 170debug_stat RO this file is used for zram debugging purposes
5a47074f 171backing_dev RW set up backend storage for zram to write out
77ba015f 172
8f7d282c
SS
173
174User space is advised to use the following files to read the device statistics.
175
77ba015f
SS
176File /sys/block/zram<id>/stat
177
178Represents block layer statistics. Read Documentation/block/stat.txt for
179details.
47f9afb3 180
2f6a3bed
SS
181File /sys/block/zram<id>/io_stat
182
183The stat file represents device's I/O statistics not accounted by block
184layer and, thus, not available in zram<id>/stat file. It consists of a
185single line of text and contains the following stats separated by
186whitespace:
c87d1655
SS
187 failed_reads the number of failed reads
188 failed_writes the number of failed writes
189 invalid_io the number of non-page-size-aligned I/O requests
190 notify_free Depending on device usage scenario it may account
191 a) the number of pages freed because of swap slot free
192 notifications or b) the number of pages freed because of
193 REQ_DISCARD requests sent by bio. The former ones are
194 sent to a swap block device when a swap slot is freed,
195 which implies that this disk is being used as a swap disk.
196 The latter ones are sent by filesystem mounted with
197 discard option, whenever some data blocks are getting
198 discarded.
2f6a3bed 199
4f2109f6
SS
200File /sys/block/zram<id>/mm_stat
201
202The stat file represents device's mm statistics. It consists of a single
203line of text and contains the following stats separated by whitespace:
c87d1655 204 orig_data_size uncompressed size of data stored in this disk.
8e19d540 205 This excludes same-element-filled pages (same_pages) since
206 no memory is allocated for them.
c87d1655
SS
207 Unit: bytes
208 compr_data_size compressed size of data stored in this disk
209 mem_used_total the amount of memory allocated for this disk. This
210 includes allocator fragmentation and metadata overhead,
211 allocated for this disk. So, allocator space efficiency
212 can be calculated using compr_data_size and this statistic.
213 Unit: bytes
214 mem_limit the maximum amount of memory ZRAM can use to store
215 the compressed data
216 mem_used_max the maximum amount of memory zram have consumed to
217 store the data
8e19d540 218 same_pages the number of same element filled pages written to this disk.
c87d1655
SS
219 No memory is allocated for such pages.
220 pages_compacted the number of pages freed during compaction
4f2109f6 221
6566d1a3 2229) Deactivate:
00ac9ba0
NG
223 swapoff /dev/zram0
224 umount /dev/zram1
47f9afb3 225
6566d1a3 22610) Reset:
9b9913d8
NG
227 Write any positive value to 'reset' sysfs node
228 echo 1 > /sys/block/zram0/reset
229 echo 1 > /sys/block/zram1/reset
230
0231c403
MK
231 This frees all the memory allocated for the given device and
232 resets the disksize to zero. You must set the disksize again
233 before reusing the device.
47f9afb3 234
5a47074f
MK
235* Optional Feature
236
237= writeback
238
239With incompressible pages, there is no memory saving with zram.
240Instead, with CONFIG_ZRAM_WRITEBACK, zram can write incompressible page
241to backing storage rather than keeping it in memory.
242User should set up backing device via /sys/block/zramX/backing_dev
243before disksize setting.
244
47f9afb3
NG
245Nitin Gupta
246ngupta@vflare.org