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;
Date:   Wed, 29 Mar 2023 21:42:39 +0100
From:   Gary Guo <gary@garyguo.net>
To:     Asahi Lina <lina@asahilina.net>, asahi@lists.linux.dev
Cc:     Miguel Ojeda <ojeda@kernel.org>,
        Alex Gaynor <alex.gaynor@gmail.com>,
        Wedson Almeida Filho <wedsonaf@gmail.com>,
        Boqun Feng <boqun.feng@gmail.com>,
        =?UTF-8?B?QmrDtnJu?= Roy Baron <bjorn3_gh@protonmail.com>,
        Sven Van Asbroeck <thesven73@gmail.com>,
        Fox Chen <foxhlchen@gmail.com>,
        Martin Rodriguez Reboredo <yakoyoku@gmail.com>,
        Andreas Hindborg <a.hindborg@samsung.com>,
        rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 5/6] rust: error: Add a helper to convert a C ERR_PTR
 to a `Result`
Message-ID: <20230329214239.6a19825a.gary@garyguo.net>
In-Reply-To: <20230224-rust-error-v2-5-3900319812da@asahilina.net>
References: <20230224-rust-error-v2-0-3900319812da@asahilina.net>
        <20230224-rust-error-v2-5-3900319812da@asahilina.net>
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?9rktulCcuXSC6EP1Zat3NQPmEyshTRG0tTRDr2QA0SW87DOF9JlTA70c9g2q?=
 =?us-ascii?Q?u54zDp24KSwybTPsAmTe6nyO5I0Dn0KQhEWl7P1G8zL7Nnd7OC76TDH2JPxx?=
 =?us-ascii?Q?LLZTCxMsAJlJzIopb93OqvTFjfFQc3iVcqVh4UuAK3wWJnXApka8AnUuNKv6?=
 =?us-ascii?Q?jJWA5ywhmNiL26aJ21y8FHn/KuFx2OtwxkCvQlORa3c43VRcgLSVW9ic11GE?=
 =?us-ascii?Q?TKPuoFjQrgayX5mQsluowXQEv5qvjjGVvblznDANi8gSdLTe9sLH4dVK0FmI?=
 =?us-ascii?Q?RkNZfUa2IohqZfHX7ygQihdzwGeHeWgdziNjvYF4Yhz5feyn1JZme9VW8U3q?=
 =?us-ascii?Q?BzDYCgdOZy6t+sBN+xVdbMOiqGNdNltVcYvN9vdLcR++/OZQpu9FR54z88DB?=
 =?us-ascii?Q?nKK9QZN69/tXpjwJJGZJpC5t5HblYQR7zCNYDj1/9NmQn8YMlH9rFfIBJs6t?=
 =?us-ascii?Q?5DtYreCU7hkFc3yd9OThHbDuNbk0FIcfCuwY27BOYp3DHrNJBlE8RB95kz2K?=
 =?us-ascii?Q?wE+GJzqQfRUexYux5tl/Hhte5wEsIsYQC7kMIejmuvCLfUca4Ph1zAAExOzF?=
 =?us-ascii?Q?E3UR++03G1en3HRXC0AiAbqD5iRXiQc+pcrWXDJK0cnFugwickgOvHbsVRQD?=
 =?us-ascii?Q?1K6am8/iVs1hn4K/5V0mJ/atwx7ggjeYxz8cjCsngcqAl41fJCazopAr4qe+?=
 =?us-ascii?Q?F4R+VKyMwari/cnKZe4zjkoU0M/Pgiv757XD7OdzHhAlIS249w8lzwAEY92y?=
 =?us-ascii?Q?U42yOgD8WRHud3O4l46vqGHft8U3DWLQBNlcjaWA6TLol5pA1xzxCfzroXeO?=
 =?us-ascii?Q?FF5QSAI+jwAKhcneQraElmZdQmGVWqaz+ZioXkwGUfE1wBzhaf8HQgKUhtYQ?=
 =?us-ascii?Q?G1Fu9+9zAmsUPf4e9KcFWPViUikQEimLeaFe7+J8SHlWdwXjMB0pHgs1JM7f?=
 =?us-ascii?Q?oD31qWngGyGI5SofkA2FuRQQzuSXTtJzNbCrfCh7muCQ0DrRn9FePVLtb7CH?=
 =?us-ascii?Q?mzSuhkLRa/Ydp+pQ6UH3rMnyMhNcftnyHGwgt9qCd1qKB1+WR7FZfKVdiNpE?=
 =?us-ascii?Q?an+XjwHpskOnP9+pwyeCQRlV4j6YX0kt0zyHYJVuomksFyRQIbwGu0Au4/AA?=
 =?us-ascii?Q?U2U7fJQsdkFVvbN9Ddw1izXrSggGOswBdE+PDMZs6O2o8U5F28ZaoLe+XYnp?=
 =?us-ascii?Q?UUnDvT0myPvijTxjvJOUFdEXOt9VOqwo2UCiu9YyQtkGjTAP8bqHhz5RVHh9?=
 =?us-ascii?Q?Xgi1TnLgM24CzurObS82Mw1qqfei5Npk5KKRTxVgeLLOO0UUHqeR9A4khNbW?=
 =?us-ascii?Q?GFUWMmCdORrDnuRqF4igkmj0bcRWuRv3vCHqLgC2P4Hza77uqtetp+zvbpL+?=
 =?us-ascii?Q?V8gEVfkWNzV0PdWXNvJNhDzWct5HegcEtgZ9nlDWHBnouCgkYP5LU9vQuTLj?=
 =?us-ascii?Q?dG6b0uT7AHh+vtPYmlLwojpsrcEo70JfwJms+HvkF1hWGKgtQ6nhAjg7Wuov?=
 =?us-ascii?Q?5Mek0Nbe9RsxtAOeZ1RCjMQaBQRd2LCCKwDTTZjCvt9K/qnrQiSRJ4SJ/7Vd?=
 =?us-ascii?Q?M3cQOQCzkYkcLJFLom3gSdO6vAliMTK2QPge/ryX?=
