btrfs: document device locking

			     struct btrfs_bio **bbio_ret,

			     int mirror_num, int need_raid_map);

/*

 * Device locking

 * ==============

 *

 * There are several mutexes that protect manipulation of devices and low-level

 * structures like chunks but not block groups, extents or files

 *

 * uuid_mutex (global lock)

 * ------------------------

 * protects the fs_uuids list that tracks all per-fs fs_devices, resulting from

 * the SCAN_DEV ioctl registration or from mount either implicitly (the first

 * device) or requested by the device= mount option

 *

 * the mutex can be very coarse and can cover long-running operations

 *

 * protects: updates to fs_devices counters like missing devices, rw devices,

 * seeding, structure cloning, openning/closing devices at mount/umount time

 *

 * global::fs_devs - add, remove, updates to the global list

 *

 * does not protect: manipulation of the fs_devices::devices list!

 *

 * btrfs_device::name - renames (write side), read is RCU

 *

 * fs_devices::device_list_mutex (per-fs, with RCU)

 * ------------------------------------------------

 * protects updates to fs_devices::devices, ie. adding and deleting

 *

 * simple list traversal with read-only actions can be done with RCU protection

 *

 * may be used to exclude some operations from running concurrently without any

 * modifications to the list (see write_all_supers)

 *

 * volume_mutex

 * ------------

 * coarse lock owned by a mounted filesystem; used to exclude some operations

 * that cannot run in parallel and affect the higher-level properties of the

 * filesystem like: device add/deleting/resize/replace, or balance

 *

 * balance_mutex

 * -------------

 * protects balance structures (status, state) and context accessed from

 * several places (internally, ioctl)

 *

 * chunk_mutex

 * -----------

 * protects chunks, adding or removing during allocation, trim or when a new

 * device is added/removed

 *

 * cleaner_mutex

 * -------------

 * a big lock that is held by the cleaner thread and prevents running subvolume

 * cleaning together with relocation or delayed iputs

 *

 *

 * Lock nesting

 * ============

 *

 * uuid_mutex

 *   volume_mutex

 *     device_list_mutex

 *       chunk_mutex

 *     balance_mutex

 */

DEFINE_MUTEX(uuid_mutex);

static LIST_HEAD(fs_uuids);

struct list_head *btrfs_get_fs_uuids(void)