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 AF69AC19F32 for ; Fri, 7 Mar 2025 15:03:24 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 09DAA6B0082; Fri, 7 Mar 2025 10:03:23 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 026BD6B0083; Fri, 7 Mar 2025 10:03:22 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id E08C46B0085; Fri, 7 Mar 2025 10:03:22 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0013.hostedemail.com [216.40.44.13]) by kanga.kvack.org (Postfix) with ESMTP id C0BDD6B0082 for ; Fri, 7 Mar 2025 10:03:22 -0500 (EST) Received: from smtpin05.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay06.hostedemail.com (Postfix) with ESMTP id 70797B78C0 for ; Fri, 7 Mar 2025 15:03:23 +0000 (UTC) X-FDA: 83195073486.05.5BA28EA Received: from smtp-fw-52004.amazon.com (smtp-fw-52004.amazon.com [52.119.213.154]) by imf26.hostedemail.com (Postfix) with ESMTP id 726AE14001E for ; Fri, 7 Mar 2025 15:03:21 +0000 (UTC) Authentication-Results: imf26.hostedemail.com; dkim=pass header.d=amazon.de header.s=amazon201209 header.b=PTaD5YiF; spf=pass (imf26.hostedemail.com: domain of "prvs=154feec4e=ptyadav@amazon.de" designates 52.119.213.154 as permitted sender) smtp.mailfrom="prvs=154feec4e=ptyadav@amazon.de"; dmarc=pass (policy=quarantine) header.from=amazon.de ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1741359801; 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=qqZcaiLaNCbDu9YJf0F0p4Av7x9/ggfLV9yLqVI9lR8=; b=mjxFri3uxWW5d5+kM/mZgA2jxSfWSrHPv//i0x6hZsyKIPDHs4vhT4w1ORK8Tfhuh9emKp fAxO24qNkn0HCHVT621+kICq+SHtGmuwwCWINwqRadnMh4iX4dn6lMa2ZRHI5N6mFFKVPL AUelSnuvp0s12wWgM1OxPO7I/Iv4uu8= ARC-Authentication-Results: i=1; imf26.hostedemail.com; dkim=pass header.d=amazon.de header.s=amazon201209 header.b=PTaD5YiF; spf=pass (imf26.hostedemail.com: domain of "prvs=154feec4e=ptyadav@amazon.de" designates 52.119.213.154 as permitted sender) smtp.mailfrom="prvs=154feec4e=ptyadav@amazon.de"; dmarc=pass (policy=quarantine) header.from=amazon.de ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1741359801; a=rsa-sha256; cv=none; b=doMLwZZTR5CVOIVDb/nfyZb/evlzQ7XJWBDO+tPKBGzxYOiqZFJ1OjirmNpaS7U6qGBGUc MklrahWCke++xHVpxEr6mJ0xy2s5Sw8GD8R//VS0sfzblq256ayf2e9ixrKaG04znkjT1m 5HtJhQWnDtKJfGXkQlAlACW+q4rGZhY= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amazon.de; i=@amazon.de; q=dns/txt; s=amazon201209; t=1741359802; x=1772895802; h=from:to:cc:subject:in-reply-to:references:date: message-id:mime-version; bh=qqZcaiLaNCbDu9YJf0F0p4Av7x9/ggfLV9yLqVI9lR8=; b=PTaD5YiFFggXebRV8TEr+rFnoPNSvNRK6ICyqvYBoxx8+QLUrWlLMz0i lTXkYuAM6Yf7Ocj+ToPUMEtOs6Lvsw3jYD+c0+l5KXM8SaEp3z4FfrmgM LN99vluEduiNZf+ZRQReLNhk34TYBvgSsJVHW5iSGhTBIsxy1Aa8wgop6 E=; X-IronPort-AV: E=Sophos;i="6.14,229,1736812800"; d="scan'208";a="277234234" Received: from iad12-co-svc-p1-lb1-vlan2.amazon.com (HELO smtpout.prod.us-west-2.prod.farcaster.email.amazon.dev) ([10.43.8.2]) by smtp-border-fw-52004.iad7.amazon.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 07 Mar 2025 15:03:16 +0000 Received: from EX19MTAUWC001.ant.amazon.com [10.0.38.20:12889] by smtpin.naws.us-west-2.prod.farcaster.email.amazon.dev [10.0.40.101:2525] with esmtp (Farcaster) id 581fd502-d217-44f4-a221-2819cfffdf66; Fri, 7 Mar 2025 15:03:15 +0000 (UTC) X-Farcaster-Flow-ID: 581fd502-d217-44f4-a221-2819cfffdf66 Received: from EX19D020UWC004.ant.amazon.com (10.13.138.149) by EX19MTAUWC001.ant.amazon.com (10.250.64.174) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA) id 15.2.1544.14; Fri, 7 Mar 2025 15:03:01 +0000 Received: from EX19MTAUWA002.ant.amazon.com (10.250.64.202) by EX19D020UWC004.ant.amazon.com (10.13.138.149) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA) id 15.2.1544.14; Fri, 7 Mar 2025 15:03:01 +0000 Received: from email-imr-corp-prod-pdx-all-2c-785684ef.us-west-2.amazon.com (10.25.36.210) by mail-relay.amazon.com (10.250.64.203) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA) id 15.2.1544.14 via Frontend Transport; Fri, 7 Mar 2025 15:03:01 +0000 Received: from dev-dsk-ptyadav-1c-43206220.eu-west-1.amazon.com (dev-dsk-ptyadav-1c-43206220.eu-west-1.amazon.com [172.19.91.144]) by email-imr-corp-prod-pdx-all-2c-785684ef.us-west-2.amazon.com (Postfix) with ESMTP id 3C58BA05AE; Fri, 7 Mar 2025 15:03:01 +0000 (UTC) Received: by dev-dsk-ptyadav-1c-43206220.eu-west-1.amazon.com (Postfix, from userid 23027615) id C61C752B5; Fri, 7 Mar 2025 15:03:00 +0000 (UTC) From: Pratyush Yadav To: Randy Dunlap CC: , Jonathan Corbet , "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 , , , , 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> Date: Fri, 7 Mar 2025 15:03:00 +0000 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Rspam-User: X-Rspamd-Server: rspam10 X-Rspamd-Queue-Id: 726AE14001E X-Stat-Signature: 9ggidpo5aco1nht613q38joi3p5eh6sy X-HE-Tag: 1741359801-586161 X-HE-Meta: U2FsdGVkX19t/BrCwsRu+Y3aC1WuscEwH6HVKYZ7GAtT+rdYMZJbYDqEGY8ulqD/Ge34oAGgeUK5MXs6C4CsA9DuJDFJbYlHd2ZebtS9cJPHZywiWgMb738yAuGicAIss3EbVeU6mjTcnLFcUqiOOMywUtHjNmaD+UuvcjWMmlg25VUdfVBFqrADEKC711i0kweYhFwJlR+Nf7uusHjmhjl8cxSbDywXKCb8X20Gz6gZaIeBdHcIEYOUNZPFmIY5ehIEw0EAvS1sImhmPEG08h0jk5dVTbzsybUzE5K2RQBG9IjJDo9TGEvrVS98c1K3JQWWIMRuZvn+DFXbhk0/8AprGvXmpxNIM0G90wext/dNW+oENbRkPVw3uc92fIFj+qE/9WK6rSuFAF7UEjnJkSE79lmgbN0jsKmg0fNfrv2n28mVF+hCsxDDgWfMZ3+16TwfujrFUtoiIte+o60MtAujyNAy8zgfz+XZ66/L7NAc8h0bUKzvX20dEDZQ45+H+LloHZOWng/0WOlHnYdWI//teIwqVCjGMA4EtSv4BPJ5GYVqZrhTX+GOoIpTMPnH+Vw6iYPyYUJ81hsPaZk5PoWxNakPV8NOP+qdOP759W/iJI83+apSiM/ia0HELIyuPTroSWgYL94T/4Q5Ym2n3G1bFRTAj4w9ajJfxd8ofhsP42qj6EHN5KAoQ2M86wQZg340aN546IYQZykxAXTnDfbjTiCgjjuw3MHVJlzPhX9j5l8aAmlKi8047sl871LziGck8y6IpfVR3oFBSMn44I/9Oxl6kqVtQJCgXC9HAaf5vh8SkdZgJUTQynjIOymA8mKR0Kv53cmHIAo8qy3YFVNDkIxSN5/hcpWGhNM6MzM56s6QyK+OpwKIAHTArbKcGQiij01CkfnuzsENm0MYUEPO7P40rElM5rh3EWiwjp/rxG7xcm40saHWVw/0ezQ7vEYtTHyiqJLuGhnZXAa SQrDSKdG E+mKK20ABkeb/94cLLWvfTERmO77+GUvd+iLFGORJh09FRERhcpjvu68ZiMLDydM6AqzIN5sObYQk4LGQIvUIN+VmWZkKt8Upi2yzN1t+wwWth64HHo4A+I0RUDFk6dV50+LGQF70oZA/vfMSMyeeZUDKg4cBj60wCxpBfvK1PydwZiH+d4xqyJC99Ohr/YyTU63jOawI0GQYQ7+jUEbYsnMfE5HxHUHj8lyhpM3Mk5xlG/0ufWtEX8TAOsLLFPkZZRY17uo8mM0prbo0t4RzAXvOb35rrQnVJad+liTMfPebzZvPfWsGH+8N87j84CXjGBcurZwhqXyeVdiKAn9sRJ40wgk5BlP49xXPRBiDISIhkZXeLyTJFISuHjv2VxYZCD4daTNtvnUdQnQOjKA5qqheQGo5SqHLe5SqJPcFCQtnDKA= 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: On Thu, Mar 06 2025, Randy Dunlap wrote: > On March 6, 2025 4:57:36 PM PST, Pratyush Yadav wrote: >>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 >>--- [...] >>+ >>+The File Descriptor Box (FDBox) is a mechanism for userspace to name file >>+descriptors and give them over to the kernel to hold. They can later be >>+retrieved by passing in the same name. >>+ >>+The primary purpose of FDBox is to be used with :ref:`kho`. There are many kinds > > many kinds of > >>+anonymous file descriptors in the kernel like memfd, guest_memfd, iommufd, etc. > > etc., Thanks, will fix these. [...] >>+ >>+Box >>+--- >>+ >>+The box is a container for FDs. Boxes are identified by their name, which must >>+be unique. Userspace can put FDs in the box using the ``FDBOX_PUT_FD`` >>+operation, and take them out of the box using the ``FDBOX_GET_FD`` operation. > > Is this ioctl range documented is ioctl-number.rst? > I didn't notice a patch for that. My bad, missed that. > >>+Once all the required FDs are put into the box, it can be sealed to make it >>+ready for shipping. This can be done by the ``FDBOX_SEAL`` operation. The seal >>+operation notifies each FD in the box. If any of the FDs have a dependency on >>+another, this gives them an opportunity to ensure all dependencies are met, or >>+fail the seal if not. Once a box is sealed, no FDs can be added or removed from >>+the box until it is unsealed. Only sealed boxes are transported to a new kernel > > What if KHO is not being used? Then the FDs are lost on shutdown. > >>+via KHO. The box can be unsealed by the ``FDBOX_UNSEAL`` operation. This is the >>+opposite of seal. It also notifies each FD in the box to ensure all dependencies >>+are met. This can be useful in case some FDs fail to be restored after KHO. >>+ >>+Box FD >>+------ > > I can't tell in my email font, but is each underlinoat least as long as the title above it? They are. I went and double-checked as well. Maybe just something with your email font. [...] -- Regards, Pratyush Yadav