Merge branch 'docs-next' of git://git.lwn.net/linux into devel/docs-next

output

*.pyc

PS_METHOD	= $(prefer-db2x)

###

# The targets that may be used.

PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs

targets += $(DOCBOOKS)

BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))

xmldocs: $(BOOKS)

		sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \

		xargs install -m 644 -t /usr/local/man/man9/

# no-op for the DocBook toolchain

epubdocs:

###

#External programs used

KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref

###

# Help targets as used by the top-level makefile

dochelp:

	@echo  ' Linux kernel internal documentation in different formats:'

	@echo  ' Linux kernel internal documentation in different formats (DocBook):'

	@echo  '  htmldocs        - HTML'

	@echo  '  pdfdocs         - PDF'

	@echo  '  psdocs          - Postscript'

# -*- makefile -*-

# Makefile for Sphinx documentation

#

# You can set these variables from the command line.

SPHINXBUILD   = sphinx-build

SPHINXOPTS    =

PAPER         =

BUILDDIR      = $(obj)/output

# User-friendly check for sphinx-build

HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)

ifeq ($(HAVE_SPHINX),0)

.DEFAULT:

	$(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)

	@echo "  SKIP    Sphinx $@ target."

else # HAVE_SPHINX

# User-friendly check for rst2pdf

HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)

# Internal variables.

PAPEROPT_a4     = -D latex_paper_size=a4

PAPEROPT_letter = -D latex_paper_size=letter

KERNELDOC       = $(srctree)/scripts/kernel-doc

KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)

ALLSPHINXOPTS   = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)

# the i18n builder cannot share the environment and doctrees with the others

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

quiet_cmd_sphinx = SPHINX  $@

      cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2

htmldocs:

	$(call cmd,sphinx,html)

pdfdocs:

ifeq ($(HAVE_RST2PDF),0)

	$(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)

	@echo "  SKIP    Sphinx $@ target."

else # HAVE_RST2PDF

	$(call cmd,sphinx,pdf)

endif # HAVE_RST2PDF

epubdocs:

	$(call cmd,sphinx,epub)

xmldocs:

	$(call cmd,sphinx,xml)

# no-ops for the Sphinx toolchain

sgmldocs:

psdocs:

mandocs:

installmandocs:

cleandocs:

	$(Q)rm -rf $(BUILDDIR)

dochelp:

	@echo  ' Linux kernel internal documentation in different formats (Sphinx):'

	@echo  '  htmldocs        - HTML'

	@echo  '  pdfdocs         - PDF'

	@echo  '  epubdocs        - EPUB'

	@echo  '  xmldocs         - XML'

	@echo  '  cleandocs       - clean all generated files'

endif # HAVE_SPHINX

Say you've got a big slow raid 6, and an X-25E 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.

Wiki and git repositories are at:

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

extants (which can be anywhere from a single sector to the bucket size). It's

extents (which can be anywhere from a single sector to the bucket size). It's

designed to avoid random writes at all costs; it fills up an erase block

sequentially, then issues a discard before reusing it.

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.

If you are thinking about using bcache later, it is recommended to setup all your

slow devices as bcache backing devices without a cache, and you can choose to add

a caching device later.

See 'ATTACHING' section below.

The devices show up as:

  mount /dev/bcache0 /mnt

You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .

You can also control them through /sys/fs//bcache/<cset-uuid>/ .

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>

ATTACHING:

ATTACHING

---------

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

cache, don't expect the filesystem to be recoverable - you will have massive

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

affecting normal operation; if it sees too many errors (the threshold is

   writeback mode). It currently doesn't do anything intelligent if it fails to

   read some of the dirty data, though.

TROUBLESHOOTING PERFORMANCE:

HOWTO/COOKBOOK

--------------

A) Starting a bcache with a missing caching device

If registering the backing device doesn't help, it's already there, you just need

to force it to run without the cache:

	host:~# echo /dev/sdb1 > /sys/fs/bcache/register

	[  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

if it's absent, or registration fails for some reason, you can still

start your bcache without its cache, like so:

	host:/sys/block/sdb/sdb1/bcache# echo 1 > running

Note that this may cause data loss if you were running in writeback mode.

B) Bcache does not find its cache

	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.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8

	[ 1933.478179] : cache set not found

In this case, the caching device was simply not registered at boot

or disappeared and came back, and needs to be (re-)registered:

	host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register

C) Corrupt bcache crashes the kernel at device registration time:

This should never happen.  If it does happen, then you have found a bug!

Please report it to the bcache development list: linux-bcache@vger.kernel.org

Be sure to provide as much information that you can including kernel dmesg

output if available so that we may assist.

D) Recovering data without bcache:

If bcache is not available in the kernel, a filesystem on the backing

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

--data-offset when you originally formatted bcache with `make-bcache`.

For example:

	losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev

This should present your unmodified backing device data in /dev/loop0

If your cache is in writethrough mode, then you can safely discard the

cache device without loosing data.

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:~# make-bcache -C /dev/sdh2

UUID:                   7be7e175-8f4c-4f99-94b2-9c904d227045

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

	host:/sys/block/sda/sda7/bcache# echo 1 > detach

	[  695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7

	host:~# wipefs -a /dev/nvme0n1p4

	wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy

	Ooops, it's disabled, but not unregistered, so it's still protected

We need to go and unregister it:

	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/

	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

Now we can wipe it:

	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

G) dm-crypt and bcache

First setup bcache unencrypted and then install dmcrypt on top of

/dev/bcache<N> This will work faster than if you dmcrypt both the backing

and caching devices and then install bcache on top. [benchmarks?]

H) Stop/free a registered bcache to wipe and/or recreate it

Suppose that you need to free up all bcache references so that you can

fdisk run and re-register a changed partition table, which won't work

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)

If so, it's easy:

	host:/sys/block/bcache0/bcache# echo 1 > stop

2) But if your backing device is gone, this won't work:

	host:/sys/block/bcache0# cd bcache

	bash: cd: bcache: No such file or directory

In this case, you may have to unregister the dmcrypt block device that

references this bcache to free it up:

	host:~# dmsetup remove oldds1

	bcache: bcache_device_free() bcache0 stopped

	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

then it can be reused.  This would be true of any block device stacking

where bcache is a lower device.

3) In other cases, you can also look in /sys/fs/bcache/:

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/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/

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

This will free up bcache references and let you reuse the partition for

other purposes.

TROUBLESHOOTING PERFORMANCE

---------------------------

Bcache has a bunch of config options and tunables. The defaults are intended to

be reasonable for typical desktop and server workloads, but they're not what you

want for getting the best possible numbers when benchmarking.

 - Backing device alignment

   The default metadata size in bcache is 8k.  If your backing device is

   RAID based, then be sure to align this by a multiple of your stride

   width using `make-bcache --data-offset`. If you intend to expand your

   disk array in the future, then multiply a series of primes by your

   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

   would provide alignment for many common RAID5 data spindle counts:

	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

   volume to the following data-spindle counts without re-aligning:

	3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...

 - Bad write performance

   If write performance is not what you expected, you probably wanted to be

   maturity, but simply because in writeback mode you'll lose data if something

   happens to your SSD)

   # echo writeback > /sys/block/bcache0/cache_mode

   # echo writeback > /sys/block/bcache0/bcache/cache_mode

 - Bad performance, or traffic not going to the SSD that you'd expect

   Solution: warm the cache by doing writes, or use the testing branch (there's

   a fix for the issue there).

SYSFS - BACKING DEVICE:

SYSFS - BACKING DEVICE

----------------------

Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and

(if attached) /sys/fs/bcache/<cset-uuid>/bdev*