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