From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) (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 EFA9A135A53 for ; Fri, 26 Dec 2025 19:22:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=18.9.28.11 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766776983; cv=none; b=c66wYkOfbeEqlwlxjeyXuvpMDYAa0FhtSwnDe+aeNSxif/MnoNbI/553REJQU/Pjp7d555BowkCst7i9Sii6sglI+yEMoOA7fReNAS7KByIkudZ/kbNFFfS2iaGEpD+IDOYLSE/Q69fSIGG2HEiGUjUvyS9AF/eerawLLNSVxxw= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766776983; c=relaxed/simple; bh=ZcNKjgt6Lt3K9sp4M7338if2ioSxZxNfGjfvdLfgAnU=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=J2UWSDzhrV9aovjQT6xZQ4BsvEu+f1vjJie+LYcUd/dFa4/CB9eAt3BZfUHBCqO+62/7w1GbB1M7skiav91ycGa/dlBxTZCNEsA5aa5JQXMTJ1Ae+aHyxclvPGMdoeBScDeg4OqYBpogeebaUoBc/qKhqWQr1B1FXkJdUdEZMxA= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=mit.edu; spf=pass smtp.mailfrom=mit.edu; dkim=pass (2048-bit key) header.d=mit.edu header.i=@mit.edu header.b=FU9fiFj+; arc=none smtp.client-ip=18.9.28.11 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=mit.edu Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=mit.edu Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=mit.edu header.i=@mit.edu header.b="FU9fiFj+" Received: from macsyma.thunk.org (c-69-138-114-91.hsd1.fl.comcast.net [69.138.114.91]) (authenticated bits=0) (User authenticated as tytso@ATHENA.MIT.EDU) by outgoing.mit.edu (8.14.7/8.12.4) with ESMTP id 5BQJMIlp018309 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Fri, 26 Dec 2025 14:22:19 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mit.edu; s=outgoing; t=1766776943; bh=o/WRrYUqABDBD82ZfU8dQFxoUUnZ+ddF35c9QzBOfp0=; h=Date:From:Subject:Message-ID:MIME-Version:Content-Type; b=FU9fiFj+zvvNGt7GeAwL8XyCsCy0Uo60YaJtIUAqJ0iFUt6HU6u54YWQKDBkKq8rJ m33eZ0JcId494m0//LuSjggad4cylAddYE6ZWkynoy80NFoV7UdiGiDCrDd1mIx9ro nFHFeHi9AxpZ4ngnL5MGXmUjGzWXEcwa2xdQVEKpouDRwnnonZ/0o+lTJqkvgSh2Vt dlo7Gvv8TattWLkW4u5bZaswGCG7mbNOXqqxDpqbDfUtvuNJsXATjNeM5f53mz5Nmm +739IcO7vnoSeng6XkOmdT2g+l/TwEUDF0oP4C3bTone2HZrsrh4WxxSozeaFAD1nJ JOY9w+nWVQZ0A== Received: by macsyma.thunk.org (Postfix, from userid 15806) id B8D8851E9B81; Fri, 26 Dec 2025 14:22:17 -0500 (EST) Date: Fri, 26 Dec 2025 14:22:17 -0500 From: "Theodore Tso" To: Steven Rostedt Cc: "Paul E. McKenney" , Sasha Levin , 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: <20251226192217.GB67711@macsyma.local> References: <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> <20251224091158.6ab443cb@gandalf.local.home> <20251225150331.GB15088@macsyma.lan> <20251226114830.6bc7a3eb@gandalf.local.home> 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-Disposition: inline In-Reply-To: <20251226114830.6bc7a3eb@gandalf.local.home> On Fri, Dec 26, 2025 at 11:48:30AM -0500, Steven Rostedt wrote: > Agreed, but knowing what the function is doing should give you some idea of > how it is doing it. > > "Loop doing repeated quiescent-state forcing until the grace period ends." > > Is the only description of "what the function is doing", but it gives you > no clue to why it's using those magic numbers. There should be comments > about how the magic numbers relate to the what. Sure, but rcu_gp_fqs_loop() is a static, internal function. I agree that better documentation would be usefui for people who want to modify the internals of the RCU infrastructure, but it's not something that should be in kernel documentation for newcomers to kernel development. When we talk about making the kernel code more accessible, it's really important to keep in mind that different audiences may have different needs, and too much information can be just as confusing as too little. It seems likely that most newcomers aren't going to be looking to make changes to important systems like RCU. That being said, even though most newcomers aren't probably going to be making changes to file systems, as a file system maintainer I admittedly to have a vested interest in making easier for intermediate-level kernel developers who might take an interest to ext4 development to have an easy path to do so. So I get where Paul is coming from. When we're talking about making the kernel code more accessible, we need need to be very explicit about which target audiences we are targetting, because the strategies might be different for different readers. - Ted