From patchwork Wed Aug 31 18:06:19 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Paul E. McKenney" X-Patchwork-Id: 12961190 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 225DAECAAD1 for ; Wed, 31 Aug 2022 18:06:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232164AbiHaSGf (ORCPT ); Wed, 31 Aug 2022 14:06:35 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40658 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232115AbiHaSGc (ORCPT ); Wed, 31 Aug 2022 14:06:32 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 54BE3E3947; Wed, 31 Aug 2022 11:06:29 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id ECD1961C0C; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4BE77C4347C; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1661969187; bh=u6+OpkwptEc2yhoOgNkuvcCrF65KG3Z4JJroWIzxvQA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tdz2xhPcuQlqdbwWJcq8kGmBxqXYpiBJ3RnaoQOPswiOYyaIxarvXI+u1pljhT8t5 +baji/Gw2jI8ItXDuxj7JZLN0OY7LmB4Hwk4JM9OPWzSxA6gXurl0kD5A1pQ3X6vya fXnuNKlph5Xcq9QWzWZ83Cz9+HRLLXrJQQLEbdo1FeiK6GykBNmJBF6teOqWOyVmUU MPNaoXyU/LALbw8ydyp+4FJC9d+dGeijTzOCC14054gSJgZs3L5BZLw7abL3ZVz7/t bH9w1RK5duH/Ec6NYjs836YXCPrZ3M/1iamD4ZAOanNqqxvQu9x8wz1tzDVozqmHGL oCqRN816FZ+IA== Received: by paulmck-ThinkPad-P17-Gen-1.home (Postfix, from userid 1000) id F247A5C015D; Wed, 31 Aug 2022 11:06:26 -0700 (PDT) From: "Paul E. McKenney" To: rcu@vger.kernel.org Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com, rostedt@goodmis.org, "Paul E. McKenney" Subject: [PATCH rcu 1/7] doc: Emphasize the need for explicit RCU read-side markers Date: Wed, 31 Aug 2022 11:06:19 -0700 Message-Id: <20220831180625.2692892-1-paulmck@kernel.org> X-Mailer: git-send-email 2.31.1.189.g2e36527f23 In-Reply-To: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> References: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: rcu@vger.kernel.org This commit updates checklist.rst to emphasize the need for explicit markers for RCU read-side critical sections. Signed-off-by: Paul E. McKenney --- Documentation/RCU/checklist.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 42cc5d891bd26..5eedef027d922 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -66,8 +66,13 @@ over a rather long period of time, but improvements are always welcome! As a rough rule of thumb, any dereference of an RCU-protected pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(), rcu_read_lock_sched(), or by the appropriate update-side lock. - Disabling of preemption can serve as rcu_read_lock_sched(), but - is less readable and prevents lockdep from detecting locking issues. + Explicit disabling of preemption (preempt_disable(), for example) + can serve as rcu_read_lock_sched(), but is less readable and + prevents lockdep from detecting locking issues. + + Please not that you *cannot* rely on code known to be built + only in non-preemptible kernels. Such code can and will break, + especially in kernels built with CONFIG_PREEMPT_COUNT=y. Letting RCU-protected pointers "leak" out of an RCU read-side critical section is every bit as bad as letting them leak out From patchwork Wed Aug 31 18:06:20 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Paul E. McKenney" X-Patchwork-Id: 12961192 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6F1FEECAAD1 for ; Wed, 31 Aug 2022 18:06:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232208AbiHaSGg (ORCPT ); Wed, 31 Aug 2022 14:06:36 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40748 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232140AbiHaSGe (ORCPT ); Wed, 31 Aug 2022 14:06:34 -0400 Received: from ams.source.kernel.org (ams.source.kernel.org [145.40.68.75]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 81385E3981; Wed, 31 Aug 2022 11:06:30 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 98E51B82272; Wed, 31 Aug 2022 18:06:28 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4ED4EC43142; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1661969187; bh=YULC0Awo0Pmc3BNtKXn9TIdi3s0Oc+2WQtMPeTYpzNg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bQUcWmkPJrpPakJFFhALVi+buMr/rimCe9eo9vtqxMWvPwSN22Pk1+aMA52vIuQfo sx/JtT95oOe+YpTicgrT362gvTmRzQGMTlZ2GzNJ5btt5A0AmJqTOPsZmouD6pkv2G LTZLJXyKAEOR9sB/Le11G7SciQg0d/BmGCjlj7rxqFT6ipIjcOc0tFbL89kJ/2j/R7 m7uP4oouL7HJ63C+sVrEwdGfCW0JYX5cocAQLZPJJp7JbFbR1smksgbEad6GObxkGM 3YCT0xGfDiuiPDbYfZwkJ2b61okWEM1Cj0q5MeMYS/NioZHSmHpTmjqO+3N4i8OJ8Q fM+M1Y4HFjIug== Received: by paulmck-ThinkPad-P17-Gen-1.home (Postfix, from userid 1000) id 013A65C019C; Wed, 31 Aug 2022 11:06:26 -0700 (PDT) From: "Paul E. McKenney" To: rcu@vger.kernel.org Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com, rostedt@goodmis.org, "Paul E. McKenney" Subject: [PATCH rcu 2/7] doc: Call out queue_rcu_work() for blocking RCU callbacks Date: Wed, 31 Aug 2022 11:06:20 -0700 Message-Id: <20220831180625.2692892-2-paulmck@kernel.org> X-Mailer: git-send-email 2.31.1.189.g2e36527f23 In-Reply-To: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> References: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: rcu@vger.kernel.org The current checklist.rst file correctly notes that RCU callbacks execute in BH context, and cannot block. This commit adds words advising people needing callbacks to block to use workqueues, for example, by replacing call_rcu() with queue_rcu_work(). Signed-off-by: Paul E. McKenney --- Documentation/RCU/checklist.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 5eedef027d922..2db206fc3465f 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -190,6 +190,9 @@ over a rather long period of time, but improvements are always welcome! 5. If call_rcu() or call_srcu() is used, the callback function will be called from softirq context. In particular, it cannot block. + If you need the callback to block, run that code in a workqueue + handler scheduled from the callback. The queue_rcu_work() + function does this for you in the case of call_rcu(). 6. Since synchronize_rcu() can block, it cannot be called from any sort of irq context. The same rule applies From patchwork Wed Aug 31 18:06:21 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Paul E. McKenney" X-Patchwork-Id: 12961195 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id CAF1EECAAD1 for ; Wed, 31 Aug 2022 18:06:40 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232176AbiHaSGj (ORCPT ); Wed, 31 Aug 2022 14:06:39 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40754 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232141AbiHaSGe (ORCPT ); Wed, 31 Aug 2022 14:06:34 -0400 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 813E8E3983; Wed, 31 Aug 2022 11:06:30 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id A0E3AB82273; Wed, 31 Aug 2022 18:06:28 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 48530C433D6; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1661969187; bh=j7Vt+WhUPkmdxBzO+D24Yf2KD8/sQg3Uw1rN8AJx8XI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DwI9B3r+CnqTXMKM5ybBKM/kKxZC0BwiGC+MLk85ckyYsA0g/s+tmuhe1SnCxrpBR hV2j2FGREwfxQ8ySaPlnI8p9/uZHyEZgcCAXUZ3goC3ifogzdf09qKf6claChLd84S ghDrcrHaOxX8iDjjfhJkTvxsbJRx8fExndJ2cL8CD2neyLxxHorM0VCGl4k6G+KNMX peLDis2g5qr5G/lsXoHmOYvCgIeEZAT7ukw1D6P97jR1s0i0rt3K0oWcIfHsZ6CW1O lc+BUXcJs883AbhVb07GNpibDI5K7FRJEh/YScwaBt8pVP6XAdIk21oyjAN0XxJ0ZU CsoVnuiASbO6Q== Received: by paulmck-ThinkPad-P17-Gen-1.home (Postfix, from userid 1000) id 034755C02A9; Wed, 31 Aug 2022 11:06:27 -0700 (PDT) From: "Paul E. McKenney" To: rcu@vger.kernel.org Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com, rostedt@goodmis.org, "Paul E. McKenney" Subject: [PATCH rcu 3/7] doc: Use rcu_barrier() to rate-limit RCU callbacks Date: Wed, 31 Aug 2022 11:06:21 -0700 Message-Id: <20220831180625.2692892-3-paulmck@kernel.org> X-Mailer: git-send-email 2.31.1.189.g2e36527f23 In-Reply-To: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> References: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: rcu@vger.kernel.org The checklist.rst document advises periodic synchronize_rcu() invocations to prevent callback flooding. However, rcu_barrier() is often a better choice. This commit therefore adds words to this effect. Signed-off-by: Paul E. McKenney --- Documentation/RCU/checklist.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 2db206fc3465f..178ca7547b987 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -305,7 +305,8 @@ over a rather long period of time, but improvements are always welcome! the machine. d. Periodically invoke synchronize_rcu(), permitting a limited - number of updates per grace period. + number of updates per grace period. Better yet, periodically + invoke rcu_barrier() to wait for all outstanding callbacks. The same cautions apply to call_srcu() and kfree_rcu(). From patchwork Wed Aug 31 18:06:22 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Paul E. McKenney" X-Patchwork-Id: 12961194 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 270B6C3DA6B for ; Wed, 31 Aug 2022 18:06:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232136AbiHaSGh (ORCPT ); Wed, 31 Aug 2022 14:06:37 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40684 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231482AbiHaSGe (ORCPT ); Wed, 31 Aug 2022 14:06:34 -0400 Received: from sin.source.kernel.org (sin.source.kernel.org [145.40.73.55]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 870C4E2C77; Wed, 31 Aug 2022 11:06:31 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sin.source.kernel.org (Postfix) with ESMTPS id 08F37CE205C; Wed, 31 Aug 2022 18:06:29 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 43737C43470; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1661969187; bh=sun+T8lzCvE9Y/BRrlU22ISf75bNVcTgeX9rLFqYRB8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iCaRESPLHwkWlJoW9d0TkE9FRZlHhA2uF3DyFY1pucQ/RM3ugsObCtlFes/gkHP9E O6Vb011GJ9V21qlWUeeEbHYb0rjt2N33wHXUkrF7vTw1375Xg/RiX33fd5q3wH7zIA 7aip6Vv3j6gWbpl8mNWvs3d6iWk/7TlsfgcvA77GKMimPf8YWe2V9Z2QTY9ara/cny 6nsq7daNg7GyruvI+BVR4aClH4nddTvlB1xcoEQ1RuE+4W7FSBlT4V8dgc0XApejta amqng886nnnq9cfRd+La5WPNr2HJck3jGn8RpVG5aFsmRPXq3Y3HHYRFT3SinGG4M+ RWnb1/FekwgPA== Received: by paulmck-ThinkPad-P17-Gen-1.home (Postfix, from userid 1000) id 0578F5C0513; Wed, 31 Aug 2022 11:06:27 -0700 (PDT) From: "Paul E. McKenney" To: rcu@vger.kernel.org Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com, rostedt@goodmis.org, "Paul E. McKenney" Subject: [PATCH rcu 4/7] doc: Fix list: rcu_access_pointer() is not lockdep-checked Date: Wed, 31 Aug 2022 11:06:22 -0700 Message-Id: <20220831180625.2692892-4-paulmck@kernel.org> X-Mailer: git-send-email 2.31.1.189.g2e36527f23 In-Reply-To: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> References: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: rcu@vger.kernel.org The rcu_access_pointer() macro does not consult lockdep by design because it is intended to be used outside of RCU read-side critical sections. This commit therefore makes a separate list for it in whatisRCU.rst. Similarly, RCU_LOCKDEP_WARN(), rcu_sleep_check(), and RCU_NONIDLE() do not do anything with pointer access. This commit therefore creates a separate utility-API list for them. Signed-off-by: Paul E. McKenney --- Documentation/RCU/whatisRCU.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 77ea260efd120..6940e0fe8599b 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -1057,14 +1057,20 @@ SRCU: Initialization/cleanup:: init_srcu_struct cleanup_srcu_struct -All: lockdep-checked RCU-protected pointer access:: +All: lockdep-checked RCU utility APIs:: - rcu_access_pointer - rcu_dereference_raw RCU_LOCKDEP_WARN rcu_sleep_check RCU_NONIDLE +All: Unchecked RCU-protected pointer access:: + + rcu_dereference_raw + +All: Unchecked RCU-protected pointer access with dereferencing prohibited:: + + rcu_access_pointer + See the comment headers in the source code (or the docbook generated from them) for more information. From patchwork Wed Aug 31 18:06:23 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Paul E. McKenney" X-Patchwork-Id: 12961189 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id CD0F3ECAAD3 for ; Wed, 31 Aug 2022 18:06:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232120AbiHaSGe (ORCPT ); Wed, 31 Aug 2022 14:06:34 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40656 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232114AbiHaSGc (ORCPT ); Wed, 31 Aug 2022 14:06:32 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 20DCBE1902; Wed, 31 Aug 2022 11:06:28 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 069CC61BF0; Wed, 31 Aug 2022 18:06:28 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 58934C43140; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1661969187; bh=We5lyI+7f6SWu202lqcy/4q82tJxbRstsBHMbMVe9Zw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=F4GZ/sk9gMawWzdvEX3ArkdMhIauSgivfCT3kCmZ82bEygfTM+qjfIbBqwu0G9lUN n20NW5MQ6vsoKmVSi85PpWTpRkvXIcWYoTQtXED7A/FEaJKRPgqJxO9fl/Y1s03NHU dWl/VRNrpsZzhM0GKUyMPLVFv6r6ady5qMZbel5YvRoXakk1gg2zlNotF1CLfGa7DQ IDKeKXzjIdUK5DDYmw48Z4+e3hiJj1Mhm8o+Yi3gD0aZWRRF/GH/l01ffxt1kDtp6C sE2S43ArxjLz5kjzIO+e5J9nvzg0NaB9AX63z4+B3M38edIfjyJdWh5QmiGyUCskAL 0qvFCqVB/pzbw== Received: by paulmck-ThinkPad-P17-Gen-1.home (Postfix, from userid 1000) id 075505C06A7; Wed, 31 Aug 2022 11:06:27 -0700 (PDT) From: "Paul E. McKenney" To: rcu@vger.kernel.org Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com, rostedt@goodmis.org, "Paul E. McKenney" Subject: [PATCH rcu 5/7] doc: Update rcu_access_pointer() advice in rcu_dereference.rst Date: Wed, 31 Aug 2022 11:06:23 -0700 Message-Id: <20220831180625.2692892-5-paulmck@kernel.org> X-Mailer: git-send-email 2.31.1.189.g2e36527f23 In-Reply-To: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> References: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: rcu@vger.kernel.org This commit updates the rcu_access_pointer() advice, noting that its return value should not be assigned to a local variable, and also noting that there is little point in using rcu_access_pointer() within an RCU read-side critical section. Signed-off-by: Paul E. McKenney --- Documentation/RCU/rcu_dereference.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst index 0b418a5b243c5..81e828c8313b8 100644 --- a/Documentation/RCU/rcu_dereference.rst +++ b/Documentation/RCU/rcu_dereference.rst @@ -128,10 +128,16 @@ Follow these rules to keep your RCU code working properly: This sort of comparison occurs frequently when scanning RCU-protected circular linked lists. - Note that if checks for being within an RCU read-side - critical section are not required and the pointer is never - dereferenced, rcu_access_pointer() should be used in place - of rcu_dereference(). + Note that if the pointer comparison is done outside + of an RCU read-side critical section, and the pointer + is never dereferenced, rcu_access_pointer() should be + used in place of rcu_dereference(). In most cases, + it is best to avoid accidental dereferences by testing + the rcu_access_pointer() return value directly, without + assigning it to a variable. + + Within an RCU read-side critical section, there is little + reason to use rcu_access_pointer(). - The comparison is against a pointer that references memory that was initialized "a long time ago." The reason From patchwork Wed Aug 31 18:06:24 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Paul E. McKenney" X-Patchwork-Id: 12961193 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id C5A38C0502A for ; Wed, 31 Aug 2022 18:06:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232212AbiHaSGi (ORCPT ); Wed, 31 Aug 2022 14:06:38 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40756 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232143AbiHaSGe (ORCPT ); Wed, 31 Aug 2022 14:06:34 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8072AE395B; Wed, 31 Aug 2022 11:06:29 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 8E40D61C11; Wed, 31 Aug 2022 18:06:28 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A1410C433B5; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1661969187; bh=kpYKwMnffVl1nsj+jg2r15lnrXjU997U2XZSk+XwMCw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lcosIxom1w6n589swGSjYVyxOy0WWlOjPSWmLPz1RWc3RBFuybkPWoKbGBI7pclgg ZUquTdoerz5JsV2KTDpU2POTgRcVft49OhyFWjOZR3R4/dMv/Qfu2q76pxImQBiQFF ygql/vhgJHuJodsJ2ktyjDZuzoD0An0gAuLble+w2ufEuFSP2hqgGtuhMxDO72xUsP VfLaqgfxm54gv4hleGgkuCY4nX/4MZWZYFA0BOhSet7EAGkqVJ5V/afy+f8moocxVY nv5gcMjGYM00uop1FL/hDR7Y4uBRpu2J+KdduUEUatbydnjHd6FnUGX3kf4wwdTLHx tqg3H0yb5x1wQ== Received: by paulmck-ThinkPad-P17-Gen-1.home (Postfix, from userid 1000) id 091545C090A; Wed, 31 Aug 2022 11:06:27 -0700 (PDT) From: "Paul E. McKenney" To: rcu@vger.kernel.org Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com, rostedt@goodmis.org, "Paul E. McKenney" Subject: [PATCH rcu 6/7] doc: SLAB_TYPESAFE_BY_RCU uses cannot rely on spinlocks Date: Wed, 31 Aug 2022 11:06:24 -0700 Message-Id: <20220831180625.2692892-6-paulmck@kernel.org> X-Mailer: git-send-email 2.31.1.189.g2e36527f23 In-Reply-To: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> References: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: rcu@vger.kernel.org Because the SLAB_TYPESAFE_BY_RCU code does not zero pages that are to be broken up into slabs, the memory returned by kmem_cache_alloc() must be fully initialized, including any spinlocks included in the newly allocated structure. This means that readers attempting to look up an SLAB_TYPESAFE_BY_RCU object must use a reference-counting approach. A spinlock may be acquired only after a reference is obtained, which prevents that object from being passed to kmem_struct_free(), but only while that reference continues to be held. Signed-off-by: Paul E. McKenney --- Documentation/RCU/whatisRCU.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 6940e0fe8599b..97f2d0fa84dfa 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -915,13 +915,18 @@ which an RCU reference is held include: The understanding that RCU provides a reference that only prevents a change of type is particularly visible with objects allocated from a slab cache marked ``SLAB_TYPESAFE_BY_RCU``. RCU operations may yield a -reference to an object from such a cache that has been concurrently -freed and the memory reallocated to a completely different object, -though of the same type. In this case RCU doesn't even protect the -identity of the object from changing, only its type. So the object -found may not be the one expected, but it will be one where it is safe -to take a reference or spinlock and then confirm that the identity -matches the expectations. +reference to an object from such a cache that has been concurrently freed +and the memory reallocated to a completely different object, though of +the same type. In this case RCU doesn't even protect the identity of the +object from changing, only its type. So the object found may not be the +one expected, but it will be one where it is safe to take a reference +(and then potentially acquiring a spinlock), allowing subsequent code +to check whether the identity matches expectations. It is tempting +to simply acquire the spinlock without first taking the reference, but +unfortunately any spinlock in a ``SLAB_TYPESAFE_BY_RCU`` object must be +initialized after each and every call to kmem_cache_alloc(), which renders +reference-free spinlock acquisition completely unsafe. Therefore, when +using ``SLAB_TYPESAFE_BY_RCU``, make proper use of a reference counter. With traditional reference counting -- such as that implemented by the kref library in Linux -- there is typically code that runs when the last From patchwork Wed Aug 31 18:06:25 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Paul E. McKenney" X-Patchwork-Id: 12961191 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id DAF09ECAAD4 for ; Wed, 31 Aug 2022 18:06:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231978AbiHaSGg (ORCPT ); Wed, 31 Aug 2022 14:06:36 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40726 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232131AbiHaSGd (ORCPT ); Wed, 31 Aug 2022 14:06:33 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8096CE3961; Wed, 31 Aug 2022 11:06:29 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 8DD8B61C0D; Wed, 31 Aug 2022 18:06:28 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A160EC4314D; Wed, 31 Aug 2022 18:06:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1661969187; bh=rs0JwDT2NwpNg38wdlwMWQtd1f0wzKLTC7t9vHoDofY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GN6Vr0/SNEhlqwkE+C5hAfS6zQ5Iok6a4N2Fb5De2CM4iQb/KMMVUSP1RkrICOmDl SahAKk0uFt3MD0/222qERXCycipcYwy/rm5gNF2yZyIS1ofQS6DMAk0d1sDIOC2t4y vqa1JBNrMygaX51m80KrFCMxnnWJfwZ41s0dOInC82vPESXkKmsuSK/SRMpH5EYlux v29dm+9+CeMbNeGjzKPavJycTB33Y77UwdTyMCbAydH7QH6T+LjBwTkDGsB7n76/HO +QDw7/6HkRZb6WWty68pYAwrvH+dDDg3hNkjrldVy14arAiVrL9JXa8EaOg4j67D7+ ZeR0mjkoUmv9A== Received: by paulmck-ThinkPad-P17-Gen-1.home (Postfix, from userid 1000) id 0AD6A5C0950; Wed, 31 Aug 2022 11:06:27 -0700 (PDT) From: "Paul E. McKenney" To: rcu@vger.kernel.org Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com, rostedt@goodmis.org, Shao-Tse Hung , "Paul E . McKenney" Subject: [PATCH rcu 7/7] doc/rcu: Update LWN article URLs and add 2019 article Date: Wed, 31 Aug 2022 11:06:25 -0700 Message-Id: <20220831180625.2692892-7-paulmck@kernel.org> X-Mailer: git-send-email 2.31.1.189.g2e36527f23 In-Reply-To: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> References: <20220831180617.GA2692480@paulmck-ThinkPad-P17-Gen-1> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: rcu@vger.kernel.org From: Shao-Tse Hung This patch adds LWN articles about RCU APIs which were released in 2019. Also, HTTP URLs are replaced by HTTPS. Signed-off-by: Shao-Tse Hung Signed-off-by: Paul E. McKenney --- Documentation/RCU/whatisRCU.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 97f2d0fa84dfa..1c747ac3f2c8e 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -6,13 +6,15 @@ What is RCU? -- "Read, Copy, Update" Please note that the "What is RCU?" LWN series is an excellent place to start learning about RCU: -| 1. What is RCU, Fundamentally? http://lwn.net/Articles/262464/ -| 2. What is RCU? Part 2: Usage http://lwn.net/Articles/263130/ -| 3. RCU part 3: the RCU API http://lwn.net/Articles/264090/ -| 4. The RCU API, 2010 Edition http://lwn.net/Articles/418853/ -| 2010 Big API Table http://lwn.net/Articles/419086/ -| 5. The RCU API, 2014 Edition http://lwn.net/Articles/609904/ -| 2014 Big API Table http://lwn.net/Articles/609973/ +| 1. What is RCU, Fundamentally? https://lwn.net/Articles/262464/ +| 2. What is RCU? Part 2: Usage https://lwn.net/Articles/263130/ +| 3. RCU part 3: the RCU API https://lwn.net/Articles/264090/ +| 4. The RCU API, 2010 Edition https://lwn.net/Articles/418853/ +| 2010 Big API Table https://lwn.net/Articles/419086/ +| 5. The RCU API, 2014 Edition https://lwn.net/Articles/609904/ +| 2014 Big API Table https://lwn.net/Articles/609973/ +| 6. The RCU API, 2019 Edition https://lwn.net/Articles/777036/ +| 2019 Big API Table https://lwn.net/Articles/777165/ What is RCU?