From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752386AbeENDQG (ORCPT ); Sun, 13 May 2018 23:16:06 -0400 Received: from mail-pl0-f68.google.com ([209.85.160.68]:44129 "EHLO mail-pl0-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752191AbeENDQB (ORCPT ); Sun, 13 May 2018 23:16:01 -0400 X-Google-Smtp-Source: AB8JxZpKzvH2A8Fu/x9tcC3kCvDk0mA+R7AITfHxPtZXJ1fd9qfjrVGmuPC8bvLTG+feGM7fuaJMEA== From: "Joel Fernandes (Google)" To: linux-kernel@vger.kernel.org Cc: "Joel Fernandes (Google)" , "Paul E. McKenney" , Josh Triplett , Steven Rostedt , Mathieu Desnoyers , Lai Jiangshan , byungchul.park@lge.com, kernel-team@android.com Subject: [PATCH RFC 1/8] rcu: Add comment documenting how rcu_seq_snap works Date: Sun, 13 May 2018 20:15:34 -0700 Message-Id: <20180514031541.67247-2-joel@joelfernandes.org> X-Mailer: git-send-email 2.17.0.441.gb46fe60e1d-goog In-Reply-To: <20180514031541.67247-1-joel@joelfernandes.org> References: <20180514031541.67247-1-joel@joelfernandes.org> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org rcu_seq_snap may be tricky for someone looking at it for the first time. Lets document how it works with an example to make it easier. Signed-off-by: Joel Fernandes (Google) --- kernel/rcu/rcu.h | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/kernel/rcu/rcu.h b/kernel/rcu/rcu.h index 003671825d62..fc3170914ac7 100644 --- a/kernel/rcu/rcu.h +++ b/kernel/rcu/rcu.h @@ -91,7 +91,29 @@ static inline void rcu_seq_end(unsigned long *sp) WRITE_ONCE(*sp, rcu_seq_endval(sp)); } -/* Take a snapshot of the update side's sequence number. */ +/* + * Take a snapshot of the update side's sequence number. + * + * This function predicts what the grace period number will be the next + * time an RCU callback will be executed, given the current grace period's + * number. This can be gp+1 if RCU is idle, or gp+2 if a grace period is + * already in progress. + * + * We do this with a single addition and masking. + * For example, if RCU_SEQ_STATE_MASK=1 and the least significant bit (LSB) of + * the seq is used to track if a GP is in progress or not, its sufficient if we + * add (2+1) and mask with ~1. Let's see why with an example: + * + * Say the current seq is 6 which is 0b110 (gp is 3 and state bit is 0). + * To get the next GP number, we have to at least add 0b10 to this (0x1 << 1) + * to account for the state bit. However, if the current seq is 7 (gp is 3 and + * state bit is 1), then it means the current grace period is already in + * progress so the next time the callback will run is at the end of grace + * period number gp+2. To account for the extra +1, we just overflow the LSB by + * adding another 0x1 and masking with ~0x1. In case no GP was in progress (RCU + * is idle), then the addition of the extra 0x1 and masking will have no + * effect. This is calculated as below. + */ static inline unsigned long rcu_seq_snap(unsigned long *sp) { unsigned long s; -- 2.17.0.441.gb46fe60e1d-goog