Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit cafe5635 authored by Kent Overstreet's avatar Kent Overstreet
Browse files

bcache: A block layer cache 

Does writethrough and writeback caching, handles unclean shutdown, and
has a bunch of other nifty features motivated by real world usage.

See the wiki at http://bcache.evilpiepirate.org

 for more.

Signed-off-by: default avatarKent Overstreet <koverstreet@google.com>
parent ea6749c7

Documentation/ABI/testing/sysfs-block-bcache

0 → 100644
+156 −0
Original line number Diff line number Diff line 
What:		/sys/block/<disk>/bcache/unregister

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		A write to this file causes the backing device or cache to be

		unregistered. If a backing device had dirty data in the cache,

		writeback mode is automatically disabled and all dirty data is

		flushed before the device is unregistered. Caches unregister

		all associated backing devices before unregistering themselves.



What:		/sys/block/<disk>/bcache/clear_stats

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		Writing to this file resets all the statistics for the device.



What:		/sys/block/<disk>/bcache/cache

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a backing device that has cache, a symlink to

		the bcache/ dir of that cache.



What:		/sys/block/<disk>/bcache/cache_hits

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: integer number of full cache hits,

		counted per bio. A partial cache hit counts as a miss.



What:		/sys/block/<disk>/bcache/cache_misses

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: integer number of cache misses.



What:		/sys/block/<disk>/bcache/cache_hit_ratio

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: cache hits as a percentage.



What:		/sys/block/<disk>/bcache/sequential_cutoff

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: Threshold past which sequential IO will

		skip the cache. Read and written as bytes in human readable

		units (i.e. echo 10M > sequntial_cutoff).



What:		/sys/block/<disk>/bcache/bypassed

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		Sum of all reads and writes that have bypassed the cache (due

		to the sequential cutoff).  Expressed as bytes in human

		readable units.



What:		/sys/block/<disk>/bcache/writeback

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: When on, writeback caching is enabled and

		writes will be buffered in the cache. When off, caching is in

		writethrough mode; reads and writes will be added to the

		cache but no write buffering will take place.



What:		/sys/block/<disk>/bcache/writeback_running

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: when off, dirty data will not be written

		from the cache to the backing device. The cache will still be

		used to buffer writes until it is mostly full, at which point

		writes transparently revert to writethrough mode. Intended only

		for benchmarking/testing.



What:		/sys/block/<disk>/bcache/writeback_delay

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: In writeback mode, when dirty data is

		written to the cache and the cache held no dirty data for that

		backing device, writeback from cache to backing device starts

		after this delay, expressed as an integer number of seconds.



What:		/sys/block/<disk>/bcache/writeback_percent

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For backing devices: If nonzero, writeback from cache to

		backing device only takes place when more than this percentage

		of the cache is used, allowing more write coalescing to take

		place and reducing total number of writes sent to the backing

		device. Integer between 0 and 40.



What:		/sys/block/<disk>/bcache/synchronous

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a cache, a boolean that allows synchronous mode to be

		switched on and off. In synchronous mode all writes are ordered

		such that the cache can reliably recover from unclean shutdown;

		if disabled bcache will not generally wait for writes to

		complete but if the cache is not shut down cleanly all data

		will be discarded from the cache. Should not be turned off with

		writeback caching enabled.



What:		/sys/block/<disk>/bcache/discard

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a cache, a boolean allowing discard/TRIM to be turned off

		or back on if the device supports it.



What:		/sys/block/<disk>/bcache/bucket_size

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a cache, bucket size in human readable units, as set at

		cache creation time; should match the erase block size of the

		SSD for optimal performance.



What:		/sys/block/<disk>/bcache/nbuckets

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a cache, the number of usable buckets.



What:		/sys/block/<disk>/bcache/tree_depth

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a cache, height of the btree excluding leaf nodes (i.e. a

		one node tree will have a depth of 0).



What:		/sys/block/<disk>/bcache/btree_cache_size

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		Number of btree buckets/nodes that are currently cached in

		memory; cache dynamically grows and shrinks in response to

		memory pressure from the rest of the system.



What:		/sys/block/<disk>/bcache/written

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a cache, total amount of data in human readable units

		written to the cache, excluding all metadata.



What:		/sys/block/<disk>/bcache/btree_written

