1 ========================================
2 zram: Compressed RAM based block devices
3 ========================================
8 The zram module creates RAM based block devices named /dev/zram<id>
9 (<id> = 0, 1, ...). Pages written to these disks are compressed and stored
10 in memory itself. These disks allow very fast I/O and compression provides
11 good amounts of memory savings. Some of the usecases include /tmp storage,
12 use as swap disks, various caches under /var and maybe many more :)
14 Statistics for individual zram devices are exported through sysfs nodes at
20 There are several ways to configure and manage zram device(-s):
22 a) using zram and zram_control sysfs attributes
23 b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
25 In this document we will describe only 'manual' zram configuration steps,
26 IOW, zram and zram_control sysfs attributes.
28 In order to get a better idea about zramctl please consult util-linux
29 documentation, zramctl man-page or `zramctl --help`. Please be informed
30 that zram maintainers do not develop/maintain util-linux or zramctl, should
31 you have any questions please contact util-linux@vger.kernel.org
33 Following shows a typical sequence of steps for using zram.
38 For the sake of simplicity we skip error checking parts in most of the
39 examples below. However, it is your sole responsibility to handle errors.
41 zram sysfs attributes always return negative values in case of errors.
42 The list of possible return codes:
44 ======== =============================================================
45 -EBUSY an attempt to modify an attribute that cannot be changed once
46 the device has been initialised. Please reset device first;
47 -ENOMEM zram was not able to allocate enough memory to fulfil your
49 -EINVAL invalid input has been provided.
50 ======== =============================================================
52 If you use 'echo', the returned value that is changed by 'echo' utility,
53 and, in general case, something like::
55 echo 3 > /sys/block/zram0/max_comp_streams
67 modprobe zram num_devices=4
68 This creates 4 devices: /dev/zram{0,1,2,3}
70 num_devices parameter is optional and tells zram how many devices should be
71 pre-created. Default: 1.
73 2) Set max number of compression streams
74 ========================================
76 Regardless the value passed to this attribute, ZRAM will always
77 allocate multiple compression streams - one per online CPUs - thus
78 allowing several concurrent compression operations. The number of
79 allocated compression streams goes down when some of the CPUs
80 become offline. There is no single-compression-stream mode anymore,
81 unless you are running a UP system or has only 1 CPU online.
83 To find out how many streams are currently available::
85 cat /sys/block/zram0/max_comp_streams
87 3) Select compression algorithm
88 ===============================
90 Using comp_algorithm device attribute one can see available and
91 currently selected (shown in square brackets) compression algorithms,
92 change selected compression algorithm (once the device is initialised
93 there is no way to change compression algorithm).
97 #show supported compression algorithms
98 cat /sys/block/zram0/comp_algorithm
101 #select lzo compression algorithm
102 echo lzo > /sys/block/zram0/comp_algorithm
104 For the time being, the `comp_algorithm` content does not necessarily
105 show every compression algorithm supported by the kernel. We keep this
106 list primarily to simplify device configuration and one can configure
107 a new device with a compression algorithm that is not listed in
108 `comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API
109 and, if some of the algorithms were built as modules, it's impossible
110 to list all of them using, for instance, /proc/crypto or any other
111 method. This, however, has an advantage of permitting the usage of
112 custom crypto compression modules (implementing S/W or H/W compression).
117 Set disk size by writing the value to sysfs node 'disksize'.
118 The value can be either in bytes or you can use mem suffixes.
121 # Initialize /dev/zram0 with 50MB disksize
122 echo $((50*1024*1024)) > /sys/block/zram0/disksize
125 echo 256K > /sys/block/zram0/disksize
126 echo 512M > /sys/block/zram0/disksize
127 echo 1G > /sys/block/zram0/disksize
130 There is little point creating a zram of greater than twice the size of memory
131 since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
132 size of the disk when not in use so a huge zram is wasteful.
134 5) Set memory limit: Optional
135 =============================
137 Set memory limit by writing the value to sysfs node 'mem_limit'.
138 The value can be either in bytes or you can use mem suffixes.
139 In addition, you could change the value in runtime.
142 # limit /dev/zram0 with 50MB memory
143 echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
146 echo 256K > /sys/block/zram0/mem_limit
147 echo 512M > /sys/block/zram0/mem_limit
148 echo 1G > /sys/block/zram0/mem_limit
150 # To disable memory limit
151 echo 0 > /sys/block/zram0/mem_limit
162 mount /dev/zram1 /tmp
164 7) Add/remove zram devices
165 ==========================
167 zram provides a control interface, which enables dynamic (on-demand) device
168 addition and removal.
170 In order to add a new /dev/zramX device, perform read operation on hot_add
171 attribute. This will return either new device's device id (meaning that you
172 can use /dev/zram<id>) or error code.
176 cat /sys/class/zram-control/hot_add
179 To remove the existing /dev/zramX device (where X is a device id)
182 echo X > /sys/class/zram-control/hot_remove
187 Per-device statistics are exported as various nodes under /sys/block/zram<id>/
189 A brief description of exported device attributes. For more details please
190 read Documentation/ABI/testing/sysfs-block-zram.
192 ====================== ====== ===============================================
193 Name access description
194 ====================== ====== ===============================================
195 disksize RW show and set the device's disk size
196 initstate RO shows the initialization state of the device
197 reset WO trigger device reset
198 mem_used_max WO reset the `mem_used_max` counter (see later)
199 mem_limit WO specifies the maximum amount of memory ZRAM can
200 use to store the compressed data
201 writeback_limit WO specifies the maximum amount of write IO zram
202 can write out to backing device as 4KB unit
203 writeback_limit_enable RW show and set writeback_limit feature
204 max_comp_streams RW the number of possible concurrent compress
206 comp_algorithm RW show and change the compression algorithm
207 compact WO trigger memory compaction
208 debug_stat RO this file is used for zram debugging purposes
209 backing_dev RW set up backend storage for zram to write out
210 idle WO mark allocated slot as idle
211 ====================== ====== ===============================================
214 User space is advised to use the following files to read the device statistics.
216 File /sys/block/zram<id>/stat
218 Represents block layer statistics. Read Documentation/block/stat.rst for
221 File /sys/block/zram<id>/io_stat
223 The stat file represents device's I/O statistics not accounted by block
224 layer and, thus, not available in zram<id>/stat file. It consists of a
225 single line of text and contains the following stats separated by
228 ============= =============================================================
229 failed_reads The number of failed reads
230 failed_writes The number of failed writes
231 invalid_io The number of non-page-size-aligned I/O requests
232 notify_free Depending on device usage scenario it may account
234 a) the number of pages freed because of swap slot free
236 b) the number of pages freed because of
237 REQ_OP_DISCARD requests sent by bio. The former ones are
238 sent to a swap block device when a swap slot is freed,
239 which implies that this disk is being used as a swap disk.
241 The latter ones are sent by filesystem mounted with
242 discard option, whenever some data blocks are getting
244 ============= =============================================================
246 File /sys/block/zram<id>/mm_stat
248 The stat file represents device's mm statistics. It consists of a single
249 line of text and contains the following stats separated by whitespace:
251 ================ =============================================================
252 orig_data_size uncompressed size of data stored in this disk.
253 This excludes same-element-filled pages (same_pages) since
254 no memory is allocated for them.
256 compr_data_size compressed size of data stored in this disk
257 mem_used_total the amount of memory allocated for this disk. This
258 includes allocator fragmentation and metadata overhead,
259 allocated for this disk. So, allocator space efficiency
260 can be calculated using compr_data_size and this statistic.
262 mem_limit the maximum amount of memory ZRAM can use to store
264 mem_used_max the maximum amount of memory zram have consumed to
266 same_pages the number of same element filled pages written to this disk.
267 No memory is allocated for such pages.
268 pages_compacted the number of pages freed during compaction
269 huge_pages the number of incompressible pages
270 ================ =============================================================
272 File /sys/block/zram<id>/bd_stat
274 The stat file represents device's backing device statistics. It consists of
275 a single line of text and contains the following stats separated by whitespace:
277 ============== =============================================================
278 bd_count size of data written in backing device.
280 bd_reads the number of reads from backing device
282 bd_writes the number of writes to backing device
284 ============== =============================================================
297 Write any positive value to 'reset' sysfs node::
299 echo 1 > /sys/block/zram0/reset
300 echo 1 > /sys/block/zram1/reset
302 This frees all the memory allocated for the given device and
303 resets the disksize to zero. You must set the disksize again
304 before reusing the device.
312 With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
313 to backing storage rather than keeping it in memory.
314 To use the feature, admin should set up backing device via::
316 echo /dev/sda5 > /sys/block/zramX/backing_dev
318 before disksize setting. It supports only partition at this moment.
319 If admin want to use incompressible page writeback, they could do via::
321 echo huge > /sys/block/zramX/write
323 To use idle page writeback, first, user need to declare zram pages
326 echo all > /sys/block/zramX/idle
328 From now on, any pages on zram are idle pages. The idle mark
329 will be removed until someone request access of the block.
330 IOW, unless there is access request, those pages are still idle pages.
332 Admin can request writeback of those idle pages at right timing via::
334 echo idle > /sys/block/zramX/writeback
336 With the command, zram writeback idle pages from memory to the storage.
338 If there are lots of write IO with flash device, potentially, it has
339 flash wearout problem so that admin needs to design write limitation
340 to guarantee storage health for entire product life.
342 To overcome the concern, zram supports "writeback_limit" feature.
343 The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
344 any writeback. IOW, if admin want to apply writeback budget, he should
345 enable writeback_limit_enable via::
347 $ echo 1 > /sys/block/zramX/writeback_limit_enable
349 Once writeback_limit_enable is set, zram doesn't allow any writeback
350 until admin set the budget via /sys/block/zramX/writeback_limit.
352 (If admin doesn't enable writeback_limit_enable, writeback_limit's value
353 assigned via /sys/block/zramX/writeback_limit is meaninless.)
355 If admin want to limit writeback as per-day 400M, he could do it
360 $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
361 /sys/block/zram0/writeback_limit.
362 $ echo 1 > /sys/block/zram0/writeback_limit_enable
364 If admin want to allow further write again once the bugdet is exausted,
365 he could do it like below::
367 $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
368 /sys/block/zram0/writeback_limit
370 If admin want to see remaining writeback budget since he set::
372 $ cat /sys/block/zramX/writeback_limit
374 If admin want to disable writeback limit, he could do::
376 $ echo 0 > /sys/block/zramX/writeback_limit_enable
378 The writeback_limit count will reset whenever you reset zram(e.g.,
379 system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
380 writeback happened until you reset the zram to allocate extra writeback
381 budget in next setting is user's job.
383 If admin want to measure writeback count in a certain period, he could
384 know it via /sys/block/zram0/bd_stat's 3rd column.
389 With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
390 zram block. It could be useful to catch cold or incompressible
391 pages of the process with*pagemap.
393 If you enable the feature, you could see block state via
394 /sys/kernel/debug/zram/zram0/block_state". The output is as follows::
403 access time since the system was booted
410 written page to backing store
416 First line of above example says 300th block is accessed at 75.033841sec
417 and the block's state is huge so it is written back to the backing
418 storage. It's a debugging feature so anyone shouldn't rely on it to work