From mboxrd@z Thu Jan 1 00:00:00 1970 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 34E70C77B70 for ; Thu, 6 Apr 2023 12:38:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237674AbjDFMit (ORCPT ); Thu, 6 Apr 2023 08:38:49 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38774 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229546AbjDFMir (ORCPT ); Thu, 6 Apr 2023 08:38:47 -0400 Received: from casper.infradead.org (casper.infradead.org [IPv6:2001:8b0:10b:1236::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 366CF76A9; Thu, 6 Apr 2023 05:38:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=In-Reply-To:Content-Type:MIME-Version: References:Message-ID:Subject:Cc:To:From:Date:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description; bh=6G0PeHjBucaMpcTqS+MbmLttXP4X+8vdHS54iSMHEkE=; b=pocCnMFjveWReclFnOvNIHXaFy 3GrG9RU1yLbNQTlpqnucYYV6Vo765+4G1vrs+PrS2z6+TblszZYRJ0sAu9sAolqPHY8Tp8KAhAx4r oiWVOzNoX/o/MUudT1aKAAs0W8mSmuV5tz0uUB76tbxk8uF8Dc6OZ728w1kpE3i8o+u/GJAXDJYtC oVXXOKLTsGSCzdjzmTQbivx8VQ2VymC+L+sxhHMvJd6L4TX5oxAtAITYIbtut0ZzqL2LVmIkmxa2U 3PUdMvlbPRNC9SfEdWT8zsC2K/IBJQQxdtLcWHsBft4T43Qj0OBiFHHMshHhOO5qBZIAb4+XkKIh5 Vf6HDY5A==; Received: from j130084.upc-j.chello.nl ([24.132.130.84] helo=noisy.programming.kicks-ass.net) by casper.infradead.org with esmtpsa (Exim 4.94.2 #2 (Red Hat Linux)) id 1pkOsI-00HPw3-BW; Thu, 06 Apr 2023 12:37:58 +0000 Received: from hirez.programming.kicks-ass.net (hirez.programming.kicks-ass.net [192.168.1.225]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by noisy.programming.kicks-ass.net (Postfix) with ESMTPS id 11D04300194; Thu, 6 Apr 2023 14:37:55 +0200 (CEST) Received: by hirez.programming.kicks-ass.net (Postfix, from userid 1000) id 903182CB641A9; Thu, 6 Apr 2023 14:37:55 +0200 (CEST) Date: Thu, 6 Apr 2023 14:37:55 +0200 From: Peter Zijlstra To: Jiri Slaby Cc: Paolo Bonzini , Lai Jiangshan , Dave Hansen , linux-kernel@vger.kernel.org, Lai Jiangshan , "H. Peter Anvin" , Andi Kleen , Andrew Cooper , Andy Lutomirski , Asit Mallick , Cfir Cohen , Dan Williams , David Kaplan , David Rientjes , Erdem Aktas , Jan Kiszka , Joerg Roedel , Juergen Gross , Kees Cook , Kirill Shutemov , Kuppuswamy Sathyanarayanan , Linus Torvalds , Mike Stunes , Raj Ashok , Sean Christopherson , Thomas Gleixner , Tom Lendacky , Tony Luck , kvm@vger.kernel.org, linux-coco@lists.linux.dev, x86@kernel.org Subject: Re: [RFC PATCH 0/7] x86/entry: Atomic statck switching for IST Message-ID: <20230406123755.GC392176@hirez.programming.kicks-ass.net> References: <20230403140605.540512-1-jiangshanlai@gmail.com> <19035c40-e756-6efd-1c02-b09109fb44c1@intel.com> <3591487f-96ae-3ab7-6ce7-e524a070c9e7@redhat.com> <20230406101254.GI386572@hirez.programming.kicks-ass.net> <26be2c81-9431-6b43-e3e9-52d7d184750e@kernel.org> <20230406104750.GA392176@hirez.programming.kicks-ass.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, Apr 06, 2023 at 01:04:16PM +0200, Jiri Slaby wrote: > Definitely it _can_ defeat the purpose and be heavily formatted.But it > doesn't have to. It's like programming in perl. > > What I had in mind was e.g. "DOC: TTY Struct Flags": > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/tty.h#n261 * TTY_THROTTLED * Driver input is throttled. The ldisc should call * :c:member:`tty_driver.unthrottle()` in order to resume reception when * it is ready to process more data (at threshold min). That whole :c:member:'tty_driver.unthrottle()' is an abomination and has no place in a comment. > Resulting in: > https://www.kernel.org/doc/html/latest/driver-api/tty/tty_struct.html#tty-struct-flags > > Both the source and the result are quite readable, IMO. And the markup in > the source is not mandatory, it's only for emphasizing and hyperlinks. > > As I wrote, you can link the comment in the code. But definitely you don't > have to, if you don't want. I like the linking in Documentation as I can put > the pieces from various sources/headers together to one place and build a > bigger picture. > > > I really detest that whole RST thing, and my solution is to explicitly > > not write kerneldoc, that way the doc generation stuff doesn't complain > > and I don't get random drive by patches wrecking the perfectly readable > > comment. > > Sure. Rst _sources_ are not readable, IMO. Only generated man pages or html > are. But code comments are read in a text editor, not a browser. Hence all the markup is counter productive. Why would you go read something in a browser if you have the code right there in a text editor?