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 8308AC3DA4A for ; Wed, 14 Aug 2024 21:58:24 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id DA3F16B00A0; Wed, 14 Aug 2024 17:58:23 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id D51286B00A2; Wed, 14 Aug 2024 17:58:23 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id C189E6B00A4; Wed, 14 Aug 2024 17:58:23 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id A2E446B00A0 for ; Wed, 14 Aug 2024 17:58:23 -0400 (EDT) Received: from smtpin14.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id 594DDA0C51 for ; Wed, 14 Aug 2024 21:58:23 +0000 (UTC) X-FDA: 82452215286.14.6000B97 Received: from sin.source.kernel.org (sin.source.kernel.org [145.40.73.55]) by imf26.hostedemail.com (Postfix) with ESMTP id E8FF514000A for ; Wed, 14 Aug 2024 21:58:20 +0000 (UTC) Authentication-Results: imf26.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=k7w3kvYt; spf=pass (imf26.hostedemail.com: domain of dakr@kernel.org designates 145.40.73.55 as permitted sender) smtp.mailfrom=dakr@kernel.org; dmarc=pass (policy=none) header.from=kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1723672605; 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=patGwuZv3EZQshPfLZK7DBNmPsaUH8C3UGRaFRYHl/k=; b=5lVgAas7XlG0rcPl4NhpGx3FZxZBg1u+ecQe1Eahf+wnb8jLC+9SoWfwNJDK/67jy/dlx/ Wk4VhS6aM4BJ7GsfuGog4+dAczkfkOJQTOsZcuXazdrb8mxY1bfxyGKyZ1kM7vFy1ogf9d ivOKdCw0OgQ7xfo26GnycOaRMQwHJLs= ARC-Authentication-Results: i=1; imf26.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=k7w3kvYt; spf=pass (imf26.hostedemail.com: domain of dakr@kernel.org designates 145.40.73.55 as permitted sender) smtp.mailfrom=dakr@kernel.org; dmarc=pass (policy=none) header.from=kernel.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1723672605; a=rsa-sha256; cv=none; b=H6hJ4JNYMdfhVgz+di7WqhWo4cfN8i34qnoWZvruL0FwlpuvlC9ypEOy95autRcBTruSbE nnxDy5bnOaIWE+5+w+MlO6Bhnn3YuXviWF24fsMugYOuqi3mrWQYfmTmbXcU2z7pmRMbIU AVAoS42MDMMLLNOCO7TWW0nHtXLKkTI= Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sin.source.kernel.org (Postfix) with ESMTP id 59F54CE1B09; Wed, 14 Aug 2024 21:58:17 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id CE173C116B1; Wed, 14 Aug 2024 21:58:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1723672696; bh=WF7mh1nnaAx+2BtQVDbvZ9mTMjWH5kKojT+9NKpDGDM=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=k7w3kvYtTLgFnwfGAbkC9JLrNGliHDW5YldIQLHAnWlAQGLs5TsJfY66aO72aESXS NKAzOS5reSFyMrmYzZ6KT8V7gvFvZ8RKwAiLJsMU3kolElPZKA1GKL7EtSHkv4IDfZ OrcYAKWjTCHnih6lBPj/FTY+Ps8T/7fVqhjQB4/wMuu4lJEx4eGp2LQ0aQb+Ya88lX eRD4kWGW5rTkeu7hPh90Tlpo7OFTwu0dbV4ED5qAEDdyopTMmdoH/WIrQ0YNW1FTLP xj9y8L/Brrs+/tYVEm9lgyMshxJo91uuSjbWuSsRZehjzQQBzGRva4ZNBNFvz+ypmx 6Me9Hd3WpGkEw== Date: Wed, 14 Aug 2024 23:58:08 +0200 From: Danilo Krummrich To: Benno Lossin Cc: ojeda@kernel.org, alex.gaynor@gmail.com, wedsonaf@gmail.com, boqun.feng@gmail.com, gary@garyguo.net, bjorn3_gh@protonmail.com, a.hindborg@samsung.com, aliceryhl@google.com, akpm@linux-foundation.org, daniel.almeida@collabora.com, faith.ekstrand@collabora.com, boris.brezillon@collabora.com, lina@asahilina.net, mcanal@igalia.com, zhiw@nvidia.com, cjia@nvidia.com, jhubbard@nvidia.com, airlied@redhat.com, ajanulgu@redhat.com, lyude@redhat.com, linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, linux-mm@kvack.org Subject: Re: [PATCH v5 09/26] rust: alloc: implement kernel `Box` Message-ID: References: <20240812182355.11641-1-dakr@kernel.org> <20240812182355.11641-10-dakr@kernel.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Rspamd-Server: rspam06 X-Rspamd-Queue-Id: E8FF514000A X-Stat-Signature: i39psd9w6dnqf9h486qcunumkaefasz7 X-Rspam-User: X-HE-Tag: 1723672700-344263 X-HE-Meta: U2FsdGVkX1/SihxxwFMYvs2jL6KZo85ZWiI65VjrmSt9DscVMHXWCAImFljX0743G1PudfOABToVk58bsa0awZCDX/mvSnz9u2NhTjy6pPxltx4H2z9iuQIq27Q/TIop65KL6OEW6SAKBT2bCIvS7Fch2xWaI+UKhZ6542yA1O7xeItMmHdYHBQ+YPlV9Tw4rAnNej42wpKZx0NGLSzKXDea2Gv8SzRJ75gIzUWxKfwYlP58FQuuumemyvno3Aziw6u725ivfOPzHA+Fh9ruH3qiySzSnSKTyhHhRfCqIyqRidRPCOhmEMYkaoGK1oiE5AWnYV7qrFfaECk5PqwYn2rHKK/RU1Y3MfHXrkMJeNS5WAZg38XMHnf+65F7ZbA8/BYJMiRlS8R85deJeWEz+oPfZUY4mZaLQi3cAybOQpmD+jVKzNlZEbrjH4e36Y7iTsCI5erMUPtXHa6zLZyEqpkMdupxAnjy8hRM7UhWX2JOOZaFRyvBr+YV3TO5WO6V40RE/DV+KWjDKppfqEmWr44Nho4gK6ist8JW4z04xG2PGRjXMlvjAXO6WRV7LpxrH1sAioaGrOz/ZnHIc4D5CoP2as9XI3rjJwUiti6wfRyNssiiTkx9LfsdRHvn06rWLyg0/ZRDOb7GuQ2AHm56Tn64y2ZRf6vn/mZeIEas5XAUed31QhcpMyjdp8MQOMjhrOBOfXxQa2NPpwRb4UeA7sYiaFetO7ay7q611hjUHgow9UIRXxrCLKcEzQ1vIDqOYLyLvpaUIcsXywOrObe7dddcmX2MEZI+niS2fM0Lj89TtM5ke28fuOMdF7V4yL3FN+aUYtVUAdJmi83CIr781heWdoxzGRv0TX1LvqQcyVvYVzMUi4uj46Z00oIG1Ejm2r4pIh7tH6VREWu6toGCE3xRe98BC6Sm0S8m8l8GZp0OfjP2IWS0rS9ZpKPd4ZsaoXdGsHuN0BhoMtNGRNw QsUntM83 8LodRpMTqXuSYoJg7VbkyN5dFISHtV8srkh0t20hltj4POgRm5qefTDc3n1adsp6ZQReyhBGuNbMTsgCgguvBgo9BTutLASj80tfhHHVoQJTTFf0CnLvw796vj+w+ozXR0UJMpXsmu1WZdnf14qzH9lvk5eAbvJudw6sshdmp94zHMrM/vHK1DVwpftsHJfl+pAVkkQkeXRu3OM6mb88m5wHBIsBcvpFex28lDcQODtjRWH+FcynUPcWGKYdLo+OySfHbWY4o61Wl9zhhmepnRWM0fiDNItEjqDzr22O+JAtwwSaZ6zrgq8yvoLk31eSV5Kj7xsuEXupJ2M/NFMQp1eNkiiJ1dTBj3Md9/hjWowkJjnsYFStubOqOD2jy2PEsKAtyEzqBeAB1BTEhMwbS0U5A5F/U2klp6VmEYTG5f0klronvmo6SlBd3+w== X-Bogosity: Ham, tests=bogofilter, spamicity=0.000002, 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 Wed, Aug 14, 2024 at 05:01:34PM +0000, Benno Lossin wrote: > On 12.08.24 20:22, Danilo Krummrich wrote: > > +/// The kernel's [`Box`] type - a heap allocation for a single value of type `T`. > > +/// > > +/// This is the kernel's version of the Rust stdlib's `Box`. There are a couple of differences, > > +/// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not > > +/// supported. > > I would add "But otherwise it works the same." (I don't know if there is > a comma needed after the "otherwise"). There are more differences we don't list here, and probably don't need to. Hence, saying that it otherwise works the same isn't correct. > Also I remember that there was one more difference with a custom box > compared to the stdlib, but I forgot what that was, does someone else > remember? We should also put that here. Obviously, there are also quite some API differences. For instance, `Box` generally requires two generics, value type and allocator, we take page flags and return a `Result`, where std just panics on failure. > > > +/// > > +/// `Box` works with any of the kernel's allocators, e.g. [`super::allocator::Kmalloc`], > > +/// [`super::allocator::Vmalloc`] or [`super::allocator::KVmalloc`]. There are aliases for `Box` > > +/// with these allocators ([`KBox`], [`VBox`], [`KVBox`]). > > +/// > > +/// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed. > > +/// > > +/// # Examples > > +/// > > +/// ``` > > +/// let b = KBox::::new(24_u64, GFP_KERNEL)?; > > +/// > > +/// assert_eq!(*b, 24_u64); > > +/// > > +/// # Ok::<(), Error>(()) > > +/// ``` > > +/// > > +/// ``` > > +/// # use kernel::bindings; > > +/// > > +/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1; > > +/// struct Huge([u8; SIZE]); > > +/// > > +/// assert!(KBox::::new_uninit(GFP_KERNEL | __GFP_NOWARN).is_err()); > > +/// ``` > > +/// > > +/// ``` > > +/// # use kernel::bindings; > > +/// > > +/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1; > > +/// struct Huge([u8; SIZE]); > > +/// > > +/// assert!(KVBox::::new_uninit(GFP_KERNEL).is_ok()); > > +/// ``` > > +/// > > +/// # Invariants > > +/// > > +/// The [`Box`]' pointer always properly aligned and either points to memory allocated with `A` or, > > "pointer always properly" -> "pointer is properly" > > > +/// for zero-sized types, is a dangling pointer. > > I think this section would look nicer, if it were formatted using bullet > points (that way the bracketing of the "or" is also unambiguous). > > Additionally, this is missing that the pointer is valid for reads and > writes. > > > +pub struct Box(NonNull, PhantomData); > > Why no `repr(transparent)`? I wasn't entirely sure whether that's OK with the additional `PhantomData`, but I think it is, gonna add it. > > > + > > +/// Type alias for `Box` with a `Kmalloc` allocator. > > I think we should add that this is only designed for small values. I don't want duplicate the existing documentation around kmalloc and friends [1]. Maybe we can refer to the existing documentation somehow. [1] https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html > > > +/// > > +/// # Examples > > +/// > > +/// ``` > > +/// let b = KBox::new(24_u64, GFP_KERNEL)?; > > +/// > > +/// assert_eq!(*b, 24_u64); > > +/// > > +/// # Ok::<(), Error>(()) > > +/// ``` > > +pub type KBox = Box; > > + > > +/// Type alias for `Box` with a `Vmalloc` allocator. > > Same here, add that this is supposed to be used for big values (or is > this also a general-purpose allocator, just not guaranteeing that the > memory is physically contiguous? in that case I would document it > here and also on `Vmalloc`). Same as above, I'd rather not duplicate that. But I'm happy to link things in, just not sure what's the best way doing it.