diff options
Diffstat (limited to 'Documentation/bcache.txt')
| -rw-r--r-- | Documentation/bcache.txt | 59 |
1 files changed, 38 insertions, 21 deletions
diff --git a/Documentation/bcache.txt b/Documentation/bcache.txt index 77db8809bd96..32b6c3189d98 100644 --- a/Documentation/bcache.txt +++ b/Documentation/bcache.txt @@ -46,29 +46,33 @@ 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: +bcache-tools now ships udev rules, and bcache devices are known to the kernel +immediately. Without udev, you can manually register devices like this: 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: +Registering the backing device makes the bcache device 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. - echo /dev/sd* > /sys/fs/bcache/register_quiet +The devices show up as: -It'll look for bcache superblocks and ignore everything that doesn't have one. + /dev/bcache<N> -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. +As well as (with udev): -The devices show up at /dev/bcacheN, and can be controlled via sysfs from -/sys/block/bcacheN/bcache: + /dev/bcache/by-uuid/<uuid> + /dev/bcache/by-label/<label> + +To get started: mkfs.ext4 /dev/bcache0 mount /dev/bcache0 /mnt +You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache . + 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> @@ -80,11 +84,11 @@ 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 + echo <CSET-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 +/dev/bcache<N> 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 @@ -181,7 +185,7 @@ want for getting the best possible numbers when benchmarking. In practice this isn't an issue because as soon as a write comes along it'll cause the btree node to be split, and you need almost no write traffic for - this to not show up enough to be noticable (especially since bcache's btree + this to not show up enough to be noticeable (especially since bcache's btree nodes are huge and index large regions of the device). But when you're benchmarking, if you're trying to warm the cache by reading a bunch of data and there's no other traffic - that can be a problem. @@ -191,6 +195,9 @@ want for getting the best possible numbers when benchmarking. SYSFS - BACKING DEVICE: +Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and +(if attached) /sys/fs/bcache/<cset-uuid>/bdev* + attach Echo the UUID of a cache set to this file to enable caching. @@ -222,7 +229,7 @@ running it's in passthrough mode or caching). sequential_cutoff - A sequential IO will bypass the cache once it passes this threshhold; the + A sequential IO will bypass the cache once it passes this threshold; the most recent 128 IOs are tracked so sequential IO can be detected even when it isn't all done at once. @@ -296,10 +303,12 @@ cache_miss_collisions since the synchronization for cache misses was rewritten) cache_readaheads - Count of times readahead occured. + Count of times readahead occurred. SYSFS - CACHE SET: +Available at /sys/fs/bcache/<cset-uuid> + average_key_size Average data per key in the btree. @@ -319,7 +328,10 @@ cache<0..n> Symlink to each of the cache devices comprising this cache set. cache_available_percent - Percentage of cache device free. + Percentage of cache device which doesn't contain dirty data, and could + potentially be used for writeback. This doesn't mean this space isn't used + for clean cached data; the unused statistic (in priority_stats) is typically + much lower. clear_stats Clears the statistics associated with this cache @@ -359,7 +371,7 @@ unregister 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 +separate files for average duration, average frequency, last occurrence and max duration: garbage collection, btree read, btree node sorts and btree splits. active_journal_entries @@ -387,6 +399,8 @@ trigger_gc SYSFS - CACHE DEVICE: +Available at /sys/block/<cdev>/bcache + block_size Minimum granularity of writes - should match hardware sector size. @@ -414,7 +428,7 @@ freelist_percent space. io_errors - Number of errors that have occured, decayed by io_error_halflife. + Number of errors that have occurred, decayed by io_error_halflife. metadata_written Sum of all non data writes (btree writes and all other metadata). @@ -423,8 +437,11 @@ 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. + Statistics about how recently data in the cache has been accessed. + This can reveal your working set size. Unused is the percentage of + the cache that doesn't contain any data. Metadata is bcache's + metadata overhead. Average is the average priority of cache buckets. + Next is a list of quantiles with the priority threshold of each. written Sum of all data that has been written to the cache; comparison with |