s390: mm: add SPDX identifiers to the remaining files
[linux/fpc-iii.git] / Documentation / bcache.txt
blobc0ce64d75bbf7cfe02fa0a99af136f3ae02ba60c
1 ============================
2 A block layer cache (bcache)
3 ============================
5 Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
6 nice if you could use them as cache... Hence bcache.
8 Wiki and git repositories are at:
10   - http://bcache.evilpiepirate.org
11   - http://evilpiepirate.org/git/linux-bcache.git
12   - http://evilpiepirate.org/git/bcache-tools.git
14 It's designed around the performance characteristics of SSDs - it only allocates
15 in erase block sized buckets, and it uses a hybrid btree/log to track cached
16 extents (which can be anywhere from a single sector to the bucket size). It's
17 designed to avoid random writes at all costs; it fills up an erase block
18 sequentially, then issues a discard before reusing it.
20 Both writethrough and writeback caching are supported. Writeback defaults to
21 off, but can be switched on and off arbitrarily at runtime. Bcache goes to
22 great lengths to protect your data - it reliably handles unclean shutdown. (It
23 doesn't even have a notion of a clean shutdown; bcache simply doesn't return
24 writes as completed until they're on stable storage).
26 Writeback caching can use most of the cache for buffering writes - writing
27 dirty data to the backing device is always done sequentially, scanning from the
28 start to the end of the index.
30 Since random IO is what SSDs excel at, there generally won't be much benefit
31 to caching large sequential IO. Bcache detects sequential IO and skips it;
32 it also keeps a rolling average of the IO sizes per task, and as long as the
33 average is above the cutoff it will skip all IO from that task - instead of
34 caching the first 512k after every seek. Backups and large file copies should
35 thus entirely bypass the cache.
37 In the event of a data IO error on the flash it will try to recover by reading
38 from disk or invalidating cache entries.  For unrecoverable errors (meta data
39 or dirty data), caching is automatically disabled; if dirty data was present
40 in the cache it first disables writeback caching and waits for all dirty data
41 to be flushed.
43 Getting started:
44 You'll need make-bcache from the bcache-tools repository. Both the cache device
45 and backing device must be formatted before use::
47   make-bcache -B /dev/sdb
48   make-bcache -C /dev/sdc
50 make-bcache has the ability to format multiple devices at the same time - if
51 you format your backing devices and cache device at the same time, you won't
52 have to manually attach::
54   make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
56 bcache-tools now ships udev rules, and bcache devices are known to the kernel
57 immediately.  Without udev, you can manually register devices like this::
59   echo /dev/sdb > /sys/fs/bcache/register
60   echo /dev/sdc > /sys/fs/bcache/register
62 Registering the backing device makes the bcache device show up in /dev; you can
63 now format it and use it as normal. But the first time using a new bcache
64 device, it'll be running in passthrough mode until you attach it to a cache.
65 If you are thinking about using bcache later, it is recommended to setup all your
66 slow devices as bcache backing devices without a cache, and you can choose to add
67 a caching device later.
68 See 'ATTACHING' section below.
70 The devices show up as::
72   /dev/bcache<N>
74 As well as (with udev)::
76   /dev/bcache/by-uuid/<uuid>
77   /dev/bcache/by-label/<label>
79 To get started::
81   mkfs.ext4 /dev/bcache0
82   mount /dev/bcache0 /mnt
84 You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .
85 You can also control them through /sys/fs//bcache/<cset-uuid>/ .
87 Cache devices are managed as sets; multiple caches per set isn't supported yet
88 but will allow for mirroring of metadata and dirty data in the future. Your new
89 cache set shows up as /sys/fs/bcache/<UUID>
91 Attaching
92 ---------
94 After your cache device and backing device are registered, the backing device
95 must be attached to your cache set to enable caching. Attaching a backing
96 device to a cache set is done thusly, with the UUID of the cache set in
97 /sys/fs/bcache::
99   echo <CSET-UUID> > /sys/block/bcache0/bcache/attach
101 This only has to be done once. The next time you reboot, just reregister all
102 your bcache devices. If a backing device has data in a cache somewhere, the
103 /dev/bcache<N> device won't be created until the cache shows up - particularly
104 important if you have writeback caching turned on.
106 If you're booting up and your cache device is gone and never coming back, you
107 can force run the backing device::
109   echo 1 > /sys/block/sdb/bcache/running
111 (You need to use /sys/block/sdb (or whatever your backing device is called), not
112 /sys/block/bcache0, because bcache0 doesn't exist yet. If you're using a
113 partition, the bcache directory would be at /sys/block/sdb/sdb2/bcache)
115 The backing device will still use that cache set if it shows up in the future,
116 but all the cached data will be invalidated. If there was dirty data in the
117 cache, don't expect the filesystem to be recoverable - you will have massive
118 filesystem corruption, though ext4's fsck does work miracles.
120 Error Handling
121 --------------
123 Bcache tries to transparently handle IO errors to/from the cache device without
124 affecting normal operation; if it sees too many errors (the threshold is
125 configurable, and defaults to 0) it shuts down the cache device and switches all
126 the backing devices to passthrough mode.
128  - For reads from the cache, if they error we just retry the read from the
129    backing device.
131  - For writethrough writes, if the write to the cache errors we just switch to
132    invalidating the data at that lba in the cache (i.e. the same thing we do for
133    a write that bypasses the cache)
135  - For writeback writes, we currently pass that error back up to the
136    filesystem/userspace. This could be improved - we could retry it as a write
137    that skips the cache so we don't have to error the write.
139  - When we detach, we first try to flush any dirty data (if we were running in
140    writeback mode). It currently doesn't do anything intelligent if it fails to
141    read some of the dirty data, though.
144 Howto/cookbook
145 --------------
147 A) Starting a bcache with a missing caching device
149 If registering the backing device doesn't help, it's already there, you just need
150 to force it to run without the cache::
152         host:~# echo /dev/sdb1 > /sys/fs/bcache/register
153         [  119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered
155 Next, you try to register your caching device if it's present. However
156 if it's absent, or registration fails for some reason, you can still
157 start your bcache without its cache, like so::
159         host:/sys/block/sdb/sdb1/bcache# echo 1 > running
161 Note that this may cause data loss if you were running in writeback mode.
164 B) Bcache does not find its cache::
166         host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach
167         [ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set
168         [ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8
169         [ 1933.478179] : cache set not found
171 In this case, the caching device was simply not registered at boot
172 or disappeared and came back, and needs to be (re-)registered::
174         host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register
177 C) Corrupt bcache crashes the kernel at device registration time:
179 This should never happen.  If it does happen, then you have found a bug!
180 Please report it to the bcache development list: linux-bcache@vger.kernel.org
182 Be sure to provide as much information that you can including kernel dmesg
183 output if available so that we may assist.
186 D) Recovering data without bcache:
188 If bcache is not available in the kernel, a filesystem on the backing
189 device is still available at an 8KiB offset. So either via a loopdev
190 of the backing device created with --offset 8K, or any value defined by
191 --data-offset when you originally formatted bcache with `make-bcache`.
193 For example::
195         losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev
197 This should present your unmodified backing device data in /dev/loop0
199 If your cache is in writethrough mode, then you can safely discard the
200 cache device without loosing data.
203 E) Wiping a cache device
207         host:~# wipefs -a /dev/sdh2
208         16 bytes were erased at offset 0x1018 (bcache)
209         they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
211 After you boot back with bcache enabled, you recreate the cache and attach it::
213         host:~# make-bcache -C /dev/sdh2
214         UUID:                   7be7e175-8f4c-4f99-94b2-9c904d227045
215         Set UUID:               5bc072a8-ab17-446d-9744-e247949913c1
216         version:                0
217         nbuckets:               106874
218         block_size:             1
219         bucket_size:            1024
220         nr_in_set:              1
221         nr_this_dev:            0
222         first_bucket:           1
223         [  650.511912] bcache: run_cache_set() invalidating existing data
224         [  650.549228] bcache: register_cache() registered cache device sdh2
226 start backing device with missing cache::
228         host:/sys/block/md5/bcache# echo 1 > running
230 attach new cache::
232         host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
233         [  865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
236 F) Remove or replace a caching device::
238         host:/sys/block/sda/sda7/bcache# echo 1 > detach
239         [  695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7
241         host:~# wipefs -a /dev/nvme0n1p4
242         wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy
243         Ooops, it's disabled, but not unregistered, so it's still protected
245 We need to go and unregister it::
247         host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0
248         lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/
249         host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop
250         kernel: [  917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered
252 Now we can wipe it::
254         host:~# wipefs -a /dev/nvme0n1p4
255         /dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
258 G) dm-crypt and bcache
260 First setup bcache unencrypted and then install dmcrypt on top of
261 /dev/bcache<N> This will work faster than if you dmcrypt both the backing
262 and caching devices and then install bcache on top. [benchmarks?]
265 H) Stop/free a registered bcache to wipe and/or recreate it
267 Suppose that you need to free up all bcache references so that you can
268 fdisk run and re-register a changed partition table, which won't work
269 if there are any active backing or caching devices left on it:
271 1) Is it present in /dev/bcache* ? (there are times where it won't be)
273    If so, it's easy::
275         host:/sys/block/bcache0/bcache# echo 1 > stop
277 2) But if your backing device is gone, this won't work::
279         host:/sys/block/bcache0# cd bcache
280         bash: cd: bcache: No such file or directory
282    In this case, you may have to unregister the dmcrypt block device that
283    references this bcache to free it up::
285         host:~# dmsetup remove oldds1
286         bcache: bcache_device_free() bcache0 stopped
287         bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered
289    This causes the backing bcache to be removed from /sys/fs/bcache and
290    then it can be reused.  This would be true of any block device stacking
291    where bcache is a lower device.
293 3) In other cases, you can also look in /sys/fs/bcache/::
295         host:/sys/fs/bcache# ls -l */{cache?,bdev?}
296         lrwxrwxrwx 1 root root 0 Mar  5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
297         lrwxrwxrwx 1 root root 0 Mar  5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
298         lrwxrwxrwx 1 root root 0 Mar  5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
300    The device names will show which UUID is relevant, cd in that directory
301    and stop the cache::
303         host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop
305    This will free up bcache references and let you reuse the partition for
306    other purposes.
310 Troubleshooting performance
311 ---------------------------
313 Bcache has a bunch of config options and tunables. The defaults are intended to
314 be reasonable for typical desktop and server workloads, but they're not what you
315 want for getting the best possible numbers when benchmarking.
317  - Backing device alignment
319    The default metadata size in bcache is 8k.  If your backing device is
320    RAID based, then be sure to align this by a multiple of your stride
321    width using `make-bcache --data-offset`. If you intend to expand your
322    disk array in the future, then multiply a series of primes by your
323    raid stripe size to get the disk multiples that you would like.
325    For example:  If you have a 64k stripe size, then the following offset
326    would provide alignment for many common RAID5 data spindle counts::
328         64k * 2*2*2*3*3*5*7 bytes = 161280k
330    That space is wasted, but for only 157.5MB you can grow your RAID 5
331    volume to the following data-spindle counts without re-aligning::
333         3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
335  - Bad write performance
337    If write performance is not what you expected, you probably wanted to be
338    running in writeback mode, which isn't the default (not due to a lack of
339    maturity, but simply because in writeback mode you'll lose data if something
340    happens to your SSD)::
342         # echo writeback > /sys/block/bcache0/bcache/cache_mode
344  - Bad performance, or traffic not going to the SSD that you'd expect
346    By default, bcache doesn't cache everything. It tries to skip sequential IO -
347    because you really want to be caching the random IO, and if you copy a 10
348    gigabyte file you probably don't want that pushing 10 gigabytes of randomly
349    accessed data out of your cache.
351    But if you want to benchmark reads from cache, and you start out with fio
352    writing an 8 gigabyte test file - so you want to disable that::
354         # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff
356    To set it back to the default (4 mb), do::
358         # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff
360  - Traffic's still going to the spindle/still getting cache misses
362    In the real world, SSDs don't always keep up with disks - particularly with
363    slower SSDs, many disks being cached by one SSD, or mostly sequential IO. So
364    you want to avoid being bottlenecked by the SSD and having it slow everything
365    down.
367    To avoid that bcache tracks latency to the cache device, and gradually
368    throttles traffic if the latency exceeds a threshold (it does this by
369    cranking down the sequential bypass).
371    You can disable this if you need to by setting the thresholds to 0::
373         # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us
374         # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us
376    The default is 2000 us (2 milliseconds) for reads, and 20000 for writes.
378  - Still getting cache misses, of the same data
380    One last issue that sometimes trips people up is actually an old bug, due to
381    the way cache coherency is handled for cache misses. If a btree node is full,
382    a cache miss won't be able to insert a key for the new data and the data
383    won't be written to the cache.
385    In practice this isn't an issue because as soon as a write comes along it'll
386    cause the btree node to be split, and you need almost no write traffic for
387    this to not show up enough to be noticeable (especially since bcache's btree
388    nodes are huge and index large regions of the device). But when you're
389    benchmarking, if you're trying to warm the cache by reading a bunch of data
390    and there's no other traffic - that can be a problem.
392    Solution: warm the cache by doing writes, or use the testing branch (there's
393    a fix for the issue there).
396 Sysfs - backing device
397 ----------------------
399 Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
400 (if attached) /sys/fs/bcache/<cset-uuid>/bdev*
402 attach
403   Echo the UUID of a cache set to this file to enable caching.
405 cache_mode
406   Can be one of either writethrough, writeback, writearound or none.
408 clear_stats
409   Writing to this file resets the running total stats (not the day/hour/5 minute
410   decaying versions).
412 detach
413   Write to this file to detach from a cache set. If there is dirty data in the
414   cache, it will be flushed first.
416 dirty_data
417   Amount of dirty data for this backing device in the cache. Continuously
418   updated unlike the cache set's version, but may be slightly off.
420 label
421   Name of underlying device.
423 readahead
424   Size of readahead that should be performed.  Defaults to 0.  If set to e.g.
425   1M, it will round cache miss reads up to that size, but without overlapping
426   existing cache entries.
428 running
429   1 if bcache is running (i.e. whether the /dev/bcache device exists, whether
430   it's in passthrough mode or caching).
432 sequential_cutoff
433   A sequential IO will bypass the cache once it passes this threshold; the
434   most recent 128 IOs are tracked so sequential IO can be detected even when
435   it isn't all done at once.
437 sequential_merge
438   If non zero, bcache keeps a list of the last 128 requests submitted to compare
439   against all new requests to determine which new requests are sequential
440   continuations of previous requests for the purpose of determining sequential
441   cutoff. This is necessary if the sequential cutoff value is greater than the
442   maximum acceptable sequential size for any single request.
444 state
445   The backing device can be in one of four different states:
447   no cache: Has never been attached to a cache set.
449   clean: Part of a cache set, and there is no cached dirty data.
451   dirty: Part of a cache set, and there is cached dirty data.
453   inconsistent: The backing device was forcibly run by the user when there was
454   dirty data cached but the cache set was unavailable; whatever data was on the
455   backing device has likely been corrupted.
457 stop
458   Write to this file to shut down the bcache device and close the backing
459   device.
461 writeback_delay
462   When dirty data is written to the cache and it previously did not contain
463   any, waits some number of seconds before initiating writeback. Defaults to
464   30.
466 writeback_percent
467   If nonzero, bcache tries to keep around this percentage of the cache dirty by
468   throttling background writeback and using a PD controller to smoothly adjust
469   the rate.
471 writeback_rate
472   Rate in sectors per second - if writeback_percent is nonzero, background
473   writeback is throttled to this rate. Continuously adjusted by bcache but may
474   also be set by the user.
476 writeback_running
477   If off, writeback of dirty data will not take place at all. Dirty data will
478   still be added to the cache until it is mostly full; only meant for
479   benchmarking. Defaults to on.
481 Sysfs - backing device stats
482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
484 There are directories with these numbers for a running total, as well as
485 versions that decay over the past day, hour and 5 minutes; they're also
486 aggregated in the cache set directory as well.
488 bypassed
489   Amount of IO (both reads and writes) that has bypassed the cache
491 cache_hits, cache_misses, cache_hit_ratio
492   Hits and misses are counted per individual IO as bcache sees them; a
493   partial hit is counted as a miss.
495 cache_bypass_hits, cache_bypass_misses
496   Hits and misses for IO that is intended to skip the cache are still counted,
497   but broken out here.
499 cache_miss_collisions
500   Counts instances where data was going to be inserted into the cache from a
501   cache miss, but raced with a write and data was already present (usually 0
502   since the synchronization for cache misses was rewritten)
504 cache_readaheads
505   Count of times readahead occurred.
507 Sysfs - cache set
508 ~~~~~~~~~~~~~~~~~
510 Available at /sys/fs/bcache/<cset-uuid>
512 average_key_size
513   Average data per key in the btree.
515 bdev<0..n>
516   Symlink to each of the attached backing devices.
518 block_size
519   Block size of the cache devices.
521 btree_cache_size
522   Amount of memory currently used by the btree cache
524 bucket_size
525   Size of buckets
527 cache<0..n>
528   Symlink to each of the cache devices comprising this cache set.
530 cache_available_percent
531   Percentage of cache device which doesn't contain dirty data, and could
532   potentially be used for writeback.  This doesn't mean this space isn't used
533   for clean cached data; the unused statistic (in priority_stats) is typically
534   much lower.
536 clear_stats
537   Clears the statistics associated with this cache
539 dirty_data
540   Amount of dirty data is in the cache (updated when garbage collection runs).
542 flash_vol_create
543   Echoing a size to this file (in human readable units, k/M/G) creates a thinly
544   provisioned volume backed by the cache set.
546 io_error_halflife, io_error_limit
547   These determines how many errors we accept before disabling the cache.
548   Each error is decayed by the half life (in # ios).  If the decaying count
549   reaches io_error_limit dirty data is written out and the cache is disabled.
551 journal_delay_ms
552   Journal writes will delay for up to this many milliseconds, unless a cache
553   flush happens sooner. Defaults to 100.
555 root_usage_percent
556   Percentage of the root btree node in use.  If this gets too high the node
557   will split, increasing the tree depth.
559 stop
560   Write to this file to shut down the cache set - waits until all attached
561   backing devices have been shut down.
563 tree_depth
564   Depth of the btree (A single node btree has depth 0).
566 unregister
567   Detaches all backing devices and closes the cache devices; if dirty data is
568   present it will disable writeback caching and wait for it to be flushed.
570 Sysfs - cache set internal
571 ~~~~~~~~~~~~~~~~~~~~~~~~~~
573 This directory also exposes timings for a number of internal operations, with
574 separate files for average duration, average frequency, last occurrence and max
575 duration: garbage collection, btree read, btree node sorts and btree splits.
577 active_journal_entries
578   Number of journal entries that are newer than the index.
580 btree_nodes
581   Total nodes in the btree.
583 btree_used_percent
584   Average fraction of btree in use.
586 bset_tree_stats
587   Statistics about the auxiliary search trees
589 btree_cache_max_chain
590   Longest chain in the btree node cache's hash table
592 cache_read_races
593   Counts instances where while data was being read from the cache, the bucket
594   was reused and invalidated - i.e. where the pointer was stale after the read
595   completed. When this occurs the data is reread from the backing device.
597 trigger_gc
598   Writing to this file forces garbage collection to run.
600 Sysfs - Cache device
601 ~~~~~~~~~~~~~~~~~~~~
603 Available at /sys/block/<cdev>/bcache
605 block_size
606   Minimum granularity of writes - should match hardware sector size.
608 btree_written
609   Sum of all btree writes, in (kilo/mega/giga) bytes
611 bucket_size
612   Size of buckets
614 cache_replacement_policy
615   One of either lru, fifo or random.
617 discard
618   Boolean; if on a discard/TRIM will be issued to each bucket before it is
619   reused. Defaults to off, since SATA TRIM is an unqueued command (and thus
620   slow).
622 freelist_percent
623   Size of the freelist as a percentage of nbuckets. Can be written to to
624   increase the number of buckets kept on the freelist, which lets you
625   artificially reduce the size of the cache at runtime. Mostly for testing
626   purposes (i.e. testing how different size caches affect your hit rate), but
627   since buckets are discarded when they move on to the freelist will also make
628   the SSD's garbage collection easier by effectively giving it more reserved
629   space.
631 io_errors
632   Number of errors that have occurred, decayed by io_error_halflife.
634 metadata_written
635   Sum of all non data writes (btree writes and all other metadata).
637 nbuckets
638   Total buckets in this cache
640 priority_stats
641   Statistics about how recently data in the cache has been accessed.
642   This can reveal your working set size.  Unused is the percentage of
643   the cache that doesn't contain any data.  Metadata is bcache's
644   metadata overhead.  Average is the average priority of cache buckets.
645   Next is a list of quantiles with the priority threshold of each.
647 written
648   Sum of all data that has been written to the cache; comparison with
649   btree_written gives the amount of write inflation in bcache.