From patchwork Tue Mar 21 19:49:50 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: y86-dev X-Patchwork-Id: 73032 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:604a:0:0:0:0:0 with SMTP id j10csp1978470wrt; Tue, 21 Mar 2023 12:54:30 -0700 (PDT) X-Google-Smtp-Source: AK7set/fJjy7qTyayhsv6cmV7ZbH93P8NOxHxfqJRM1uynzXTyRgolcq3R5RjGXxxHuh6sExo1cd X-Received: by 2002:a62:1881:0:b0:623:dfdd:f7eb with SMTP id 123-20020a621881000000b00623dfddf7ebmr803492pfy.12.1679428470386; Tue, 21 Mar 2023 12:54:30 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1679428470; cv=none; d=google.com; s=arc-20160816; b=rYrpKI85imNKZSRAtaDmriL3SOBnCawG5mibn1t1olAL8j1zMFo5ZQethCGV3lrFzK Y1rknJR3z6Jj9RvSamEX4++bAQiquJgiaOejfbSyfelMHbYnxb2oUqU02bvIjf6A5531 slcSs0GDLk9Sc+oVL8AGDkE1CBB6NVbg1fqOA4Ash3bgln2ZuhmnX+4N5Cvd1O05la3w szu6YAwrjvqzQlrM7/eAuLwK1Ag7VzxwpVd6RxpKzFlDsa5Z9T5YMu7cNmZFuXmpgZWU eEvGqAvPe3tp2tgj/WidSaWEQOBs6a0M9lXcb3HZjS8GCDo6EMW0qcv5TTgV41UvAMWg tgww== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :feedback-id:references:in-reply-to:message-id:subject:cc:from:to :dkim-signature:date; bh=G5OcfJ1sRCppIjvccB3dNK4jRstnIpG0oGXnr2BMLSs=; b=qy1uCSiXGR+k18y8herxoVe87m3DJM7U0qJr3ZqotFN8CqHgx2/FawhOO7B7nUGqrw UPFumQU7PZSy2OR/2Y6JoQNrvqq0sKvQvUkHGhZqWtsLRabh5tefJF4fH6LJQHB0Bn7S vaatfymUYyJxm4bZyvb0adr09H6erE3uda6tpeJkrrBYMrQSX4hWVlh0Rjgc+hudgBjr pwqXzxqYKD2OUv2k1MUTlB0QgY1BFICYGKZfjJLRUdosFp7Hsntbib52wPJ3f1WGKwBU IFiU2eOwHEyEdDgv1a41Xld6/hMRzc6QoAeqtf46GEttmyQ2KmC0+TxTULZfBJGlgeG6 32kA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=bHvk1Ac6; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id z186-20020a6265c3000000b005a8bd21e2f7si12840650pfb.186.2023.03.21.12.54.15; Tue, 21 Mar 2023 12:54:30 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=bHvk1Ac6; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229836AbjCUTuG (ORCPT + 99 others); Tue, 21 Mar 2023 15:50:06 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48000 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229513AbjCUTuE (ORCPT ); Tue, 21 Mar 2023 15:50:04 -0400 Received: from mail-40134.protonmail.ch (mail-40134.protonmail.ch [185.70.40.134]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 550D5976F; Tue, 21 Mar 2023 12:49:58 -0700 (PDT) Date: Tue, 21 Mar 2023 19:49:50 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail3; t=1679428196; x=1679687396; bh=G5OcfJ1sRCppIjvccB3dNK4jRstnIpG0oGXnr2BMLSs=; h=Date:To:From:Cc:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=bHvk1Ac6pHL1Afyx6ou/eLGrvVaRYvERQsJeRAoexo24UmVJqgmqvvdOXPZPrFOrd GCM0mZBrWS+WbSjx1EK1rf5EAyhWxLCGo02NsFUgf48HdZiEiW3Od+d/oFo7P1zE68 WJoztjM+mAl51Ou63bBjHuh1I+ButYNT2pYoG4KcwNukLo4C77VifWr+yL3GRezN7J 8QkOauGfoSnv/Zr+cl/ybjMTuCgb4ZJJ4O+aT7tbgHzIvCW8ccBeQxcDSnyZCnrYrs iQp6vcWcaY3sAoWsGC1GeM/nhVseJKJ1YVO8yZBY30bq9U/bnSUtc2t3ohM22CMlkE T2VnyFRGIC77Q== To: Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= From: Benno Lossin Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, patches@lists.linux.dev Subject: [PATCH v2 1/5] rust: macros: add `quote!` macro Message-ID: <20230321194934.908891-2-y86-dev@protonmail.com> In-Reply-To: <20230321194934.908891-1-y86-dev@protonmail.com> References: <20230321194934.908891-1-y86-dev@protonmail.com> Feedback-ID: 40624463:user:proton MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_MSPIKE_H2, SPF_HELO_PASS,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1761008387662211563?= X-GMAIL-MSGID: =?utf-8?q?1761008387662211563?= From: Gary Guo Add the `quote!` macro for creating `TokenStream`s directly via the given Rust tokens. It also supports repetitions using iterators. It will be used by the pin-init API proc-macros to generate code. Signed-off-by: Gary Guo Signed-off-by: Benno Lossin --- rust/macros/lib.rs | 2 + rust/macros/quote.rs | 143 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 rust/macros/quote.rs -- 2.39.2 diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index c1d385e345b9..82b520f024dd 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -2,6 +2,8 @@ //! Crate for all kernel procedural macros. +#[macro_use] +mod quote; mod concat_idents; mod helpers; mod module; diff --git a/rust/macros/quote.rs b/rust/macros/quote.rs new file mode 100644 index 000000000000..00fc75fecd03 --- /dev/null +++ b/rust/macros/quote.rs @@ -0,0 +1,143 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{TokenStream, TokenTree}; + +pub(crate) trait ToTokens { + fn to_tokens(&self, tokens: &mut TokenStream); +} + +impl ToTokens for Option { + fn to_tokens(&self, tokens: &mut TokenStream) { + if let Some(v) = self { + v.to_tokens(tokens); + } + } +} + +impl ToTokens for proc_macro::Group { + fn to_tokens(&self, tokens: &mut TokenStream) { + tokens.extend([TokenTree::from(self.clone())]); + } +} + +impl ToTokens for TokenTree { + fn to_tokens(&self, tokens: &mut TokenStream) { + tokens.extend([self.clone()]); + } +} + +impl ToTokens for TokenStream { + fn to_tokens(&self, tokens: &mut TokenStream) { + tokens.extend(self.clone()); + } +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// the given span. +/// +/// This is a similar to the +/// [`quote_spanned!`](https://docs.rs/quote/latest/quote/macro.quote_spanned.html) macro from the +/// `quote` crate but provides only just enough functionality needed by the current `macros` crate. +macro_rules! quote_spanned { + ($span:expr => $($tt:tt)*) => { + #[allow(clippy::vec_init_then_push)] + { + let mut tokens = Vec::new(); + let span = $span; + quote_spanned!(@proc tokens span $($tt)*); + proc_macro::TokenStream::from_iter(tokens) + }}; + (@proc $v:ident $span:ident) => {}; + (@proc $v:ident $span:ident #$id:ident $($tt:tt)*) => { + let mut ts = proc_macro::TokenStream::new(); + crate::quote::ToTokens::to_tokens(&$id, &mut ts); + $v.extend(ts.into_iter()); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident #(#$id:ident)* $($tt:tt)*) => { + for token in $id { + let mut ts = proc_macro::TokenStream::new(); + crate::quote::ToTokens::to_tokens(&token, &mut ts); + $v.extend(ts.into_iter()); + } + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ( $($inner:tt)* ) $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Parenthesis, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident [ $($inner:tt)* ] $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Bracket, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident { $($inner:tt)* } $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Brace, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident :: $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Joint)) + ); + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident : $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident , $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(',', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident @ $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new('@', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ! $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new('!', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident $id:ident $($tt:tt)*) => { + $v.push(proc_macro::TokenTree::Ident(proc_macro::Ident::new(stringify!($id), $span))); + quote_spanned!(@proc $v $span $($tt)*); + }; +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// mixed site span ([`Span::mixed_site()`]). +/// +/// This is a similar to the [`quote!`](https://docs.rs/quote/latest/quote/macro.quote.html) macro +/// from the `quote` crate but provides only just enough functionality needed by the current +/// `macros` crate. +/// +/// [`Span::mixed_site()`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.mixed_site +macro_rules! quote { + ($($tt:tt)*) => { + quote_spanned!(proc_macro::Span::mixed_site() => $($tt)*) + } +} From patchwork Tue Mar 21 19:49:55 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: y86-dev X-Patchwork-Id: 73034 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:604a:0:0:0:0:0 with SMTP id j10csp1980093wrt; Tue, 21 Mar 2023 12:58:29 -0700 (PDT) X-Google-Smtp-Source: AK7set8hF3Hx4I6M2i0p/T6yv3QRiApDJfUEYDkJe9ry16O4CuEtqR+EINkCvnuzLfS8FJOF0zj7 X-Received: by 2002:a05:6a20:389e:b0:d9:d8e4:4cad with SMTP id n30-20020a056a20389e00b000d9d8e44cadmr3250530pzf.16.1679428708928; Tue, 21 Mar 2023 12:58:28 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1679428708; cv=none; d=google.com; s=arc-20160816; b=Lkbx3OtQsWFJ6pvZMAm7H2vIXrbh8kI9+wUsrbfLJN46uFD5Aca+Z3BoRKKuDHgF9w 36YEN6OmrYyyDBIXFOX+3qUW4hc9I9xwgNur2JXOmE27FYUv1vCyeBR+Q2sj+pxHnGDc lQDB+dra/NhgIEo010EnCAiVFMBJlvtQ8s9vXhsdcDf649FB1rik43ltFsUa4H4QILxX bcEVKNQeGLrh9fUJd5OY7fRLT/dK1JaQWMbihspcPzTPpGBOLBoCmZBFIGXvaFAGvYGy Rby+zj6722JYHQRClQA+YAyN+aCCRj+a8s0VeHVgoHh5wlT/bGZN2bsvv03GSBkT4Mpc P8LQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :feedback-id:references:in-reply-to:message-id:subject:cc:from:to :dkim-signature:date; bh=5wFTfQvkkunlIrsARX4Vq7hYHVmiJWCfu28xcLcdviI=; b=UuWKHizwxoraNSB73fLJRhWY0y7FtCWRHR5q+a+EkX0XQzp2S1Nsux6dBtkNZqk+yk G259H5K5jyAVrwFfKLmiaO+YRJed41JLg1IjOWndfWN2JYaRKh1bmkLb+HYJHhk3ZpTy CTzc9JYj/wXRr+AFM6cB36VNrp6dG8kFlA78/ngHVNxjF2cNp0QE3uezm+/pR6Eey2UD horE/YhPygGS5utqMXPRPlPuSuwPFX6qTIMt7U+Q+FK6adQIGfT/hdNQwZe9MYk1hYpu bsAGqMwvN4WQ4BSDJQWTfErraIrERXa2BZw72EeMVMoIu6WuTxPC1NOOKHwxLu5yjWSa ShhQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=yo3gFfxM; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id j18-20020a056a00131200b0062806504839si4615099pfu.168.2023.03.21.12.58.14; Tue, 21 Mar 2023 12:58:28 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=yo3gFfxM; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229904AbjCUTuQ (ORCPT + 99 others); Tue, 21 Mar 2023 15:50:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48054 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229841AbjCUTuG (ORCPT ); Tue, 21 Mar 2023 15:50:06 -0400 Received: from mail-4316.protonmail.ch (mail-4316.protonmail.ch [185.70.43.16]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 594A69EF2 for ; Tue, 21 Mar 2023 12:50:02 -0700 (PDT) Date: Tue, 21 Mar 2023 19:49:55 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail3; t=1679428200; x=1679687400; bh=5wFTfQvkkunlIrsARX4Vq7hYHVmiJWCfu28xcLcdviI=; h=Date:To:From:Cc:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=yo3gFfxMfaxuil6kpYNQ51W526MtY1XzriLAqtUMsU0wfTlOKpcjd6bWdEB4zJvCK EO9rf+vJFjiQCEsarmSXWn1yMJLfbMI+/d+ufWy9ZgpjQRMnVu0eymjMAT6UJ9kPmF LiNAF8i9KPRDecEJlTM5LEaW0nlUmq78H/IFkQXYSRGamiWBT448a9HLgwC2QZZoLu sIE/ivUqLaPUY5pKp8CL1RGEPoH72x0VjHLExdvu/7Ga+LX1U8sbDGK5L4MdDzZ2ed xZzPxbWPYTiTZP9KSs6dNPwJqlalOo1Zoysefsd0mVxf45dCAA4LI6KH0ahkrPnTJX MVu5aeUxjc+aA== To: Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= From: Benno Lossin Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, patches@lists.linux.dev Subject: [PATCH v2 2/5] rust: sync: add `assume_init` to `UniqueArc` Message-ID: <20230321194934.908891-3-y86-dev@protonmail.com> In-Reply-To: <20230321194934.908891-1-y86-dev@protonmail.com> References: <20230321194934.908891-1-y86-dev@protonmail.com> Feedback-ID: 40624463:user:proton MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_MSPIKE_H2, SPF_HELO_PASS,SPF_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1761008638094783153?= X-GMAIL-MSGID: =?utf-8?q?1761008638094783153?= Adds the `assume_init` function to `UniqueArc>` that unsafely assumes the value to be initialized and yields a value of type `UniqueArc`. This function is used when manually initializing the pointee of an `UniqueArc`. Signed-off-by: Benno Lossin --- rust/kernel/sync/arc.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) -- 2.39.2 diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index f2f1c83d72ba..16ec174637b2 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -489,6 +489,17 @@ impl UniqueArc> { /// Converts a `UniqueArc>` into a `UniqueArc` by writing a value into it. pub fn write(mut self, value: T) -> UniqueArc { self.deref_mut().write(value); + // SAFETY: We just wrote the value to be initialized. + unsafe { self.assume_init() } + } + + /// Unsafely assume that `self` is initialized. + /// + /// # Safety + /// + /// The caller guarantees that the value behind this pointer has been initialized. It is + /// *immediate* UB to call this when the value is not initialized. + pub unsafe fn assume_init(self) -> UniqueArc { let inner = ManuallyDrop::new(self).inner.ptr; UniqueArc { // SAFETY: The new `Arc` is taking over `ptr` from `self.inner` (which won't be From patchwork Tue Mar 21 19:50:00 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: y86-dev X-Patchwork-Id: 73035 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:604a:0:0:0:0:0 with SMTP id j10csp1980829wrt; Tue, 21 Mar 2023 13:00:20 -0700 (PDT) X-Google-Smtp-Source: AK7set9YO5JT1I3eVkcQLcZLWDAq40we2LLxJr9gKD5hlcNa2wdvZZVZpkhKblWsOJn69MicBPWx X-Received: by 2002:a17:902:fb47:b0:19e:6700:174 with SMTP id lf7-20020a170902fb4700b0019e67000174mr253415plb.25.1679428820320; Tue, 21 Mar 2023 13:00:20 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1679428820; cv=none; d=google.com; s=arc-20160816; b=cY9EJSWIYavJfdFAqWJ/KI7cpB0tY1DzDjtERm/49d0GkrD/IlnEj6IkwrhdclVlUB 1E+XnaMr72qFkRrpfm686j+kfN7IGCPQKF5NRVy34/Sq0AevG7ZQn4lFtEnQCGRVBpm3 x6d+FthGMi5oGqKIFIPHooUosQi0oVHBIyG8JXIdBSFU3rnlBMHBDWvuMl6sr84meD2D 0yum8S9sZlNwfg2B80fjS6B5/sA4+9r+OlYSTlXiApz6NsOU2bBDpjxeDAmxmE0lkc7y jBDtRa1BhsBy7WS2xfqSGgCCPvjj0KWLLOGyF4ZX9hoTOzrIoIRwPjfb1Buu7Bb3amyp k2SA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :feedback-id:references:in-reply-to:message-id:subject:cc:from:to :dkim-signature:date; bh=SSvQe9S1lWzR2BDPdkFkw4Ie3E5mE+jtFZ616l94XVg=; b=xvPY6uIcDPJ/6pdJ0z0bWa9O8Hw9abzJ/ZmED/7hCtU8ZCNlk82Dq5FO46dByV0cU2 mEeVIHHuTy8KiJdpkNj9bjyMw/385MZG0cbUNDlntphPfEtfTaTX2dhTpKjjJaa4qlVp SaFJucZMQ6T7q61K6zZfQpzkRe3H4EZJxLMGCya9Nkv5K7fLadkoCbkgjWYsvhf40qzO SPxpDnpASMEa0buqTDuIKBbXMXCOHHpOtpeGPMpMGTl/Z4YcIjzg3BZ2GfsOQMkPMhFI BiuDoNedJEQlHb18z+2M1eSP6TAtiCRNMKNFMaGkPjb0b0NW+IkiOzCUS0EF4GatY9gL 1uaQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=aHuL763q; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id s20-20020a63f054000000b004ff70043ff9si13866157pgj.770.2023.03.21.13.00.04; Tue, 21 Mar 2023 13:00:20 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=aHuL763q; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229788AbjCUTu6 (ORCPT + 99 others); Tue, 21 Mar 2023 15:50:58 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49546 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229736AbjCUTuz (ORCPT ); Tue, 21 Mar 2023 15:50:55 -0400 Received: from mail-4322.protonmail.ch (mail-4322.protonmail.ch [185.70.43.22]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 41B6A58B7F; Tue, 21 Mar 2023 12:50:22 -0700 (PDT) Date: Tue, 21 Mar 2023 19:50:00 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail3; t=1679428218; x=1679687418; bh=SSvQe9S1lWzR2BDPdkFkw4Ie3E5mE+jtFZ616l94XVg=; h=Date:To:From:Cc:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=aHuL763qiCM64KjGDG2fxvrqbhoZNuROdVqJfHnMB+wI+3yuHRk8QnOW8EEt5ftbm VpfBg/HHcl+U7uL25bAoG46Hh7r2n8+I7GfzHSv+0OBZMY/TdY/h28PRcTfhlY4vHH Skbhn1PVTXiUOAjFT3yTms3L17K2RMkSVU01SCxfhfTKN5HazQDhqFFg1hVUOXjAaF 8iKsNoTXayeL4hC6I5KUR9+xhb8TtROgHZ9Q7CMGzM2K3LuVCHk+U/QeBOcGIxebQK 77lh695DM+3piO+nsLw5a7r8obzzfIXLkHIHZS86xxWhAOVWU1yuKZCf/6qWeyD70/ tA84f4lTBCnwg== To: Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= From: Benno Lossin Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, patches@lists.linux.dev Subject: [PATCH v2 3/5] rust: add pin-init API Message-ID: <20230321194934.908891-4-y86-dev@protonmail.com> In-Reply-To: <20230321194934.908891-1-y86-dev@protonmail.com> References: <20230321194934.908891-1-y86-dev@protonmail.com> Feedback-ID: 40624463:user:proton MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_MSPIKE_H2, SPF_HELO_PASS,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1761008754794660493?= X-GMAIL-MSGID: =?utf-8?q?1761008754794660493?= This API is used to facilitate safe pinned initialization of structs. It replaces cumbersome `unsafe` manual initialization with elegant safe macro invocations. --- In this section the problem that the new pin-init API solves is outlined. For a more granular explanation and additional information on pinning and this issue, view [1]. Pinning is Rust's way of enforcing the address stability of a value. When a value gets pinned it will be impossible for safe code to move it to another location. This is done by wrapping pointers to said object with `Pin

`. This wrapper prevents safe code from creating mutable references to the object, preventing mutable access, which is needed to move the value. `Pin

` provides `unsafe` functions to circumvent this and allow modifications regardless. It is then the programmer's responsibility to uphold the pinning guarantee. Many kernel data structures require a stable address, because there are foreign pointers to them which would get invalidated by moving the structure. Since these data structures are usually embedded in structs to use them, this pinning property propagates to the container struct. Resulting in most structs in both Rust and C code needing to be pinned. So if we want to have a `mutex` field in a Rust struct, this struct also needs to be pinned, because a `mutex` contains a `list_head`. Additionally initializing a `list_head` requires already having the final memory location available, because it is initialized by pointing it to itself. But this presents another challenge in Rust: values have to be initialized at all times. There is the `MaybeUninit` wrapper type, which allows handling uninitialized memory, but this requires using the `unsafe` raw pointers and a casting the type to the initialized variant. This problem gets exacerbated when considering encapsulation and the normal safety requirements of Rust code. The fields of the Rust `Mutex` should not be accessible to normal driver code. After all if anyone can modify the fields, there is no way to ensure the invariants of the `Mutex` are upheld. But if the fields are inaccessible, then initialization of a `Mutex` needs to be somehow achieved via a function or a macro. Because the `Mutex` must be pinned in memory, the function cannot return it by value. It also cannot allocate a `Box` to put the `Mutex` into, because that is an unnecessary allocation and indirection which would hurt performance. The current solution was to split this function into two parts: 1. A `new` function that returns a partially initialized `Mutex`, 2. An `init` function that requires the `Mutex` to be pinned and that fully initializes the `Mutex`. Both of these functions have to be marked `unsafe`, since a call to `new` needs to be accompanied with a call to `init`, otherwise using the `Mutex` could result in UB. And because calling `init` twice also is not safe. While `Mutex` initialization cannot fail, other structs might also have to allocate memory, which would result in conditional successful initialization requiring even more manual accommodation work. Combine this with the problem of pin-projections -- the way of accessing fields of a pinned struct -- which also have an `unsafe` API, pinned initialization is riddled with `unsafe` resulting in very poor ergonomics. Not only that, but also having to call two functions possibly multiple lines apart makes it very easy to forget it outright or during refactoring. Here is an example of the current way of initializing a struct with two synchronization primitives (see [2] for the full example): struct SharedState { state_changed: CondVar, inner: Mutex, } impl SharedState { fn try_new() -> Result> { let mut state = Pin::from(UniqueArc::try_new(Self { // SAFETY: `condvar_init!` is called below. state_changed: unsafe { CondVar::new() }, // SAFETY: `mutex_init!` is called below. inner: unsafe { Mutex::new(SharedStateInner { token_count: 0 }) }, })?); // SAFETY: `state_changed` is pinned when `state` is. let pinned = unsafe { state.as_mut().map_unchecked_mut(|s| &mut s.state_changed) }; kernel::condvar_init!(pinned, "SharedState::state_changed"); // SAFETY: `inner` is pinned when `state` is. let pinned = unsafe { state.as_mut().map_unchecked_mut(|s| &mut s.inner) }; kernel::mutex_init!(pinned, "SharedState::inner"); Ok(state.into()) } } The pin-init API of this patch solves this issue by providing a comprehensive solution comprised of macros and traits. Here is the example from above using the pin-init API: #[pin_data] struct SharedState { #[pin] state_changed: CondVar, #[pin] inner: Mutex, } impl SharedState { fn new() -> impl PinInit { pin_init!(Self { state_changed <- new_condvar!("SharedState::state_changed"), inner <- new_mutex!( SharedStateInner { token_count: 0 }, "SharedState::inner", ), }) } } Notably the way the macro is used here requires no `unsafe` and thus comes with the usual Rust promise of safe code not introducing any memory violations. Additionally it is now up to the caller of `new()` to decide the memory location of the `SharedState`. They can choose at the moment `Arc`, `Box` or the stack. -- The API has the following architecture: 1. Initializer traits `PinInit` and `Init` that act like closures. 2. Macros to create these initializer traits safely. 3. Functions to allow manually writing initializers. The initializers (an `impl PinInit`) receive a raw pointer pointing to uninitialized memory and their job is to fully initialize a `T` at that location. If initialization fails, they return an error (`E`) by value. This way of initializing cannot be safely exposed to the user, since it relies upon these properties outside of the control of the trait: - the memory location (slot) needs to be valid memory, - if initialization fails, the slot should not be read from, - the value in the slot should be pinned, so it cannot move and the memory cannot be deallocated until the value is dropped. This is why using an initializer is facilitated by another trait that ensures these requirements. These initializers can be created manually by just supplying a closure that fulfills the same safety requirements as `PinInit`. But this is an `unsafe` operation. To allow safe initializer creation, the `pin_init!` is provided along with three other variants: `try_pin_init!`, `try_init!` and `init!`. These take a modified struct initializer as a parameter and generate a closure that initializes the fields in sequence. The macros take great care in upholding the safety requirements: - A shadowed struct type is used as the return type of the closure instead of `()`. This is to prevent early returns, as these would prevent full initialization. - To ensure every field is only initialized once, a normal struct initializer is placed in unreachable code. The type checker will emit errors if a field is missing or specified multiple times. - When initializing a field fails, the whole initializer will fail and automatically drop fields that have been initialized earlier. - Only the correct initializer type is allowed for unpinned fields. You cannot use a `impl PinInit` to initialize a structurally not pinned field. To ensure the last point, an additional macro `#[pin_data]` is needed. This macro annotates the struct itself and the user specifies structurally pinned and not pinned fields. Because dropping a pinned struct is also not allowed to break the pinning invariants, another macro attribute `#[pinned_drop]` is needed. These two macros also have mechanisms to ensure the overall safety of the API. Additionally, they utilize a combined proc-macro, declarative macro design: first a proc-macro enables the outer attribute syntax `#[...]` and does some important pre-parsing. Notably this prepares the generics such that the declarative macro can handle them using token trees. Then the actual parsing of the structure and the emission of code is handled by a declarative macro. For pin-projections the crates `pin-project` [3] and `pin-project-lite` [4] had been considered, but were ultimately rejected: - `pin-project` depends on `syn` [5] which is a very big dependency, around 50k lines of code. - `pin-project-lite` is a more reasonable 5k lines of code, but contains a very complex declarative macro to parse generics. On top of that it would require modification that would need to be maintained independently. Link: https://rust-for-linux.com/the-safe-pinned-initialization-problem [1] Link: https://github.com/Rust-for-Linux/linux/blob/f509ede33fc10a07eba3da14aa00302bd4b5dddd/samples/rust/rust_miscdev.rs [2] Link: https://crates.io/crates/pin-project [3] Link: https://crates.io/crates/pin-project-lite [4] Link: https://crates.io/crates/syn [5] Co-developed-by: Gary Guo Signed-off-by: Gary Guo Signed-off-by: Benno Lossin --- rust/kernel/init.rs | 1428 ++++++++++++++++++++++++++++++++++++ rust/kernel/init/macros.rs | 481 ++++++++++++ rust/kernel/lib.rs | 7 + rust/kernel/prelude.rs | 6 +- rust/kernel/sync/arc.rs | 25 +- rust/kernel/types.rs | 8 + rust/macros/lib.rs | 78 ++ rust/macros/pin_data.rs | 79 ++ rust/macros/pinned_drop.rs | 49 ++ scripts/Makefile.build | 2 +- 10 files changed, 2160 insertions(+), 3 deletions(-) create mode 100644 rust/kernel/init.rs create mode 100644 rust/kernel/init/macros.rs create mode 100644 rust/macros/pin_data.rs create mode 100644 rust/macros/pinned_drop.rs -- 2.39.2 diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs new file mode 100644 index 000000000000..895845db6f2b --- /dev/null +++ b/rust/kernel/init.rs @@ -0,0 +1,1428 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +//! API to safely and fallibly initialize pinned `struct`s using in-place constructors. +//! +//! It also allows in-place initialization of big `struct`s that would otherwise produce a stack +//! overflow. +//! +//! Most `struct`s from the [`sync`] module need to be pinned, because they contain self-referential +//! `struct`s from C. [Pinning][pinning] is Rust's way of ensuring data does not move. +//! +//! # Overview +//! +//! To initialize a `struct` with an in-place constructor you will need two things: +//! - an in-place constructor, +//! - a memory location that can hold your `struct` (this can be the [stack], an [`Arc`], +//! [`UniqueArc`], [`Box`] or any other smart pointer that implements [`InPlaceInit`]). +//! +//! To get an in-place constructor there are generally three options: +//! - directly creating an in-place constructor using the [`pin_init!`] macro, +//! - a custom function/macro returning an in-place constructor provided by someone else, +//! - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer. +//! +//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix. +//! +//! # Examples +//! +//! ## Using the [`pin_init!`] macro +//! +//! If you want to use [`PinInit`], then you will have to annotate your `struct` with +//! `#[`[`pin_data`]`]`. It is a macro that uses `#[pin]` as a marker for +//! [structurally pinned fields]. After doing this, you can then create an in-place constructor via +//! [`pin_init!`]. The syntax is almost the same as normal `struct` initializers. The difference is +//! that you need to write `<-` instead of `:` for fields that you want to initialize in-place. +//! +//! ```rust +//! # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +//! use kernel::{prelude::*, sync::Mutex, new_mutex}; +//! # use core::pin::Pin; +//! #[pin_data] +//! struct Foo { +//! #[pin] +//! a: Mutex, +//! b: u32, +//! } +//! +//! let foo = pin_init!(Foo { +//! a <- new_mutex!(42, "Foo::a"), +//! b: 24, +//! }); +//! ``` +//! +//! `foo` now is of the type [`impl PinInit`]. We can now use any smart pointer that we like +//! (or just the stack) to actually initialize a `Foo`: +//! +//! ```rust +//! # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +//! # use kernel::{prelude::*, sync::Mutex, new_mutex}; +//! # use core::pin::Pin; +//! # #[pin_data] +//! # struct Foo { +//! # #[pin] +//! # a: Mutex, +//! # b: u32, +//! # } +//! # let foo = pin_init!(Foo { +//! # a <- new_mutex!(42, "Foo::a"), +//! # b: 24, +//! # }); +//! let foo: Result>> = Box::pin_init(foo); +//! ``` +//! +//! For more information see the [`pin_init!`] macro. +//! +//! ## Using a custom function/macro that returns an initializer +//! +//! Many types from the kernel supply a function/macro that returns an initializer, because the +//! above method only works for types where you can access the fields. +//! +//! ```rust +//! # use kernel::{new_mutex, sync::{Arc, Mutex}}; +//! let mtx: Result>> = Arc::pin_init(new_mutex!(42, "example::mtx")); +//! ``` +//! +//! To declare an init macro/function you just return an [`impl PinInit`]: +//! +//! ```rust +//! # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +//! # use kernel::{sync::Mutex, prelude::*, new_mutex, init::PinInit, try_pin_init}; +//! #[pin_data] +//! struct DriverData { +//! #[pin] +//! status: Mutex, +//! buffer: Box<[u8; 1_000_000]>, +//! } +//! +//! impl DriverData { +//! fn new() -> impl PinInit { +//! try_pin_init!(Self { +//! status <- new_mutex!(0, "DriverData::status"), +//! buffer: Box::init(kernel::init::zeroed())?, +//! }) +//! } +//! } +//! ``` +//! +//! ## Manual creation of an initializer +//! +//! Often when working with primitives the previous approaches are not sufficient. That is where +//! [`pin_init_from_closure()`] comes in. This `unsafe` function allows you to create a +//! [`impl PinInit`] directly from a closure. Of course you have to ensure that the closure +//! actually does the initialization in the correct way. Here are the things to look out for +//! (we are calling the parameter to the closure `slot`): +//! - when the closure returns `Ok(())`, then it has completed the initialization successfully, so +//! `slot` now contains a valid bit pattern for the type `T`, +//! - when the closure returns `Err(e)`, then the caller may deallocate the memory at `slot`, so +//! you need to take care to clean up anything if your initialization fails mid-way, +//! - you may assume that `slot` will stay pinned even after the closure returns until `drop` of +//! `slot` gets called. +//! +//! ```rust +//! use kernel::init::{PinInit, self}; +//! use core::{ptr::addr_of_mut, marker::PhantomPinned}; +//! # mod bindings { +//! # pub struct foo; +//! # pub unsafe fn init_foo(_ptr: *mut foo) {} +//! # pub unsafe fn destroy_foo(_ptr: *mut foo) {} +//! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 } +//! # } +//! /// # Invariants +//! /// +//! /// `foo` is always initialized +//! pub struct RawFoo { +//! foo: Opaque, +//! _p: PhantomPinned, +//! } +//! +//! impl RawFoo { +//! pub fn new(flags: u32) -> impl PinInit { +//! // SAFETY: +//! // - when the closure returns `Ok(())`, then it has successfully initialized and +//! // enabled `foo`, +//! // - when it returns `Err(e)`, then it has cleaned up before +//! unsafe { +//! init::pin_init_from_closure(move |slot: *mut Self| { +//! // `slot` contains uninit memory, avoid creating a reference. +//! let foo = addr_of_mut!((*slot).foo); +//! +//! // Initialize the `foo` +//! bindings::init_foo(Opaque::raw_get(foo)); +//! +//! // Try to enable it. +//! let err = bindings::enable_foo(Opaque::raw_get(foo), flags); +//! if err != 0 { +//! // Enabling has failed, first clean up the foo and then return the error. +//! bindings::destroy_foo(Opaque::raw_get(foo)); +//! return Err(Error::from_kernel_errno(err)); +//! } +//! +//! // All fields of `RawFoo` have been initialized, since `_p` is a ZST. +//! Ok(()) +//! }) +//! } +//! } +//! } +//! +//! impl Drop for RawFoo { +//! fn drop(&mut self) { +//! // SAFETY: Since `foo` is initialized, destroying is safe. +//! unsafe { bindings::destroy_foo(self.foo.get()) }; +//! } +//! } +//! ``` +//! +//! For the special case where initializing a field is a single FFI-function call that cannot fail, +//! there exist helper functions in [`kernel::init::common`]. These functions initialize a single +//! [`Opaque`] field by just delegating to the FFI-function. You can use these in combination with +//! [`pin_init!`]. +//! +//! For more information on how to use [`pin_init_from_closure()`], take a look at the uses inside +//! the `kernel` crate. The [`sync`] module is a good starting point. +//! +//! [`sync`]: kernel::sync +//! [pinning]: https://doc.rust-lang.org/std/pin/index.html +//! [structurally pinned fields]: +//! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +//! [stack]: crate::stack_pin_init +//! [`Arc`]: crate::sync::Arc +//! [`impl PinInit`]: PinInit +//! [`impl PinInit`]: PinInit +//! [`impl Init`]: Init +//! [`Opaque`]: kernel::types::Opaque +//! [`pin_data`]: ::macros::pin_data + +use crate::{ + error::{self, Error}, + sync::UniqueArc, +}; +use alloc::boxed::Box; +use core::{ + cell::Cell, + convert::Infallible, + marker::{PhantomData, Unpin}, + mem::MaybeUninit, + pin::Pin, + ptr, +}; + +#[doc(hidden)] +pub mod macros; + +/// Initialize and pin a type directly on the stack. +/// +/// # Examples +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use macros::pin_data; +/// # use core::pin::Pin; +/// #[pin_data] +/// struct Foo { +/// #[pin] +/// a: Mutex, +/// b: Bar, +/// } +/// +/// #[pin_data] +/// struct Bar { +/// x: u32, +/// } +/// +/// let a = new_mutex!(42, "Foo::a"); +/// +/// stack_pin_init!(let foo =? pin_init!(Foo { +/// a, +/// b: Bar { +/// x: 64, +/// }, +/// })); +/// let foo: Pin<&mut Foo> = foo; +/// # Ok::<(), core::convert::Infallible>(()) +/// ``` +/// +/// # Syntax +/// +/// A normal `let` binding with optional type annotation. The expression is expected to implement +/// [`PinInit`]. Additionally a `?` can be put after the `=`, this will assign `Pin<&mut T>` to the +/// variable instead of `Result, E>`. +#[macro_export] +macro_rules! stack_pin_init { + (let $var:ident $(: $t:ty)? = $val:expr) => { + let mut $var = $crate::init::StackInit$(::<$t>)?::uninit(); + let mut $var = { + let val = $val; + unsafe { $crate::init::StackInit::init(&mut $var, val) } + }; + }; + (let $var:ident $(: $t:ty)? =? $val:expr) => { + let mut $var = $crate::init::StackInit$(::<$t>)?::uninit(); + let mut $var = { + let val = $val; + unsafe { $crate::init::StackInit::init(&mut $var, val)? } + }; + }; +} + +/// Construct an in-place, pinned initializer for `struct`s. +/// +/// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use +/// [`try_pin_init!`]. +/// +/// The syntax is almost identical to that of a normal `struct` initializer: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use core::pin::Pin; +/// #[pin_data] +/// struct Foo { +/// a: usize, +/// b: Bar, +/// } +/// +/// #[pin_data] +/// struct Bar { +/// x: u32, +/// } +/// +/// # fn demo() -> impl PinInit { +/// let a = 42; +/// +/// let initializer = pin_init!(Foo { +/// a, +/// b: Bar { +/// x: 64, +/// }, +/// }); +/// # initializer } +/// # Box::pin_init(demo()).unwrap(); +/// ``` +/// +/// Arbitrary Rust expressions can be used to set the value of a variable. +/// +/// # Init-functions +/// +/// When working with this API it is often desired to let others construct your types without +/// giving access to all fields. This is where you would normally write a plain function `new` +/// that would return a new instance of your type. With this API that is also possible. +/// However, there are a few extra things to keep in mind. +/// +/// To create an initializer function, simply declare it like this: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, prelude::*, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo { +/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar { +/// # x: u32, +/// # } +/// +/// impl Foo { +/// fn new() -> impl PinInit { +/// pin_init!(Self { +/// a: 42, +/// b: Bar { +/// x: 64, +/// }, +/// }) +/// } +/// } +/// ``` +/// +/// Users of `Foo` can now create it like this: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo { +/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar { +/// # x: u32, +/// # } +/// # impl Foo { +/// # fn new() -> impl PinInit { +/// # pin_init!(Self { +/// # a: 42, +/// # b: Bar { +/// # x: 64, +/// # }, +/// # }) +/// # } +/// # } +/// let foo = Box::pin_init(Foo::new()); +/// ``` +/// +/// They can also easily embed it into their own `struct`s: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo { +/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar { +/// # x: u32, +/// # } +/// # impl Foo { +/// # fn new() -> impl PinInit { +/// # pin_init!(Self { +/// # a: 42, +/// # b: Bar { +/// # x: 64, +/// # }, +/// # }) +/// # } +/// # } +/// #[pin_data] +/// struct FooContainer { +/// #[pin] +/// foo1: Foo, +/// #[pin] +/// foo2: Foo, +/// other: u32, +/// } +/// +/// impl FooContainer { +/// fn new(other: u32) -> impl PinInit { +/// pin_init!(Self { +/// foo1 <- Foo::new(), +/// foo2 <- Foo::new(), +/// other, +/// }) +/// } +/// } +/// ``` +/// +/// Here we see that when using `pin_init!` with `PinInit`, one needs to write `<-` instead of `:`. +/// This signifies that the given field is initialized in-place. As with `struct` initializers, just +/// writing the field (in this case `other`) without `:` or `<-` means `other: other,`. +/// +/// # Syntax +/// +/// As already mentioned in the examples above, inside of `pin_init!` a `struct` initializer with +/// the following modifications is expected: +/// - Fields that you want to initialize in-place have to use `<-` instead of `:`. +/// - In front of the initializer you can write `&this in` to have access to a [`NonNull`] +/// pointer named `this` inside of the initializer. +/// +/// For instance: +/// +/// ```rust +/// # use kernel::pin_init; +/// # use macros::pin_data; +/// # use core::{ptr::addr_of_mut, marker::PhantomPinned}; +/// #[pin_data] +/// struct Buf { +/// ptr: *mut u8, +/// buf: [u8; 64], +/// #[pin] +/// pin: PhantomPinned, +/// } +/// pin_init!(&this in Buf { +/// buf: [0; 64], +/// ptr: unsafe { addr_of_mut!((*this.as_ptr()).buf).cast() }, +/// pin: PhantomPinned, +/// }); +/// ``` +/// +/// [`try_pin_init!`]: kernel::try_pin_init +/// [`NonNull`]: core::ptr::NonNull +#[macro_export] +macro_rules! pin_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_pin_init!( + @this($($this)?), + @type_name($t), + @typ($t $(<$($generics),*>)?), + @fields($($fields)*), + @error(::core::convert::Infallible), + ) + }; +} + +/// Construct an in-place, fallible pinned initializer for `struct`s. +/// +/// If the initialization can complete without error (or [`Infallible`]), then use [`pin_init!`]. +/// +/// You can use the `?` operator or use `return Err(err)` inside the initializer to stop +/// initialization and return the error. +/// +/// IMPORTANT: if you have `unsafe` code inside of the initializer you have to ensure that when +/// initialization fails, the memory can be safely deallocated without any further modifications. +/// +/// This macro defaults the error to [`Error`]. +/// +/// The syntax is identical to [`pin_init!`] with the following exception: you can append `? $type` +/// after the `struct` initializer to specify the error type you want to use. +/// +/// # Examples +/// +/// ```rust +/// use kernel::{init::PinInit, error::Error}; +/// struct BigBuf { +/// big: Box<[u8; 1024 * 1024 * 1024]>, +/// small: [u8; 1024 * 1024], +/// ptr: *mut u8, +/// } +/// +/// impl BigBuf { +/// fn new() -> impl PinInit { +/// try_pin_init!(Self { +/// big: { +/// let zero = Box::try_new_zeroed()?; +/// unsafe { zero.assume_init() } +/// }, +/// small: [0; 1024 * 1024], +/// ptr: core::ptr::null_mut(), +/// }? Error) +/// } +/// } +/// ``` +#[macro_export] +macro_rules! try_pin_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_pin_init!( + @this($($this)?), + @type_name($t), + @typ($t $(<$($generics),*>)?), + @fields($($fields)*), + @error($crate::error::Error), + ) + }; + ($(&$this:ident in)? $t:ident $(<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }? $err:ty) => { + $crate::try_pin_init!( + @this($($this)?), + @type_name($t), + @typ($t $(<$($generics),*>)?), + @fields($($fields)*), + @error($err), + ) + }; + ( + @this($($this:ident)?), + @type_name($t:ident), + @typ($ty:ty), + @fields($($fields:tt)*), + @error($err:ty), + ) => {{ + // We do not want to allow arbitrary returns, so we declare this type as the `Ok` return + // type and shadow it later when we insert the arbitrary user code. That way there will be + // no possibility of returning without `unsafe`. + struct __InitOk; + let init = move |slot: *mut $ty| -> ::core::result::Result<__InitOk, $err> { + { + // Shadow the structure so it cannot be used to return early. + struct __InitOk; + // Create the `this` so it can be referenced by the user inside of the expressions + // creating the individual fields. + $(let $this = unsafe { ::core::ptr::NonNull::new_unchecked(slot) };)? + // Initialize every field. + $crate::try_pin_init!(init_slot: + @typ($ty), + @slot(slot), + @munch_fields($($fields)*,), + ); + // We use unreachable code to ensure that all fields have been mentioned exactly + // once, this struct initializer will still be type-checked and complain with a + // very natural error message if a field is forgotten/mentioned more than once. + #[allow(unreachable_code, clippy::diverging_sub_expression)] + if false { + $crate::try_pin_init!(make_initializer: + @typ($ty), + @type_name($t), + @munch_fields($($fields)*,), + @acc(), + ); + } + // Forget all guards, since initialization was a success. + $crate::try_pin_init!(forget_guards: + @munch_fields($($fields)*,), + ); + } + Ok(__InitOk) + }; + let init = move |slot: *mut $ty| -> ::core::result::Result<(), $err> { + init(slot).map(|__InitOk| ()) + }; + let init = unsafe { $crate::init::pin_init_from_closure::<$ty, $err>(init) }; + init + }}; + (init_slot: + @typ($ty:ty), + @slot($slot:ident), + @munch_fields($(,)?), + ) => { + // Endpoint of munching, no fields are left. + }; + (init_slot: + @typ($ty:ty), + @slot($slot:ident), + // In-place initialization syntax. + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { + let $field = $val; + // Call the initializer. + // + // SAFETY: `slot` is valid, because we are inside of an initializer closure, we + // return when an error/panic occurs. + // We also use the `__PinData` to request the correct trait (`Init` or `PinInit`). + unsafe { + <$ty as $crate::init::__PinData>::__PinData::$field( + ::core::ptr::addr_of_mut!((*$slot).$field), + $field, + )?; + } + // Create the drop guard. + // + // We only give access to `&DropGuard`, so it cannot be forgotten via safe code. + // + // SAFETY: We forget the guard later when initialization has succeeded. + let $field = &unsafe { + $crate::init::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_pin_init!(init_slot: + @typ($ty), + @slot($slot), + @munch_fields($($rest)*), + ); + }; + (init_slot: + @typ($ty:ty), + @slot($slot:ident), + // Direct value init, this is safe for every field. + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { + $(let $field = $val;)? + // Call the initializer. + // + // SAFETY: The memory at `slot` is uninitialized. + unsafe { ::core::ptr::addr_of_mut!((*$slot).$field).write($field) }; + // Create the drop guard: + // + // We only give access to `&DropGuard`, so it cannot be accidentally forgotten. + // + // SAFETY: We forget the guard later when initialization has succeeded. + let $field = &unsafe { + $crate::init::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_pin_init!(init_slot: + @typ($ty), + @slot($slot), + @munch_fields($($rest)*), + ); + }; + (make_initializer: + @typ($ty:ty), + @type_name($t:ident), + @munch_fields($(,)?), + @acc($($acc:tt)*), + ) => { + // Endpoint, nothing more to munch. + let _: $ty = $t { + $($acc)* + }; + }; + (make_initializer: + @typ($ty:ty), + @type_name($t:ident), + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_pin_init!(make_initializer: + @typ($ty), + @type_name($t), + @munch_fields($($rest)*), + @acc($($acc)* $field: ::core::panic!(),), + ); + }; + (make_initializer: + @typ($ty:ty), + @type_name($t:ident), + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_pin_init!(make_initializer: + @typ($ty), + @type_name($t), + @munch_fields($($rest)*), + @acc($($acc)* $field: ::core::panic!(),), + ); + }; + (forget_guards: + @munch_fields($(,)?), + ) => { + // Munching finished. + }; + (forget_guards: + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { + unsafe { $crate::init::DropGuard::forget($field) }; + + $crate::try_pin_init!(forget_guards: + @munch_fields($($rest)*), + ); + }; + (forget_guards: + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { + unsafe { $crate::init::DropGuard::forget($field) }; + + $crate::try_pin_init!(forget_guards: + @munch_fields($($rest)*), + ); + }; +} + +/// Construct an in-place initializer for `struct`s. +/// +/// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use +/// [`try_init!`]. +/// +/// The syntax is identical to [`pin_init!`]. +/// +/// This initializer is for initializing data in-place that might later be moved. If you want to +/// pin-initialize, use [`pin_init!`]. +#[macro_export] +macro_rules! init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_init!( + @this($($this)?), + @type_name($t), + @typ($t $(<$($generics),*>)?), + @fields($($fields)*), + @error(::core::convert::Infallible), + ) + } +} + +/// Construct an in-place fallible initializer for `struct`s. +/// +/// This macro defaults the error to [`Error`]. If you need [`Infallible`], then use +/// [`init!`]. +/// +/// The syntax is identical to [`try_pin_init!`]. If you want to specify a custom error, +/// append `? $type` after the `struct` initializer. +/// +/// # Examples +/// +/// ```rust +/// use kernel::{init::PinInit, error::Error}; +/// struct BigBuf { +/// big: Box<[u8; 1024 * 1024 * 1024]>, +/// small: [u8; 1024 * 1024], +/// } +/// +/// impl BigBuf { +/// fn new() -> impl Init { +/// try_init!(Self { +/// big: { +/// let zero = Box::try_new_zeroed()?; +/// unsafe { zero.assume_init() } +/// }, +/// small: [0; 1024 * 1024], +/// }? Error) +/// } +/// } +/// ``` +#[macro_export] +macro_rules! try_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_init!( + @this($($this)?), + @type_name($t), + @typ($t $(<$($generics),*>)?), + @fields($($fields)*), + @error($crate::error::Error), + ) + }; + ($(&$this:ident in)? $t:ident $(<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }? $err:ty) => { + $crate::try_init!( + @this($($this)?), + @type_name($t), + @typ($t $(<$($generics),*>)?), + @fields($($fields)*), + @error($err), + ) + }; + ( + @this($($this:ident)?), + @type_name($t:ident), + @typ($ty:ty), + @fields($($fields:tt)*), + @error($err:ty), + ) => {{ + // We do not want to allow arbitrary returns, so we declare this type as the `Ok` return + // type and shadow it later when we insert the arbitrary user code. That way there will be + // no possibility of returning without `unsafe`. + struct __InitOk; + let init = move |slot: *mut $ty| -> ::core::result::Result<__InitOk, $err> { + { + // Shadow the structure so it cannot be used to return early. + struct __InitOk; + // Create the `this` so it can be referenced by the user inside of the expressions + // creating the individual fields. + $(let $this = unsafe { ::core::ptr::NonNull::new_unchecked(slot) };)? + // Initialize every field. + $crate::try_init!(init_slot: + @typ($ty), + @slot(slot), + @munch_fields($($fields)*,), + ); + // We use unreachable code to ensure that all fields have been mentioned exactly + // once, this struct initializer will still be type-checked and complain with a + // very natural error message if a field is forgotten/mentioned more than once. + #[allow(unreachable_code, clippy::diverging_sub_expression)] + if false { + $crate::try_init!(make_initializer: + @typ($ty), + @type_name($t), + @munch_fields($($fields)*,), + @acc(), + ); + } + // Forget all guards, since initialization was a success. + $crate::try_init!(forget_guards: + @munch_fields($($fields)*,), + ); + } + Ok(__InitOk) + }; + let init = move |slot: *mut $ty| -> ::core::result::Result<(), $err> { + init(slot).map(|__InitOk| ()) + }; + let init = unsafe { $crate::init::init_from_closure::<$ty, $err>(init) }; + init + }}; + (init_slot: + @typ($ty:ty), + @slot($slot:ident), + @munch_fields( $(,)?), + ) => { + // Endpoint of munching, no fields are left. + }; + (init_slot: + @typ($ty:ty), + @slot($slot:ident), + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { + let $field = $val; + // Call the initializer. + // + // SAFETY: `slot` is valid, because we are inside of an initializer closure, we + // return when an error/panic occurs. + unsafe { + $crate::init::Init::__init($field, ::core::ptr::addr_of_mut!((*$slot).$field))?; + } + // Create the drop guard. + // + // We only give access to `&DropGuard`, so it cannot be accidentally forgotten. + // + // SAFETY: We forget the guard later when initialization has succeeded. + let $field = &unsafe { + $crate::init::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_init!(init_slot: + @typ($ty), + @slot($slot), + @munch_fields($($rest)*), + ); + }; + (init_slot: + @typ($ty:ty), + @slot($slot:ident), + // Direct value init. + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { + $(let $field = $val;)? + // Call the initializer. + // + // SAFETY: The memory at `slot` is uninitialized. + unsafe { ::core::ptr::addr_of_mut!((*$slot).$field).write($field) }; + // Create the drop guard. + // + // We only give access to `&DropGuard`, so it cannot be accidentally forgotten. + // + // SAFETY: We forget the guard later when initialization has succeeded. + let $field = &unsafe { + $crate::init::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_init!(init_slot: + @typ($ty), + @slot($slot), + @munch_fields($($rest)*), + ); + }; + (make_initializer: + @typ($ty:ty), + @type_name($t:ident), + @munch_fields( $(,)?), + @acc($($acc:tt)*), + ) => { + // Endpoint, nothing more to munch. + let _: $ty = $t { + $($acc)* + }; + }; + (make_initializer: + @typ($ty:ty), + @type_name($t:ident), + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_init!(make_initializer: + @typ($ty), + @type_name($t), + @munch_fields($($rest)*), + @acc($($acc)*$field: ::core::panic!(),), + ); + }; + (make_initializer: + @typ($ty:ty), + @type_name($t:ident), + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_init!(make_initializer: + @typ($ty), + @type_name($t), + @munch_fields($($rest)*), + @acc($($acc)*$field: ::core::panic!(),), + ); + }; + (forget_guards: + @munch_fields($(,)?), + ) => { + // Munching finished. + }; + (forget_guards: + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { + unsafe { $crate::init::DropGuard::forget($field) }; + + $crate::try_init!(forget_guards: + @munch_fields($($rest)*), + ); + }; + (forget_guards: + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { + unsafe { $crate::init::DropGuard::forget($field) }; + + $crate::try_init!(forget_guards: + @munch_fields($($rest)*), + ); + }; +} + +/// A pinned initializer for `T`. +/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box`], [`Arc`], [`UniqueArc`] or even the stack (see [`stack_pin_init!`]). Use the +/// [`InPlaceInit::pin_init`] function of a smart pointer like [`Arc::pin_init`] on this. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`from_value`] and +/// [`pin_init_from_closure`] where possible. +/// +/// The [`PinInit::__pinned_init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// [`Arc`]: crate::sync::Arc +/// [`Arc::pin_init`]: crate::sync::Arc::pin_init +#[must_use = "An initializer must be used in order to create its value."] +pub unsafe trait PinInit: Sized { + /// Initializes `slot`. + /// + /// # Safety + /// + /// - `slot` is a valid pointer to uninitialized memory. + /// - the caller does not touch `slot` when `Err` is returned, they are only permitted to + /// deallocate. + /// - `slot` will not move until it is dropped, i.e. it will be pinned. + unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E>; +} + +/// An initializer for `T`. +/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box`], [`Arc`], [`UniqueArc`] or even the stack (see [`stack_pin_init!`]). Use the +/// `init` function of a smart pointer like [`Box::init`] on this. Because [`PinInit`] is a +/// super trait, you can use every function that takes it as well. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`from_value`] and +/// [`init_from_closure`] where possible. +/// +/// The [`Init::__init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// The `__pinned_init` function from the supertrait [`PinInit`] needs to execute the exact same +/// code as `__init`. +/// +/// Contrary to its supertype [`PinInit`] the caller is allowed to +/// move the pointee after initialization. +/// +/// [`Arc`]: crate::sync::Arc +#[must_use = "An initializer must be used in order to create its value."] +pub unsafe trait Init: PinInit { + /// Initializes `slot`. + /// + /// # Safety + /// + /// - `slot` is a valid pointer to uninitialized memory. + /// - the caller does not touch `slot` when `Err` is returned, they are only permitted to + /// deallocate. + unsafe fn __init(self, slot: *mut T) -> Result<(), E>; +} + +type Invariant = PhantomData *mut T>; +// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure(F, Invariant<(E, T)>); + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__pinned_init` invariants. +unsafe impl PinInit for InitClosure +where + F: FnOnce(*mut T) -> Result<(), E>, +{ + #[inline] + unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> { + (self.0)(slot) + } +} + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__init` invariants. +unsafe impl Init for InitClosure +where + F: FnOnce(*mut T) -> Result<(), E>, +{ + #[inline] + unsafe fn __init(self, slot: *mut T) -> Result<(), E> { + (self.0)(slot) + } +} + +/// Creates a new [`PinInit`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - may assume that the `slot` does not move if `T: !Unpin`, +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn pin_init_from_closure( + f: impl FnOnce(*mut T) -> Result<(), E>, +) -> impl PinInit { + InitClosure(f, PhantomData) +} + +/// Creates a new [`Init`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - the `slot` may move after initialization. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn init_from_closure( + f: impl FnOnce(*mut T) -> Result<(), E>, +) -> impl Init { + InitClosure(f, PhantomData) +} + +/// Trait facilitating pinned destruction. +/// +/// Use [`pinned_drop`] to implement this trait safely: +/// +/// ```rust +/// # use kernel::sync::Mutex; +/// use kernel::macros::pinned_drop; +/// use core::pin::Pin; +/// #[pin_data(PinnedDrop)] +/// struct Foo { +/// #[pin] +/// mtx: Mutex, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for Foo { +/// fn drop(self: Pin<&mut Self>) { +/// pr_info!("Foo is being dropped!"); +/// } +/// } +/// ``` +/// +/// # Safety +/// +/// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl. +/// +/// [`pinned_drop`]: kernel::macros::pinned_drop +pub unsafe trait PinnedDrop: __PinData { + /// Executes the pinned destructor of this type. + /// + /// While this function is marked safe, it is actually unsafe to call it manually. For this + /// reason it takes an additional parameter. This type can only be constructed by `unsafe` code + /// and thus prevents this function from being called where it should not. + /// + /// This extra parameter will be generated by the `#[pinned_drop]` proc-macro attribute + /// automatically. + fn drop(self: Pin<&mut Self>, only_call_from_drop: OnlyCallFromDrop); +} + +// We need one private field, because otherwise it can be constructed. +#[doc(hidden)] +pub struct OnlyCallFromDrop(()); + +impl OnlyCallFromDrop { + /// # Safety + /// + /// This function should only be called from the [`Drop::drop`] function and only be used to + /// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type. + #[doc(hidden)] + pub unsafe fn create() -> Self { + Self(()) + } +} + +/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit: Sized { + /// Use the given initializer to in-place initialize a `T`. + /// + /// If `T: !Unpin` it will not be able to move afterwards. + fn pin_init(init: impl PinInit) -> error::Result> + where + Error: From; + + /// Use the given initializer to in-place initialize a `T`. + fn init(init: impl Init) -> error::Result + where + Error: From; +} + +impl InPlaceInit for Box { + #[inline] + fn pin_init(init: impl PinInit) -> error::Result> + where + Error: From, + { + let mut this = Box::try_new_uninit()?; + let slot = this.as_mut_ptr(); + // SAFETY: When init errors/panics, slot will get deallocated but not dropped, + // slot is valid and will not be moved because of the `Pin::new_unchecked` + unsafe { init.__pinned_init(slot)? }; + // SAFETY: All fields have been initialized. + Ok(unsafe { Pin::new_unchecked(this.assume_init()) }) + } + + #[inline] + fn init(init: impl Init) -> error::Result + where + Error: From, + { + let mut this = Box::try_new_uninit()?; + let slot = this.as_mut_ptr(); + // SAFETY: When init errors/panics, slot will get deallocated but not dropped, + // slot is valid + unsafe { init.__init(slot)? }; + // SAFETY: All fields have been initialized. + Ok(unsafe { this.assume_init() }) + } +} + +impl InPlaceInit for UniqueArc { + #[inline] + fn pin_init(init: impl PinInit) -> error::Result> + where + Error: From, + { + let mut this = UniqueArc::try_new_uninit()?; + let slot = this.as_mut_ptr(); + // SAFETY: When init errors/panics, slot will get deallocated but not dropped, + // slot is valid and will not be moved because of the `Pin::new_unchecked`. + unsafe { init.__pinned_init(slot)? }; + // SAFETY: All fields have been initialized. + Ok(unsafe { Pin::new_unchecked(this.assume_init()) }) + } + + #[inline] + fn init(init: impl Init) -> error::Result + where + Error: From, + { + let mut this = UniqueArc::try_new_uninit()?; + let slot = this.as_mut_ptr(); + // SAFETY: When init errors/panics, slot will get deallocated but not dropped, + // slot is valid. + unsafe { init.__init(slot)? }; + // SAFETY: All fields have been initialized. + Ok(unsafe { this.assume_init() }) + } +} + +/// Marker trait for types that can be initialized by writing just zeroes. +/// +/// # Safety +/// +/// The bit pattern consisting of only zeroes is a valid bit pattern for this type. In other words, +/// this is not UB: +/// +/// ```rust,ignore +/// let val: Self = unsafe { core::mem::zeroed() }; +/// ``` +pub unsafe trait Zeroable {} + +/// Create a new zeroed T. +/// +/// The returned initializer will write `0x00` to every byte of the given `slot`. +#[inline] +pub fn zeroed() -> impl Init { + // SAFETY: Because `T: Zeroable`, all bytes zero is a valid bit pattern for `T` + // and because we write all zeroes, the memory is initialized. + unsafe { + init_from_closure(|slot: *mut T| { + slot.write_bytes(0, 1); + Ok(()) + }) + } +} + +/// An initializer that leaves the memory uninitialized. +/// +/// The initializer is a no-op. The `slot` memory is not changed. +#[inline] +pub fn uninit() -> impl Init> { + // SAFETY: The memory is allowed to be uninitialized. + unsafe { init_from_closure(|_| Ok(())) } +} + +/// Convert a value into an initializer. +/// +/// Directly moves the value into the given `slot`. +/// +/// Note that you can just write `field: value,` in all initializer macros. This function's purpose +/// is to provide compatibility with APIs that only have `PinInit`/`Init` as parameters. +#[inline] +pub fn from_value(value: T) -> impl Init { + // SAFETY: We use the value to initialize the slot. + unsafe { + init_from_closure(move |slot: *mut T| { + slot.write(value); + Ok(()) + }) + } +} + +unsafe impl PinInit for T { + unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), Infallible> { + unsafe { slot.write(self) }; + Ok(()) + } +} + +unsafe impl Init for T { + unsafe fn __init(self, slot: *mut T) -> Result<(), Infallible> { + unsafe { slot.write(self) }; + Ok(()) + } +} + +macro_rules! impl_zeroable { + ($($t:ty, )*) => { + $(unsafe impl Zeroable for $t {})* + }; +} +impl_zeroable! { + // SAFETY: All primitives that are allowed to be zero. + bool, + char, + u8, u16, u32, u64, u128, usize, + i8, i16, i32, i64, i128, isize, + f32, f64, + // SAFETY: There is nothing to zero. + core::marker::PhantomPinned, Infallible, (), +} + +// SAFETY: We are allowed to zero padding bytes. +unsafe impl Zeroable for [T; N] {} + +// SAFETY: There is nothing to zero. +unsafe impl Zeroable for PhantomData {} + +// SAFETY: `null` pointer is valid. +unsafe impl Zeroable for *mut T {} +unsafe impl Zeroable for *const T {} + +macro_rules! impl_tuple_zeroable { + ($(,)?) => {}; + ($first:ident, $($t:ident),* $(,)?) => { + // SAFETY: All elements are zeroable and padding can be zero. + unsafe impl<$first: Zeroable, $($t: Zeroable),*> Zeroable for ($first, $($t),*) {} + impl_tuple_zeroable!($($t),* ,); + } +} + +impl_tuple_zeroable!(A, B, C, D, E, F, G, H, I, J); + +// This trait is only implemented via the `#[pin_data]` proc-macro. It is used to facilitate +// the pin projections within the initializers. +#[doc(hidden)] +pub unsafe trait __PinData { + type __PinData; +} + +/// Stack initializer helper type. Use [`stack_pin_init`] instead of this primitive. +/// +/// # Invariants +/// +/// If `self.1` is true, then `self.0` is initialized. +/// +/// [`stack_pin_init`]: kernel::stack_pin_init +#[doc(hidden)] +pub struct StackInit(MaybeUninit, bool); + +impl Drop for StackInit { + #[inline] + fn drop(&mut self) { + if self.1 { + // SAFETY: As we are being dropped, we only call this once. And since `self.1 == true`, + // `self.0` has to be initialized. + unsafe { self.0.assume_init_drop() }; + } + } +} + +impl StackInit { + /// Creates a new [`StackInit`] that is uninitialized. Use [`stack_pin_init`] instead of this + /// primitive. + /// + /// [`stack_pin_init`]: kernel::stack_pin_init + #[inline] + pub fn uninit() -> Self { + Self(MaybeUninit::uninit(), false) + } + + /// Initializes the contents and returns the result. + /// + /// # Safety + /// + /// The caller ensures that `self` is on the stack and not accessible in any other way, if this + /// function returns `Ok`. + #[inline] + pub unsafe fn init(&mut self, init: impl PinInit) -> Result, E> { + // SAFETY: The memory slot is valid and this type ensures that it will stay pinned. + unsafe { init.__pinned_init(self.0.as_mut_ptr())? }; + self.1 = true; + // SAFETY: The slot is now pinned, since we will never give access to `&mut T`. + Ok(unsafe { Pin::new_unchecked(self.0.assume_init_mut()) }) + } +} + +/// When a value of this type is dropped, it drops a `T`. +/// +/// Public, but hidden type, since it should only be used by the macros of this module. +#[doc(hidden)] +pub struct DropGuard(*mut T, Cell); + +impl DropGuard { + /// Creates a new [`DropGuard`]. It will [`ptr::drop_in_place`] `ptr` when it gets dropped. + /// + /// # Safety + /// + /// `ptr` must be a valid pointer. + /// + /// It is the callers responsibility that `self` will only get dropped if the pointee of `ptr`: + /// - has not been dropped, + /// - is not accessible by any other means, + /// - will not be dropped by any other means. + #[inline] + pub unsafe fn new(ptr: *mut T) -> Self { + Self(ptr, Cell::new(true)) + } + + /// Prevents this guard from dropping the supplied pointer. + /// + /// # Safety + /// + /// This function is unsafe in order to prevent safe code from forgetting this guard. It should + /// only be called by the macros in this module. + #[inline] + pub unsafe fn forget(&self) { + self.1.set(false); + } +} + +impl Drop for DropGuard { + #[inline] + fn drop(&mut self) { + if self.1.get() { + // SAFETY: A `DropGuard` can only be constructed using the unsafe `new` function + // ensuring that this operation is safe. + unsafe { ptr::drop_in_place(self.0) } + } + } +} diff --git a/rust/kernel/init/macros.rs b/rust/kernel/init/macros.rs new file mode 100644 index 000000000000..aec03f0b0897 --- /dev/null +++ b/rust/kernel/init/macros.rs @@ -0,0 +1,481 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +//! This module provides the macros that actually implement the proc-macros `pin_data` and +//! `pinned_drop`. These macros should never be called directly, since they expect their input to be +//! in a certain format which is internal. Use the proc-macros instead. +//! +//! This architecture has been chosen because the kernel does not yet have access to `syn` which +//! would make matters a lot easier for implementing these as proc-macros. + +/// This macro creates a `unsafe impl<...> PinnedDrop for $type` block. +/// +/// See [`PinnedDrop`] for more information. +#[doc(hidden)] +#[macro_export] +macro_rules! __pinned_drop { + ( + @impl_sig($($impl_sig:tt)*), + @impl_body( + $(#[$($attr:tt)*])* + fn drop($self:ident: $st:ty) { + $($inner:stmt)* + } + ), + ) => { + unsafe $($impl_sig)* { + // Inherit all attributes and the type/ident tokens for the signature. + $(#[$($attr)*])* + fn drop($self: $st, _: $crate::init::OnlyCallFromDrop) { + $($inner)* + } + } + } +} + +/// This macro first parses the struct definition such that it separates pinned and not pinned +/// fields. Afterwards it declares the struct and implement the `__PinData` trait safely. +#[doc(hidden)] +#[macro_export] +macro_rules! __pin_data { + // Proc-macro entry point, this is supplied by the proc-macro pre-parsing. + (parse_input: + @args($($pinned_drop:ident)?), + @sig( + $(#[$($struct_attr:tt)*])* + $vis:vis struct $name:ident + $(where $($whr:tt)*)? + ), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @body({ $($fields:tt)* }), + ) => { + // We now use token munching to iterate through all of the fields. While doing this we + // identify fields marked with `#[pin]`, these fields are the 'pinned fields'. The user + // wants these to be structurally pinned. The rest of the fields are the + // 'not pinned fields'. Additionally we collect all fields, since we need them in the right + // order to declare the struct. + // + // In this call we also put some explaining comments for the parameters. + $crate::__pin_data!(find_pinned_fields: + // Attributes on the struct itself, these will just be propagated to be put onto the + // struct definition. + @struct_attrs($(#[$($struct_attr)*])*), + // The visibility of the struct. + @vis($vis), + // The name of the struct. + @name($name), + // The 'impl generics', the generics that will need to be specified on the struct inside + // of an `impl<$ty_generics>` block. + @impl_generics($($impl_generics)*), + // The 'ty generics', the generics that will need to be specified on the impl blocks. + @ty_generics($($ty_generics)*), + // The where clause of any impl block and the declaration. + @where($($($whr)*)?), + // The remaining fields tokens that need to be processed. + // We add a `,` at the end to ensure correct parsing. + @fields_munch($($fields)* ,), + // The pinned fields. + @pinned(), + // The not pinned fields. + @not_pinned(), + // All fields. + @fields(), + // The accumulator containing all attributes already parsed. + @accum(), + // Contains `yes` or `` to indicate if `#[pin]` was found on the current field. + @is_pinned(), + // The proc-macro argument, this should be `PinnedDrop` or ``. + @pinned_drop($($pinned_drop)?), + ); + }; + (find_pinned_fields: + @struct_attrs($($struct_attrs:tt)*), + @vis($vis:vis), + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + // We found a PhantomPinned field, this should generally be pinned! + @fields_munch($field:ident : $($($(::)?core::)?marker::)?PhantomPinned, $($rest:tt)*), + @pinned($($pinned:tt)*), + @not_pinned($($not_pinned:tt)*), + @fields($($fields:tt)*), + @accum($($accum:tt)*), + // This field is not pinned. + @is_pinned(), + @pinned_drop($($pinned_drop:ident)?), + ) => { + ::core::compile_error!(concat!( + "The field `", + stringify!($field), + "` of type `PhantomPinned` only has an effect, if it has the `#[pin]` attribute.", + )); + $crate::__pin_data!(find_pinned_fields: + @struct_attrs($($struct_attrs)*), + @vis($vis), + @name($name), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @fields_munch($($rest)*), + @pinned($($pinned)* $($accum)* $field: ::core::marker::PhantomPinned,), + @not_pinned($($not_pinned)*), + @fields($($fields)* $($accum)* $field: ::core::marker::PhantomPinned,), + @accum(), + @is_pinned(), + @pinned_drop($($pinned_drop)?), + ); + }; + (find_pinned_fields: + @struct_attrs($($struct_attrs:tt)*), + @vis($vis:vis), + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + // We reached the field declaration. + @fields_munch($field:ident : $type:ty, $($rest:tt)*), + @pinned($($pinned:tt)*), + @not_pinned($($not_pinned:tt)*), + @fields($($fields:tt)*), + @accum($($accum:tt)*), + // This field is pinned. + @is_pinned(yes), + @pinned_drop($($pinned_drop:ident)?), + ) => { + $crate::__pin_data!(find_pinned_fields: + @struct_attrs($($struct_attrs)*), + @vis($vis), + @name($name), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @fields_munch($($rest)*), + @pinned($($pinned)* $($accum)* $field: $type,), + @not_pinned($($not_pinned)*), + @fields($($fields)* $($accum)* $field: $type,), + @accum(), + @is_pinned(), + @pinned_drop($($pinned_drop)?), + ); + }; + (find_pinned_fields: + @struct_attrs($($struct_attrs:tt)*), + @vis($vis:vis), + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + // We reached the field declaration. + @fields_munch($field:ident : $type:ty, $($rest:tt)*), + @pinned($($pinned:tt)*), + @not_pinned($($not_pinned:tt)*), + @fields($($fields:tt)*), + @accum($($accum:tt)*), + // This field is not pinned. + @is_pinned(), + @pinned_drop($($pinned_drop:ident)?), + ) => { + $crate::__pin_data!(find_pinned_fields: + @struct_attrs($($struct_attrs)*), + @vis($vis), + @name($name), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @fields_munch($($rest)*), + @pinned($($pinned)*), + @not_pinned($($not_pinned)* $($accum)* $field: $type,), + @fields($($fields)* $($accum)* $field: $type,), + @accum(), + @is_pinned(), + @pinned_drop($($pinned_drop)?), + ); + }; + (find_pinned_fields: + @struct_attrs($($struct_attrs:tt)*), + @vis($vis:vis), + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + // We found the `#[pin]` attr. + @fields_munch(#[pin] $($rest:tt)*), + @pinned($($pinned:tt)*), + @not_pinned($($not_pinned:tt)*), + @fields($($fields:tt)*), + @accum($($accum:tt)*), + @is_pinned($($is_pinned:ident)?), + @pinned_drop($($pinned_drop:ident)?), + ) => { + $crate::__pin_data!(find_pinned_fields: + @struct_attrs($($struct_attrs)*), + @vis($vis), + @name($name), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @fields_munch($($rest)*), + // We do not include `#[pin]` in the list of attributes, since it is not actually an + // attribute that is defined somewhere. + @pinned($($pinned)*), + @not_pinned($($not_pinned)*), + @fields($($fields)*), + @accum($($accum)*), + // Set this to `yes`. + @is_pinned(yes), + @pinned_drop($($pinned_drop)?), + ); + }; + (find_pinned_fields: + @struct_attrs($($struct_attrs:tt)*), + @vis($vis:vis), + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + // We reached the field declaration with visibility, for simplicity we only munch the + // visibility and put it into `$accum`. + @fields_munch($fvis:vis $field:ident $($rest:tt)*), + @pinned($($pinned:tt)*), + @not_pinned($($not_pinned:tt)*), + @fields($($fields:tt)*), + @accum($($accum:tt)*), + @is_pinned($($is_pinned:ident)?), + @pinned_drop($($pinned_drop:ident)?), + ) => { + $crate::__pin_data!(find_pinned_fields: + @struct_attrs($($struct_attrs)*), + @vis($vis), + @name($name), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @fields_munch($field $($rest)*), + @pinned($($pinned)*), + @not_pinned($($not_pinned)*), + @fields($($fields)*), + @accum($($accum)* $fvis), + @is_pinned($($is_pinned)?), + @pinned_drop($($pinned_drop)?), + ); + }; + (find_pinned_fields: + @struct_attrs($($struct_attrs:tt)*), + @vis($vis:vis), + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + // Some other attribute, just put it into `$accum`. + @fields_munch(#[$($attr:tt)*] $($rest:tt)*), + @pinned($($pinned:tt)*), + @not_pinned($($not_pinned:tt)*), + @fields($($fields:tt)*), + @accum($($accum:tt)*), + @is_pinned($($is_pinned:ident)?), + @pinned_drop($($pinned_drop:ident)?), + ) => { + $crate::__pin_data!(find_pinned_fields: + @struct_attrs($($struct_attrs)*), + @vis($vis), + @name($name), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @fields_munch($($rest)*), + @pinned($($pinned)*), + @not_pinned($($not_pinned)*), + @fields($($fields)*), + @accum($($accum)* #[$($attr)*]), + @is_pinned($($is_pinned)?), + @pinned_drop($($pinned_drop)?), + ); + }; + (find_pinned_fields: + @struct_attrs($($struct_attrs:tt)*), + @vis($vis:vis), + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + // We reached the end of the fields, plus an optional additional comma, since we added one + // before and the user is also allowed to put a trailing comma. + @fields_munch($(,)?), + @pinned($($pinned:tt)*), + @not_pinned($($not_pinned:tt)*), + @fields($($fields:tt)*), + @accum(), + @is_pinned(), + @pinned_drop($($pinned_drop:ident)?), + ) => { + // Declare the struct with all fields in the correct order. + $($struct_attrs)* + $vis struct $name <$($impl_generics)*> + where $($whr)* + { + $($fields)* + } + + // We put the rest into this const item, because it then will not be accessible to anything + // outside. + const _: () = { + // We declare this struct which will host all of the projection function for our type. + // it will be invariant over all generic parameters which are inherited from the + // struct. + $vis struct __ThePinData<$($impl_generics)*> + where $($whr)* + { + __phantom: ::core::marker::PhantomData< + fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*> + >, + } + + // Make all projection functions. + $crate::__pin_data!(make_pin_data: + @pin_data(__ThePinData), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @pinned($($pinned)*), + @not_pinned($($not_pinned)*), + ); + + // SAFETY: We have added the correct projection functions above to `__ThePinData` and + // we also use the least restrictive generics possible. + unsafe impl<$($impl_generics)*> $crate::init::__PinData for $name<$($ty_generics)*> + where $($whr)* + { + type __PinData = __ThePinData<$($ty_generics)*>; + } + + // This struct will be used for the unpin analysis. Since only structurally pinned + // fields are relevant whether the struct should implement `Unpin`. + #[allow(dead_code)] + struct __Unpin <'__pin, $($impl_generics)*> + where $($whr)* + { + __phantom_pin: ::core::marker::PhantomData &'__pin ()>, + __phantom: ::core::marker::PhantomData< + fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*> + >, + // Only the pinned fields. + $($pinned)* + } + + #[doc(hidden)] + impl<'__pin, $($impl_generics)*> ::core::marker::Unpin for $name<$($ty_generics)*> + where + __Unpin<'__pin, $($ty_generics)*>: ::core::marker::Unpin, + $($whr)* + {} + + // We need to disallow normal `Drop` implementation, the exact behavior depends on + // whether `PinnedDrop` was specified as the parameter. + $crate::__pin_data!(drop_prevention: + @name($name), + @impl_generics($($impl_generics)*), + @ty_generics($($ty_generics)*), + @where($($whr)*), + @pinned_drop($($pinned_drop)?), + ); + }; + }; + // When no `PinnedDrop` was specified, then we have to prevent implementing drop. + (drop_prevention: + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + @pinned_drop(), + ) => { + // We prevent this by creating a trait that will be implemented for all types implementing + // `Drop`. Additionally we will implement this trait for the struct leading to a conflict, + // if it also implements `Drop` + trait MustNotImplDrop {} + #[allow(drop_bounds)] + impl MustNotImplDrop for T {} + impl<$($impl_generics)*> MustNotImplDrop for $name<$($ty_generics)*> + where $($whr)* {} + // We also take care to prevent users from writing a useless PinnedDrop implementation. + // They might implement PinnedDrop correctly for the struct, but forget to give + // `PinnedDrop` as the parameter to `#[pin_data]`. + #[allow(non_camel_case_types)] + trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {} + impl + UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {} + impl<$($impl_generics)*> + UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for $name<$($ty_generics)*> + where $($whr)* {} + }; + // When `PinnedDrop` was specified we just implement drop and delegate. + (drop_prevention: + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + @pinned_drop(PinnedDrop), + ) => { + impl<$($impl_generics)*> ::core::ops::Drop for $name<$($ty_generics)*> + where $($whr)* + { + fn drop(&mut self) { + // SAFETY: since this is a destructor, `self` will not move after this function + // terminates, since it is inaccessible. + let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) }; + // SAFETY: since this is a drop function, we can create this token to call the + // pinned destructor of this type. + let token = unsafe { $crate::init::OnlyCallFromDrop::create() }; + $crate::init::PinnedDrop::drop(pinned, token); + } + } + }; + // If some other parameter was specified, we emit a readable error. + (drop_prevention: + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + @pinned_drop($($rest:tt)*), + ) => { + compile_error!( + "Wrong parameters to `#[pin_data]`, expected nothing or `PinnedDrop`, got '{}'.", + stringify!($($rest)*), + ); + }; + (make_pin_data: + @pin_data($pin_data:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + @pinned($($(#[$($p_attr:tt)*])* $pvis:vis $p_field:ident : $p_type:ty),* $(,)?), + @not_pinned($($(#[$($attr:tt)*])* $fvis:vis $field:ident : $type:ty),* $(,)?), + ) => { + // For every field, we create a projection function according to its projection type. If a + // field is structurally pinned, then it must be initialized via `PinInit`, if it is not + // structurally pinned, then it can be initialized via `Init`. + // + // The functions are `unsafe` to prevent accidentally calling them. + #[allow(dead_code)] + impl<$($impl_generics)*> $pin_data<$($ty_generics)*> + where $($whr)* + { + $( + $pvis unsafe fn $p_field( + slot: *mut $p_type, + init: impl $crate::init::PinInit<$p_type, E>, + ) -> ::core::result::Result<(), E> { + unsafe { $crate::init::PinInit::__pinned_init(init, slot) } + } + )* + $( + $fvis unsafe fn $field( + slot: *mut $type, + init: impl $crate::init::Init<$type, E>, + ) -> ::core::result::Result<(), E> { + unsafe { $crate::init::Init::__init(init, slot) } + } + )* + } + }; +} diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 223564f9f0cc..3e2777d26ff5 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -16,7 +16,9 @@ #![feature(coerce_unsized)] #![feature(core_ffi_c)] #![feature(dispatch_from_dyn)] +#![feature(explicit_generic_args_with_impl_trait)] #![feature(generic_associated_types)] +#![feature(new_uninit)] #![feature(receiver_trait)] #![feature(unsize)] @@ -25,11 +27,16 @@ #[cfg(not(CONFIG_RUST))] compile_error!("Missing kernel configuration for conditional compilation"); +#[allow(unused_extern_crates)] +// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate). +extern crate self as kernel; + #[cfg(not(test))] #[cfg(not(testlib))] mod allocator; mod build_assert; pub mod error; +pub mod init; pub mod prelude; pub mod print; mod static_assert; diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index 0bc1c97e5604..fcdc511d2ce8 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -18,7 +18,7 @@ pub use core::pin::Pin; pub use alloc::{boxed::Box, vec::Vec}; #[doc(no_inline)] -pub use macros::{module, vtable}; +pub use macros::{module, pin_data, pinned_drop, vtable}; pub use super::build_assert; @@ -27,8 +27,12 @@ pub use super::build_assert; pub use super::dbg; pub use super::{pr_alert, pr_crit, pr_debug, pr_emerg, pr_err, pr_info, pr_notice, pr_warn}; +pub use super::{init, pin_init, try_init, try_pin_init}; + pub use super::static_assert; pub use super::error::{code::*, Error, Result}; pub use super::{str::CStr, ThisModule}; + +pub use super::init::{InPlaceInit, Init, PinInit}; diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index 16ec174637b2..5b4f64dd3ac8 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -17,7 +17,8 @@ use crate::{ bindings, - error::Result, + error::{Error, Result}, + init::{InPlaceInit, Init, PinInit}, types::{ForeignOwnable, Opaque}, }; use alloc::boxed::Box; @@ -163,6 +164,28 @@ impl Arc { // `Arc` object. Ok(unsafe { Self::from_inner(Box::leak(inner).into()) }) } + + /// Use the given initializer to in-place initialize a `T`. + /// + /// If `T: !Unpin` it will not be able to move afterwards. + #[inline] + pub fn pin_init(init: impl PinInit) -> Result + where + Error: From, + { + UniqueArc::pin_init(init).map(|u| u.into()) + } + + /// Use the given initializer to in-place initialize a `T`. + /// + /// This is equivalent to [`pin_init`], since an `Arc` is always pinned. + #[inline] + pub fn init(init: impl Init) -> Result + where + Error: From, + { + UniqueArc::init(init).map(|u| u.into()) + } } impl Arc { diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs index 9d0fdbc55843..ff2b2fac951d 100644 --- a/rust/kernel/types.rs +++ b/rust/kernel/types.rs @@ -238,6 +238,14 @@ impl Opaque { pub fn get(&self) -> *mut T { UnsafeCell::raw_get(self.0.as_ptr()) } + + /// Gets the value behind `this`. + /// + /// This function is useful to get access to the value without creating intermediate + /// references. + pub const fn raw_get(this: *const Self) -> *mut T { + UnsafeCell::raw_get(this.cast::>()) + } } /// A sum type that always holds either a value of type `L` or `R`. diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 82b520f024dd..5afd88cfe124 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -7,6 +7,8 @@ mod quote; mod concat_idents; mod helpers; mod module; +mod pin_data; +mod pinned_drop; mod vtable; use proc_macro::TokenStream; @@ -168,3 +170,79 @@ pub fn vtable(attr: TokenStream, ts: TokenStream) -> TokenStream { pub fn concat_idents(ts: TokenStream) -> TokenStream { concat_idents::concat_idents(ts) } + +/// Used to specify the pinning information of the fields of a struct. +/// +/// This is somewhat similar in purpose as +/// [pin-project-lite](https://crates.io/crates/pin-project-lite). +/// Place this macro on a struct definition and then `#[pin]` in front of the attributes of each +/// field you want to structurally pin. +/// +/// This macro enables the use of the [`pin_init!`] macro. When pinned-initializing a `struct`, +/// then `#[pin]` directs the type of intializer that is required. +/// +/// If your `struct` implements `Drop`, then you need to add `PinnedDrop` as arguments to this +/// macro, and change your `Drop` implementation to `PinnedDrop` annotated with +/// `#[`[`macro@pinned_drop`]`]`, since dropping pinned values requires extra care. +/// +/// # Examples +/// +/// ```rust,ignore +/// #[pin_data] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: Box<[u8; 1024 * 1024]>, +/// } +/// ``` +/// +/// ```rust,ignore +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: Box<[u8; 1024 * 1024]>, +/// raw_info: *mut Info, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for DriverData { +/// fn drop(self: Pin<&mut Self>) { +/// unsafe { bindings::destroy_info(self.raw_info) }; +/// } +/// } +/// ``` +/// +/// [`pin_init!`]: ../kernel/macro.pin_init.html +// ^ cannot use direct link, since `kernel` is not a dependency of `macros` +#[proc_macro_attribute] +pub fn pin_data(inner: TokenStream, item: TokenStream) -> TokenStream { + pin_data::pin_data(inner, item) +} + +/// Used to implement `PinnedDrop` safely. +/// +/// Only works on structs that are annotated via `#[`[`macro@pin_data`]`]`. +/// +/// # Examples +/// +/// ```rust,ignore +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: Box<[u8; 1024 * 1024]>, +/// raw_info: *mut Info, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for DriverData { +/// fn drop(self: Pin<&mut Self>) { +/// unsafe { bindings::destroy_info(self.raw_info) }; +/// } +/// } +/// ``` +#[proc_macro_attribute] +pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream { + pinned_drop::pinned_drop(args, input) +} diff --git a/rust/macros/pin_data.rs b/rust/macros/pin_data.rs new file mode 100644 index 000000000000..973053a0b539 --- /dev/null +++ b/rust/macros/pin_data.rs @@ -0,0 +1,79 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{Punct, Spacing, TokenStream, TokenTree}; + +pub(crate) fn pin_data(args: TokenStream, input: TokenStream) -> TokenStream { + // This proc-macro only does some pre-parsing and then delegates the actual parsing to + // `kernel::_pin_data!`. + // + // In here we only collect the generics, since parsing them in declarative macros is very + // elaborate. We also do not need to analyse their structure, we only need to collect them. + + // `impl_generics`, the declared generics with their bounds. + let mut impl_generics = vec![]; + // Only the names of the generics, without any bounds. + let mut ty_generics = vec![]; + // Tokens not related to the generics e.g. the `impl` token. + let mut rest = vec![]; + // The current level of `<`. + let mut nesting = 0; + let mut toks = input.into_iter(); + // if we are at the beginning of a generic parameter + let mut at_start = true; + for tt in &mut toks { + match tt.clone() { + TokenTree::Punct(p) if p.as_char() == '<' => { + if nesting >= 1 { + impl_generics.push(tt); + } + nesting += 1; + } + TokenTree::Punct(p) if p.as_char() == '>' => { + if nesting == 0 { + break; + } else { + nesting -= 1; + if nesting >= 1 { + impl_generics.push(tt); + } + if nesting == 0 { + break; + } + } + } + tt => { + if nesting == 1 { + match &tt { + TokenTree::Ident(i) if i.to_string() == "const" => {} + TokenTree::Ident(_) if at_start => { + ty_generics.push(tt.clone()); + ty_generics.push(TokenTree::Punct(Punct::new(',', Spacing::Alone))); + at_start = false; + } + TokenTree::Punct(p) if p.as_char() == ',' => at_start = true, + TokenTree::Punct(p) if p.as_char() == '\'' && at_start => { + ty_generics.push(tt.clone()); + } + _ => {} + } + } + if nesting >= 1 { + impl_generics.push(tt); + } else if nesting == 0 { + rest.push(tt); + } + } + } + } + rest.extend(toks); + // This should be the body of the struct `{...}`. + let last = rest.pop(); + quote!(::kernel::__pin_data! { + parse_input: + @args(#args), + @sig(#(#rest)*), + @impl_generics(#(#impl_generics)*), + @ty_generics(#(#ty_generics)*), + @body(#last), + }) +} diff --git a/rust/macros/pinned_drop.rs b/rust/macros/pinned_drop.rs new file mode 100644 index 000000000000..88fb72b20660 --- /dev/null +++ b/rust/macros/pinned_drop.rs @@ -0,0 +1,49 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{TokenStream, TokenTree}; + +pub(crate) fn pinned_drop(_args: TokenStream, input: TokenStream) -> TokenStream { + let mut toks = input.into_iter().collect::>(); + assert!(!toks.is_empty()); + // Ensure that we have an `impl` item. + assert!(matches!(&toks[0], TokenTree::Ident(i) if i.to_string() == "impl")); + // Ensure that we are implementing `PinnedDrop`. + let mut nesting: usize = 0; + let mut pinned_drop_idx = None; + for (i, tt) in toks.iter().enumerate() { + match tt { + TokenTree::Punct(p) if p.as_char() == '<' => { + nesting += 1; + } + TokenTree::Punct(p) if p.as_char() == '>' => { + nesting = nesting.checked_sub(1).unwrap(); + continue; + } + _ => {} + } + if i >= 1 && nesting == 0 { + // Found the end of the generics, this should be `PinnedDrop`. + assert!( + matches!(tt, TokenTree::Ident(i) if i.to_string() == "PinnedDrop"), + "expected 'PinnedDrop', found: '{:?}'", + tt + ); + pinned_drop_idx = Some(i); + break; + } + } + let idx = pinned_drop_idx + .unwrap_or_else(|| panic!("Expected an `impl` block implementing `PinnedDrop`.")); + // Fully qualify the `PinnedDrop`, as to avoid any tampering. + toks.splice(idx..idx, quote!(::kernel::init::)); + // Take the `{}` body and call the declarative macro. + if let Some(TokenTree::Group(last)) = toks.pop() { + let last = last.stream(); + quote!(::kernel::__pinned_drop! { + @impl_sig(#(#toks)*), + @impl_body(#last), + }) + } else { + TokenStream::from_iter(toks) + } +} diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 76323201232a..f9bdc01c8191 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -277,7 +277,7 @@ $(obj)/%.lst: $(src)/%.c FORCE # Compile Rust sources (.rs) # --------------------------------------------------------------------------- -rust_allowed_features := core_ffi_c +rust_allowed_features := core_ffi_c,explicit_generic_args_with_impl_trait rust_common_cmd = \ RUST_MODFILE=$(modfile) $(RUSTC_OR_CLIPPY) $(rust_flags) \ From patchwork Tue Mar 21 19:50:05 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: y86-dev X-Patchwork-Id: 73037 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:604a:0:0:0:0:0 with SMTP id j10csp1986173wrt; Tue, 21 Mar 2023 13:11:08 -0700 (PDT) X-Google-Smtp-Source: AK7set+4/FqmkF9KDtuIYQYI0NaDLgogn3fnTUAcpoL6AEIx6v76+wpFaPkgdY8OFYYZ+NdwK8by X-Received: by 2002:a17:903:1111:b0:1a1:db10:7ba5 with SMTP id n17-20020a170903111100b001a1db107ba5mr249321plh.41.1679429467900; Tue, 21 Mar 2023 13:11:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1679429467; cv=none; d=google.com; s=arc-20160816; b=IYrF690J8mLouoisT6t2JLZ51XUrUwfLzreMtEUqzQuBg56S66FvwPPMUqMSRqzNpC miT32EW6pU5O9bAYoqNAZ/XUZoyuDoGSu3vC7BCAFyzDPa+8KEeiPGB3TW9hoiUPm7Su w3hCOBxdpVI279lzPYFlz7GZigNDItjM5P8DVgpUccJ6jYsEkhy4BNyLhmj7caTK6eWh q4aN4a7r++mvNWb5d9aDhbvPx05o5teJ+3hDF+DHMqFh1RGmR/dq1MsHfGWiMqcPBTSJ wgKWmRlw5aG+QxmGR6RymYrq5JjCIORvv+m9bGjbSriDRDvkmsXFbEJVA/HkGpcOkm8Y sEPQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :feedback-id:references:in-reply-to:message-id:subject:cc:from:to :dkim-signature:date; bh=+p+odlGt4Lpa7j8EN6KwSae2Ae/jbNLZRSBVIgNchK8=; b=QS0jikBglFWd72idOgJO98k+4gIriaxiuPYkfx7hXL9cGHZ3FofsX2Ra0c4MPm40T6 faRtz7ouZBA8zRJZ/LmVEeQEWNZdPjQRn6TESKCtLWnkncY4aFAaW3Y330tIZctiT8o5 Pd5Bprwv06Tx1SZrxd4xGdapeD0ISBrzYpKYiOYs5zEJTPuGe8hQzGYauZhuLA6ln9co upE21diD4J8h9jesnpE0b5peDbBCOgwBKVRdaxDFD7BbArADTFX1XDHT7ajWXyR84PAn YNdDltYMwuXheLnungcpzU3BI1lPuUlRgpSEJG+oI2iEfkQIoCM4xmOzSED0Amvljzio J1ng== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b="ZWimU1u/"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id q13-20020a17090311cd00b001a0433208easi15249972plh.410.2023.03.21.13.10.53; Tue, 21 Mar 2023 13:11:07 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b="ZWimU1u/"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229839AbjCUTvT (ORCPT + 99 others); Tue, 21 Mar 2023 15:51:19 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50030 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229923AbjCUTvQ (ORCPT ); Tue, 21 Mar 2023 15:51:16 -0400 Received: from mail-4316.protonmail.ch (mail-4316.protonmail.ch [185.70.43.16]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7047858492; Tue, 21 Mar 2023 12:50:35 -0700 (PDT) Date: Tue, 21 Mar 2023 19:50:05 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail3; t=1679428225; x=1679687425; bh=+p+odlGt4Lpa7j8EN6KwSae2Ae/jbNLZRSBVIgNchK8=; h=Date:To:From:Cc:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=ZWimU1u/tRce1Mxz5ecaVPMKqjL4yJUpOxb+ZGSdYyUVD6VkjzFJQjhS+kawVYSzv nw/t3h0YWanoOp6hEZtOc3V//NDlXM1wzgW7elSg4u5fPmUHykFyYvr3Byg/nRRvcw wNXK4RhrTKqBsj6MdgJyNjSiDZ0U92FOKPKmlCC/ks8rwhYJajqoFk4qV+cEUZ05AP B8rTj9FUHq/OXcnoQX8okfDxICJYkJWfB4Wp0v5A9F6Oun6HBMkGxWHfcrPD0kqSIm nQGqAti6lV6lsT++J9p5+yGi6Gs/ltT4YJMaYNFdyIyFeS8b+/6WDgWo4KU39uB7vg a8pZlbHLUerdg== To: Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= From: Benno Lossin Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, patches@lists.linux.dev Subject: [PATCH v2 4/5] rust: init: add common init-helper functions for `Opaque` Message-ID: <20230321194934.908891-5-y86-dev@protonmail.com> In-Reply-To: <20230321194934.908891-1-y86-dev@protonmail.com> References: <20230321194934.908891-1-y86-dev@protonmail.com> Feedback-ID: 40624463:user:proton MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_MSPIKE_H2, SPF_HELO_PASS,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1761009327383247398?= X-GMAIL-MSGID: =?utf-8?q?1761009433983179834?= Add helper functions to more easily initialize `Opaque` via FFI. These functions take a function pointer to the FFI-initialization function and take between 0-4 other arguments. It then returns an initializer that uses the FFI function along with the given arguments to initialize an `Opaque`. Signed-off-by: Benno Lossin --- rust/kernel/init.rs | 1 + rust/kernel/init/common.rs | 42 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 rust/kernel/init/common.rs -- 2.39.2 diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs index 895845db6f2b..5b8adb8727b2 100644 --- a/rust/kernel/init.rs +++ b/rust/kernel/init.rs @@ -207,6 +207,7 @@ use core::{ ptr, }; +pub mod common; #[doc(hidden)] pub mod macros; diff --git a/rust/kernel/init/common.rs b/rust/kernel/init/common.rs new file mode 100644 index 000000000000..f8c6e9dff786 --- /dev/null +++ b/rust/kernel/init/common.rs @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +//! Module containing common kernel initializer functions. + +use crate::{ + init::{self, PinInit}, + types::Opaque, +}; + +macro_rules! create_func { + ($name:ident $(, $arg_name:ident: $arg_typ:ident)*) => { + /// Create an initializer using the given initializer function from C. + /// + /// # Safety + /// + /// The given function **must** under all circumstances initialize the memory location to a + /// valid `T`. If it fails to do so it results in UB. + /// + /// If any parameters are given, those need to be valid for the function. Valid means that + /// calling the function with those parameters complies with the above requirement **and** + /// every other requirement on the function itself. + pub unsafe fn $name( + init_func: unsafe extern "C" fn(*mut T $(, $arg_name: $arg_typ)*), + $($arg_name: $arg_typ,)* + ) -> impl PinInit> { + // SAFETY: The safety contract of this function ensures that `init_func` fully + // initializes `slot`. + unsafe { + init::pin_init_from_closure(move |slot| { + init_func(Opaque::raw_get(slot) $(, $arg_name)*); + Ok(()) + }) + } + } + } +} + +create_func!(ffi_init); +create_func!(ffi_init1, arg1: A1); +create_func!(ffi_init2, arg1: A1, arg2: A2); +create_func!(ffi_init3, arg1: A1, arg2: A2, arg3: A3); +create_func!(ffi_init4, arg1: A1, arg2: A2, arg3: A3, arg4: A4); From patchwork Tue Mar 21 19:50:10 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: y86-dev X-Patchwork-Id: 73033 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:604a:0:0:0:0:0 with SMTP id j10csp1978934wrt; Tue, 21 Mar 2023 12:55:39 -0700 (PDT) X-Google-Smtp-Source: AK7set9PXIUmWaDJGKhc9PvQxOmNtY0SBQyZwhPiXV+fOdJ56DcWfB22F4S7KP6Lx0vTM0Jg+YHB X-Received: by 2002:a17:902:ec92:b0:1a1:c2cb:f44e with SMTP id x18-20020a170902ec9200b001a1c2cbf44emr238278plg.53.1679428539476; Tue, 21 Mar 2023 12:55:39 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1679428539; cv=none; d=google.com; s=arc-20160816; b=CSB0d2l8sZjR++oLNiaq4yoJRHVRbybywR1cYfDgp78GSYecklsLq72F79C6OrIYiX 88lJjUgPWVdfmKAu0VkS0uM8ZE4WCEw+bIeFqNfBqB+nctG7UaWzyah845suajaTnPaM BFbN5f8ZgnQ9MhgFqPMS2pUyWprJV2wjlwgrxD0rZh1xKUJSkVhTI/NZaHxTBvgIKv+F 3vKAtlNeGNiOb7u/mjPZXPHy+nmuyKFg/1ysECfo/84q6032LP/t1zY086ghgDDJXx0O qb9Lx4i6fm8hbVbq8JOeo3beDKm5fk2K3Drf2Q8pR7oUdVnduNicCoWpZoHZOmAd1/MV 03OA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :feedback-id:references:in-reply-to:message-id:subject:cc:from:to :dkim-signature:date; bh=FNlCN3cHsJdz3JxxhBIbrUQMYy+/cKZuDeBnqnufKaQ=; b=k+epqmyh4M/1QtW7OhKT+wBk36GhopJZQflkHq00nDvic68UmVMoL8zhBOA+7wQ1nF 7WhQK6oDOYsaxNIa8ih4chVIL4pKE/xlBvtJwAt5JffWOL4J+sTDiCt1Vv1oXzQ6rQ4T T9+9cA33jsrQ1DX8/pG438VdL8b0UVqRFklkbs28cyPdQZGJRC0KhS+ruBrHsrR/in09 RFOv5EGs9hZm6t3SH9AxCRiCZta6neqrNdmv2iSK6kvzYTluaxKQ+1YOk7Ecb+wNREC5 kgv5iDMdKP1e3L54wiu8tJcWd1BGI4ytB1sdoGBUSQN7CDEKRmmyPuJIXZmdYti6HkYR QiQA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=Og5rTLKV; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id bj11-20020a170902850b00b0019ad832a6f1si13850395plb.168.2023.03.21.12.55.26; Tue, 21 Mar 2023 12:55:39 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@protonmail.com header.s=protonmail3 header.b=Og5rTLKV; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=protonmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229841AbjCUTut (ORCPT + 99 others); Tue, 21 Mar 2023 15:50:49 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49382 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229459AbjCUTur (ORCPT ); Tue, 21 Mar 2023 15:50:47 -0400 Received: from mail-4322.protonmail.ch (mail-4322.protonmail.ch [185.70.43.22]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3FDA04BE8E for ; Tue, 21 Mar 2023 12:50:24 -0700 (PDT) Date: Tue, 21 Mar 2023 19:50:10 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail3; t=1679428219; x=1679687419; bh=FNlCN3cHsJdz3JxxhBIbrUQMYy+/cKZuDeBnqnufKaQ=; h=Date:To:From:Cc:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=Og5rTLKVLPegceIya3psm7F/BerxmDfAFFqiPBwcw8oflNcadzZX9R6uU+QWVPW8O Y9m/o1sNRQzKtYQ6BXCErgut/8YWPXIndUd81bUaiMiklBCVvQ2PvNaOBjAlKDrAFQ RCu1WHJOJPIObRLRMaXKupJNP7Ia66UcCPfunnI3m4HAn5nR3oemQbU+oFkqewylpG Znv3UBP+tMUEanZndB8AqeG3RzPo2Am0W1cNvcKQTAAk2L/8v0vqid3Um/wWSfMI1z 3JoGgXoh/xEGgijXgNapaKTnIsq+P4ePMmTSN80lBVUADn/RYJ2V2k0Pb+5CtK1nlr Y2VRfX8RZylag== To: Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= From: Benno Lossin Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, patches@lists.linux.dev Subject: [PATCH v2 5/5] rust: sync: reduce stack usage of `UniqueArc::try_new_uninit` Message-ID: <20230321194934.908891-6-y86-dev@protonmail.com> In-Reply-To: <20230321194934.908891-1-y86-dev@protonmail.com> References: <20230321194934.908891-1-y86-dev@protonmail.com> Feedback-ID: 40624463:user:proton MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_MSPIKE_H2, SPF_HELO_PASS,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1761008460143491736?= X-GMAIL-MSGID: =?utf-8?q?1761008460143491736?= `UniqueArc::try_new_uninit` calls `Arc::try_new(MaybeUninit::uninit())`. This results in the uninitialized memory being placed on the stack, which may be arbitrarily large due to the generic `T` and thus could cause a stack overflow for large types. Change the implementation to use the pin-init API which enables in-place initialization. In particular it avoids having to first construct and then move the uninitialized memory from the stack into the final location. Signed-off-by: Benno Lossin --- rust/kernel/lib.rs | 1 - rust/kernel/sync/arc.rs | 12 +++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) -- 2.39.2 diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 3e2777d26ff5..d9df77132fa2 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -27,7 +27,6 @@ #[cfg(not(CONFIG_RUST))] compile_error!("Missing kernel configuration for conditional compilation"); -#[allow(unused_extern_crates)] // Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate). extern crate self as kernel; diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index 5b4f64dd3ac8..0518ff99b6c5 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -18,6 +18,7 @@ use crate::{ bindings, error::{Error, Result}, + init, init::{InPlaceInit, Init, PinInit}, types::{ForeignOwnable, Opaque}, }; @@ -29,6 +30,7 @@ use core::{ pin::Pin, ptr::NonNull, }; +use macros::pin_data; /// A reference-counted pointer to an instance of `T`. /// @@ -121,6 +123,7 @@ pub struct Arc { _p: PhantomData>, } +#[pin_data] #[repr(C)] struct ArcInner { refcount: Opaque, @@ -501,9 +504,16 @@ impl UniqueArc { /// Tries to allocate a new [`UniqueArc`] instance whose contents are not initialised yet. pub fn try_new_uninit() -> Result>> { + // INVARIANT: The refcount is initialised to a non-zero value. + let inner = Box::init(init!(ArcInner::> { + // SAFETY: There are no safety requirements for this FFI call. + refcount: Opaque::new(unsafe { bindings::REFCOUNT_INIT(1) }), + data <- init::uninit(), + }))?; Ok(UniqueArc::> { // INVARIANT: The newly-created object has a ref-count of 1. - inner: Arc::try_new(MaybeUninit::uninit())?, + // SAFETY: The pointer from the `Box` is valid. + inner: unsafe { Arc::from_inner(Box::leak(inner).into()) }, }) } }