From patchwork Tue May 23 20:51:01 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thomas Gleixner X-Patchwork-Id: 13252906 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 1F274C7EE23 for ; Tue, 23 May 2023 20:51:07 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 7B5926B0074; Tue, 23 May 2023 16:51:06 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 765B1900003; Tue, 23 May 2023 16:51:06 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 6545D900002; Tue, 23 May 2023 16:51:06 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 569196B0074 for ; Tue, 23 May 2023 16:51:06 -0400 (EDT) Received: from smtpin23.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id D6FCEA0570 for ; Tue, 23 May 2023 20:51:05 +0000 (UTC) X-FDA: 80822714490.23.27DE9A2 Received: from galois.linutronix.de (Galois.linutronix.de [193.142.43.55]) by imf05.hostedemail.com (Postfix) with ESMTP id 006B7100013 for ; Tue, 23 May 2023 20:51:03 +0000 (UTC) Authentication-Results: imf05.hostedemail.com; dkim=pass header.d=linutronix.de header.s=2020 header.b=tSDD3fTq; dkim=pass header.d=linutronix.de header.s=2020e header.b=kEoXdNpA; dmarc=pass (policy=none) header.from=linutronix.de; spf=pass (imf05.hostedemail.com: domain of tglx@linutronix.de designates 193.142.43.55 as permitted sender) smtp.mailfrom=tglx@linutronix.de ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1684875064; a=rsa-sha256; cv=none; b=D6iNcMl3x9BoN2CfrvNhJS6s/5jQbam1ef/nOKdgLlXH8/pDhnw7gphwfn7OasFnR2VjiP 01WJ3dkd1whliQIxFKAWq3NcP2BxnZb1BdLuSTCfbp1FzgBB3YRe+9uxAVo9oEHRaDNX/0 45SMftjcY2F+InIA9DUu7WOqgm3DpfI= ARC-Authentication-Results: i=1; imf05.hostedemail.com; dkim=pass header.d=linutronix.de header.s=2020 header.b=tSDD3fTq; dkim=pass header.d=linutronix.de header.s=2020e header.b=kEoXdNpA; dmarc=pass (policy=none) header.from=linutronix.de; spf=pass (imf05.hostedemail.com: domain of tglx@linutronix.de designates 193.142.43.55 as permitted sender) smtp.mailfrom=tglx@linutronix.de ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1684875064; h=from:from:sender:reply-to: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:in-reply-to:references:dkim-signature; bh=xu3lh9FcdoeNVU96OzSdewnm6QGeZvQPxHHm1nN5R3o=; b=KzlDYdJ0vJ2hf7/0v6+JBUOj1vo/N62ew2SVWjLHtyQFmrbbHhp3CV13oGLjuYKq6FCxvK /QoYP/oxM+SRPO4Hfek9ycbSc2polmkGtuak15n3G93SeMitUgRb3vrYfZN4M3+WeQeJSu 2X88q8p9fGNOprJvY0QiVmLuR5WQCeA= From: Thomas Gleixner DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1684875061; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to; bh=xu3lh9FcdoeNVU96OzSdewnm6QGeZvQPxHHm1nN5R3o=; b=tSDD3fTqiWMazlzB0uscOaBYvMfkKxQ9Yr4u8hfs1K6DD8rg61sijq43Zt/QDRlF/fKD8l LdVdWgrNYPDr0EZ2IZj0uGiWiTEEJ4ufALsq/BlBFGTkHF8ALeaJc4Feb8FKsrvxdJgMAY xdbWK4lyC1JaSA9JJHvphcdDraUL+RWAlvmxFc2LTfRBcK77dlhyOjZ1M4uUMxA3MjWE3X YEWrrKkpjY+I/ITc6mzewzZLbKv8W8apJvXb0z4w4TYsHh28TwOFuy5VRJmLkYHiB4Hajn F6lCgkh/XcHysdEgZdDiqyoD9b/I4SeM4cogvr0RhgKlKirBZMG9mU2YJ7pAbQ== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1684875061; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to; bh=xu3lh9FcdoeNVU96OzSdewnm6QGeZvQPxHHm1nN5R3o=; b=kEoXdNpAMbORtwLPhvlREk3m9evosE9L6C3idDDMP4pPPX91PJFznyv0UwrE7alOmVf9FK uMwqzrRGezeT6TAQ== To: "Liam R. Howlett" Cc: LKML , Matthew Wilcox , linux-mm@kvack.org, Shanker Donthineni Subject: [PATCH v2] maple_tree: Fix a few documentation issues In-Reply-To: <20230523134646.gelsru64qvny3fi7@revolver> Date: Tue, 23 May 2023 22:51:01 +0200 Message-ID: <87ttw2n556.ffs@tglx> MIME-Version: 1.0 X-Rspam-User: X-Rspamd-Server: rspam06 X-Rspamd-Queue-Id: 006B7100013 X-Stat-Signature: qwc1tm57mso9tq6rfm9ttmajxszutrf1 X-HE-Tag: 1684875063-169363 X-HE-Meta: U2FsdGVkX185hZX66gcirRBD3W1xMIrgXdJQjl1pxMbFampD3cbxcLKu/wduD2d0DjbsQ6Y9123NWxYs+PpTIATU0hsBMemG0XqA/Dticzb2IC0Zy+/du2KZ4vp8KIfuOZyuQkCpzST3HhBX2pto7I3PLYaPVQJneJ9JdX9pSEU+7qlmn9+kMwHeb58WE31DOJA/y3D4kxxAKStUntL9FfRN0GRMn/KxE+YkxNFy722mvg2vszd5/203Ij7IsLuJCjhlqZI0wWHuvfCMGzBukemNG1KAvJuzHIxSnxsynWqDXC1IcQfQcwytV3XI7kKO3biQA5qXDhkPg7g+4z3R+OfR+i5Bu2R4ZWQ9z+C37f4iSGzOmdei8AepHoYXEL25OBRWYGK/I3tBtrMFWR8aB9gTJEBlNRaaIIfLG9wL9fJS2qCIZTrKsLROwnRU5oyQaNkc/0B94MiQU0DLa8vwK03T/CY0ZKX0gBUPvPZAVTEYQMginc9FnfHWNt7IoAqZ/nJA0t/XuZb1BClJq/ntAhVbiCzgK2M58fkbdP5F5QBGSC5jpHUxasKVUVcZFq6uokpwO4NidjmC0lSi+CweMYtWqKtmkjmlfCL3Ce0m5SerOtZ6wqmKaOyhHuCrA2gMBJoiDItnCBI8uRnuwSWNoWkZIm2yEWsvSHMD8+Ygu6GAQ7He6USNndaF3SJlDPATstFYqNxYXsFReummDc3YaXbvKZvGFGc1TYgFcfGPyW/GORiADsc+ajuoIefSNFAeuhLn8GqKmzvAIYf/OU6vsRsFXWpQSZuIbnzEIRB/Itm+JeRbx+BMnnhLxirP9nsVQqVsGqqqOF6OE/RK00tr+dZSnXPLRt73E/3XZs345j7+wCiCeJDX6tR4HR4+UXnCXZ3xaYUZqB4+3hhPUW6Sstyh83x7tV5iT3K5iZuK75BZ/HKWzKnzVTwSG3/GwLJBNwAVpmpXiZoDU4i+4M/ sSm3L9gd XHgor+yGOM+dT6HirPxUP+IvJLysIsiic+mr46HGglwreW+jRMfpN/USMWGZlaOR1SJAknO5bRynCMK8xO48sSjgd5a5x288qtr7X 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(). Reword the confusing "Note: Will not return the zero entry." comment on mt_for_each() and document @__index correctly. Signed-off-by: Thomas Gleixner Reviewed-by: Liam R. Howlett --- V2: Address review feedback. Add pointer to documentation, reword the zero entry and the index explanations. - Liam --- include/linux/maple_tree.h | 5 +++-- lib/maple_tree.c | 26 +++++++++++++++++++++----- 2 files changed, 24 insertions(+), 7 deletions(-) --- a/include/linux/maple_tree.h +++ b/include/linux/maple_tree.h @@ -659,10 +659,11 @@ 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. + * This iterator skips all entries, which resolve to a NULL pointer, + * e.g. entries which has been reserved with XA_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,11 @@ 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. + * See also: Documentation/core-api/maple_tree.rst + * + * 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 +6016,11 @@ 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. + * See also: Documentation/core-api/maple_tree.rst + * + * 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 +6495,15 @@ 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 * - * Handles locking. @index will be incremented to one beyond the range. + * Takes RCU read lock internally to protect the search, which does not + * protect the returned pointer after dropping RCU read lock. + * See also: Documentation/core-api/maple_tree.rst + * + * In case that an entry is found @index is updated to point to the next + * possible entry independent whether the found entry is occupying a + * single index or a range if indices. * * Return: The entry at or after the @index or %NULL */ @@ -6548,7 +6562,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 */