From patchwork Wed May 10 19:01:05 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thomas Gleixner X-Patchwork-Id: 13237192 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2F7D9C77B7C for ; Wed, 10 May 2023 19:01:38 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 5D8706B0072; Wed, 10 May 2023 15:01:37 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 588F56B0074; Wed, 10 May 2023 15:01:37 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 4781E6B0075; Wed, 10 May 2023 15:01:37 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0016.hostedemail.com [216.40.44.16]) by kanga.kvack.org (Postfix) with ESMTP id 36F4C6B0072 for ; Wed, 10 May 2023 15:01:37 -0400 (EDT) Received: from smtpin22.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id D80FF1C75EA for ; Wed, 10 May 2023 19:01:36 +0000 (UTC) X-FDA: 80775264192.22.8036424 Received: from galois.linutronix.de (Galois.linutronix.de [193.142.43.55]) by imf11.hostedemail.com (Postfix) with ESMTP id 75EEE4002D for ; Wed, 10 May 2023 19:01:09 +0000 (UTC) Authentication-Results: imf11.hostedemail.com; dkim=fail ("headers rsa verify failed") header.d=linutronix.de header.s=2020 header.b=0uDoQAlU; dkim=fail ("headers eddsa verify failed") header.d=linutronix.de header.s=2020e header.b=bQzJF2B8; spf=pass (imf11.hostedemail.com: domain of tglx@linutronix.de designates 193.142.43.55 as permitted sender) smtp.mailfrom=tglx@linutronix.de; dmarc=pass (policy=none) header.from=linutronix.de ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1683745271; h=from:from:sender:reply-to:subject:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding:in-reply-to: references:dkim-signature; bh=6VeszvmJNUYN70+RK5o7CAMFbLfrPw5Wbv+HBHpQnkU=; b=OiktUdPkz1hj8HnDX3wwBh680BCPcu3KRdL4EULfYscemWPJHWNISMK1QIbUKDNRqQVQAc i0xb1md0kGMKPIjRUh5Pc7tRad4BcR0yHZDaxgUdITfAjjk1w+vWTOY2PbD0ycWcs7Mjdf fdwUfEbTSWD5Jar78i4zxUjXryKnIPE= ARC-Authentication-Results: i=1; imf11.hostedemail.com; dkim=fail ("headers rsa verify failed") header.d=linutronix.de header.s=2020 header.b=0uDoQAlU; dkim=fail ("headers eddsa verify failed") header.d=linutronix.de header.s=2020e header.b=bQzJF2B8; spf=pass (imf11.hostedemail.com: domain of tglx@linutronix.de designates 193.142.43.55 as permitted sender) smtp.mailfrom=tglx@linutronix.de; dmarc=pass (policy=none) header.from=linutronix.de ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1683745271; a=rsa-sha256; cv=none; b=iq8ZCDwtMy7LxyCAGwy5/a0FMKnmWiM24lbT2A76OX+kgzLgkBLJ0wnRmaMvY3moXbLTLj wV46QAibAxR5rJQ087jQamooDVgx+0f1hgnY1usGzJ/R0zssXjBFB3AxERTlXEglKJAA/x tYh3GWcBuRK+GO+kQSSvkE6S/FgX/h4= From: Thomas Gleixner DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1683745266; h=from:from:reply-to:subject:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type; bh=6VeszvmJNUYN70+RK5o7CAMFbLfrPw5Wbv+HBHpQnkU=; b=0uDoQAlU2tDjTgPPhnww90lqnbNn10piVW/W+bhmeFD0p0eFsCkFbE1F24H0kwpyXE+0jh 6IdPqRkAYhKMjvoXq6/ZET/uLN/UdACiQvi0O88dfwfPkkVJRf4wXw8FhQIM91l19nnHR8 vS1UmxQU4H3zQI+QkivQhBv7j0Pu4Laq3klS7W4TV51l2Hjor3QwH9fZ7nwae2cWrA1vQA Y4qZelXEvuNUUo6eUR4Jk7c36bke4rCzwgBgLeAeamu1hjBvqhzHVmPyoaXLzOjMXZccCW ZldaUA0RNQeNouHF5+uT36i0X+GLwHBg3K5KPq2AbOUFmw/1tp09c2djAbnZgg== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1683745266; h=from:from:reply-to:subject:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type; bh=6VeszvmJNUYN70+RK5o7CAMFbLfrPw5Wbv+HBHpQnkU=; b=bQzJF2B85H2QAG7r3taZgh09YXEtuzcYWaVeD/EnJAeFpd7nYPHKacHxt6nF1HDZAAdBQC qOMX2x0nqFw3DuDQ== To: LKML Cc: "Liam R. Howlett" , Matthew Wilcox , linux-mm@kvack.org, Shanker Donthineni Subject: [PATCH] maple_tree: Fix a few documentation issues Subject: Date: Wed, 10 May 2023 21:01:05 +0200 Message-ID: <87mt2cxb7y.ffs@tglx> MIME-Version: 1.0 X-Rspam-User: X-Rspamd-Server: rspam01 X-Rspamd-Queue-Id: 75EEE4002D X-Stat-Signature: 9mj5hqqp431qhfrgtr1ppjm4fgwtnujq X-HE-Tag: 1683745269-59311 X-HE-Meta: U2FsdGVkX19DBd8KGMcVDxwU+5irRVMPSkm0Yv1F3uEctzME9F35YTJTA5vTsOIINAzjyFSNc9IFO0cJr22bamcEImwMyT8ahqkiHpLsvZ7899pNJQk9RjNOxjj268NYO6N82opu8eoBwRT+XllrC6KcTVD6OIcLQva2NMIqQ/MkcwTJ2rkEI45C9a8Ph5ex80flTZnVOUEZvvcT5XgnqQPJFszyvi4yStOnp4eKXo6LrcPPgVRSUZOPSGIGZkRBv4BAYESSQoqAdhyUwUod4xz5bZRLTz6T3o/Zd49HprPjr/uBbhmBK9kWgIEBMwUr9b5F8BxLU/Ae2gXKClRq4YBXjc2GlSy4Rc8gf0NrUHRQCuqhkNggw3newD7IuicXTc+Ar+UBSFk+Kn0uQrWHexxo98MZWp3T9MSu0GpHgnM9GLChQdVEm+5Dmv98c6Zacs6C1H4rVDjedcl2yK45hQg51cRAcqufRRrK/wlCv0t1/EcpD7QAT9DKxaPtvTiPlzueiUHA3EIuSEdTd9gEqpyscoj4Xm5XE/Vp78i0JZknkofA4SWWrSv4ENi69NJGPDzHR6QCCJjH0UdhI2tN4OtMCbPsipsWTHHgEwtYfY4ISAxgw4aJRsWVOcV0DaW3WEq4nFkFSz4HEiJomHVyHkWxeIB9NqfO56tAgXVC7eaYac8ku2I8er+VFAJ3ajgbVDxfZtb4uZpqJ0ttCV6lZ1rP+eR0jykW8NRXQ12TnWq4loXVbCtBnGDBsUoGI8drZBqyRKynpV+Z5iUv5K2NEQxY20L1ozrelgEHqtzqKmCAuRXo5JZ792+2nhyVuiKgwZb6NcC3UmfMjdnIzJFaU3oNRmHOTQxjqWacP74BsKpvek11txdjoPwQoLnz7f5Mx33oB9lHcem77uI2GvE4g5HVpTy4LPPYbd0jN6yeFqQqzkkah6zw5CR6hf+scJ27e/Ghr4LMcVD7rDx/Nnp /g2m5hIv s+vC7EeLlrD07CVYQlqzZKWiEcgUeX9V27lFJUfg+v7dnRzt46yd28WLUZX203cqAu6LaML9nRw+1eJb80/ozgAB09qNFEfa7olqjXm3CSrj1kODdMPhVo0RIr9e6+sX2O0zUBcuvgf8+8MOTQtLX7mvZv42/W8MsRCpYQm0ysFZS/aljUg0xjDovvz2f4EsWwl2LLJ1Y4CFnhL+1nH39YUVFEdw+aoMyTT0rx6sNb/Q8gsMguykaxKAjoN9uAJLmQyUFiIM5YEt7QgU= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: The documentation of mt_next() claims that it starts the search at the provided index. That's incorrect as it starts the search after the provided index. The documentation of mt_find() is slightly confusing. "Handles locking" is not really helpful as it does not explain how the "locking" works. Also the documentation of index talks about a range, while in reality the index is updated on a succesful search to the index of the found entry plus one. Fix similar issues for mt_find_after() and mt_prev(). Remove the completely confusing and pointless "Note: Will not return the zero entry." comment from mt_for_each() and document @__index correctly. Signed-off-by: Thomas Gleixner --- include/linux/maple_tree.h | 4 +--- lib/maple_tree.c | 23 ++++++++++++++++++----- 2 files changed, 19 insertions(+), 8 deletions(-) --- a/include/linux/maple_tree.h +++ b/include/linux/maple_tree.h @@ -659,10 +659,8 @@ void *mt_next(struct maple_tree *mt, uns * mt_for_each - Iterate over each entry starting at index until max. * @__tree: The Maple Tree * @__entry: The current entry - * @__index: The index to update to track the location in the tree + * @__index: The index to start the search from. Subsequently used as iterator. * @__max: The maximum limit for @index - * - * Note: Will not return the zero entry. */ #define mt_for_each(__tree, __entry, __index, __max) \ for (__entry = mt_find(__tree, &(__index), __max); \ --- a/lib/maple_tree.c +++ b/lib/maple_tree.c @@ -5947,7 +5947,10 @@ EXPORT_SYMBOL_GPL(mas_next); * @index: The start index * @max: The maximum index to check * - * Return: The entry at @index or higher, or %NULL if nothing is found. + * Takes RCU read lock internally to protect the search, which does not + * protect the returned pointer after dropping RCU read lock. + * + * Return: The entry higher than @index or %NULL if nothing is found. */ void *mt_next(struct maple_tree *mt, unsigned long index, unsigned long max) { @@ -6012,7 +6015,10 @@ EXPORT_SYMBOL_GPL(mas_prev); * @index: The start index * @min: The minimum index to check * - * Return: The entry at @index or lower, or %NULL if nothing is found. + * Takes RCU read lock internally to protect the search, which does not + * protect the returned pointer after dropping RCU read lock. + * + * Return: The entry before @index or %NULL if nothing is found. */ void *mt_prev(struct maple_tree *mt, unsigned long index, unsigned long min) { @@ -6487,9 +6493,14 @@ EXPORT_SYMBOL(mtree_destroy); * mt_find() - Search from the start up until an entry is found. * @mt: The maple tree * @index: Pointer which contains the start location of the search - * @max: The maximum value to check + * @max: The maximum value of the search range + * + * Takes RCU read lock internally to protect the search, which does not + * protect the returned pointer after dropping RCU read lock. * - * Handles locking. @index will be incremented to one beyond the range. + * In case that an entry is found @index contains the index of the found + * entry plus one, so it can be used as iterator index to find the next + * entry. * * Return: The entry at or after the @index or %NULL */ @@ -6548,7 +6559,9 @@ EXPORT_SYMBOL(mt_find); * @index: Pointer which contains the start location of the search * @max: The maximum value to check * - * Handles locking, detects wrapping on index == 0 + * Same as mt_find() except that it checks @index for 0 before + * searching. If @index == 0, the search is aborted. This covers a wrap + * around of @index to 0 in an iterator loop. * * Return: The entry at or after the @index or %NULL */