Date:		November 2010

Contact:	Kent Overstreet <kent.overstreet@gmail.com>

Description:

		For a cache, sum of all btree writes in human readable units.

Documentation/bcache.txt

0 → 100644
+343 −0
Original line number Diff line number Diff line 
Say you've got a big slow raid 6, and an X-25E or three. Wouldn't it be

nice if you could use them as cache... Hence bcache.



Wiki and git repositories are at:

  http://bcache.evilpiepirate.org

  http://evilpiepirate.org/git/linux-bcache.git

  http://evilpiepirate.org/git/bcache-tools.git



It's designed around the performance characteristics of SSDs - it only allocates

in erase block sized buckets, and it uses a hybrid btree/log to track cached

extants (which can be anywhere from a single sector to the bucket size). It's

designed to avoid random writes at all costs; it fills up an erase block

sequentially, then issues a discard before reusing it.



Both writethrough and writeback caching are supported. Writeback defaults to

off, but can be switched on and off arbitrarily at runtime. Bcache goes to

great lengths to protect your data - it reliably handles unclean shutdown. (It

doesn't even have a notion of a clean shutdown; bcache simply doesn't return

writes as completed until they're on stable storage).



Writeback caching can use most of the cache for buffering writes - writing

dirty data to the backing device is always done sequentially, scanning from the

start to the end of the index.



Since random IO is what SSDs excel at, there generally won't be much benefit

to caching large sequential IO. Bcache detects sequential IO and skips it;

it also keeps a rolling average of the IO sizes per task, and as long as the

average is above the cutoff it will skip all IO from that task - instead of

caching the first 512k after every seek. Backups and large file copies should

thus entirely bypass the cache.



In the event of a data IO error on the flash it will try to recover by reading

from disk or invalidating cache entries.  For unrecoverable errors (meta data

or dirty data), caching is automatically disabled; if dirty data was present

in the cache it first disables writeback caching and waits for all dirty data

to be flushed.



Getting started:

You'll need make-bcache from the bcache-tools repository. Both the cache device

and backing device must be formatted before use.

  make-bcache -B /dev/sdb

  make-bcache -C /dev/sdc



make-bcache has the ability to format multiple devices at the same time - if

you format your backing devices and cache device at the same time, you won't

have to manually attach:

  make-bcache -B /dev/sda /dev/sdb -C /dev/sdc



To make bcache devices known to the kernel, echo them to /sys/fs/bcache/register:



  echo /dev/sdb > /sys/fs/bcache/register

  echo /dev/sdc > /sys/fs/bcache/register



To register your bcache devices automatically, you could add something like

this to an init script:



  echo /dev/sd* > /sys/fs/bcache/register_quiet



It'll look for bcache superblocks and ignore everything that doesn't have one.



Registering the backing device makes the bcache show up in /dev; you can now

format it and use it as normal. But the first time using a new bcache device,

it'll be running in passthrough mode until you attach it to a cache. See the

section on attaching.



The devices show up at /dev/bcacheN, and can be controlled via sysfs from

/sys/block/bcacheN/bcache:



  mkfs.ext4 /dev/bcache0

  mount /dev/bcache0 /mnt



Cache devices are managed as sets; multiple caches per set isn't supported yet

but will allow for mirroring of metadata and dirty data in the future. Your new

cache set shows up as /sys/fs/bcache/<UUID>



ATTACHING:



After your cache device and backing device are registered, the backing device

must be attached to your cache set to enable caching. Attaching a backing

device to a cache set is done thusly, with the UUID of the cache set in

/sys/fs/bcache:



  echo <UUID> > /sys/block/bcache0/bcache/attach



This only has to be done once. The next time you reboot, just reregister all

your bcache devices. If a backing device has data in a cache somewhere, the

/dev/bcache# device won't be created until the cache shows up - particularly

important if you have writeback caching turned on.



If you're booting up and your cache device is gone and never coming back, you

can force run the backing device:



  echo 1 > /sys/block/sdb/bcache/running



(You need to use /sys/block/sdb (or whatever your backing device is called), not

/sys/block/bcache0, because bcache0 doesn't exist yet. If you're using a

partition, the bcache directory would be at /sys/block/sdb/sdb2/bcache)



The backing device will still use that cache set if it shows up in the future,

but all the cached data will be invalidated. If there was dirty data in the

cache, don't expect the filesystem to be recoverable - you will have massive

filesystem corruption, though ext4's fsck does work miracles.



SYSFS - BACKING DEVICE:



attach

  Echo the UUID of a cache set to this file to enable caching.



cache_mode

  Can be one of either writethrough, writeback, writearound or none.



clear_stats

  Writing to this file resets the running total stats (not the day/hour/5 minute

  decaying versions).



detach

  Write to this file to detach from a cache set. If there is dirty data in the

  cache, it will be flushed first.



dirty_data

  Amount of dirty data for this backing device in the cache. Continuously

  updated unlike the cache set's version, but may be slightly off.



label

  Name of underlying device.



readahead

  Size of readahead that should be performed.  Defaults to 0.  If set to e.g.

  1M, it will round cache miss reads up to that size, but without overlapping

  existing cache entries.



running

  1 if bcache is running (i.e. whether the /dev/bcache device exists, whether

  it's in passthrough mode or caching).



sequential_cutoff

  A sequential IO will bypass the cache once it passes this threshhold; the

  most recent 128 IOs are tracked so sequential IO can be detected even when

  it isn't all done at once.



sequential_merge

  If non zero, bcache keeps a list of the last 128 requests submitted to compare

  against all new requests to determine which new requests are sequential

  continuations of previous requests for the purpose of determining sequential

  cutoff. This is necessary if the sequential cutoff value is greater than the

  maximum acceptable sequential size for any single request. 



state

  The backing device can be in one of four different states:



  no cache: Has never been attached to a cache set.



  clean: Part of a cache set, and there is no cached dirty data.



  dirty: Part of a cache set, and there is cached dirty data.



  inconsistent: The backing device was forcibly run by the user when there was

  dirty data cached but the cache set was unavailable; whatever data was on the

  backing device has likely been corrupted.



stop

  Write to this file to shut down the bcache device and close the backing

  device.



writeback_delay

  When dirty data is written to the cache and it previously did not contain

  any, waits some number of seconds before initiating writeback. Defaults to

  30.



writeback_percent

  If nonzero, bcache tries to keep around this percentage of the cache dirty by

  throttling background writeback and using a PD controller to smoothly adjust

  the rate.



writeback_rate

  Rate in sectors per second - if writeback_percent is nonzero, background

  writeback is throttled to this rate. Continuously adjusted by bcache but may

  also be set by the user.



writeback_running

  If off, writeback of dirty data will not take place at all. Dirty data will

  still be added to the cache until it is mostly full; only meant for

  benchmarking. Defaults to on.



SYSFS - BACKING DEVICE STATS:



There are directories with these numbers for a running total, as well as

versions that decay over the past day, hour and 5 minutes; they're also

aggregated in the cache set directory as well.



bypassed

  Amount of IO (both reads and writes) that has bypassed the cache



cache_hits

cache_misses

cache_hit_ratio

  Hits and misses are counted per individual IO as bcache sees them; a

  partial hit is counted as a miss.



cache_bypass_hits

cache_bypass_misses

  Hits and misses for IO that is intended to skip the cache are still counted,

  but broken out here.



cache_miss_collisions

  Counts instances where data was going to be inserted into the cache from a

  cache miss, but raced with a write and data was already present (usually 0

  since the synchronization for cache misses was rewritten)



cache_readaheads

  Count of times readahead occured.



SYSFS - CACHE SET:



average_key_size

  Average data per key in the btree.



bdev<0..n>

  Symlink to each of the attached backing devices.



block_size

  Block size of the cache devices.



btree_cache_size

  Amount of memory currently used by the btree cache



bucket_size

  Size of buckets



cache<0..n>

  Symlink to each of the cache devices comprising this cache set. 



cache_available_percent

  Percentage of cache device free.



clear_stats

  Clears the statistics associated with this cache



dirty_data

  Amount of dirty data is in the cache (updated when garbage collection runs).



flash_vol_create

  Echoing a size to this file (in human readable units, k/M/G) creates a thinly

  provisioned volume backed by the cache set.



io_error_halflife

io_error_limit

  These determines how many errors we accept before disabling the cache.

  Each error is decayed by the half life (in # ios).  If the decaying count

  reaches io_error_limit dirty data is written out and the cache is disabled.



journal_delay_ms

  Journal writes will delay for up to this many milliseconds, unless a cache

  flush happens sooner. Defaults to 100.



root_usage_percent

  Percentage of the root btree node in use.  If this gets too high the node

  will split, increasing the tree depth.



stop

  Write to this file to shut down the cache set - waits until all attached

  backing devices have been shut down.



tree_depth

  Depth of the btree (A single node btree has depth 0).



unregister

  Detaches all backing devices and closes the cache devices; if dirty data is

  present it will disable writeback caching and wait for it to be flushed.



SYSFS - CACHE SET INTERNAL:



This directory also exposes timings for a number of internal operations, with

separate files for average duration, average frequency, last occurence and max

duration: garbage collection, btree read, btree node sorts and btree splits.



active_journal_entries

  Number of journal entries that are newer than the index.



btree_nodes

  Total nodes in the btree.



btree_used_percent

  Average fraction of btree in use.



bset_tree_stats

  Statistics about the auxiliary search trees



btree_cache_max_chain

  Longest chain in the btree node cache's hash table



cache_read_races

  Counts instances where while data was being read from the cache, the bucket

  was reused and invalidated - i.e. where the pointer was stale after the read

  completed. When this occurs the data is reread from the backing device.



trigger_gc

  Writing to this file forces garbage collection to run.



SYSFS - CACHE DEVICE:



block_size

  Minimum granularity of writes - should match hardware sector size.



btree_written

  Sum of all btree writes, in (kilo/mega/giga) bytes



bucket_size

  Size of buckets



cache_replacement_policy

  One of either lru, fifo or random.



discard

  Boolean; if on a discard/TRIM will be issued to each bucket before it is

  reused. Defaults to off, since SATA TRIM is an unqueued command (and thus

  slow).



freelist_percent

  Size of the freelist as a percentage of nbuckets. Can be written to to

  increase the number of buckets kept on the freelist, which lets you

  artificially reduce the size of the cache at runtime. Mostly for testing

  purposes (i.e. testing how different size caches affect your hit rate), but

  since buckets are discarded when they move on to the freelist will also make

  the SSD's garbage collection easier by effectively giving it more reserved

  space.



io_errors

  Number of errors that have occured, decayed by io_error_halflife.



metadata_written

  Sum of all non data writes (btree writes and all other metadata).



nbuckets

  Total buckets in this cache



priority_stats

  Statistics about how recently data in the cache has been accessed.  This can

  reveal your working set size.



written

  Sum of all data that has been written to the cache; comparison with

  btree_written gives the amount of write inflation in bcache.

MAINTAINERS

+7 −0
Original line number Diff line number Diff line
@@ -1616,6 +1616,13 @@ W: http://www.baycom.org/~tom/ham/ham.html 
S:	Maintained

F:	drivers/net/hamradio/baycom*



BCACHE (BLOCK LAYER CACHE)

M:	Kent Overstreet <koverstreet@google.com>

L:	linux-bcache@vger.kernel.org

W:	http://bcache.evilpiepirate.org

S:	Maintained:

F:	drivers/md/bcache/



BEFS FILE SYSTEM

S:	Orphan

F:	Documentation/filesystems/befs.txt

drivers/md/Kconfig

+2 −0
Original line number Diff line number Diff line
@@ -174,6 +174,8 @@ config MD_FAULTY 


	  In unsure, say N.



source "drivers/md/bcache/Kconfig"



config BLK_DEV_DM

	tristate "Device mapper support"

	---help---

drivers/md/Makefile

+1 −0
Original line number Diff line number Diff line
@@ -29,6 +29,7 @@ obj-$(CONFIG_MD_RAID10) += raid10.o 
obj-$(CONFIG_MD_RAID456)	+= raid456.o

obj-$(CONFIG_MD_MULTIPATH)	+= multipath.o

obj-$(CONFIG_MD_FAULTY)		+= faulty.o

obj-$(CONFIG_BCACHE)		+= bcache/

obj-$(CONFIG_BLK_DEV_MD)	+= md-mod.o

obj-$(CONFIG_BLK_DEV_DM)	+= dm-mod.o

obj-$(CONFIG_DM_BUFIO)		+= dm-bufio.o