tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1zram: Compressed RAM based block devices
2----------------------------------------
3
4* Introduction
5
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 :)
11
12Statistics for individual zram devices are exported through sysfs nodes at
13/sys/block/zram<id>/
14
15* Usage
16
17Following shows a typical sequence of steps for using zram.
18
191) Load Module:
20 modprobe zram num_devices=4
21 This creates 4 devices: /dev/zram{0,1,2,3}
22
23num_devices parameter is optional and tells zram how many devices should be
24pre-created. Default: 1.
25
262) 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
42backend (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.
47
483) 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
63 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
68
69 # Using mem suffixes
70 echo 256K > /sys/block/zram0/disksize
71 echo 512M > /sys/block/zram0/disksize
72 echo 1G > /sys/block/zram0/disksize
73
74Note:
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
795) 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:
96 mkswap /dev/zram0
97 swapon /dev/zram0
98
99 mkfs.ext4 /dev/zram1
100 mount /dev/zram1 /tmp
101
1027) 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:
120Per-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
147num_migrated RO the number of objects migrated migrated by compaction
148compact WO trigger memory compaction
149
150WARNING
151=======
152per-stat sysfs attributes are considered to be deprecated.
153The basic strategy is:
154-- the existing RW nodes will be downgraded to WO nodes (in linux 4.11)
155-- deprecated RO sysfs nodes will eventually be removed (in linux 4.11)
156
157The list of deprecated attributes can be found here:
158Documentation/ABI/obsolete/sysfs-block-zram
159
160Basically, every attribute that has its own read accessible sysfs node
161(e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat
162or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated.
163
164User space is advised to use the following files to read the device statistics.
165
166File /sys/block/zram<id>/stat
167
168Represents block layer statistics. Read Documentation/block/stat.txt for
169details.
170
171File /sys/block/zram<id>/io_stat
172
173The stat file represents device's I/O statistics not accounted by block
174layer and, thus, not available in zram<id>/stat file. It consists of a
175single line of text and contains the following stats separated by
176whitespace:
177 failed_reads
178 failed_writes
179 invalid_io
180 notify_free
181
182File /sys/block/zram<id>/mm_stat
183
184The stat file represents device's mm statistics. It consists of a single
185line of text and contains the following stats separated by whitespace:
186 orig_data_size
187 compr_data_size
188 mem_used_total
189 mem_limit
190 mem_used_max
191 zero_pages
192 num_migrated
193
1949) Deactivate:
195 swapoff /dev/zram0
196 umount /dev/zram1
197
19810) Reset:
199 Write any positive value to 'reset' sysfs node
200 echo 1 > /sys/block/zram0/reset
201 echo 1 > /sys/block/zram1/reset
202
203 This frees all the memory allocated for the given device and
204 resets the disksize to zero. You must set the disksize again
205 before reusing the device.
206
207Nitin Gupta
208ngupta@vflare.org