RDMA/rtrs: server: Fix some error return code
[linux/fpc-iii.git] / Documentation / admin-guide / blockdev / zram.rst
bloba6fd1f9b5faf52841d5fc281ef215c1ea019362d
1 ========================================
2 zram: Compressed RAM-based block devices
3 ========================================
5 Introduction
6 ============
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 use cases 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
15 /sys/block/zram<id>/
17 Usage
18 =====
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.
35 WARNING
36 =======
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
48           needs.
49 -EINVAL   invalid input has been provided.
50 ========  =============================================================
52 If you use 'echo', the returned value is set by the 'echo' utility,
53 and, in general case, something like::
55         echo 3 > /sys/block/zram0/max_comp_streams
56         if [ $? -ne 0 ]; then
57                 handle_error
58         fi
60 should suffice.
62 1) Load Module
63 ==============
67         modprobe zram num_devices=4
69 This creates 4 devices: /dev/zram{0,1,2,3}
71 num_devices parameter is optional and tells zram how many devices should be
72 pre-created. Default: 1.
74 2) Set max number of compression streams
75 ========================================
77 Regardless of the value passed to this attribute, ZRAM will always
78 allocate multiple compression streams - one per online CPU - thus
79 allowing several concurrent compression operations. The number of
80 allocated compression streams goes down when some of the CPUs
81 become offline. There is no single-compression-stream mode anymore,
82 unless you are running a UP system or have only 1 CPU online.
84 To find out how many streams are currently available::
86         cat /sys/block/zram0/max_comp_streams
88 3) Select compression algorithm
89 ===============================
91 Using comp_algorithm device attribute one can see available and
92 currently selected (shown in square brackets) compression algorithms,
93 or change the selected compression algorithm (once the device is initialised
94 there is no way to change compression algorithm).
96 Examples::
98         #show supported compression algorithms
99         cat /sys/block/zram0/comp_algorithm
100         lzo [lz4]
102         #select lzo compression algorithm
103         echo lzo > /sys/block/zram0/comp_algorithm
105 For the time being, the `comp_algorithm` content does not necessarily
106 show every compression algorithm supported by the kernel. We keep this
107 list primarily to simplify device configuration and one can configure
108 a new device with a compression algorithm that is not listed in
109 `comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API
110 and, if some of the algorithms were built as modules, it's impossible
111 to list all of them using, for instance, /proc/crypto or any other
112 method. This, however, has an advantage of permitting the usage of
113 custom crypto compression modules (implementing S/W or H/W compression).
115 4) Set Disksize
116 ===============
118 Set disk size by writing the value to sysfs node 'disksize'.
119 The value can be either in bytes or you can use mem suffixes.
120 Examples::
122         # Initialize /dev/zram0 with 50MB disksize
123         echo $((50*1024*1024)) > /sys/block/zram0/disksize
125         # Using mem suffixes
126         echo 256K > /sys/block/zram0/disksize
127         echo 512M > /sys/block/zram0/disksize
128         echo 1G > /sys/block/zram0/disksize
130 Note:
131 There is little point creating a zram of greater than twice the size of memory
132 since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
133 size of the disk when not in use so a huge zram is wasteful.
135 5) Set memory limit: Optional
136 =============================
138 Set memory limit by writing the value to sysfs node 'mem_limit'.
139 The value can be either in bytes or you can use mem suffixes.
140 In addition, you could change the value in runtime.
141 Examples::
143         # limit /dev/zram0 with 50MB memory
144         echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
146         # Using mem suffixes
147         echo 256K > /sys/block/zram0/mem_limit
148         echo 512M > /sys/block/zram0/mem_limit
149         echo 1G > /sys/block/zram0/mem_limit
151         # To disable memory limit
152         echo 0 > /sys/block/zram0/mem_limit
154 6) Activate
155 ===========
159         mkswap /dev/zram0
160         swapon /dev/zram0
162         mkfs.ext4 /dev/zram1
163         mount /dev/zram1 /tmp
165 7) Add/remove zram devices
166 ==========================
168 zram provides a control interface, which enables dynamic (on-demand) device
169 addition and removal.
171 In order to add a new /dev/zramX device, perform a read operation on the hot_add
172 attribute. This will return either the new device's device id (meaning that you
173 can use /dev/zram<id>) or an error code.
175 Example::
177         cat /sys/class/zram-control/hot_add
178         1
180 To remove the existing /dev/zramX device (where X is a device id)
181 execute::
183         echo X > /sys/class/zram-control/hot_remove
185 8) Stats
186 ========
188 Per-device statistics are exported as various nodes under /sys/block/zram<id>/
190 A brief description of exported device attributes follows. For more details
191 please read Documentation/ABI/testing/sysfs-block-zram.
193 ======================  ======  ===============================================
194 Name                    access            description
195 ======================  ======  ===============================================
196 disksize                RW      show and set the device's disk size
197 initstate               RO      shows the initialization state of the device
198 reset                   WO      trigger device reset
199 mem_used_max            WO      reset the `mem_used_max` counter (see later)
200 mem_limit               WO      specifies the maximum amount of memory ZRAM can
201                                 use to store the compressed data
202 writeback_limit         WO      specifies the maximum amount of write IO zram
203                                 can write out to backing device as 4KB unit
204 writeback_limit_enable  RW      show and set writeback_limit feature
205 max_comp_streams        RW      the number of possible concurrent compress
206                                 operations
207 comp_algorithm          RW      show and change the compression algorithm
208 compact                 WO      trigger memory compaction
209 debug_stat              RO      this file is used for zram debugging purposes
210 backing_dev             RW      set up backend storage for zram to write out
211 idle                    WO      mark allocated slot as idle
212 ======================  ======  ===============================================
215 User space is advised to use the following files to read the device statistics.
217 File /sys/block/zram<id>/stat
219 Represents block layer statistics. Read Documentation/block/stat.rst for
220 details.
222 File /sys/block/zram<id>/io_stat
224 The stat file represents device's I/O statistics not accounted by block
225 layer and, thus, not available in zram<id>/stat file. It consists of a
226 single line of text and contains the following stats separated by
227 whitespace:
229  =============    =============================================================
230  failed_reads     The number of failed reads
231  failed_writes    The number of failed writes
232  invalid_io       The number of non-page-size-aligned I/O requests
233  notify_free      Depending on device usage scenario it may account
235                   a) the number of pages freed because of swap slot free
236                      notifications
237                   b) the number of pages freed because of
238                      REQ_OP_DISCARD requests sent by bio. The former ones are
239                      sent to a swap block device when a swap slot is freed,
240                      which implies that this disk is being used as a swap disk.
242                   The latter ones are sent by filesystem mounted with
243                   discard option, whenever some data blocks are getting
244                   discarded.
245  =============    =============================================================
247 File /sys/block/zram<id>/mm_stat
249 The mm_stat file represents the device's mm statistics. It consists of a single
250 line of text and contains the following stats separated by whitespace:
252  ================ =============================================================
253  orig_data_size   uncompressed size of data stored in this disk.
254                   Unit: bytes
255  compr_data_size  compressed size of data stored in this disk
256  mem_used_total   the amount of memory allocated for this disk. This
257                   includes allocator fragmentation and metadata overhead,
258                   allocated for this disk. So, allocator space efficiency
259                   can be calculated using compr_data_size and this statistic.
260                   Unit: bytes
261  mem_limit        the maximum amount of memory ZRAM can use to store
262                   the compressed data
263  mem_used_max     the maximum amount of memory zram has consumed to
264                   store the data
265  same_pages       the number of same element filled pages written to this disk.
266                   No memory is allocated for such pages.
267  pages_compacted  the number of pages freed during compaction
268  huge_pages       the number of incompressible pages
269  ================ =============================================================
271 File /sys/block/zram<id>/bd_stat
273 The bd_stat file represents a device's backing device statistics. It consists of
274 a single line of text and contains the following stats separated by whitespace:
276  ============== =============================================================
277  bd_count       size of data written in backing device.
278                 Unit: 4K bytes
279  bd_reads       the number of reads from backing device
280                 Unit: 4K bytes
281  bd_writes      the number of writes to backing device
282                 Unit: 4K bytes
283  ============== =============================================================
285 9) Deactivate
286 =============
290         swapoff /dev/zram0
291         umount /dev/zram1
293 10) Reset
294 =========
296         Write any positive value to 'reset' sysfs node::
298                 echo 1 > /sys/block/zram0/reset
299                 echo 1 > /sys/block/zram1/reset
301         This frees all the memory allocated for the given device and
302         resets the disksize to zero. You must set the disksize again
303         before reusing the device.
305 Optional Feature
306 ================
308 writeback
309 ---------
311 With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
312 to backing storage rather than keeping it in memory.
313 To use the feature, admin should set up backing device via::
315         echo /dev/sda5 > /sys/block/zramX/backing_dev
317 before disksize setting. It supports only partition at this moment.
318 If admin wants to use incompressible page writeback, they could do via::
320         echo huge > /sys/block/zramX/writeback
322 To use idle page writeback, first, user need to declare zram pages
323 as idle::
325         echo all > /sys/block/zramX/idle
327 From now on, any pages on zram are idle pages. The idle mark
328 will be removed until someone requests access of the block.
329 IOW, unless there is access request, those pages are still idle pages.
331 Admin can request writeback of those idle pages at right timing via::
333         echo idle > /sys/block/zramX/writeback
335 With the command, zram writeback idle pages from memory to the storage.
337 If there are lots of write IO with flash device, potentially, it has
338 flash wearout problem so that admin needs to design write limitation
339 to guarantee storage health for entire product life.
341 To overcome the concern, zram supports "writeback_limit" feature.
342 The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
343 any writeback. IOW, if admin wants to apply writeback budget, he should
344 enable writeback_limit_enable via::
346         $ echo 1 > /sys/block/zramX/writeback_limit_enable
348 Once writeback_limit_enable is set, zram doesn't allow any writeback
349 until admin sets the budget via /sys/block/zramX/writeback_limit.
351 (If admin doesn't enable writeback_limit_enable, writeback_limit's value
352 assigned via /sys/block/zramX/writeback_limit is meaningless.)
354 If admin want to limit writeback as per-day 400M, he could do it
355 like below::
357         $ MB_SHIFT=20
358         $ 4K_SHIFT=12
359         $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
360                 /sys/block/zram0/writeback_limit.
361         $ echo 1 > /sys/block/zram0/writeback_limit_enable
363 If admins want to allow further write again once the bugdet is exhausted,
364 he could do it like below::
366         $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
367                 /sys/block/zram0/writeback_limit
369 If admin wants to see remaining writeback budget since last set::
371         $ cat /sys/block/zramX/writeback_limit
373 If admin want to disable writeback limit, he could do::
375         $ echo 0 > /sys/block/zramX/writeback_limit_enable
377 The writeback_limit count will reset whenever you reset zram (e.g.,
378 system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
379 writeback happened until you reset the zram to allocate extra writeback
380 budget in next setting is user's job.
382 If admin wants to measure writeback count in a certain period, he could
383 know it via /sys/block/zram0/bd_stat's 3rd column.
385 memory tracking
386 ===============
388 With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
389 zram block. It could be useful to catch cold or incompressible
390 pages of the process with*pagemap.
392 If you enable the feature, you could see block state via
393 /sys/kernel/debug/zram/zram0/block_state". The output is as follows::
395           300    75.033841 .wh.
396           301    63.806904 s...
397           302    63.806919 ..hi
399 First column
400         zram's block index.
401 Second column
402         access time since the system was booted
403 Third column
404         state of the block:
406         s:
407                 same page
408         w:
409                 written page to backing store
410         h:
411                 huge page
412         i:
413                 idle page
415 First line of above example says 300th block is accessed at 75.033841sec
416 and the block's state is huge so it is written back to the backing
417 storage. It's a debugging feature so anyone shouldn't rely on it to work
418 properly.
420 Nitin Gupta
421 ngupta@vflare.org