X-OriginatorOrg: garyguo.net
X-MS-Exchange-CrossTenant-Network-Message-Id: 67670cb9-e25d-43b8-15db-08db309623fd
X-MS-Exchange-CrossTenant-AuthSource: LO2P265MB5183.GBRP265.PROD.OUTLOOK.COM
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 29 Mar 2023 20:42:41.1485
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: bbc898ad-b10f-4e10-8552-d9377b823d45
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: Mv5xk3BsVyQpeeJ1FS033NM6m72o3TIW14vsxhKR1pnsld92XoNnspEIiOq+2K2ZqVfHH2Y5SVopGqruzEE3Nw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CWLP265MB7163
X-Spam-Status: No, score=-0.2 required=5.0 tests=DKIM_SIGNED,DKIM_VALID,
        DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,
        SPF_HELO_PASS,SPF_PASS 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: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Wed, 29 Mar 2023 21:04:37 +0900
Asahi Lina <lina@asahilina.net> wrote:

> From: Sven Van Asbroeck <thesven73@gmail.com>
> 
> Some kernel C API functions return a pointer which embeds an optional
> `errno`. Callers are supposed to check the returned pointer with
> `IS_ERR()` and if this returns `true`, retrieve the `errno` using
> `PTR_ERR()`.
> 
> Create a Rust helper function to implement the Rust equivalent:
> transform a `*mut T` to `Result<*mut T>`.
> 
> Lina: Imported from rust-for-linux/linux, with subsequent refactoring
> and contributions squashed in and attributed below. Replaced usage of
> from_kernel_errno_unchecked() with an open-coded constructor, since this
> is the only user anyway. Renamed the function to from_err_ptr().
> 
> Co-developed-by: Boqun Feng <boqun.feng@gmail.com>
> Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
> Co-developed-by: Miguel Ojeda <ojeda@kernel.org>
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> Co-developed-by: Fox Chen <foxhlchen@gmail.com>
> Signed-off-by: Fox Chen <foxhlchen@gmail.com>
> Co-developed-by: Gary Guo <gary@garyguo.net>
> Signed-off-by: Gary Guo <gary@garyguo.net>
> Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com>
> Signed-off-by: Asahi Lina <lina@asahilina.net>
> ---
>  rust/helpers.c       | 12 ++++++++++++
>  rust/kernel/error.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 61 insertions(+)
> 
> diff --git a/rust/helpers.c b/rust/helpers.c
> index 89f4cd1e0df3..04b9be46e887 100644
> --- a/rust/helpers.c
> +++ b/rust/helpers.c
> @@ -53,6 +53,18 @@ __force void *rust_helper_ERR_PTR(long err)
>  }
>  EXPORT_SYMBOL_GPL(rust_helper_ERR_PTR);
>  
> +bool rust_helper_IS_ERR(__force const void *ptr)
> +{
> +	return IS_ERR(ptr);
> +}
> +EXPORT_SYMBOL_GPL(rust_helper_IS_ERR);
> +
> +long rust_helper_PTR_ERR(__force const void *ptr)
> +{
> +	return PTR_ERR(ptr);
> +}
> +EXPORT_SYMBOL_GPL(rust_helper_PTR_ERR);
> +
>  /*
>   * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type
>   * as the Rust `usize` type, so we can use it in contexts where Rust
> diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs
> index 4f599c4d1752..6b10129075a7 100644
> --- a/rust/kernel/error.rs
> +++ b/rust/kernel/error.rs
> @@ -177,3 +177,52 @@ pub fn to_result(err: core::ffi::c_int) -> Result {
>          Ok(())
>      }
>  }
> +
> +/// Transform a kernel "error pointer" to a normal pointer.
> +///
> +/// Some kernel C API functions return an "error pointer" which optionally
> +/// embeds an `errno`. Callers are supposed to check the returned pointer
> +/// for errors. This function performs the check and converts the "error pointer"
> +/// to a normal pointer in an idiomatic fashion.
> +///
> +/// # Examples
> +///
> +/// ```ignore
> +/// # use kernel::from_err_ptr;
> +/// # use kernel::bindings;
> +/// fn devm_platform_ioremap_resource(
> +///     pdev: &mut PlatformDevice,
> +///     index: u32,
> +/// ) -> Result<*mut core::ffi::c_void> {
> +///     // SAFETY: FFI call.
> +///     unsafe {
> +///         from_err_ptr(bindings::devm_platform_ioremap_resource(
> +///             pdev.to_ptr(),
> +///             index,
> +///         ))
> +///     }
> +/// }
> +/// ```
> +// TODO: Remove `dead_code` marker once an in-kernel client is available.
> +#[allow(dead_code)]
> +pub(crate) fn from_err_ptr<T>(ptr: *mut T) -> Result<*mut T> {
> +    // CAST: Casting a pointer to `*const core::ffi::c_void` is always valid.
> +    let const_ptr: *const core::ffi::c_void = ptr.cast();
> +    // SAFETY: The FFI function does not deref the pointer.
> +    if unsafe { bindings::IS_ERR(const_ptr) } {
> +        // SAFETY: The FFI function does not deref the pointer.
> +        let err = unsafe { bindings::PTR_ERR(const_ptr) };
> +        // CAST: If `IS_ERR()` returns `true`,
> +        // then `PTR_ERR()` is guaranteed to return a
> +        // negative value greater-or-equal to `-bindings::MAX_ERRNO`,
> +        // which always fits in an `i16`, as per the invariant above.
> +        // And an `i16` always fits in an `i32`. So casting `err` to
> +        // an `i32` can never overflow, and is always valid.
> +        //
> +        // SAFETY: `IS_ERR()` ensures `err` is a
> +        // negative value greater-or-equal to `-bindings::MAX_ERRNO`.

The comment here should read `INVARIANT: ` because now you are
constructing `Error` which have type invariants.

Where is `from_kernel_errno_unchecked`? I believe the `rust` branch
on GitHub have it, as it's generally good to limit places where type
invariants are used directly, so the method is used to convert an
invariant requirement to a safety requirement that is more obvious due
to use of `unsafe`.

> +        #[cfg_attr(CONFIG_ARM, allow(clippy::unnecessary_cast))]

This should either be gated based on pointer size, or should just be a
blanket allow without cfg gating.

> +        return Err(Error(err as i32));
> +    }
> +    Ok(ptr)
> +}
> 

Best,
Gary