Merge remote-tracking branch 'regmap/topic/sparse' into regmap-next
[firefly-linux-kernel-4.4.55.git] / Documentation / bcache.txt
1 Say you've got a big slow raid 6, and an X-25E or three. Wouldn't it be
2 nice if you could use them as cache... Hence bcache.
3
4 Wiki 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
9 It's designed around the performance characteristics of SSDs - it only allocates
10 in erase block sized buckets, and it uses a hybrid btree/log to track cached
11 extants (which can be anywhere from a single sector to the bucket size). It's
12 designed to avoid random writes at all costs; it fills up an erase block
13 sequentially, then issues a discard before reusing it.
14
15 Both writethrough and writeback caching are supported. Writeback defaults to
16 off, but can be switched on and off arbitrarily at runtime. Bcache goes to
17 great lengths to protect your data - it reliably handles unclean shutdown. (It
18 doesn't even have a notion of a clean shutdown; bcache simply doesn't return
19 writes as completed until they're on stable storage).
20
21 Writeback caching can use most of the cache for buffering writes - writing
22 dirty data to the backing device is always done sequentially, scanning from the
23 start to the end of the index.
24
25 Since random IO is what SSDs excel at, there generally won't be much benefit
26 to caching large sequential IO. Bcache detects sequential IO and skips it;
27 it also keeps a rolling average of the IO sizes per task, and as long as the
28 average is above the cutoff it will skip all IO from that task - instead of
29 caching the first 512k after every seek. Backups and large file copies should
30 thus entirely bypass the cache.
31
32 In the event of a data IO error on the flash it will try to recover by reading
33 from disk or invalidating cache entries.  For unrecoverable errors (meta data
34 or dirty data), caching is automatically disabled; if dirty data was present
35 in the cache it first disables writeback caching and waits for all dirty data
36 to be flushed.
37
38 Getting started:
39 You'll need make-bcache from the bcache-tools repository. Both the cache device
40 and backing device must be formatted before use.
41   make-bcache -B /dev/sdb
42   make-bcache -C /dev/sdc
43
44 make-bcache has the ability to format multiple devices at the same time - if
45 you format your backing devices and cache device at the same time, you won't
46 have to manually attach:
47   make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
48
49 bcache-tools now ships udev rules, and bcache devices are known to the kernel
50 immediately.  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
55 Registering the backing device makes the bcache device show up in /dev; you can
56 now format it and use it as normal. But the first time using a new bcache
57 device, it'll be running in passthrough mode until you attach it to a cache.
58 See the section on attaching.
59
60 The devices show up as:
61
62   /dev/bcache<N>
63
64 As well as (with udev):
65
66   /dev/bcache/by-uuid/<uuid>
67   /dev/bcache/by-label/<label>
68
69 To get started:
70
71   mkfs.ext4 /dev/bcache0
72   mount /dev/bcache0 /mnt
73
74 You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .
75
76 Cache devices are managed as sets; multiple caches per set isn't supported yet
77 but will allow for mirroring of metadata and dirty data in the future. Your new
78 cache set shows up as /sys/fs/bcache/<UUID>
79
80 ATTACHING:
81
82 After your cache device and backing device are registered, the backing device
83 must be attached to your cache set to enable caching. Attaching a backing
84 device 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
89 This only has to be done once. The next time you reboot, just reregister all
90 your 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
92 important if you have writeback caching turned on.
93
94 If you're booting up and your cache device is gone and never coming back, you
95 can 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
101 partition, the bcache directory would be at /sys/block/sdb/sdb2/bcache)
102
103 The backing device will still use that cache set if it shows up in the future,
104 but all the cached data will be invalidated. If there was dirty data in the
105 cache, don't expect the filesystem to be recoverable - you will have massive
106 filesystem corruption, though ext4's fsck does work miracles.
107
108 ERROR HANDLING:
109
110 Bcache tries to transparently handle IO errors to/from the cache device without
111 affecting normal operation; if it sees too many errors (the threshold is
112 configurable, and defaults to 0) it shuts down the cache device and switches all
113 the 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
130 TROUBLESHOOTING PERFORMANCE:
131
132 Bcache has a bunch of config options and tunables. The defaults are intended to
133 be reasonable for typical desktop and server workloads, but they're not what you
134 want 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
196 SYSFS - BACKING DEVICE:
197
198 Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
199 (if attached) /sys/fs/bcache/<cset-uuid>/bdev*
200
201 attach
202   Echo the UUID of a cache set to this file to enable caching.
203
204 cache_mode
205   Can be one of either writethrough, writeback, writearound or none.
206
207 clear_stats
208   Writing to this file resets the running total stats (not the day/hour/5 minute
209   decaying versions).
210
211 detach
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
215 dirty_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
219 label
220   Name of underlying device.
221
222 readahead
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
227 running
228   1 if bcache is running (i.e. whether the /dev/bcache device exists, whether
229   it's in passthrough mode or caching).
230
231 sequential_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
236 sequential_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
243 state
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
256 stop
257   Write to this file to shut down the bcache device and close the backing
258   device.
259
260 writeback_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
265 writeback_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
270 writeback_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
275 writeback_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
280 SYSFS - BACKING DEVICE STATS:
281
282 There are directories with these numbers for a running total, as well as
283 versions that decay over the past day, hour and 5 minutes; they're also
284 aggregated in the cache set directory as well.
285
286 bypassed
287   Amount of IO (both reads and writes) that has bypassed the cache
288
289 cache_hits
290 cache_misses
291 cache_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
295 cache_bypass_hits
296 cache_bypass_misses
297   Hits and misses for IO that is intended to skip the cache are still counted,
298   but broken out here.
299
300 cache_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
305 cache_readaheads
306   Count of times readahead occurred.
307
308 SYSFS - CACHE SET:
309
310 Available at /sys/fs/bcache/<cset-uuid>
311
312 average_key_size
313   Average data per key in the btree.
314
315 bdev<0..n>
316   Symlink to each of the attached backing devices.
317
318 block_size
319   Block size of the cache devices.
320
321 btree_cache_size
322   Amount of memory currently used by the btree cache
323
324 bucket_size
325   Size of buckets
326
327 cache<0..n>
328   Symlink to each of the cache devices comprising this cache set. 
329
330 cache_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
336 clear_stats
337   Clears the statistics associated with this cache
338
339 dirty_data
340   Amount of dirty data is in the cache (updated when garbage collection runs).
341
342 flash_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
346 io_error_halflife
347 io_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
352 journal_delay_ms
353   Journal writes will delay for up to this many milliseconds, unless a cache
354   flush happens sooner. Defaults to 100.
355
356 root_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
360 stop
361   Write to this file to shut down the cache set - waits until all attached
362   backing devices have been shut down.
363
364 tree_depth
365   Depth of the btree (A single node btree has depth 0).
366
367 unregister
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
371 SYSFS - CACHE SET INTERNAL:
372
373 This directory also exposes timings for a number of internal operations, with
374 separate files for average duration, average frequency, last occurrence and max
375 duration: garbage collection, btree read, btree node sorts and btree splits.
376
377 active_journal_entries
378   Number of journal entries that are newer than the index.
379
380 btree_nodes
381   Total nodes in the btree.
382
383 btree_used_percent
384   Average fraction of btree in use.
385
386 bset_tree_stats
387   Statistics about the auxiliary search trees
388
389 btree_cache_max_chain
390   Longest chain in the btree node cache's hash table
391
392 cache_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
397 trigger_gc
398   Writing to this file forces garbage collection to run.
399
400 SYSFS - CACHE DEVICE:
401
402 Available at /sys/block/<cdev>/bcache
403
404 block_size
405   Minimum granularity of writes - should match hardware sector size.
406
407 btree_written
408   Sum of all btree writes, in (kilo/mega/giga) bytes
409
410 bucket_size
411   Size of buckets
412
413 cache_replacement_policy
414   One of either lru, fifo or random.
415
416 discard
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
421 freelist_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
430 io_errors
431   Number of errors that have occurred, decayed by io_error_halflife.
432
433 metadata_written
434   Sum of all non data writes (btree writes and all other metadata).
435
436 nbuckets
437   Total buckets in this cache
438
439 priority_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
446 written
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.