android/android_kernel_samsung_sm8650
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bcache.txt: standardize document format

Browse Source 
Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Add a title for the document;
- Use a list for the listed URLs;
- mark literal blocks;
- adjust whitespaces;
- Don't capitalize section titles.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2017-05-14 07:49:15 -03:00 committed by Jonathan Corbet
parent b86faee6d1
commit a966ac73d7
1 changed files with 107 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
Documentation/bcache.txt
View File

@ -1,10 +1,15 @@
============================
A block layer cache (bcache)
============================
Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
nice if you could use them as cache... Hence bcache. nice if you could use them as cache... Hence bcache.
Wiki and git repositories are at: Wiki and git repositories are at:
http://bcache.evilpiepirate.org
http://evilpiepirate.org/git/linux-bcache.git - http://bcache.evilpiepirate.org
http://evilpiepirate.org/git/bcache-tools.git - 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 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 in erase block sized buckets, and it uses a hybrid btree/log to track cached
@ -37,17 +42,19 @@ to be flushed.
Getting started: Getting started:
You'll need make-bcache from the bcache-tools repository. Both the cache device You'll need make-bcache from the bcache-tools repository. Both the cache device
and backing device must be formatted before use. and backing device must be formatted before use::
make-bcache -B /dev/sdb make-bcache -B /dev/sdb
make-bcache -C /dev/sdc make-bcache -C /dev/sdc
make-bcache has the ability to format multiple devices at the same time - if 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 you format your backing devices and cache device at the same time, you won't
have to manually attach: have to manually attach::
make-bcache -B /dev/sda /dev/sdb -C /dev/sdc make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
bcache-tools now ships udev rules, and bcache devices are known to the kernel bcache-tools now ships udev rules, and bcache devices are known to the kernel
immediately. Without udev, you can manually register devices like this: immediately. Without udev, you can manually register devices like this::
echo /dev/sdb > /sys/fs/bcache/register echo /dev/sdb > /sys/fs/bcache/register
echo /dev/sdc > /sys/fs/bcache/register echo /dev/sdc > /sys/fs/bcache/register
@ -60,16 +67,16 @@ slow devices as bcache backing devices without a cache, and you can choose to ad
a caching device later. a caching device later.
See 'ATTACHING' section below. See 'ATTACHING' section below.
The devices show up as: The devices show up as::
/dev/bcache<N> /dev/bcache<N>
As well as (with udev): As well as (with udev)::
/dev/bcache/by-uuid/<uuid> /dev/bcache/by-uuid/<uuid>
/dev/bcache/by-label/<label> /dev/bcache/by-label/<label>
To get started: To get started::
mkfs.ext4 /dev/bcache0 mkfs.ext4 /dev/bcache0
mount /dev/bcache0 /mnt mount /dev/bcache0 /mnt
@ -81,13 +88,13 @@ 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 but will allow for mirroring of metadata and dirty data in the future. Your new
cache set shows up as /sys/fs/bcache/<UUID> cache set shows up as /sys/fs/bcache/<UUID>
ATTACHING Attaching
--------- ---------
After your cache device and backing device are registered, the backing device 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 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 device to a cache set is done thusly, with the UUID of the cache set in
/sys/fs/bcache: /sys/fs/bcache::
echo <CSET-UUID> > /sys/block/bcache0/bcache/attach echo <CSET-UUID> > /sys/block/bcache0/bcache/attach
@ -97,7 +104,7 @@ your bcache devices. If a backing device has data in a cache somewhere, the
important if you have writeback caching turned on. important if you have writeback caching turned on.
If you're booting up and your cache device is gone and never coming back, you If you're booting up and your cache device is gone and never coming back, you
can force run the backing device: can force run the backing device::
echo 1 > /sys/block/sdb/bcache/running echo 1 > /sys/block/sdb/bcache/running
@ -110,7 +117,7 @@ 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 cache, don't expect the filesystem to be recoverable - you will have massive
filesystem corruption, though ext4's fsck does work miracles. filesystem corruption, though ext4's fsck does work miracles.
ERROR HANDLING Error Handling
-------------- --------------
Bcache tries to transparently handle IO errors to/from the cache device without Bcache tries to transparently handle IO errors to/from the cache device without
@ -134,25 +141,27 @@ the backing devices to passthrough mode.
read some of the dirty data, though. read some of the dirty data, though.
HOWTO/COOKBOOK Howto/cookbook
-------------- --------------
A) Starting a bcache with a missing caching device A) Starting a bcache with a missing caching device
If registering the backing device doesn't help, it's already there, you just need If registering the backing device doesn't help, it's already there, you just need
to force it to run without the cache: to force it to run without the cache::
host:~# echo /dev/sdb1 > /sys/fs/bcache/register host:~# echo /dev/sdb1 > /sys/fs/bcache/register
[ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered [ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered
Next, you try to register your caching device if it's present. However Next, you try to register your caching device if it's present. However
if it's absent, or registration fails for some reason, you can still if it's absent, or registration fails for some reason, you can still
start your bcache without its cache, like so: start your bcache without its cache, like so::
host:/sys/block/sdb/sdb1/bcache# echo 1 > running host:/sys/block/sdb/sdb1/bcache# echo 1 > running
Note that this may cause data loss if you were running in writeback mode. Note that this may cause data loss if you were running in writeback mode.
B) Bcache does not find its cache B) Bcache does not find its cache::
host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach
[ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set [ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set
@ -160,7 +169,8 @@ B) Bcache does not find its cache
[ 1933.478179] : cache set not found [ 1933.478179] : cache set not found
In this case, the caching device was simply not registered at boot In this case, the caching device was simply not registered at boot
or disappeared and came back, and needs to be (re-)registered: or disappeared and came back, and needs to be (re-)registered::
host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register
@ -180,7 +190,8 @@ device is still available at an 8KiB offset. So either via a loopdev
of the backing device created with --offset 8K, or any value defined by of the backing device created with --offset 8K, or any value defined by
--data-offset when you originally formatted bcache with `make-bcache`. --data-offset when you originally formatted bcache with `make-bcache`.
For example: For example::
losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev
This should present your unmodified backing device data in /dev/loop0 This should present your unmodified backing device data in /dev/loop0
@ -191,33 +202,38 @@ cache device without loosing data.
E) Wiping a cache device E) Wiping a cache device
host:~# wipefs -a /dev/sdh2 ::
16 bytes were erased at offset 0x1018 (bcache)
they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
After you boot back with bcache enabled, you recreate the cache and attach it: host:~# wipefs -a /dev/sdh2
host:~# make-bcache -C /dev/sdh2 16 bytes were erased at offset 0x1018 (bcache)
UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045 they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
version: 0
nbuckets: 106874
block_size: 1
bucket_size: 1024
nr_in_set: 1
nr_this_dev: 0
first_bucket: 1
[ 650.511912] bcache: run_cache_set() invalidating existing data
[ 650.549228] bcache: register_cache() registered cache device sdh2
start backing device with missing cache: After you boot back with bcache enabled, you recreate the cache and attach it::
host:/sys/block/md5/bcache# echo 1 > running
attach new cache: host:~# make-bcache -C /dev/sdh2
host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045
[ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1 Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
version: 0
nbuckets: 106874
block_size: 1
bucket_size: 1024
nr_in_set: 1
nr_this_dev: 0
first_bucket: 1
[ 650.511912] bcache: run_cache_set() invalidating existing data
[ 650.549228] bcache: register_cache() registered cache device sdh2
start backing device with missing cache::
host:/sys/block/md5/bcache# echo 1 > running
attach new cache::
host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
[ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
F) Remove or replace a caching device F) Remove or replace a caching device::
host:/sys/block/sda/sda7/bcache# echo 1 > detach host:/sys/block/sda/sda7/bcache# echo 1 > detach
[ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7 [ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7
@ -226,13 +242,15 @@ F) Remove or replace a caching device
wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy
Ooops, it's disabled, but not unregistered, so it's still protected Ooops, it's disabled, but not unregistered, so it's still protected
We need to go and unregister it: We need to go and unregister it::
host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0 host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0
lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/ lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/
host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop
kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered
Now we can wipe it: Now we can wipe it::
host:~# wipefs -a /dev/nvme0n1p4 host:~# wipefs -a /dev/nvme0n1p4
/dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81 /dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
@ -252,40 +270,44 @@ if there are any active backing or caching devices left on it:
1) Is it present in /dev/bcache* ? (there are times where it won't be) 1) Is it present in /dev/bcache* ? (there are times where it won't be)
If so, it's easy: If so, it's easy::
host:/sys/block/bcache0/bcache# echo 1 > stop host:/sys/block/bcache0/bcache# echo 1 > stop
2) But if your backing device is gone, this won't work: 2) But if your backing device is gone, this won't work::
host:/sys/block/bcache0# cd bcache host:/sys/block/bcache0# cd bcache
bash: cd: bcache: No such file or directory bash: cd: bcache: No such file or directory
In this case, you may have to unregister the dmcrypt block device that In this case, you may have to unregister the dmcrypt block device that
references this bcache to free it up: references this bcache to free it up::
host:~# dmsetup remove oldds1 host:~# dmsetup remove oldds1
bcache: bcache_device_free() bcache0 stopped bcache: bcache_device_free() bcache0 stopped
bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered
This causes the backing bcache to be removed from /sys/fs/bcache and This causes the backing bcache to be removed from /sys/fs/bcache and
then it can be reused. This would be true of any block device stacking then it can be reused. This would be true of any block device stacking
where bcache is a lower device. where bcache is a lower device.
3) In other cases, you can also look in /sys/fs/bcache/: 3) In other cases, you can also look in /sys/fs/bcache/::
host:/sys/fs/bcache# ls -l */{cache?,bdev?} host:/sys/fs/bcache# ls -l */{cache?,bdev?}
lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/ lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/ lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/ lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
The device names will show which UUID is relevant, cd in that directory
and stop the cache::
The device names will show which UUID is relevant, cd in that directory
and stop the cache:
host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop
This will free up bcache references and let you reuse the partition for This will free up bcache references and let you reuse the partition for
other purposes. other purposes.
TROUBLESHOOTING PERFORMANCE Troubleshooting performance
--------------------------- ---------------------------
Bcache has a bunch of config options and tunables. The defaults are intended to Bcache has a bunch of config options and tunables. The defaults are intended to
@ -301,11 +323,13 @@ want for getting the best possible numbers when benchmarking.
raid stripe size to get the disk multiples that you would like. raid stripe size to get the disk multiples that you would like.
For example: If you have a 64k stripe size, then the following offset For example: If you have a 64k stripe size, then the following offset
would provide alignment for many common RAID5 data spindle counts: would provide alignment for many common RAID5 data spindle counts::
64k * 2*2*2*3*3*5*7 bytes = 161280k 64k * 2*2*2*3*3*5*7 bytes = 161280k
That space is wasted, but for only 157.5MB you can grow your RAID 5 That space is wasted, but for only 157.5MB you can grow your RAID 5
volume to the following data-spindle counts without re-aligning: volume to the following data-spindle counts without re-aligning::
3,4,5,6,7,8,9,10,12,14,15,18,20,21 ... 3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
- Bad write performance - Bad write performance
@ -313,9 +337,9 @@ want for getting the best possible numbers when benchmarking.
If write performance is not what you expected, you probably wanted to be If write performance is not what you expected, you probably wanted to be
running in writeback mode, which isn't the default (not due to a lack of running in writeback mode, which isn't the default (not due to a lack of
maturity, but simply because in writeback mode you'll lose data if something maturity, but simply because in writeback mode you'll lose data if something
happens to your SSD) happens to your SSD)::
# echo writeback > /sys/block/bcache0/bcache/cache_mode # echo writeback > /sys/block/bcache0/bcache/cache_mode
- Bad performance, or traffic not going to the SSD that you'd expect - Bad performance, or traffic not going to the SSD that you'd expect
@ -325,13 +349,13 @@ want for getting the best possible numbers when benchmarking.
accessed data out of your cache. accessed data out of your cache.
But if you want to benchmark reads from cache, and you start out with fio But if you want to benchmark reads from cache, and you start out with fio
writing an 8 gigabyte test file - so you want to disable that. writing an 8 gigabyte test file - so you want to disable that::
# echo 0 > /sys/block/bcache0/bcache/sequential_cutoff # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff
To set it back to the default (4 mb), do To set it back to the default (4 mb), do::
# echo 4M > /sys/block/bcache0/bcache/sequential_cutoff # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff
- Traffic's still going to the spindle/still getting cache misses - Traffic's still going to the spindle/still getting cache misses
@ -344,10 +368,10 @@ want for getting the best possible numbers when benchmarking.
throttles traffic if the latency exceeds a threshold (it does this by throttles traffic if the latency exceeds a threshold (it does this by
cranking down the sequential bypass). cranking down the sequential bypass).
You can disable this if you need to by setting the thresholds to 0: You can disable this if you need to by setting the thresholds to 0::
# echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us
# echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us
The default is 2000 us (2 milliseconds) for reads, and 20000 for writes. The default is 2000 us (2 milliseconds) for reads, and 20000 for writes.
@ -369,7 +393,7 @@ want for getting the best possible numbers when benchmarking.
a fix for the issue there). a fix for the issue there).
SYSFS - BACKING DEVICE Sysfs - backing device
---------------------- ----------------------
Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
@ -454,7 +478,8 @@ writeback_running
still be added to the cache until it is mostly full; only meant for still be added to the cache until it is mostly full; only meant for
benchmarking. Defaults to on. benchmarking. Defaults to on.
SYSFS - BACKING DEVICE STATS: Sysfs - backing device stats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are directories with these numbers for a running total, as well as 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 versions that decay over the past day, hour and 5 minutes; they're also
@ -463,14 +488,11 @@ aggregated in the cache set directory as well.
bypassed bypassed
Amount of IO (both reads and writes) that has bypassed the cache Amount of IO (both reads and writes) that has bypassed the cache
cache_hits cache_hits, cache_misses, cache_hit_ratio
cache_misses
cache_hit_ratio
Hits and misses are counted per individual IO as bcache sees them; a Hits and misses are counted per individual IO as bcache sees them; a
partial hit is counted as a miss. partial hit is counted as a miss.
cache_bypass_hits cache_bypass_hits, cache_bypass_misses
cache_bypass_misses
Hits and misses for IO that is intended to skip the cache are still counted, Hits and misses for IO that is intended to skip the cache are still counted,
but broken out here. but broken out here.
@ -482,7 +504,8 @@ cache_miss_collisions
cache_readaheads cache_readaheads
Count of times readahead occurred. Count of times readahead occurred.
SYSFS - CACHE SET: Sysfs - cache set
~~~~~~~~~~~~~~~~~
Available at /sys/fs/bcache/<cset-uuid> Available at /sys/fs/bcache/<cset-uuid>
@ -520,8 +543,7 @@ flash_vol_create
Echoing a size to this file (in human readable units, k/M/G) creates a thinly Echoing a size to this file (in human readable units, k/M/G) creates a thinly
provisioned volume backed by the cache set. provisioned volume backed by the cache set.
io_error_halflife io_error_halflife, io_error_limit
io_error_limit
These determines how many errors we accept before disabling the cache. 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 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. reaches io_error_limit dirty data is written out and the cache is disabled.
@ -545,7 +567,8 @@ unregister
Detaches all backing devices and closes the cache devices; if dirty data is 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. present it will disable writeback caching and wait for it to be flushed.
SYSFS - CACHE SET INTERNAL: Sysfs - cache set internal
~~~~~~~~~~~~~~~~~~~~~~~~~~
This directory also exposes timings for a number of internal operations, with This directory also exposes timings for a number of internal operations, with
separate files for average duration, average frequency, last occurrence and max separate files for average duration, average frequency, last occurrence and max
@ -574,7 +597,8 @@ cache_read_races
trigger_gc trigger_gc
Writing to this file forces garbage collection to run. Writing to this file forces garbage collection to run.
SYSFS - CACHE DEVICE: Sysfs - Cache device
~~~~~~~~~~~~~~~~~~~~
Available at /sys/block/<cdev>/bcache Available at /sys/block/<cdev>/bcache