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                   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  huge_pages_since the number of incompressible pages since zram set up
 270  ================ =============================================================
 271
 272 File /sys/block/zram<id>/bd_stat
 273
 274 The bd_stat file represents a device's backing device statistics. It consists of
 275 a single line of text and contains the following stats separated by whitespace:
 276
 277  ============== =============================================================
 278  bd_count       size of data written in backing device.
 279                 Unit: 4K bytes
 280  bd_reads       the number of reads from backing device
 281                 Unit: 4K bytes
 282  bd_writes      the number of writes to backing device
 283                 Unit: 4K bytes
 284  ============== =============================================================
 285
 286 9) Deactivate
 287 =============
 288
 289 ::
 290
 291         swapoff /dev/zram0
 292         umount /dev/zram1
 293
 294 10) Reset
 295 =========
 296
 297         Write any positive value to 'reset' sysfs node::
 298
 299                 echo 1 > /sys/block/zram0/reset
 300                 echo 1 > /sys/block/zram1/reset
 301
 302         This frees all the memory allocated for the given device and
 303         resets the disksize to zero. You must set the disksize again
 304         before reusing the device.
 305
 306 Optional Feature
 307 ================
 308
 309 writeback
 310 ---------
 311
 312 With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
 313 to backing storage rather than keeping it in memory.
 314 To use the feature, admin should set up backing device via::
 315
 316         echo /dev/sda5 > /sys/block/zramX/backing_dev
 317
 318 before disksize setting. It supports only partition at this moment.
 319 If admin wants to use incompressible page writeback, they could do via::
 320
 321         echo huge > /sys/block/zramX/writeback
 322
 323 To use idle page writeback, first, user need to declare zram pages
 324 as idle::
 325
 326         echo all > /sys/block/zramX/idle
 327
 328 From now on, any pages on zram are idle pages. The idle mark
 329 will be removed until someone requests access of the block.
 330 IOW, unless there is access request, those pages are still idle pages.
 331
 332 Admin can request writeback of those idle pages at right timing via::
 333
 334         echo idle > /sys/block/zramX/writeback
 335
 336 With the command, zram writeback idle pages from memory to the storage.
 337
 338 If admin want to write a specific page in zram device to backing device,
 339 they could write a page index into the interface.
 340
 341         echo "page_index=1251" > /sys/block/zramX/writeback
 342
 343 If there are lots of write IO with flash device, potentially, it has
 344 flash wearout problem so that admin needs to design write limitation
 345 to guarantee storage health for entire product life.
 346
 347 To overcome the concern, zram supports "writeback_limit" feature.
 348 The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
 349 any writeback. IOW, if admin wants to apply writeback budget, he should
 350 enable writeback_limit_enable via::
 351
 352         $ echo 1 > /sys/block/zramX/writeback_limit_enable
 353
 354 Once writeback_limit_enable is set, zram doesn't allow any writeback
 355 until admin sets the budget via /sys/block/zramX/writeback_limit.
 356
 357 (If admin doesn't enable writeback_limit_enable, writeback_limit's value
 358 assigned via /sys/block/zramX/writeback_limit is meaningless.)
 359
 360 If admin want to limit writeback as per-day 400M, he could do it
 361 like below::
 362
 363         $ MB_SHIFT=20
 364         $ 4K_SHIFT=12
 365         $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
 366                 /sys/block/zram0/writeback_limit.
 367         $ echo 1 > /sys/block/zram0/writeback_limit_enable
 368
 369 If admins want to allow further write again once the budget is exhausted,
 370 he could do it like below::
 371
 372         $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
 373                 /sys/block/zram0/writeback_limit
 374
 375 If admin wants to see remaining writeback budget since last set::
 376
 377         $ cat /sys/block/zramX/writeback_limit
 378
 379 If admin want to disable writeback limit, he could do::
 380
 381         $ echo 0 > /sys/block/zramX/writeback_limit_enable
 382
 383 The writeback_limit count will reset whenever you reset zram (e.g.,
 384 system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
 385 writeback happened until you reset the zram to allocate extra writeback
 386 budget in next setting is user's job.
 387
 388 If admin wants to measure writeback count in a certain period, he could
 389 know it via /sys/block/zram0/bd_stat's 3rd column.
 390
 391 memory tracking
 392 ===============
 393
 394 With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
 395 zram block. It could be useful to catch cold or incompressible
 396 pages of the process with*pagemap.
 397
 398 If you enable the feature, you could see block state via
 399 /sys/kernel/debug/zram/zram0/block_state". The output is as follows::
 400
 401           300    75.033841 .wh.
 402           301    63.806904 s...
 403           302    63.806919 ..hi
 404
 405 First column
 406         zram's block index.
 407 Second column
 408         access time since the system was booted
 409 Third column
 410         state of the block:
 411
 412         s:
 413                 same page
 414         w:
 415                 written page to backing store
 416         h:
 417                 huge page
 418         i:
 419                 idle page
 420
 421 First line of above example says 300th block is accessed at 75.033841sec
 422 and the block's state is huge so it is written back to the backing
 423 storage. It's a debugging feature so anyone shouldn't rely on it to work
 424 properly.
 425
 426 Nitin Gupta
 427 ngupta@vflare.org