1 zram: Compressed RAM based block devices
2 ----------------------------------------
6 The zram module creates RAM based block devices named /dev/zram<id>
7 (<id> = 0, 1, ...). Pages written to these disks are compressed and stored
8 in memory itself. These disks allow very fast I/O and compression provides
9 good amounts of memory savings. Some of the usecases include /tmp storage,
10 use as swap disks, various caches under /var and maybe many more :)
12 Statistics for individual zram devices are exported through sysfs nodes at
17 There are several ways to configure and manage zram device(-s):
18 a) using zram and zram_control sysfs attributes
19 b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
21 In this document we will describe only 'manual' zram configuration steps,
22 IOW, zram and zram_control sysfs attributes.
24 In order to get a better idea about zramctl please consult util-linux
25 documentation, zramctl man-page or `zramctl --help'. Please be informed
26 that zram maintainers do not develop/maintain util-linux or zramctl, should
27 you have any questions please contact util-linux@vger.kernel.org
29 Following shows a typical sequence of steps for using zram.
33 For the sake of simplicity we skip error checking parts in most of the
34 examples below. However, it is your sole responsibility to handle errors.
36 zram sysfs attributes always return negative values in case of errors.
37 The list of possible return codes:
38 -EBUSY -- an attempt to modify an attribute that cannot be changed once
39 the device has been initialised. Please reset device first;
40 -ENOMEM -- zram was not able to allocate enough memory to fulfil your
42 -EINVAL -- invalid input has been provided.
44 If you use 'echo', the returned value that is changed by 'echo' utility,
45 and, in general case, something like:
47 echo 3 > /sys/block/zram0/max_comp_streams
55 modprobe zram num_devices=4
56 This creates 4 devices: /dev/zram{0,1,2,3}
58 num_devices parameter is optional and tells zram how many devices should be
59 pre-created. Default: 1.
61 2) Set max number of compression streams
62 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.
69 To find out how many streams are currently available:
70 cat /sys/block/zram0/max_comp_streams
72 3) Select compression algorithm
73 Using comp_algorithm device attribute one can see available and
74 currently selected (shown in square brackets) compression algorithms,
75 change selected compression algorithm (once the device is initialised
76 there is no way to change compression algorithm).
79 #show supported compression algorithms
80 cat /sys/block/zram0/comp_algorithm
83 #select lzo compression algorithm
84 echo lzo > /sys/block/zram0/comp_algorithm
87 Set disk size by writing the value to sysfs node 'disksize'.
88 The value can be either in bytes or you can use mem suffixes.
90 # Initialize /dev/zram0 with 50MB disksize
91 echo $((50*1024*1024)) > /sys/block/zram0/disksize
94 echo 256K > /sys/block/zram0/disksize
95 echo 512M > /sys/block/zram0/disksize
96 echo 1G > /sys/block/zram0/disksize
99 There is little point creating a zram of greater than twice the size of memory
100 since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
101 size of the disk when not in use so a huge zram is wasteful.
103 5) Set memory limit: Optional
104 Set memory limit by writing the value to sysfs node 'mem_limit'.
105 The value can be either in bytes or you can use mem suffixes.
106 In addition, you could change the value in runtime.
108 # limit /dev/zram0 with 50MB memory
109 echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
112 echo 256K > /sys/block/zram0/mem_limit
113 echo 512M > /sys/block/zram0/mem_limit
114 echo 1G > /sys/block/zram0/mem_limit
116 # To disable memory limit
117 echo 0 > /sys/block/zram0/mem_limit
124 mount /dev/zram1 /tmp
126 7) Add/remove zram devices
128 zram provides a control interface, which enables dynamic (on-demand) device
129 addition and removal.
131 In order to add a new /dev/zramX device, perform read operation on hot_add
132 attribute. This will return either new device's device id (meaning that you
133 can use /dev/zram<id>) or error code.
136 cat /sys/class/zram-control/hot_add
139 To remove the existing /dev/zramX device (where X is a device id)
141 echo X > /sys/class/zram-control/hot_remove
144 Per-device statistics are exported as various nodes under /sys/block/zram<id>/
146 A brief description of exported device attributes. For more details please
147 read Documentation/ABI/testing/sysfs-block-zram.
149 Name access description
150 ---- ------ -----------
151 disksize RW show and set the device's disk size
152 initstate RO shows the initialization state of the device
153 reset WO trigger device reset
154 num_reads RO the number of reads
155 failed_reads RO the number of failed reads
156 num_write RO the number of writes
157 failed_writes RO the number of failed writes
158 invalid_io RO the number of non-page-size-aligned I/O requests
159 max_comp_streams RW the number of possible concurrent compress operations
160 comp_algorithm RW show and change the compression algorithm
161 notify_free RO the number of notifications to free pages (either
162 slot free notifications or REQ_DISCARD requests)
163 zero_pages RO the number of zero filled pages written to this disk
164 orig_data_size RO uncompressed size of data stored in this disk
165 compr_data_size RO compressed size of data stored in this disk
166 mem_used_total RO the amount of memory allocated for this disk
167 mem_used_max RW the maximum amount of memory zram have consumed to
168 store the data (to reset this counter to the actual
169 current value, write 1 to this attribute)
170 mem_limit RW the maximum amount of memory ZRAM can use to store
172 pages_compacted RO the number of pages freed during compaction
173 (available only via zram<id>/mm_stat node)
174 compact WO trigger memory compaction
175 debug_stat RO this file is used for zram debugging purposes
179 per-stat sysfs attributes are considered to be deprecated.
180 The basic strategy is:
181 -- the existing RW nodes will be downgraded to WO nodes (in linux 4.11)
182 -- deprecated RO sysfs nodes will eventually be removed (in linux 4.11)
184 The list of deprecated attributes can be found here:
185 Documentation/ABI/obsolete/sysfs-block-zram
187 Basically, every attribute that has its own read accessible sysfs node
188 (e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat
189 or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated.
191 User space is advised to use the following files to read the device statistics.
193 File /sys/block/zram<id>/stat
195 Represents block layer statistics. Read Documentation/block/stat.txt for
198 File /sys/block/zram<id>/io_stat
200 The stat file represents device's I/O statistics not accounted by block
201 layer and, thus, not available in zram<id>/stat file. It consists of a
202 single line of text and contains the following stats separated by
209 File /sys/block/zram<id>/mm_stat
211 The stat file represents device's mm statistics. It consists of a single
212 line of text and contains the following stats separated by whitespace:
226 Write any positive value to 'reset' sysfs node
227 echo 1 > /sys/block/zram0/reset
228 echo 1 > /sys/block/zram1/reset
230 This frees all the memory allocated for the given device and
231 resets the disksize to zero. You must set the disksize again
232 before reusing the device.