linux/Documentation/bcache.txt
<<
>>
Prefs
   1Say you've got a big slow raid 6, and an X-25E or three. Wouldn't it be
   2nice if you could use them as cache... Hence bcache.
   3
   4Wiki and git repositories are at:
   5  http://bcache.evilpiepirate.org
   6  http://evilpiepirate.org/git/linux-bcache.git
   7  http://evilpiepirate.org/git/bcache-tools.git
   8
   9It's designed around the performance characteristics of SSDs - it only allocates
  10in erase block sized buckets, and it uses a hybrid btree/log to track cached
  11extants (which can be anywhere from a single sector to the bucket size). It's
  12designed to avoid random writes at all costs; it fills up an erase block
  13sequentially, then issues a discard before reusing it.
  14
  15Both writethrough and writeback caching are supported. Writeback defaults to
  16off, but can be switched on and off arbitrarily at runtime. Bcache goes to
  17great lengths to protect your data - it reliably handles unclean shutdown. (It
  18doesn't even have a notion of a clean shutdown; bcache simply doesn't return
  19writes as completed until they're on stable storage).
  20
  21Writeback caching can use most of the cache for buffering writes - writing
  22dirty data to the backing device is always done sequentially, scanning from the
  23start to the end of the index.
  24
  25Since random IO is what SSDs excel at, there generally won't be much benefit
  26to caching large sequential IO. Bcache detects sequential IO and skips it;
  27it also keeps a rolling average of the IO sizes per task, and as long as the
  28average is above the cutoff it will skip all IO from that task - instead of
  29caching the first 512k after every seek. Backups and large file copies should
  30thus entirely bypass the cache.
  31
  32In the event of a data IO error on the flash it will try to recover by reading
  33from disk or invalidating cache entries.  For unrecoverable errors (meta data
  34or dirty data), caching is automatically disabled; if dirty data was present
  35in the cache it first disables writeback caching and waits for all dirty data
  36to be flushed.
  37
  38Getting started:
  39You'll need make-bcache from the bcache-tools repository. Both the cache device
  40and backing device must be formatted before use.
  41  make-bcache -B /dev/sdb
  42  make-bcache -C /dev/sdc
  43
  44make-bcache has the ability to format multiple devices at the same time - if
  45you format your backing devices and cache device at the same time, you won't
  46have to manually attach:
  47  make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
  48
  49bcache-tools now ships udev rules, and bcache devices are known to the kernel
  50immediately.  Without udev, you can manually register devices like this:
  51
  52  echo /dev/sdb > /sys/fs/bcache/register
  53  echo /dev/sdc > /sys/fs/bcache/register
  54
  55Registering the backing device makes the bcache device show up in /dev; you can
  56now format it and use it as normal. But the first time using a new bcache
  57device, it'll be running in passthrough mode until you attach it to a cache.
  58See the section on attaching.
  59
  60The devices show up as:
  61
  62  /dev/bcache<N>
  63
  64As well as (with udev):
  65
  66  /dev/bcache/by-uuid/<uuid>
  67  /dev/bcache/by-label/<label>
  68
  69To get started:
  70
  71  mkfs.ext4 /dev/bcache0
  72  mount /dev/bcache0 /mnt
  73
  74You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .
  75
  76Cache devices are managed as sets; multiple caches per set isn't supported yet
  77but will allow for mirroring of metadata and dirty data in the future. Your new
  78cache set shows up as /sys/fs/bcache/<UUID>
  79
  80ATTACHING:
  81
  82After your cache device and backing device are registered, the backing device
  83must be attached to your cache set to enable caching. Attaching a backing
  84device to a cache set is done thusly, with the UUID of the cache set in
  85/sys/fs/bcache:
  86
  87  echo <CSET-UUID> > /sys/block/bcache0/bcache/attach
  88
  89This only has to be done once. The next time you reboot, just reregister all
  90your bcache devices. If a backing device has data in a cache somewhere, the
  91/dev/bcache<N> device won't be created until the cache shows up - particularly
  92important if you have writeback caching turned on.
  93
  94If you're booting up and your cache device is gone and never coming back, you
  95can force run the backing device:
  96
  97  echo 1 > /sys/block/sdb/bcache/running
  98
  99(You need to use /sys/block/sdb (or whatever your backing device is called), not
 100/sys/block/bcache0, because bcache0 doesn't exist yet. If you're using a
 101partition, the bcache directory would be at /sys/block/sdb/sdb2/bcache)
 102
 103The backing device will still use that cache set if it shows up in the future,
 104but all the cached data will be invalidated. If there was dirty data in the
 105cache, don't expect the filesystem to be recoverable - you will have massive
 106filesystem corruption, though ext4's fsck does work miracles.
 107
 108ERROR HANDLING:
 109
 110Bcache tries to transparently handle IO errors to/from the cache device without
 111affecting normal operation; if it sees too many errors (the threshold is
 112configurable, and defaults to 0) it shuts down the cache device and switches all
 113the backing devices to passthrough mode.
 114
 115 - For reads from the cache, if they error we just retry the read from the
 116   backing device.
 117
 118 - For writethrough writes, if the write to the cache errors we just switch to
 119   invalidating the data at that lba in the cache (i.e. the same thing we do for
 120   a write that bypasses the cache)
 121
 122 - For writeback writes, we currently pass that error back up to the
 123   filesystem/userspace. This could be improved - we could retry it as a write
 124   that skips the cache so we don't have to error the write.
 125
 126 - When we detach, we first try to flush any dirty data (if we were running in
 127   writeback mode). It currently doesn't do anything intelligent if it fails to
 128   read some of the dirty data, though.
 129
 130TROUBLESHOOTING PERFORMANCE:
 131
 132Bcache has a bunch of config options and tunables. The defaults are intended to
 133be reasonable for typical desktop and server workloads, but they're not what you
 134want for getting the best possible numbers when benchmarking.
 135
 136 - Bad write performance
 137
 138   If write performance is not what you expected, you probably wanted to be
 139   running in writeback mode, which isn't the default (not due to a lack of
 140   maturity, but simply because in writeback mode you'll lose data if something
 141   happens to your SSD)
 142
 143   # echo writeback > /sys/block/bcache0/cache_mode
 144
 145 - Bad performance, or traffic not going to the SSD that you'd expect
 146
 147   By default, bcache doesn't cache everything. It tries to skip sequential IO -
 148   because you really want to be caching the random IO, and if you copy a 10
 149   gigabyte file you probably don't want that pushing 10 gigabytes of randomly
 150   accessed data out of your cache.
 151
 152   But if you want to benchmark reads from cache, and you start out with fio
 153   writing an 8 gigabyte test file - so you want to disable that.
 154
 155   # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff
 156
 157   To set it back to the default (4 mb), do
 158
 159   # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff
 160
 161 - Traffic's still going to the spindle/still getting cache misses
 162
 163   In the real world, SSDs don't always keep up with disks - particularly with
 164   slower SSDs, many disks being cached by one SSD, or mostly sequential IO. So
 165   you want to avoid being bottlenecked by the SSD and having it slow everything
 166   down.
 167
 168   To avoid that bcache tracks latency to the cache device, and gradually
 169   throttles traffic if the latency exceeds a threshold (it does this by
 170   cranking down the sequential bypass).
 171
 172   You can disable this if you need to by setting the thresholds to 0:
 173
 174   # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us
 175   # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us
 176
 177   The default is 2000 us (2 milliseconds) for reads, and 20000 for writes.
 178
 179 - Still getting cache misses, of the same data
 180
 181   One last issue that sometimes trips people up is actually an old bug, due to
 182   the way cache coherency is handled for cache misses. If a btree node is full,
 183   a cache miss won't be able to insert a key for the new data and the data
 184   won't be written to the cache.
 185
 186   In practice this isn't an issue because as soon as a write comes along it'll
 187   cause the btree node to be split, and you need almost no write traffic for
 188   this to not show up enough to be noticeable (especially since bcache's btree
 189   nodes are huge and index large regions of the device). But when you're
 190   benchmarking, if you're trying to warm the cache by reading a bunch of data
 191   and there's no other traffic - that can be a problem.
 192
 193   Solution: warm the cache by doing writes, or use the testing branch (there's
 194   a fix for the issue there).
 195
 196SYSFS - BACKING DEVICE:
 197
 198Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
 199(if attached) /sys/fs/bcache/<cset-uuid>/bdev*
 200
 201attach
 202  Echo the UUID of a cache set to this file to enable caching.
 203
 204cache_mode
 205  Can be one of either writethrough, writeback, writearound or none.
 206
 207clear_stats
 208  Writing to this file resets the running total stats (not the day/hour/5 minute
 209  decaying versions).
 210
 211detach
 212  Write to this file to detach from a cache set. If there is dirty data in the
 213  cache, it will be flushed first.
 214
 215dirty_data
 216  Amount of dirty data for this backing device in the cache. Continuously
 217  updated unlike the cache set's version, but may be slightly off.
 218
 219label
 220  Name of underlying device.
 221
 222readahead
 223  Size of readahead that should be performed.  Defaults to 0.  If set to e.g.
 224  1M, it will round cache miss reads up to that size, but without overlapping
 225  existing cache entries.
 226
 227running
 228  1 if bcache is running (i.e. whether the /dev/bcache device exists, whether
 229  it's in passthrough mode or caching).
 230
 231sequential_cutoff
 232  A sequential IO will bypass the cache once it passes this threshold; the
 233  most recent 128 IOs are tracked so sequential IO can be detected even when
 234  it isn't all done at once.
 235
 236sequential_merge
 237  If non zero, bcache keeps a list of the last 128 requests submitted to compare
 238  against all new requests to determine which new requests are sequential
 239  continuations of previous requests for the purpose of determining sequential
 240  cutoff. This is necessary if the sequential cutoff value is greater than the
 241  maximum acceptable sequential size for any single request. 
 242
 243state
 244  The backing device can be in one of four different states:
 245
 246  no cache: Has never been attached to a cache set.
 247
 248  clean: Part of a cache set, and there is no cached dirty data.
 249
 250  dirty: Part of a cache set, and there is cached dirty data.
 251
 252  inconsistent: The backing device was forcibly run by the user when there was
 253  dirty data cached but the cache set was unavailable; whatever data was on the
 254  backing device has likely been corrupted.
 255
 256stop
 257  Write to this file to shut down the bcache device and close the backing
 258  device.
 259
 260writeback_delay
 261  When dirty data is written to the cache and it previously did not contain
 262  any, waits some number of seconds before initiating writeback. Defaults to
 263  30.
 264
 265writeback_percent
 266  If nonzero, bcache tries to keep around this percentage of the cache dirty by
 267  throttling background writeback and using a PD controller to smoothly adjust
 268  the rate.
 269
 270writeback_rate
 271  Rate in sectors per second - if writeback_percent is nonzero, background
 272  writeback is throttled to this rate. Continuously adjusted by bcache but may
 273  also be set by the user.
 274
 275writeback_running
 276  If off, writeback of dirty data will not take place at all. Dirty data will
 277  still be added to the cache until it is mostly full; only meant for
 278  benchmarking. Defaults to on.
 279
 280SYSFS - BACKING DEVICE STATS:
 281
 282There are directories with these numbers for a running total, as well as
 283versions that decay over the past day, hour and 5 minutes; they're also
 284aggregated in the cache set directory as well.
 285
 286bypassed
 287  Amount of IO (both reads and writes) that has bypassed the cache
 288
 289cache_hits
 290cache_misses
 291cache_hit_ratio
 292  Hits and misses are counted per individual IO as bcache sees them; a
 293  partial hit is counted as a miss.
 294
 295cache_bypass_hits
 296cache_bypass_misses
 297  Hits and misses for IO that is intended to skip the cache are still counted,
 298  but broken out here.
 299
 300cache_miss_collisions
 301  Counts instances where data was going to be inserted into the cache from a
 302  cache miss, but raced with a write and data was already present (usually 0
 303  since the synchronization for cache misses was rewritten)
 304
 305cache_readaheads
 306  Count of times readahead occurred.
 307
 308SYSFS - CACHE SET:
 309
 310Available at /sys/fs/bcache/<cset-uuid>
 311
 312average_key_size
 313  Average data per key in the btree.
 314
 315bdev<0..n>
 316  Symlink to each of the attached backing devices.
 317
 318block_size
 319  Block size of the cache devices.
 320
 321btree_cache_size
 322  Amount of memory currently used by the btree cache
 323
 324bucket_size
 325  Size of buckets
 326
 327cache<0..n>
 328  Symlink to each of the cache devices comprising this cache set. 
 329
 330cache_available_percent
 331  Percentage of cache device which doesn't contain dirty data, and could
 332  potentially be used for writeback.  This doesn't mean this space isn't used
 333  for clean cached data; the unused statistic (in priority_stats) is typically
 334  much lower.
 335
 336clear_stats
 337  Clears the statistics associated with this cache
 338
 339dirty_data
 340  Amount of dirty data is in the cache (updated when garbage collection runs).
 341
 342flash_vol_create
 343  Echoing a size to this file (in human readable units, k/M/G) creates a thinly
 344  provisioned volume backed by the cache set.
 345
 346io_error_halflife
 347io_error_limit
 348  These determines how many errors we accept before disabling the cache.
 349  Each error is decayed by the half life (in # ios).  If the decaying count
 350  reaches io_error_limit dirty data is written out and the cache is disabled.
 351
 352journal_delay_ms
 353  Journal writes will delay for up to this many milliseconds, unless a cache
 354  flush happens sooner. Defaults to 100.
 355
 356root_usage_percent
 357  Percentage of the root btree node in use.  If this gets too high the node
 358  will split, increasing the tree depth.
 359
 360stop
 361  Write to this file to shut down the cache set - waits until all attached
 362  backing devices have been shut down.
 363
 364tree_depth
 365  Depth of the btree (A single node btree has depth 0).
 366
 367unregister
 368  Detaches all backing devices and closes the cache devices; if dirty data is
 369  present it will disable writeback caching and wait for it to be flushed.
 370
 371SYSFS - CACHE SET INTERNAL:
 372
 373This directory also exposes timings for a number of internal operations, with
 374separate files for average duration, average frequency, last occurrence and max
 375duration: garbage collection, btree read, btree node sorts and btree splits.
 376
 377active_journal_entries
 378  Number of journal entries that are newer than the index.
 379
 380btree_nodes
 381  Total nodes in the btree.
 382
 383btree_used_percent
 384  Average fraction of btree in use.
 385
 386bset_tree_stats
 387  Statistics about the auxiliary search trees
 388
 389btree_cache_max_chain
 390  Longest chain in the btree node cache's hash table
 391
 392cache_read_races
 393  Counts instances where while data was being read from the cache, the bucket
 394  was reused and invalidated - i.e. where the pointer was stale after the read
 395  completed. When this occurs the data is reread from the backing device.
 396
 397trigger_gc
 398  Writing to this file forces garbage collection to run.
 399
 400SYSFS - CACHE DEVICE:
 401
 402Available at /sys/block/<cdev>/bcache
 403
 404block_size
 405  Minimum granularity of writes - should match hardware sector size.
 406
 407btree_written
 408  Sum of all btree writes, in (kilo/mega/giga) bytes
 409
 410bucket_size
 411  Size of buckets
 412
 413cache_replacement_policy
 414  One of either lru, fifo or random.
 415
 416discard
 417  Boolean; if on a discard/TRIM will be issued to each bucket before it is
 418  reused. Defaults to off, since SATA TRIM is an unqueued command (and thus
 419  slow).
 420
 421freelist_percent
 422  Size of the freelist as a percentage of nbuckets. Can be written to to
 423  increase the number of buckets kept on the freelist, which lets you
 424  artificially reduce the size of the cache at runtime. Mostly for testing
 425  purposes (i.e. testing how different size caches affect your hit rate), but
 426  since buckets are discarded when they move on to the freelist will also make
 427  the SSD's garbage collection easier by effectively giving it more reserved
 428  space.
 429
 430io_errors
 431  Number of errors that have occurred, decayed by io_error_halflife.
 432
 433metadata_written
 434  Sum of all non data writes (btree writes and all other metadata).
 435
 436nbuckets
 437  Total buckets in this cache
 438
 439priority_stats
 440  Statistics about how recently data in the cache has been accessed.
 441  This can reveal your working set size.  Unused is the percentage of
 442  the cache that doesn't contain any data.  Metadata is bcache's
 443  metadata overhead.  Average is the average priority of cache buckets.
 444  Next is a list of quantiles with the priority threshold of each.
 445
 446written
 447  Sum of all data that has been written to the cache; comparison with
 448  btree_written gives the amount of write inflation in bcache.
 449
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.