From patchwork Mon Jun 5 15:27:33 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans van Kranenburg X-Patchwork-Id: 9766387 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 AC7CD60353 for ; Mon, 5 Jun 2017 15:37:56 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9EB7A27CAF for ; Mon, 5 Jun 2017 15:37:56 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 939B228372; Mon, 5 Jun 2017 15:37:56 +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.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI 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 B496027CAF for ; Mon, 5 Jun 2017 15:37:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751188AbdFEPhx (ORCPT ); Mon, 5 Jun 2017 11:37:53 -0400 Received: from smtp.dpl.mendix.net ([83.96.177.10]:45561 "EHLO smtp.dpl.mendix.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751077AbdFEPhx (ORCPT ); Mon, 5 Jun 2017 11:37:53 -0400 X-Greylist: delayed 525 seconds by postgrey-1.27 at vger.kernel.org; Mon, 05 Jun 2017 11:37:52 EDT Received: from blackbox.mgt.dpl.mendix.net (blackbox.bofh.hq.mendix.net [IPv6:2001:828:13c8:10b::c]) by smtp.dpl.mendix.net (Postfix) with ESMTP id 762AA20053; Mon, 5 Jun 2017 17:29:05 +0200 (CEST) From: Hans van Kranenburg To: linux-btrfs@vger.kernel.org Cc: Hans van Kranenburg Subject: [PATCH] Btrfs: Improve btrfs_ioctl_search_key documentation Date: Mon, 5 Jun 2017 17:27:33 +0200 Message-Id: <20170605152733.25441-1-hans.van.kranenburg@mendix.com> X-Mailer: git-send-email 2.11.0 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 A programmer who is trying to implement calling the btrfs SEARCH or SEARCH_V2 ioctl will probably soon end up reading this struct definition. Properly document the input fields to prevent common misconceptions: 1. The search space is linear, not 3 dimensional. 2. The transaction id (a.k.a. generation) filter applies only on transaction id of the last COW operation on a whole metadata page, not on individual items. Ad 1. The first misunderstanding was helped by the previous misleading comments on min/max type and offset: "keys returned will be >= min and <= max". Ad 2. For example, running btrfs balance will happily cause rewriting of metadata pages that contain a filesystem tree of a read only subvolume, causing transids to be increased. Signed-off-by: Hans van Kranenburg --- include/uapi/linux/btrfs.h | 63 +++++++++++++++++++++++++++++++--------------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/include/uapi/linux/btrfs.h b/include/uapi/linux/btrfs.h index a456e5309238..864ad86c5d80 100644 --- a/include/uapi/linux/btrfs.h +++ b/include/uapi/linux/btrfs.h @@ -427,30 +427,53 @@ struct btrfs_ioctl_ino_lookup_args { }; struct btrfs_ioctl_search_key { - /* which root are we searching. 0 is the tree of tree roots */ - __u64 tree_id; - - /* keys returned will be >= min and <= max */ - __u64 min_objectid; - __u64 max_objectid; - - /* keys returned will be >= min and <= max */ - __u64 min_offset; - __u64 max_offset; - - /* max and min transids to search for */ - __u64 min_transid; - __u64 max_transid; + /* + * The tree we're searching in. 1 is the tree of tree roots, 2 is the + * extent tree, etc... + */ + __u64 tree_id; /* in */ - /* keys returned will be >= min and <= max */ - __u32 min_type; - __u32 max_type; + /* + * This struct is used to provide the search key range for the SEARCH and + * SEARCH_V2 ioctls. + * + * When doing a tree search, we're actually taking a slice from a linear + * search space of 136-bit keys: + * + * Key of the first possible item to be returned: + * (min_objectid << 72) + (min_type << 64) + min_offset + * Key of the last possible item to be returned: + * (max_objectid << 72) + (max_type << 64) + max_offset + * + * All of the min/max input numbers only define the ultimate lower and + * upper boundary of the keys of items that will be returned. In other + * words, they are not used to filter the type or offset of intermediate + * keys encountered. + * + * Additionally, we can filter the items returned on transaction id of the + * metadata block they're stored in by specifying a transid range. Be + * aware that this transaction id only denotes when the metadata page that + * currently contains the item got written the last time as result of a COW + * operation. The number does not have any meaning related to the + * transaction in which an individual item that is being returned was + * created or changed. + */ + __u64 min_objectid; /* in */ + __u64 max_objectid; /* in */ + __u64 min_offset; /* in */ + __u64 max_offset; /* in */ + __u64 min_transid; /* in */ + __u64 max_transid; /* in */ + __u32 min_type; /* in */ + __u32 max_type; /* in */ /* - * how many items did userland ask for, and how many are we - * returning + * input: The maximum amount of results desired. + * output: The actual amount of items returned, restricted by either + * stopping the search when reaching the input nr_items amount of items, + * or restricted by the size of the supplied memory buffer. */ - __u32 nr_items; + __u32 nr_items; /* in/out */ /* align to 64 bits */ __u32 unused;