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 kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8CA57C19F32 for ; Fri, 7 Mar 2025 15:25:17 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 53875280002; Fri, 7 Mar 2025 10:25:15 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 4E6B2280001; Fri, 7 Mar 2025 10:25:15 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 33B03280002; Fri, 7 Mar 2025 10:25:15 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id 11419280001 for ; Fri, 7 Mar 2025 10:25:15 -0500 (EST) Received: from smtpin10.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id D52581C93B5 for ; Fri, 7 Mar 2025 15:25:14 +0000 (UTC) X-FDA: 83195128548.10.2137F17 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf25.hostedemail.com (Postfix) with ESMTP id 35BEDA0015 for ; Fri, 7 Mar 2025 15:25:09 +0000 (UTC) Authentication-Results: imf25.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=U+c0IOxt; spf=pass (imf25.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1741361110; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=6uBJ1YUDIOKuMkF8J+Ow27cEIe6pHr5CJF/jr/dLLA4=; b=IitsQYfOLNXz34XMfqBzZBtxZhDAR1NWSyHlDj4mEZi/FYcG3JEmvdZNhd+aUH6lsrsEaR Cc5RuPxXKzvseyPKSd3VKwPgDPgVQSMoe+ZTWO1QiUVXUQg6vXXXEAVLSmkOz8yx4Z2Lmk BApVIVlt6yX0b/M22lza9IrYiRAkZSo= ARC-Authentication-Results: i=1; imf25.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=U+c0IOxt; spf=pass (imf25.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1741361110; a=rsa-sha256; cv=none; b=FggHSEnsu4kK/H6bPEDbmq0MW98Xw8gU3WxNVHzRUUZ4U2AkByuBmkmfBGlhLo0QaBrPaN +5pdrdzUEgUJexxZaq3J8s6qP8oSsMmLTyVucHwdJ4T/oG782ZY3Hl+BMOgcTyNh+cWAt4 XMt4r+iPvSMloL2otYjuFLz11p2HDpw= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E458441061 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1741361108; bh=6uBJ1YUDIOKuMkF8J+Ow27cEIe6pHr5CJF/jr/dLLA4=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=U+c0IOxtLK/yHL6U9gVkTGNWfKeHe7Cxjetxvjp7L3+fhF0t5VqDLayHbnkOecFGu qYn3EHi24lLNRlLwjvlcLjABGf3zNwLrc8NYTpQSqMb92Gzc3qmlijh49B1IC8QrGG UGpuzlIDPTGX+TwKiLQ0xQM6aM9HjXgxRQ5961CtqRyW7hfcBlIFZrACerkGfbpFkp qu8xTV/BIFh3GFTh4pYOiZCjBYXHWrLS+X/cWVmYzCIxv2PeaasmQLVOj730bUc7dd 7PzVO1c/UzvHCkp59SI9KNrfQho474Mgp4bMa0u0xA2UxewlYHUGniiP9REVJ7Voo4 LlVqxpyEj6WqQ== Received: from localhost (unknown [IPv6:2601:280:4600:2d7f::1fe]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id E458441061; Fri, 7 Mar 2025 15:25:07 +0000 (UTC) From: Jonathan Corbet To: Pratyush Yadav Cc: linux-kernel@vger.kernel.org, Eric Biederman , Arnd Bergmann , Greg Kroah-Hartman , Alexander Viro , Christian Brauner , Jan Kara , Hugh Dickins , Alexander Graf , Benjamin Herrenschmidt , David Woodhouse , James Gowans , Mike Rapoport , Paolo Bonzini , Pasha Tatashin , Anthony Yznaga , Dave Hansen , David Hildenbrand , Jason Gunthorpe , Matthew Wilcox , Wei Yang , Andrew Morton , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org, linux-mm@kvack.org, kexec@lists.infradead.org Subject: Re: [RFC PATCH 2/5] misc: add documentation for FDBox In-Reply-To: References: <20250307005830.65293-1-ptyadav@amazon.de> <20250307005830.65293-3-ptyadav@amazon.de> <87ikok7wf4.fsf@trenco.lwn.net> Date: Fri, 07 Mar 2025 08:25:07 -0700 Message-ID: <87ecz87tik.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Stat-Signature: axwut7maoc4545g4pwq6fg499r7bo5zt X-Rspamd-Server: rspam11 X-Rspamd-Queue-Id: 35BEDA0015 X-Rspam-User: X-HE-Tag: 1741361109-931563 X-HE-Meta: U2FsdGVkX19BlKPBUY8g4cd3WUEP2p+Yyp9NYvSNYeZckt9ISM3C28KeI54M4xRIG9xQ/Ej8PaYkENfYDdkHMwsRmuNvK9v6/GJsxQhcAr0Ta3++gP+PCALJymXYnuwW9dmsbP00zzbUem+3ChYrSKRUmhrESTlk0lAi+YQ5ILYmshGPOKDJaefGNkjRJWK1DIxqzyesvXPtsOWDW8D6Bqzuv9q+7EoVfTrCASTNklgm952B2S2ZHzOqv1T3FouIwVX5LDqB4tr18nva8ny4LBXT+9JF6076jfDeFFWGx5YY6hBxaVIWmYHBqs3p1xlxTQu6owNY8joyxy4QoJhRNOF2QPbSxaNajvny9BE0aTXLhI4tAaGTREIhsEneWWpWIazK0DyY0nrGz0yY82wcW7Jutk/EQWP/9YjJfAeoY7t4Dy2jvr9pMa4Sqz9aiba2u2HzHrAx2EE0yQDAvsPoha6IBpBZhKPy48YTkbh2y+b4KFIvoyScQ3ujS/hArIZzu2Do3wdSxAKlIDTA/9pXBBT88a+6rnMNtDwcyYT+IShfWAPSgthOqlXPW2WQOwX6r019bVfE+rqLceVzpboJRWd32WimyHSscvvYB3/JeOhh/gm6GXfmNGqO9nwLyjmKimsZUG6ObcMs0XGNrQ1bJwZII0kLMi5MkCpZ9/NTErwBuDtxau8WpUR41Bvycd+cJw/4cgrG05dqblXOhMkl6IdRjKJdS/adRua+iLdkXaiffgkxsoVB9NHysEt7gdtzpnW4NOrziZMhDgE1OMttys20cms16X6MRr6sC6RfgiRMW50YGQKBTKFREYGuiSH3aHGqzfL6cO/vI5wE1dtLcQgYYG3t8aQE8BWdP9hEjYvJ05oGpUQ1pO15GZpSAa1kSGjf/01SIZ0vtKHhAFJA6hbT8KG+IkMs5rSc1z0opp8/s3edb4EzRP+8M/XGDzDTrNmC92Qvwp0+3KGpXsA KMzgUe3T j8R8rT81OBZFuGbidYeMVHGNXjCDa9ZwI+YgMjHtV/Zbr55J2QZ/53hpJhlX/VceBHHmBfaEqd4l9x5Z/qFf5fxn1Eu4LHNJcXoVlIHsuWU/RIHdiWV6W+jkk8ydx4aSW/BQIZZa8gXCYdHESobFnxx4AXjOfv/OyHaaw+yXvH59OXy039CeamJbosFw6cpUNX7xSHj0fSfVcNLp4WmR3nPIo8joUO5bYagooxOWN16w/6nDqaXYc4MSWqxl5UIk7oGw0zsGTurotyeOtsAWrly/PebOqgru/5qYeEudo7bxxtMZQdkwQ6pmTkkB6qjWvwEoGGb6Z/4Ohpzd1QRaEuXgKPb1K4cMBYeKzZXuCfk3vGYk= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: Pratyush Yadav writes: > On Fri, Mar 07 2025, Jonathan Corbet wrote: > >> Pratyush Yadav writes: >> >>> With FDBox in place, add documentation that describes what it is and how >>> it is used, along with its UAPI and in-kernel API. >>> >>> Since the document refers to KHO, add a reference tag in kho/index.rst. >>> >>> Signed-off-by: Pratyush Yadav >>> --- >>> Documentation/filesystems/locking.rst | 21 +++ >>> Documentation/kho/fdbox.rst | 224 ++++++++++++++++++++++++++ >>> Documentation/kho/index.rst | 3 + >>> MAINTAINERS | 1 + >>> 4 files changed, 249 insertions(+) >>> create mode 100644 Documentation/kho/fdbox.rst >> >> Please do not create a new top-level directory under Documentation for >> this; your new file belongs in userspace-api/. > > I did not. The top-level directory comes from the KHO patches [0] (not > merged yet). This series is based on top of those. You can find the full > tree here [1]. > > Since this is closely tied to KHO I found it a good fit for putting it > on KHO's directory. I don't have strong opinions about this so don't > mind moving it elsewhere if you think that is better. I've not seen the KHO stuff, but I suspect I'll grumble about that too. Our documentation should be organized for its audience, not for its authors. So yes, I think that your documentation of the user-space interface should definitely go in the userspace-api book. Thanks, jon (Who now realizes he has been arguing this point of view for over ten years ... eventually it will get across... :)