Documentation/admin-guide/blockdev/zram.rst

   1 ========================================
   2 zram: Compressed RAM-based block devices
   3 ========================================
   4
   5 Introduction
   6 ============
   7
   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. :)
  13
  14 Statistics for individual zram devices are exported through sysfs nodes at
  15 /sys/block/zram<id>/
  16
  17 Usage
  18 =====
  19
  20 There are several ways to configure and manage zram device(-s):
  21
  22 a) using zram and zram_control sysfs attributes
  23 b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
  24
  25 In this document we will describe only 'manual' zram configuration steps,
  26 IOW, zram and zram_control sysfs attributes.
  27
  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
  32
  33 Following shows a typical sequence of steps for using zram.
  34
  35 WARNING
  36 =======
  37
  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.
  40
  41 zram sysfs attributes always return negative values in case of errors.
  42 The list of possible return codes:
  43
  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 ========  =============================================================
  51
  52 If you use 'echo', the returned value is set by the 'echo' utility,
  53 and, in general case, something like::
  54
  55         echo 3 > /sys/block/zram0/max_comp_streams
  56         if [ $? -ne 0 ]; then
  57                 handle_error
  58         fi
  59
  60 should suffice.
  61
  62 1) Load Module
  63 ==============
  64
  65 ::
  66
  67         modprobe zram num_devices=4
  68
  69 This creates 4 devices: /dev/zram{0,1,2,3}
  70
  71 num_devices parameter is optional and tells zram how many devices should be
  72 pre-created. Default: 1.
  73
  74 2) Set max number of compression streams
  75 ========================================
  76
  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.
  83
  84 To find out how many streams are currently available::
  85
  86         cat /sys/block/zram0/max_comp_streams
  87
  88 3) Select compression algorithm
  89 ===============================
  90
  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).
  95
  96 Examples::
  97
  98         #show supported compression algorithms
  99         cat /sys/block/zram0/comp_algorithm
 100         lzo [lz4]
 101
 102         #select lzo compression algorithm
 103         echo lzo > /sys/block/zram0/comp_algorithm
 104
 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).
 114
 115 4) Set Disksize
 116 ===============
 117
 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::
 121
 122         # Initialize /dev/zram0 with 50MB disksize
 123         echo $((50*1024*1024)) > /sys/block/zram0/disksize
 124
 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
 129
 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.
 134
 135 5) Set memory limit: Optional
 136 =============================
 137
 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::
 142
 143         # limit /dev/zram0 with 50MB memory
 144         echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
 145
 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
 150
 151         # To disable memory limit
 152         echo 0 > /sys/block/zram0/mem_limit
 153
 154 6) Activate
 155 ===========
 156
 157 ::
 158
 159         mkswap /dev/zram0
 160         swapon /dev/zram0
 161
 162         mkfs.ext4 /dev/zram1
 163         mount /dev/zram1 /tmp
 164
 165 7) Add/remove zram devices
 166 ==========================
 167
 168 zram provides a control interface, which enables dynamic (on-demand) device
 169 addition and removal.
 170
 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.
 174
 175 Example::
 176
 177         cat /sys/class/zram-control/hot_add
 178         1
 179
 180 To remove the existing /dev/zramX device (where X is a device id)
 181 execute::
 182
 183         echo X > /sys/class/zram-control/hot_remove
 184
 185 8) Stats
 186 ========
 187
 188 Per-device statistics are exported as various nodes under /sys/block/zram<id>/
 189
 190 A brief description of exported device attributes follows. For more details
 191 please read Documentation/ABI/testing/sysfs-block-zram.
 192
 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 ======================  ======  ===============================================
 213
 214
 215 User space is advised to use the following files to read the device statistics.
 216
 217 File /sys/block/zram<id>/stat
 218
 219 Represents block layer statistics. Read Documentation/block/stat.rst for
 220 details.
 221
 222 File /sys/block/zram<id>/io_stat
 223
 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:
 228
 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
 234
 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.
 241
 242                   The latter ones are sent by filesystem mounted with
 243                   discard option, whenever some data blocks are getting
 244                   discarded.
 245  =============    =============================================================
 246
 247 File /sys/block/zram<id>/mm_stat
 248
 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:
 251
 252  ================ =============================================================
 253  orig_data_size   uncompressed size of data stored in this disk.
 254                   This excludes same-element-filled pages (same_pages) since
 255                   no memory is allocated for them.
 256                   Unit: bytes
 257  compr_data_size  compressed size of data stored in this disk
 258  mem_used_total   the amount of memory allocated for this disk. This
 259                   includes allocator fragmentation and metadata overhead,
 260                   allocated for this disk. So, allocator space efficiency
 261                   can be calculated using compr_data_size and this statistic.
 262                   Unit: bytes
 263  mem_limit        the maximum amount of memory ZRAM can use to store
 264                   the compressed data
 265  mem_used_max     the maximum amount of memory zram has consumed to
 266                   store the data
 267  same_pages       the number of same element filled pages written to this disk.
 268                   No memory is allocated for such pages.
 269  pages_compacted  the number of pages freed during compaction
 270  huge_pages       the number of incompressible pages
 271  ================ =============================================================
 272
 273 File /sys/block/zram<id>/bd_stat
 274
 275 The bd_stat file represents a device's backing device statistics. It consists of
 276 a single line of text and contains the following stats separated by whitespace:
 277
 278  ============== =============================================================
 279  bd_count       size of data written in backing device.
 280                 Unit: 4K bytes
 281  bd_reads       the number of reads from backing device
 282                 Unit: 4K bytes
 283  bd_writes      the number of writes to backing device
 284                 Unit: 4K bytes
 285  ============== =============================================================
 286
 287 9) Deactivate
 288 =============
 289
 290 ::
 291
 292         swapoff /dev/zram0
 293         umount /dev/zram1
 294
 295 10) Reset
 296 =========
 297
 298         Write any positive value to 'reset' sysfs node::
 299
 300                 echo 1 > /sys/block/zram0/reset
 301                 echo 1 > /sys/block/zram1/reset
 302
 303         This frees all the memory allocated for the given device and
 304         resets the disksize to zero. You must set the disksize again
 305         before reusing the device.
 306
 307 Optional Feature
 308 ================
 309
 310 writeback
 311 ---------
 312
 313 With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
 314 to backing storage rather than keeping it in memory.
 315 To use the feature, admin should set up backing device via::
 316
 317         echo /dev/sda5 > /sys/block/zramX/backing_dev
 318
 319 before disksize setting. It supports only partition at this moment.
 320 If admin wants to use incompressible page writeback, they could do via::
 321
 322         echo huge > /sys/block/zramX/writeback
 323
 324 To use idle page writeback, first, user need to declare zram pages
 325 as idle::
 326
 327         echo all > /sys/block/zramX/idle
 328
 329 From now on, any pages on zram are idle pages. The idle mark
 330 will be removed until someone requests access of the block.
 331 IOW, unless there is access request, those pages are still idle pages.
 332
 333 Admin can request writeback of those idle pages at right timing via::
 334
 335         echo idle > /sys/block/zramX/writeback
 336
 337 With the command, zram writeback idle pages from memory to the storage.
 338
 339 If there are lots of write IO with flash device, potentially, it has
 340 flash wearout problem so that admin needs to design write limitation
 341 to guarantee storage health for entire product life.
 342
 343 To overcome the concern, zram supports "writeback_limit" feature.
 344 The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
 345 any writeback. IOW, if admin wants to apply writeback budget, he should
 346 enable writeback_limit_enable via::
 347
 348         $ echo 1 > /sys/block/zramX/writeback_limit_enable
 349
 350 Once writeback_limit_enable is set, zram doesn't allow any writeback
 351 until admin sets the budget via /sys/block/zramX/writeback_limit.
 352
 353 (If admin doesn't enable writeback_limit_enable, writeback_limit's value
 354 assigned via /sys/block/zramX/writeback_limit is meaningless.)
 355
 356 If admin want to limit writeback as per-day 400M, he could do it
 357 like below::
 358
 359         $ MB_SHIFT=20
 360         $ 4K_SHIFT=12
 361         $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
 362                 /sys/block/zram0/writeback_limit.
 363         $ echo 1 > /sys/block/zram0/writeback_limit_enable
 364
 365 If admins want to allow further write again once the bugdet is exhausted,
 366 he could do it like below::
 367
 368         $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
 369                 /sys/block/zram0/writeback_limit
 370
 371 If admin wants to see remaining writeback budget since last set::
 372
 373         $ cat /sys/block/zramX/writeback_limit
 374
 375 If admin want to disable writeback limit, he could do::
 376
 377         $ echo 0 > /sys/block/zramX/writeback_limit_enable
 378
 379 The writeback_limit count will reset whenever you reset zram (e.g.,
 380 system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
 381 writeback happened until you reset the zram to allocate extra writeback
 382 budget in next setting is user's job.
 383
 384 If admin wants to measure writeback count in a certain period, he could
 385 know it via /sys/block/zram0/bd_stat's 3rd column.
 386
 387 memory tracking
 388 ===============
 389
 390 With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
 391 zram block. It could be useful to catch cold or incompressible
 392 pages of the process with*pagemap.
 393
 394 If you enable the feature, you could see block state via
 395 /sys/kernel/debug/zram/zram0/block_state". The output is as follows::
 396
 397           300    75.033841 .wh.
 398           301    63.806904 s...
 399           302    63.806919 ..hi
 400
 401 First column
 402         zram's block index.
 403 Second column
 404         access time since the system was booted
 405 Third column
 406         state of the block:
 407
 408         s:
 409                 same page
 410         w:
 411                 written page to backing store
 412         h:
 413                 huge page
 414         i:
 415                 idle page
 416
 417 First line of above example says 300th block is accessed at 75.033841sec
 418 and the block's state is huge so it is written back to the backing
 419 storage. It's a debugging feature so anyone shouldn't rely on it to work
 420 properly.
 421
 422 Nitin Gupta
 423 ngupta@vflare.org