blob: 7c05357360a763371fd4396b049f48092815797d [file] [log] [blame]
Nitin Gupta00ac9ba2010-06-01 13:31:26 +05301zram: Compressed RAM based block devices
2----------------------------------------
Nitin Gupta47f9afb2009-09-22 10:26:54 +05303
Nitin Gupta47f9afb2009-09-22 10:26:54 +05304* Introduction
5
Nitin Gupta9b9913d2010-08-09 22:56:55 +05306The 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 :)
Nitin Gupta47f9afb2009-09-22 10:26:54 +053011
Nitin Gupta9b9913d2010-08-09 22:56:55 +053012Statistics for individual zram devices are exported through sysfs nodes at
13/sys/block/zram<id>/
Nitin Gupta47f9afb2009-09-22 10:26:54 +053014
15* Usage
16
Sergey SENOZHATSKY3657c202015-09-24 18:56:41 +090017There 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
Nitin Gupta00ac9ba2010-06-01 13:31:26 +053029Following shows a typical sequence of steps for using zram.
Nitin Gupta47f9afb2009-09-22 10:26:54 +053030
Sergey SENOZHATSKY3657c202015-09-24 18:56:41 +090031WARNING
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
Nitin Gupta9b9913d2010-08-09 22:56:55 +0530541) Load Module:
Nitin Gupta00ac9ba2010-06-01 13:31:26 +053055 modprobe zram num_devices=4
Nitin Gupta9b9913d2010-08-09 22:56:55 +053056 This creates 4 devices: /dev/zram{0,1,2,3}
Sergey Senozhatskyc3cdb402015-06-25 15:00:11 -070057
58num_devices parameter is optional and tells zram how many devices should be
59pre-created. Default: 1.
Nitin Gupta47f9afb2009-09-22 10:26:54 +053060
Sergey Senozhatskybeca3ec2014-04-07 15:38:14 -0700612) Set max number of compression streams
Sergey Senozhatsky43209ea2016-05-20 16:59:59 -070062 Regardless the value passed to this attribute, ZRAM will always
63 allocate multiple compression streams - one per online CPUs - thus
64 allowing several concurrent compression operations. The number of
65 allocated compression streams goes down when some of the CPUs
66 become offline. There is no single-compression-stream mode anymore,
67 unless you are running a UP system or has only 1 CPU online.
Sergey Senozhatskybeca3ec2014-04-07 15:38:14 -070068
Sergey Senozhatsky43209ea2016-05-20 16:59:59 -070069 To find out how many streams are currently available:
Sergey Senozhatskybeca3ec2014-04-07 15:38:14 -070070 cat /sys/block/zram0/max_comp_streams
71
Sergey Senozhatskye46b8a02014-04-07 15:38:17 -0700723) Select compression algorithm
73 Using comp_algorithm device attribute one can see available and
Sergey SENOZHATSKY3657c202015-09-24 18:56:41 +090074 currently selected (shown in square brackets) compression algorithms,
Sergey Senozhatskye46b8a02014-04-07 15:38:17 -070075 change selected compression algorithm (once the device is initialised
76 there is no way to change compression algorithm).
77
78 Examples:
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
Sergey Senozhatsky415403b2016-07-26 15:22:48 -070086 For the time being, the `comp_algorithm' content does not necessarily
87 show every compression algorithm supported by the kernel. We keep this
88 list primarily to simplify device configuration and one can configure
89 a new device with a compression algorithm that is not listed in
90 `comp_algorithm'. The thing is that, internally, ZRAM uses Crypto API
91 and, if some of the algorithms were built as modules, it's impossible
92 to list all of them using, for instance, /proc/crypto or any other
93 method. This, however, has an advantage of permitting the usage of
94 custom crypto compression modules (implementing S/W or H/W
95 compression).
96
Sergey Senozhatskye46b8a02014-04-07 15:38:17 -0700974) Set Disksize
Minchan Kim0231c402013-01-30 11:41:40 +090098 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
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530103
Minchan Kim0231c402013-01-30 11:41:40 +0900104 # Using mem suffixes
105 echo 256K > /sys/block/zram0/disksize
106 echo 512M > /sys/block/zram0/disksize
107 echo 1G > /sys/block/zram0/disksize
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530108
Sergey Senozhatskye64cd512014-04-07 15:38:07 -0700109Note:
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
Minchan Kim9ada9da2014-10-09 15:29:53 -07001145) 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:
Nitin Gupta00ac9ba2010-06-01 13:31:26 +0530131 mkswap /dev/zram0
132 swapon /dev/zram0
133
134 mkfs.ext4 /dev/zram1
135 mount /dev/zram1 /tmp
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530136
Sergey Senozhatsky6566d1a2015-06-25 15:00:24 -07001377) 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:
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700155Per-device statistics are exported as various nodes under /sys/block/zram<id>/
156
Sergey SENOZHATSKY3657c202015-09-24 18:56:41 +0900157A brief description of exported device attributes. For more details please
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700158read 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
Sergey SENOZHATSKY3657c202015-09-24 18:56:41 +0900178mem_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)
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700181mem_limit RW the maximum amount of memory ZRAM can use to store
182 the compressed data
Sergey Senozhatsky860c7072015-09-08 15:04:38 -0700183pages_compacted RO the number of pages freed during compaction
184 (available only via zram<id>/mm_stat node)
Sergey Senozhatsky3d8ed882015-06-25 15:00:00 -0700185compact WO trigger memory compaction
Sergey Senozhatsky623e47f2016-05-20 17:00:02 -0700186debug_stat RO this file is used for zram debugging purposes
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700187
Sergey Senozhatsky8f7d2822015-04-15 16:16:09 -0700188WARNING
189=======
190per-stat sysfs attributes are considered to be deprecated.
191The basic strategy is:
192-- the existing RW nodes will be downgraded to WO nodes (in linux 4.11)
193-- deprecated RO sysfs nodes will eventually be removed (in linux 4.11)
194
195The list of deprecated attributes can be found here:
196Documentation/ABI/obsolete/sysfs-block-zram
197
198Basically, every attribute that has its own read accessible sysfs node
199(e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat
200or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated.
201
202User space is advised to use the following files to read the device statistics.
203
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700204File /sys/block/zram<id>/stat
205
206Represents block layer statistics. Read Documentation/block/stat.txt for
207details.
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530208
Sergey Senozhatsky2f6a3be2015-04-15 16:16:03 -0700209File /sys/block/zram<id>/io_stat
210
211The stat file represents device's I/O statistics not accounted by block
212layer and, thus, not available in zram<id>/stat file. It consists of a
213single line of text and contains the following stats separated by
214whitespace:
215 failed_reads
216 failed_writes
217 invalid_io
218 notify_free
219
Sergey Senozhatsky4f2109f2015-04-15 16:16:06 -0700220File /sys/block/zram<id>/mm_stat
221
222The stat file represents device's mm statistics. It consists of a single
223line of text and contains the following stats separated by whitespace:
224 orig_data_size
225 compr_data_size
226 mem_used_total
227 mem_limit
228 mem_used_max
229 zero_pages
230 num_migrated
231
Sergey Senozhatsky6566d1a2015-06-25 15:00:24 -07002329) Deactivate:
Nitin Gupta00ac9ba2010-06-01 13:31:26 +0530233 swapoff /dev/zram0
234 umount /dev/zram1
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530235
Sergey Senozhatsky6566d1a2015-06-25 15:00:24 -070023610) Reset:
Nitin Gupta9b9913d2010-08-09 22:56:55 +0530237 Write any positive value to 'reset' sysfs node
238 echo 1 > /sys/block/zram0/reset
239 echo 1 > /sys/block/zram1/reset
240
Minchan Kim0231c402013-01-30 11:41:40 +0900241 This frees all the memory allocated for the given device and
242 resets the disksize to zero. You must set the disksize again
243 before reusing the device.
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530244
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530245Nitin Gupta
246ngupta@vflare.org