blob: 62435bb252660f0e870e71f0f7f3f6ae0449d397 [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
Nitin Gupta00ac9ba2010-06-01 13:31:26 +053017Following shows a typical sequence of steps for using zram.
Nitin Gupta47f9afb2009-09-22 10:26:54 +053018
Nitin Gupta9b9913d2010-08-09 22:56:55 +0530191) Load Module:
Nitin Gupta00ac9ba2010-06-01 13:31:26 +053020 modprobe zram num_devices=4
Nitin Gupta9b9913d2010-08-09 22:56:55 +053021 This creates 4 devices: /dev/zram{0,1,2,3}
Sergey Senozhatskyc3cdb402015-06-25 15:00:11 -070022
23num_devices parameter is optional and tells zram how many devices should be
24pre-created. Default: 1.
Nitin Gupta47f9afb2009-09-22 10:26:54 +053025
Sergey Senozhatskybeca3ec2014-04-07 15:38:14 -0700262) Set max number of compression streams
27 Compression backend may use up to max_comp_streams compression streams,
28 thus allowing up to max_comp_streams concurrent compression operations.
29 By default, compression backend uses single compression stream.
30
31 Examples:
32 #show max compression streams number
33 cat /sys/block/zram0/max_comp_streams
34
35 #set max compression streams number to 3
36 echo 3 > /sys/block/zram0/max_comp_streams
37
38Note:
39In order to enable compression backend's multi stream support max_comp_streams
40must be initially set to desired concurrency level before ZRAM device
41initialisation. Once the device initialised as a single stream compression
Minchan Kim60a726e2014-04-07 15:38:21 -070042backend (max_comp_streams equals to 1), you will see error if you try to change
43the value of max_comp_streams because single stream compression backend
44implemented as a special case by lock overhead issue and does not support
45dynamic max_comp_streams. Only multi stream backend supports dynamic
46max_comp_streams adjustment.
Sergey Senozhatskybeca3ec2014-04-07 15:38:14 -070047
Sergey Senozhatskye46b8a02014-04-07 15:38:17 -0700483) Select compression algorithm
49 Using comp_algorithm device attribute one can see available and
50 currently selected (shown in square brackets) compression algortithms,
51 change selected compression algorithm (once the device is initialised
52 there is no way to change compression algorithm).
53
54 Examples:
55 #show supported compression algorithms
56 cat /sys/block/zram0/comp_algorithm
57 lzo [lz4]
58
59 #select lzo compression algorithm
60 echo lzo > /sys/block/zram0/comp_algorithm
61
624) Set Disksize
Minchan Kim0231c402013-01-30 11:41:40 +090063 Set disk size by writing the value to sysfs node 'disksize'.
64 The value can be either in bytes or you can use mem suffixes.
65 Examples:
66 # Initialize /dev/zram0 with 50MB disksize
67 echo $((50*1024*1024)) > /sys/block/zram0/disksize
Nitin Gupta47f9afb2009-09-22 10:26:54 +053068
Minchan Kim0231c402013-01-30 11:41:40 +090069 # Using mem suffixes
70 echo 256K > /sys/block/zram0/disksize
71 echo 512M > /sys/block/zram0/disksize
72 echo 1G > /sys/block/zram0/disksize
Nitin Gupta47f9afb2009-09-22 10:26:54 +053073
Sergey Senozhatskye64cd512014-04-07 15:38:07 -070074Note:
75There is little point creating a zram of greater than twice the size of memory
76since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
77size of the disk when not in use so a huge zram is wasteful.
78
Minchan Kim9ada9da2014-10-09 15:29:53 -0700795) Set memory limit: Optional
80 Set memory limit by writing the value to sysfs node 'mem_limit'.
81 The value can be either in bytes or you can use mem suffixes.
82 In addition, you could change the value in runtime.
83 Examples:
84 # limit /dev/zram0 with 50MB memory
85 echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
86
87 # Using mem suffixes
88 echo 256K > /sys/block/zram0/mem_limit
89 echo 512M > /sys/block/zram0/mem_limit
90 echo 1G > /sys/block/zram0/mem_limit
91
92 # To disable memory limit
93 echo 0 > /sys/block/zram0/mem_limit
94
956) Activate:
Nitin Gupta00ac9ba2010-06-01 13:31:26 +053096 mkswap /dev/zram0
97 swapon /dev/zram0
98
99 mkfs.ext4 /dev/zram1
100 mount /dev/zram1 /tmp
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530101
Sergey Senozhatsky6566d1a2015-06-25 15:00:24 -07001027) Add/remove zram devices
103
104zram provides a control interface, which enables dynamic (on-demand) device
105addition and removal.
106
107In order to add a new /dev/zramX device, perform read operation on hot_add
108attribute. This will return either new device's device id (meaning that you
109can use /dev/zram<id>) or error code.
110
111Example:
112 cat /sys/class/zram-control/hot_add
113 1
114
115To remove the existing /dev/zramX device (where X is a device id)
116execute
117 echo X > /sys/class/zram-control/hot_remove
118
1198) Stats:
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700120Per-device statistics are exported as various nodes under /sys/block/zram<id>/
121
122A brief description of exported device attritbutes. For more details please
123read Documentation/ABI/testing/sysfs-block-zram.
124
125Name access description
126---- ------ -----------
127disksize RW show and set the device's disk size
128initstate RO shows the initialization state of the device
129reset WO trigger device reset
130num_reads RO the number of reads
131failed_reads RO the number of failed reads
132num_write RO the number of writes
133failed_writes RO the number of failed writes
134invalid_io RO the number of non-page-size-aligned I/O requests
135max_comp_streams RW the number of possible concurrent compress operations
136comp_algorithm RW show and change the compression algorithm
137notify_free RO the number of notifications to free pages (either
138 slot free notifications or REQ_DISCARD requests)
139zero_pages RO the number of zero filled pages written to this disk
140orig_data_size RO uncompressed size of data stored in this disk
141compr_data_size RO compressed size of data stored in this disk
142mem_used_total RO the amount of memory allocated for this disk
143mem_used_max RW the maximum amount memory zram have consumed to
144 store compressed data
145mem_limit RW the maximum amount of memory ZRAM can use to store
146 the compressed data
Sergey Senozhatsky860c7072015-09-08 15:04:38 -0700147pages_compacted RO the number of pages freed during compaction
148 (available only via zram<id>/mm_stat node)
Sergey Senozhatsky3d8ed882015-06-25 15:00:00 -0700149compact WO trigger memory compaction
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700150
Sergey Senozhatsky8f7d2822015-04-15 16:16:09 -0700151WARNING
152=======
153per-stat sysfs attributes are considered to be deprecated.
154The basic strategy is:
155-- the existing RW nodes will be downgraded to WO nodes (in linux 4.11)
156-- deprecated RO sysfs nodes will eventually be removed (in linux 4.11)
157
158The list of deprecated attributes can be found here:
159Documentation/ABI/obsolete/sysfs-block-zram
160
161Basically, every attribute that has its own read accessible sysfs node
162(e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat
163or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated.
164
165User space is advised to use the following files to read the device statistics.
166
Sergey Senozhatsky77ba0152015-04-15 16:16:00 -0700167File /sys/block/zram<id>/stat
168
169Represents block layer statistics. Read Documentation/block/stat.txt for
170details.
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530171
Sergey Senozhatsky2f6a3be2015-04-15 16:16:03 -0700172File /sys/block/zram<id>/io_stat
173
174The stat file represents device's I/O statistics not accounted by block
175layer and, thus, not available in zram<id>/stat file. It consists of a
176single line of text and contains the following stats separated by
177whitespace:
178 failed_reads
179 failed_writes
180 invalid_io
181 notify_free
182
Sergey Senozhatsky4f2109f2015-04-15 16:16:06 -0700183File /sys/block/zram<id>/mm_stat
184
185The stat file represents device's mm statistics. It consists of a single
186line of text and contains the following stats separated by whitespace:
187 orig_data_size
188 compr_data_size
189 mem_used_total
190 mem_limit
191 mem_used_max
192 zero_pages
193 num_migrated
194
Sergey Senozhatsky6566d1a2015-06-25 15:00:24 -07001959) Deactivate:
Nitin Gupta00ac9ba2010-06-01 13:31:26 +0530196 swapoff /dev/zram0
197 umount /dev/zram1
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530198
Sergey Senozhatsky6566d1a2015-06-25 15:00:24 -070019910) Reset:
Nitin Gupta9b9913d2010-08-09 22:56:55 +0530200 Write any positive value to 'reset' sysfs node
201 echo 1 > /sys/block/zram0/reset
202 echo 1 > /sys/block/zram1/reset
203
Minchan Kim0231c402013-01-30 11:41:40 +0900204 This frees all the memory allocated for the given device and
205 resets the disksize to zero. You must set the disksize again
206 before reusing the device.
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530207
Nitin Gupta47f9afb2009-09-22 10:26:54 +0530208Nitin Gupta
209ngupta@vflare.org