From patchwork Thu Oct 12 13:21:46 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Benno Lossin X-Patchwork-Id: 152012 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:612c:2908:b0:403:3b70:6f57 with SMTP id ib8csp1226254vqb; Thu, 12 Oct 2023 06:22:27 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFy7EKTZ5p8EOVr6Sl4tyoNFjK14QKBmHgQ4taYlf+bWGwhp1Gc4r7DZ9npYnqik1qpB0Vb X-Received: by 2002:a05:6870:ea9e:b0:1e1:e6ee:93f2 with SMTP id s30-20020a056870ea9e00b001e1e6ee93f2mr26888874oap.5.1697116947609; Thu, 12 Oct 2023 06:22:27 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1697116947; cv=none; d=google.com; s=arc-20160816; b=jH/gDzLE7Zn+gOkxMTJmHIyi26WffdrZNtpjjBtoNK1UoEk1oE796VU2FqjiPCPFcK WYUe6r9mxJO7rYeH/V6afUPQMODEx8J5GU6CGBOuZX0k3NTO6DQJ1W/kTDqmqIaj4EVr MW3VrudEbVQZ4d7M8+U3sqaAe3cTSQLtWNa0GP+MgO4Y4346oRPl6+fGJxKbR43rGNO8 PAwH6Dvhr4Ph/hd+PRNoRQqlQbxSZgGV07wYYc1udZHQdFHp+CIqUgyWr8KFeL+y7G4j JF30f2VBGfIf/JGit+m5LMaC4sArD5C4gTVhkooRuUvb02tIRho84vz0IVLEPJ3ORUOy OIBw== 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:message-id:subject:cc:from:to:date:dkim-signature; bh=a9Ak0X7bSTujHRssN+a+Hftra+UlXwNVYvmyqQQCilw=; fh=V11RwCzO6FhrwwR400IeaCztZOiMPvinK8BR27/cP4s=; b=v0TFdd9HE3bQF29KZJ+yT2IaNMV7XubO9A5kWclndpdJf1Mufh1XOvzHLdYFBsOGfa zG4pMglK56FZljgUlAVWsh+9rJxwS2xv/t3ZGJhl1lvZcQTshAec4JClqbXbpMsj8niy e79KKBXW3o+c1Q9gtLaoxiqu3ilIGDvboNvku1eE23vOHJAZt/njfaI3oGJFl3hjvsJy M2ZkYHLnnSz6znJxA7pFAjA0KgGS8QOqANBfYfXOd7QLI73CbD3caVFIL6UnuWehXkBC oDhXJWKcLN/ITOfXPbfk4ojVVuBpxEUGKkVGX62TrcjLZifNkkiXNp7a0TpK8zmn8q5S d8Ug== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@proton.me header.s=protonmail header.b=CakwaJnK; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:3 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=proton.me Received: from lipwig.vger.email (lipwig.vger.email. [2620:137:e000::3:3]) by mx.google.com with ESMTPS id e7-20020a62ee07000000b0068fa57d2442si13521126pfi.130.2023.10.12.06.22.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 Oct 2023 06:22:27 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:3 as permitted sender) client-ip=2620:137:e000::3:3; Authentication-Results: mx.google.com; dkim=pass header.i=@proton.me header.s=protonmail header.b=CakwaJnK; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:3 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=proton.me Received: from out1.vger.email (depot.vger.email [IPv6:2620:137:e000::3:0]) by lipwig.vger.email (Postfix) with ESMTP id 3B7BF8255481; Thu, 12 Oct 2023 06:22:25 -0700 (PDT) X-Virus-Status: Clean X-Virus-Scanned: clamav-milter 0.103.10 at lipwig.vger.email Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1347209AbjJLNWE (ORCPT + 19 others); Thu, 12 Oct 2023 09:22:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42490 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1343733AbjJLNWC (ORCPT ); Thu, 12 Oct 2023 09:22:02 -0400 Received: from mail-4316.protonmail.ch (mail-4316.protonmail.ch [185.70.43.16]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 79B4594; Thu, 12 Oct 2023 06:21:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=proton.me; s=protonmail; t=1697116916; x=1697376116; bh=a9Ak0X7bSTujHRssN+a+Hftra+UlXwNVYvmyqQQCilw=; h=Date:To:From:Cc:Subject:Message-ID:Feedback-ID:From:To:Cc:Date: Subject:Reply-To:Feedback-ID:Message-ID:BIMI-Selector; b=CakwaJnKAjcxT7b1G6jSKT+/BpZ3n4TnAJBO+wUhocU6wDlKI0nP6WhL3GDpYIuVE 3k+/Yb3acb18mnH+POGqFjYWjep/842QnWQkdVKtVjlEIvZNx6QofnjHqFN9j6Be96 DR9+/HiPdmnid2Fx0HaIcmtRo69k3Yft/IhUMoKmtFjrfi2t3jv+BuuVYL7e5T2YrQ QzgYq9iQfC+Yj69RHyPe0jMoPIMcR+Et7ovrd4/H+i53LxRniPGghs2zgQyyBGdRaI XtxPXUwaLpCc4pxaSGm+6QWomk58RgZKY+Te7tgXc8Sqs5ZQYbeqEkamajMZ/9F+8u qJ19tjsuo75bA== Date: Thu, 12 Oct 2023 13:21:46 +0000 To: Miguel Ojeda , Wedson Almeida Filho , Alex Gaynor From: Benno Lossin Cc: Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , Benno Lossin , Alice Ryhl , Andreas Hindborg , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH] rust: macros: improve `#[vtable]` documentation Message-ID: <20231012132131.300014-1-benno.lossin@proton.me> Feedback-ID: 71780778:user:proton MIME-Version: 1.0 X-Spam-Status: No, score=-0.8 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lipwig.vger.email Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.6.4 (lipwig.vger.email [0.0.0.0]); Thu, 12 Oct 2023 06:22:25 -0700 (PDT) X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1779556100450297296 X-GMAIL-MSGID: 1779556100450297296 Traits marked with `#[vtable]` need to provide default implementations for optional functions. The C side represents these with `NULL` in the vtable, so the default functions are never actually called. We do not want to replicate the default behavior from C in Rust, because that is not maintainable. Therefore we should use `build_error` in those default implementations. The error message for that is provided at `kernel::error::VTABLE_DEFAULT_ERROR`. Signed-off-by: Benno Lossin Reviewed-by: Alice Ryhl Reviewed-By: Wedson Almeida Filho --- rust/kernel/error.rs | 4 ++++ rust/macros/lib.rs | 32 ++++++++++++++++++++++++-------- 2 files changed, 28 insertions(+), 8 deletions(-) base-commit: b2516f7af9d238ebc391bdbdae01ac9528f1109e diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 05fcab6abfe6..1373cde025ef 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -335,3 +335,7 @@ pub(crate) fn from_result(f: F) -> T Err(e) => T::from(e.to_errno() as i16), } } + +/// Error message for calling a default function of a [`#[vtable]`](macros::vtable) trait. +pub const VTABLE_DEFAULT_ERROR: &str = + "This function must not be called, see the #[vtable] documentation."; diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index c42105c2ff96..dab9a1080b82 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -87,27 +87,41 @@ pub fn module(ts: TokenStream) -> TokenStream { /// implementation could just return `Error::EINVAL`); Linux typically use C /// `NULL` pointers to represent these functions. /// -/// This attribute is intended to close the gap. Traits can be declared and -/// implemented with the `#[vtable]` attribute, and a `HAS_*` associated constant -/// will be generated for each method in the trait, indicating if the implementor -/// has overridden a method. +/// This attribute closes that gap. A trait can be annotated with the `#[vtable]` attribute. +/// Implementers of the trait will then also have to annotate the trait with `#[vtable]`. This +/// attribute generates a `HAS_*` associated constant bool for each method in the trait that is set +/// to true if the implementer has overridden the associated method. +/// +/// If you want to make a function optional, you must provide a default implementation. But this +/// default implementation will never be executed, since these functions are exclusively called +/// from callbacks from the C side. This is because the vtable will have a `NULL` entry and the C +/// side will execute the default behavior. Since it is not maintainable to replicate the default +/// behavior in Rust, you should use the following code: +/// +/// ```compile_fail +/// # use kernel::error::VTABLE_DEFAULT_ERROR; +/// kernel::build_error(VTABLE_DEFAULT_ERROR) +/// ``` +/// +/// note that you might need to import [`kernel::error::VTABLE_DEFAULT_ERROR`]. /// -/// This attribute is not needed if all methods are required. +/// This macro should not be used when all function are required. /// /// # Examples /// /// ```ignore +/// # use kernel::error::VTABLE_DEFAULT_ERROR; /// use kernel::prelude::*; /// /// // Declares a `#[vtable]` trait /// #[vtable] -/// pub trait Operations: Send + Sync + Sized { +/// pub trait Operations { /// fn foo(&self) -> Result<()> { -/// Err(EINVAL) +/// kernel::build_error(VTABLE_DEFAULT_ERROR) /// } /// /// fn bar(&self) -> Result<()> { -/// Err(EINVAL) +/// kernel::build_error(VTABLE_DEFAULT_ERROR) /// } /// } /// @@ -125,6 +139,8 @@ pub fn module(ts: TokenStream) -> TokenStream { /// assert_eq!(::HAS_FOO, true); /// assert_eq!(::HAS_BAR, false); /// ``` +/// +/// [`kernel::error::VTABLE_DEFAULT_ERROR`]: ../kernel/error/constant.VTABLE_DEFAULT_ERROR.html #[proc_macro_attribute] pub fn vtable(attr: TokenStream, ts: TokenStream) -> TokenStream { vtable::vtable(attr, ts)