From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 40B11256C88 for ; Wed, 24 Dec 2025 14:10:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=216.40.44.10 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766585415; cv=none; b=naCCGvfr9H99m1MSR1yzPCzHOgFP/5GedgTdCyvA0Kvq69SG4hk27SsKSMKyfalWBmp/U2TznV5KWhwUxrgagY5FNqUeErfikc+uUZOzQREe1EIJLxoEGC1sm8Anzc/2nsR1IGcP2lJWWxCS2+IHuRXGMEGal78CcJVOR/m8/XU= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766585415; c=relaxed/simple; bh=x4uYaHFY6ZHFYJ7hWHqvHdo9jwxm7dM2+LRynU1+Klc=; h=Date:From:To:Cc:Subject:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=d13uoKExgbogw27V6qMMKB9763Badm3pVqAKpRQjqiQkSCzXdXl7YP5Qj7qnj7NWhhv+5lLkFuQnsUeTmQVCsrPHVU7eTMThWKy2zgC+IbVwmQwaW74UAgU5yGW34TBVK96VzlASMm4zUN+i1aOwWJ35YHnwigQIEqmWMnCRoNo= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=goodmis.org; spf=pass smtp.mailfrom=goodmis.org; arc=none smtp.client-ip=216.40.44.10 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=goodmis.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=goodmis.org Received: from omf18.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay06.hostedemail.com (Postfix) with ESMTP id 9FFF81381BB; Wed, 24 Dec 2025 14:10:09 +0000 (UTC) Received: from [HIDDEN] (Authenticated sender: rostedt@goodmis.org) by omf18.hostedemail.com (Postfix) with ESMTPA id C62EB30; Wed, 24 Dec 2025 14:10:06 +0000 (UTC) Date: Wed, 24 Dec 2025 09:11:58 -0500 From: Steven Rostedt To: "Paul E. McKenney" Cc: Sasha Levin , Theodore Tso , Julia Lawall , Gabriele Paoloni , Kate Stewart , Chuck Wolber , Dmitry Vyukov , Mark Rutland , Thomas Gleixner , Lorenzo Stoakes , Shuah Khan , Chris Mason , linux-kernel@vger.kernel.org Subject: Re: Follow-up on Linux-kernel code accessibility Message-ID: <20251224091158.6ab443cb@gandalf.local.home> In-Reply-To: <89457d2d-153e-4274-b485-2ace983cec4f@paulmck-laptop> References: <90d56d30-232d-4930-ad9f-5aebade7cdf2@paulmck-laptop> <636d1798-3b37-293a-51b2-55d2ecc6d2d@inria.fr> <20251219170945.GA32430@macsyma.lan> <20251219132812.2a3516df@gandalf.local.home> <20251222104209.15e98861@gandalf.local.home> <89457d2d-153e-4274-b485-2ace983cec4f@paulmck-laptop> X-Mailer: Claws Mail 3.20.0git84 (GTK+ 2.24.33; x86_64-pc-linux-gnu) Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Rspamd-Server: rspamout07 X-Rspamd-Queue-Id: C62EB30 X-Stat-Signature: dn3ynp9xxuuh6ycsoxew5g6wwk6dywgk X-Session-Marker: 726F737465647440676F6F646D69732E6F7267 X-Session-ID: U2FsdGVkX19rN79/hkUBP5K3mOpjiW9ropgZaWPNTBo= X-HE-Tag: 1766585406-96801 X-HE-Meta: U2FsdGVkX18h1W1DAFcH75yU9ZKMInc0658D0LU9Lhm4+D73nmdfC1kJxrY0d0XQNg3vi9bnFBRSJkmm9gS36TzKtGo1MFD60lfYXP8A2EHMjSfPqfXJOOltzvroYwdImVf6Ld0u+WBVyFadErlzIiGDmFbdylXXlPXrXe0vD2o7/O+/NbSREoBoBkLlUgcc2dbDffP5uYf479Tad29boTQRB5UAFP1cBRlgDNySTFGRWOHLsqnJRP6qsmj7N61TXrrkUhy71NRWhKLtHsjdPYinTS3DLUwrGcQzXlUt5cwylp7ORCdMMdbiLX49zKwZUDoFTQH8MOM40Q4Pedvh8AwjRv7L6UgT On Tue, 23 Dec 2025 15:46:10 -0800 "Paul E. McKenney" wrote: > > I'm really only interested in the more subtle and complex functions. The > > majority of those 100,000 functions do not need extra comments. > > Sigh. "Subtle" and "Complex" are rather subjective, and given the > goals of one of the LPC MCs, others outside the community might decide > to weigh in. I only stated what I'm interested in. Others may have different ideas. > > > And I honestly don't care about increasing the source due to comments. > > That's a good thing. I like going to a subsystem and seeing a lot of > > comments in the code. I hate going to a subsystem where there's no > > comments, thus you need to try to figure out the context from the code, and > > when I had that, I usually got it wrong. > > I do care. After all, life got much better when (mostly) ineffective > "Only invoke this function with interrupts disabled" comments became > "lockdep_assert_irqs_disabled()" executable code. Yes, constraints of a function do better with annotations like this. But "Only invoke this function if interrupts are disabled" does nothing to describe what the function is doing. > > So if we are going to add more explicit constraints in header comments, > we owe it to ourselves to see what can be made executable so that > normal testing has at least some chance of detecting violations of > these constraints. I agree on constraints. But how a function works is different. > What about walkthroughs? Producing external documentation based on > the code? I'm not sure what you mean by "walkthroughs". AI can help give a general idea on code, but it still needs the author of the code to verify it. One place I recently found where I wish there was some more descriptions of what the code is doing was here: /* * Loop doing repeated quiescent-state forcing until the grace period ends. */ static noinline_for_stack void rcu_gp_fqs_loop(void) { bool first_gp_fqs = true; int gf = 0; unsigned long j; int ret; struct rcu_node *rnp = rcu_get_root(); j = READ_ONCE(jiffies_till_first_fqs); if (rcu_state.cbovld) gf = RCU_GP_FLAG_OVLD; ret = 0; for (;;) { if (rcu_state.cbovld) { j = (j + 2) / 3; if (j <= 0) j = 1; } if (!ret || time_before(jiffies + j, rcu_state.jiffies_force_qs)) { WRITE_ONCE(rcu_state.jiffies_force_qs, jiffies + j); /* * jiffies_force_qs before RCU_GP_WAIT_FQS state * update; required for stall checks. */ smp_wmb(); WRITE_ONCE(rcu_state.jiffies_kick_kthreads, jiffies + (j ? 3 * j : 2)); } There's a bit of magical manipulation of "j" that I have no idea why it's doing that. ;-) I would love if Julia or Gabriele came up with some specification for that function. -- Steve