Commit | Line | Data |
---|---|---|
00ac9ba0 NG |
1 | zram: Compressed RAM based block devices |
2 | ---------------------------------------- | |
47f9afb3 | 3 | |
47f9afb3 NG |
4 | * Introduction |
5 | ||
9b9913d8 NG |
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 :) | |
47f9afb3 | 11 | |
9b9913d8 NG |
12 | Statistics for individual zram devices are exported through sysfs nodes at |
13 | /sys/block/zram<id>/ | |
47f9afb3 NG |
14 | |
15 | * Usage | |
16 | ||
00ac9ba0 | 17 | Following shows a typical sequence of steps for using zram. |
47f9afb3 | 18 | |
9b9913d8 | 19 | 1) Load Module: |
00ac9ba0 | 20 | modprobe zram num_devices=4 |
9b9913d8 | 21 | This creates 4 devices: /dev/zram{0,1,2,3} |
c3cdb40e SS |
22 | |
23 | num_devices parameter is optional and tells zram how many devices should be | |
24 | pre-created. Default: 1. | |
47f9afb3 | 25 | |
beca3ec7 SS |
26 | 2) 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 | ||
38 | Note: | |
39 | In order to enable compression backend's multi stream support max_comp_streams | |
40 | must be initially set to desired concurrency level before ZRAM device | |
41 | initialisation. Once the device initialised as a single stream compression | |
60a726e3 MK |
42 | backend (max_comp_streams equals to 1), you will see error if you try to change |
43 | the value of max_comp_streams because single stream compression backend | |
44 | implemented as a special case by lock overhead issue and does not support | |
45 | dynamic max_comp_streams. Only multi stream backend supports dynamic | |
46 | max_comp_streams adjustment. | |
beca3ec7 | 47 | |
e46b8a03 SS |
48 | 3) 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 | ||
62 | 4) Set Disksize | |
0231c403 MK |
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 | |
47f9afb3 | 73 | |
e64cd51d SS |
74 | Note: |
75 | There is little point creating a zram of greater than twice the size of memory | |
76 | since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the | |
77 | size of the disk when not in use so a huge zram is wasteful. | |
78 | ||
9ada9da9 MK |
79 | 5) 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 | ||
95 | 6) Activate: | |
00ac9ba0 NG |
96 | mkswap /dev/zram0 |
97 | swapon /dev/zram0 | |
98 | ||
99 | mkfs.ext4 /dev/zram1 | |
100 | mount /dev/zram1 /tmp | |
47f9afb3 | 101 | |
6566d1a3 SS |
102 | 7) Add/remove zram devices |
103 | ||
104 | zram provides a control interface, which enables dynamic (on-demand) device | |
105 | addition and removal. | |
106 | ||
107 | In order to add a new /dev/zramX device, perform read operation on hot_add | |
108 | attribute. This will return either new device's device id (meaning that you | |
109 | can use /dev/zram<id>) or error code. | |
110 | ||
111 | Example: | |
112 | cat /sys/class/zram-control/hot_add | |
113 | 1 | |
114 | ||
115 | To remove the existing /dev/zramX device (where X is a device id) | |
116 | execute | |
117 | echo X > /sys/class/zram-control/hot_remove | |
118 | ||
119 | 8) Stats: | |
77ba015f SS |
120 | Per-device statistics are exported as various nodes under /sys/block/zram<id>/ |
121 | ||
122 | A brief description of exported device attritbutes. For more details please | |
123 | read Documentation/ABI/testing/sysfs-block-zram. | |
124 | ||
125 | Name access description | |
126 | ---- ------ ----------- | |
127 | disksize RW show and set the device's disk size | |
128 | initstate RO shows the initialization state of the device | |
129 | reset WO trigger device reset | |
130 | num_reads RO the number of reads | |
131 | failed_reads RO the number of failed reads | |
132 | num_write RO the number of writes | |
133 | failed_writes RO the number of failed writes | |
134 | invalid_io RO the number of non-page-size-aligned I/O requests | |
135 | max_comp_streams RW the number of possible concurrent compress operations | |
136 | comp_algorithm RW show and change the compression algorithm | |
137 | notify_free RO the number of notifications to free pages (either | |
138 | slot free notifications or REQ_DISCARD requests) | |
139 | zero_pages RO the number of zero filled pages written to this disk | |
140 | orig_data_size RO uncompressed size of data stored in this disk | |
141 | compr_data_size RO compressed size of data stored in this disk | |
142 | mem_used_total RO the amount of memory allocated for this disk | |
143 | mem_used_max RW the maximum amount memory zram have consumed to | |
144 | store compressed data | |
145 | mem_limit RW the maximum amount of memory ZRAM can use to store | |
146 | the compressed data | |
147 | num_migrated RO the number of objects migrated migrated by compaction | |
3d8ed88b | 148 | compact WO trigger memory compaction |
77ba015f | 149 | |
8f7d282c SS |
150 | WARNING |
151 | ======= | |
152 | per-stat sysfs attributes are considered to be deprecated. | |
153 | The 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 | ||
157 | The list of deprecated attributes can be found here: | |
158 | Documentation/ABI/obsolete/sysfs-block-zram | |
159 | ||
160 | Basically, 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 | |
162 | or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated. | |
163 | ||
164 | User space is advised to use the following files to read the device statistics. | |
165 | ||
77ba015f SS |
166 | File /sys/block/zram<id>/stat |
167 | ||
168 | Represents block layer statistics. Read Documentation/block/stat.txt for | |
169 | details. | |
47f9afb3 | 170 | |
2f6a3bed SS |
171 | File /sys/block/zram<id>/io_stat |
172 | ||
173 | The stat file represents device's I/O statistics not accounted by block | |
174 | layer and, thus, not available in zram<id>/stat file. It consists of a | |
175 | single line of text and contains the following stats separated by | |
176 | whitespace: | |
177 | failed_reads | |
178 | failed_writes | |
179 | invalid_io | |
180 | notify_free | |
181 | ||
4f2109f6 SS |
182 | File /sys/block/zram<id>/mm_stat |
183 | ||
184 | The stat file represents device's mm statistics. It consists of a single | |
185 | line 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 | ||
6566d1a3 | 194 | 9) Deactivate: |
00ac9ba0 NG |
195 | swapoff /dev/zram0 |
196 | umount /dev/zram1 | |
47f9afb3 | 197 | |
6566d1a3 | 198 | 10) Reset: |
9b9913d8 NG |
199 | Write any positive value to 'reset' sysfs node |
200 | echo 1 > /sys/block/zram0/reset | |
201 | echo 1 > /sys/block/zram1/reset | |
202 | ||
0231c403 MK |
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. | |
47f9afb3 | 206 | |
47f9afb3 NG |
207 | Nitin Gupta |
208 | ngupta@vflare.org |