From patchwork Sun Nov 13 19:35:24 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Omar Sandoval X-Patchwork-Id: 9424923 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id C7A5C60233 for ; Sun, 13 Nov 2016 19:44:05 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B3551287AC for ; Sun, 13 Nov 2016 19:44:05 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id A6050288B1; Sun, 13 Nov 2016 19:44:05 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.8 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 46E40287AC for ; Sun, 13 Nov 2016 19:44:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S934791AbcKMToC (ORCPT ); Sun, 13 Nov 2016 14:44:02 -0500 Received: from mail-pf0-f176.google.com ([209.85.192.176]:33512 "EHLO mail-pf0-f176.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S934208AbcKMToB (ORCPT ); Sun, 13 Nov 2016 14:44:01 -0500 Received: by mail-pf0-f176.google.com with SMTP id d2so24731834pfd.0 for ; Sun, 13 Nov 2016 11:44:01 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=osandov-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :in-reply-to:references; bh=yx5wnnEDarNSFlWKmZgoCxvkNJni+kgZKdUVb02P+JU=; b=DKLxhkdWjqRe94kVQ8oYCLnGnU0ZThkr7Sg4liqULTw/DbxGwUEDquZ5ZAcKnIoXNC K16CkcHwwpeh3jom9phRkU1B05kocGsViYXgjLN9+fxVSL1S/84G6KV/gjnMBcdCiWdG cRQlLdRWCo8xMqXHSV3g5a0qyHLemQqd+8gWJVhY3XwpC6gWa4D+XeFxkvQKQE1Lz0KI gbWy6kNv7Z0wXVSrmqhKU5SeGuSEB/UQQ/ZF7MOLg4xB0HgGwdIV0BAr8twVbXDUBR7p Y8ygbVl7lXnk4u1gS2FNDE+/D32kFZpvYueFfq3uD7fmPF1uUqyRlr5mV36y1e6sByIB Dp/g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:in-reply-to:references; bh=yx5wnnEDarNSFlWKmZgoCxvkNJni+kgZKdUVb02P+JU=; b=gWrHsfq/VnTq+d/LfyTWgrxs+IO6NMBXUjmBNmhASPpbGo9IgEX+z9+Cr0qq6cN44m 79NRNflwDw8E5kGKyiS6rAp9W0wpx7T3NpJH6/krQesAva5kYA9RAmd+EXbMQ+x69wMR 9t2eFxBvp3hcLQAXAkp+vMaQCNdqhTbCd1wtPd5sA73pES1rqXPGM6W3PQQ0UuZEsV8i DOlzg5s6SPGPtWa7aZEV7fTmD38D+P+pmtqe/XZ+wG5NHTj/4M4EkjB9n58zsN1VcImx C5GVBK1l9G3LkXh4FBBxJbGFlI9rL+Ii5lGMC+sogXO3UHDyE2IoGbTBXshjOJIX3kIk 9KHA== X-Gm-Message-State: ABUngvdgJ9qTX3B0Ls3OQKNM7QqzVzqtuWQ22O5ymsFOoldXr+PSvdOL5wGB0ps764aV3JpW X-Received: by 10.98.17.80 with SMTP id z77mr28872469pfi.166.1479065737996; Sun, 13 Nov 2016 11:35:37 -0800 (PST) Received: from localhost.localdomain ([2601:602:8801:8110:1a5e:fff:fea7:e0ef]) by smtp.gmail.com with ESMTPSA id v76sm8289029pfk.77.2016.11.13.11.35.37 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 13 Nov 2016 11:35:37 -0800 (PST) From: Omar Sandoval To: linux-btrfs@vger.kernel.org Cc: kernel-team@fb.com Subject: [PATCH 6/6] btrfs-progs: document space_cache=v2 more thoroughly Date: Sun, 13 Nov 2016 11:35:24 -0800 Message-Id: <215dd6b41e1aa835f46b2a28bdd3732c7f349845.1479064970.git.osandov@fb.com> X-Mailer: git-send-email 2.10.2 In-Reply-To: References: In-Reply-To: References: Sender: linux-btrfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-btrfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Omar Sandoval Signed-off-by: Omar Sandoval --- Documentation/btrfs-man5.asciidoc | 43 +++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc index d12b059..3b003d3 100644 --- a/Documentation/btrfs-man5.asciidoc +++ b/Documentation/btrfs-man5.asciidoc @@ -319,25 +319,32 @@ May be resumed with *btrfs balance resume* or the paused state can be removed by *btrfs balance cancel*. The default behaviour is to start interrutpd balance. *space_cache*:: -*space_cache=v2*:: +*space_cache='version'*:: *nospace_cache*:: -('nospace_cache' since: 3.2, 'space_cache=v2' since 4.5, default: on) -+ -Options to control the free space cache. This affects performance as searching -for new free blocks could take longer if the space cache is not enabled. On the -other hand, managing the space cache consumes some resources. It can be -disabled without clearing at mount time. -+ -There are two implementations of how the space is tracked. The safe default is -'v1'. On large filesystems (many-terabytes) and certain workloads the 'v1' -performance may degrade. This problem is addressed by 'v2', that is based on -b-trees, sometimes referred to as 'free-space-tree'. -+ -'Compatibility notes:' -+ -* the 'v2' has to be enabled manually at mount time, once -* kernel without 'v2' support will be able to mount the filesystem in read-only mode -* 'v2' can be removed by mounting with 'clear_cache' +('nospace_cache' since: 3.2, 'space_cache=v1' and 'space_cache=v2' since 4.5, default: 'space_cache=v1') ++ +Options to control the free space cache. The free space cache greatly improves +performance when reading block group free space into memory. However, managing +the space cache consumes some resources, including a small amount of disk +space. ++ +There are two implementations of the free space cache. The original +implementation, 'v1', is the safe default. The 'v1' space cache can be disabled +at mount time with 'nospace_cache' without clearing. ++ +On very large filesystems (many terabytes) and certain workloads, the +performance of the 'v1' space cache may degrade drastically. The 'v2' +implementation, which adds a new B-tree called the free space tree, addresses +this issue. Once enabled, the 'v2' space cache will always be used and cannot +be disabled unless it is cleared. Use 'clear_cache,space_cache=v1' or +'clear_cache,nospace_cache' to do so. If 'v2' is enabled, kernels without 'v2' +support will only be able to mount the filesystem in read-only mode. The +`btrfs(8)` command currently only has read-only support for 'v2'. A read-write +command may be run on a 'v2' filesystem by clearing the cache, running the +command, and then remounting with 'space_cache=v2'. ++ +If a version is not explicitly specified, the default implementation will be +chosen, which is 'v1' as of 4.9. *ssd*:: *nossd*::