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