From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) (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 CF3CF1EB9E1 for ; Fri, 26 Dec 2025 16:48:41 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=216.40.44.17 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766767723; cv=none; b=qht6EP7CaCLqMEEJoNPgMzc5xsNhdQyBFgz3FVZbBpiRymrpA8QqYJfbrynOjjL3VlpcQPTlEeJo59MCDtNYcbWjJkFOoxyFaRokkDNsdlxVZq2s0GcUGFvyWkzK3IgbyGxX61+yKXfRmB4fWR5puGmJlmN2Fe8koPAp/ChrQKw= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766767723; c=relaxed/simple; bh=5j6zb1jMQ7JWGXgLg1+WW/9qg/WJy7L2ogcYAEiWxwQ=; h=Date:From:To:Cc:Subject:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=JG5aSZZR5zKdL+JIb2RuWLAt+S26hgXa6/7Ogh0D2IgKL2IYximFYRxfSzBawh11GDaTDJuqIbNvH8RYse3PFdIi3wqJzIrx8YBrcjHqI2ppWhTJYeUvfUkJ0969mvwSNdeQ7AasxsjxJV+cgESIqVtm27LuSfLdFdk5xHXu2bc= 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.17 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 omf11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay08.hostedemail.com (Postfix) with ESMTP id 86070141799; Fri, 26 Dec 2025 16:48:34 +0000 (UTC) Received: from [HIDDEN] (Authenticated sender: rostedt@goodmis.org) by omf11.hostedemail.com (Postfix) with ESMTPA id 9963E20031; Fri, 26 Dec 2025 16:48:31 +0000 (UTC) Date: Fri, 26 Dec 2025 11:48:30 -0500 From: Steven Rostedt To: "Theodore Tso" 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: <20251226114830.6bc7a3eb@gandalf.local.home> In-Reply-To: <20251225150331.GB15088@macsyma.lan> 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> <20251224091158.6ab443cb@gandalf.local.home> <20251225150331.GB15088@macsyma.lan> 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-Stat-Signature: os754p88615sti3ukbtxwszwjdba7th7 X-Rspamd-Server: rspamout01 X-Rspamd-Queue-Id: 9963E20031 X-Session-Marker: 726F737465647440676F6F646D69732E6F7267 X-Session-ID: U2FsdGVkX1+xfMkNm7e5OjJkuvz7RFOOxDg3CxUI0q8= X-HE-Tag: 1766767711-128127 X-HE-Meta: U2FsdGVkX1+BpHfGBS9MrQmLR2aBdFj/4DTERkhLeSL6PcLeTMmlIYccRgloqaFVzm4zWDaOk8Iyb5MIgtQear8yqv5MNx8iVdUb8uuP3cPr0MHB2pOa6TkZ6ARk++tyBNAkDIiPy1zFlc70TaOngTlCSUtxQAOsIquZ3O2M+mYwJam6jyPVveidPk8ChnEnKOBXKQnCsT2F+bdABvBIiuuqqJ31/gkAVNsNtFdKt7/STkP6/J6jBFuh0JL33WrOXJLqSJhoW+eXSAboOma0yC6zIwO/wdfzHRNuE1ICEFpnZzMxaz2dKeuV+GYELq/M On Thu, 25 Dec 2025 10:03:31 -0500 "Theodore Tso" wrote: > > 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. > > I think we need to separate out two different things. The first is > <> the function is doing, and the other is <> the function > is doing it. The first is the specification, or the interface > contract. The second is the implementation details that are important > if you need to modify the function, or want to verify its corrections. 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. As Julia said in one of our meetings, the "what a function is doing" should describe enough so that if you gave that to two different developers they would come up with similar code. Different implementations, but at least they should have the same result. > > I'm reminded of the ancient Unix documentation of how context > switching was implemented on a PDP-11, "You are not expected to > understand this". But as long as you understood what it was doing, > the fact the magic wasn't described in the source code might be OK. > OTOH, it's what inspired the Lion's Commentary on the Unix Source > Code book. :-) Reminds me of a saying I saw posted to a developer's desk back in 1992 at Martin Marietta: "I don't document my code. If it was hard to write, it should be hard to understand!" :-p -- Steve