Date:   Mon, 30 Jan 2023 18:49:37 +0000
From:   Gary Guo <gary@garyguo.net>
To:     Wedson Almeida Filho <wedsonaf@gmail.com>
Cc:     rust-for-linux@vger.kernel.org, Miguel Ojeda <ojeda@kernel.org>,
        Alex Gaynor <alex.gaynor@gmail.com>,
        Boqun Feng <boqun.feng@gmail.com>,
        =?UTF-8?B?QmrDtnJu?= Roy Baron <bjorn3_gh@protonmail.com>,
        linux-kernel@vger.kernel.org,
        Vincenzo Palazzo <vincenzopalazzodev@gmail.com>,
        Martin Rodriguez Reboredo <yakoyoku@gmail.com>
Subject: Re: [PATCH v2 2/5] rust: types: introduce `ForeignOwnable`
Message-ID: <20230130184937.13dd037e.gary@garyguo.net>
In-Reply-To: <20230130064404.744600-2-wedsonaf@gmail.com>
References: <20230130064404.744600-1-wedsonaf@gmail.com>
        <20230130064404.744600-2-wedsonaf@gmail.com>
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?0KYBIzwqkoC5i8vr12byJ2JQhTU9dQh8cuNmIxCk/LQtGSYdapoO/0EDYrpZ?=
 =?us-ascii?Q?/a8EaPN9MsFsjP8co+WadiNXMw8rbptfZZeZTldUNid+fxdGVliL/NBXhI4Z?=
 =?us-ascii?Q?uNSZ8ia5eWwuAI+Iz2yMfKyXi32HZ0hV9wr2MvUe+iCdQYRqXv/d4gbhczrZ?=
 =?us-ascii?Q?QYDJj9OSkberjkj21QH9/VnGZ+hMG1v2kAr6xlpB//I6F0PJfcbwsai3Bn7L?=
 =?us-ascii?Q?NhIvnWK5/tbn838DUedJ8oNjLO+X+M4d+w9JFydtx/cfN3rjmhJwW0qat8rg?=
 =?us-ascii?Q?LIpPTqyd0FeyumOZY4ArOna7OAHPnQcyKafHAioE0RaKb0N0sX80pbCy8fVf?=
 =?us-ascii?Q?+9JBVSNeBmYGQcmPcvqW0mk1NPmyq/0PSfeymVQmfJrBG+rnJ4PTR4LBTemm?=
 =?us-ascii?Q?xB5GIf0PZ6EsqQKM0dGeYbpfo+ZToRwKtmVwlXQKonEe8JF/FVD7SgHnWTCa?=
 =?us-ascii?Q?xWJlFu+dqBdELekoYSuaEDmimzkqJzjscUIXWcTsk+hhCTf6G64+vE+O53ry?=
 =?us-ascii?Q?JRyXDe4KUit0mb8/PpQlRxxI5sGh15rinHYfM9kmABkt9YVAKAG79e2LkEMq?=
 =?us-ascii?Q?/fPSkke66AEmVw2Ox8qy1EI7fDZPSdGDnCi5K6EOHD5WDs/lGh4WmBzwtqzx?=
 =?us-ascii?Q?V/p93IRhBxNndJlzkfbgBvK8LkzoDaOq4ppoVkvVm8YjuUyDUykyZKuze0eG?=
 =?us-ascii?Q?gY2vn5IDya3c6yEp4OSBST/B4jFq8Oi3rC0da5vVUlOmotvWdQQ+skMXksWj?=
 =?us-ascii?Q?rgEwxzkuyW8FPlxPxFvw/XFTtjc2Ra8jYgy1ibbqH2p46nC7Wif+kK/65TRn?=
 =?us-ascii?Q?vRfkv3G7Nvt3Wue/FhFvRgpXmbiUqrYZ8IDAcrj1eWcs+vc+dpdRwSihV2S+?=
 =?us-ascii?Q?78GQbMYEHTekTmfxXMClss5aE3N4jfKuQ0cPy1oDJZb4shWLLcVCFIeIwMSu?=
 =?us-ascii?Q?Ba5CCfAZCqfDPPLvt8o7zR8Nma9fqHJk9ueK+sdcv6WK+WnHkIem0f4W1w7z?=
 =?us-ascii?Q?XFuErV/z/TpiCNx+CuolPVkmyWVGi0DMCRwww3QgaJTN/C3qQe9DDdNMes5u?=
 =?us-ascii?Q?MgIIYwaf17hpbCcy2m9yP7tyZWGoaJ5OJzgoNS6B8IDIBMzJFKXrRgZFlV3u?=
 =?us-ascii?Q?5WvvAq0oj9BUxP83ToVqd+qMCDX+vItoOPd6F7QEn0/6scw7X6085ELsM8Ts?=
 =?us-ascii?Q?DQ1AhfW/mI4d+3qKzy5xCgHE/h9q0ZMcJdv+78gOcZgWEtTY3SYhS2QVOpMw?=
 =?us-ascii?Q?BgcIZMCFDc/VlgIzGfI82vD91LJgu++5THcDX96rUwx/eY8D79RLmTcK3FgC?=
 =?us-ascii?Q?00aizvc7cINPRGXRKUXBDvkm1enQwBoy4LfC3ylQVrWe50SmXZPaVLMJXku2?=
 =?us-ascii?Q?HfnV9wVZc4hmS2YHIkyZuc8pVzJM4XblEPFfWnMRVdDZec46+pSGaQXgkut3?=
 =?us-ascii?Q?OvXztT9UqjqnLG7zyAVT4vcQ7lBL1wbf0OfxNEGqyFiXpqcn2BcT3z7iw1iQ?=
 =?us-ascii?Q?GPtgYCKKbanR/U0HJkXaCzukFhK5fkDnCr/fKeITcXio0OmerckX8uYFJIUC?=
 =?us-ascii?Q?PJIuuWwiAMUtARPE+TXzH96ff6iY1HY3pYGYMzUd?=
X-OriginatorOrg: garyguo.net
X-MS-Exchange-CrossTenant-Network-Message-Id: f15bdea0-4f29-4560-3547-08db02f2bd59
X-MS-Exchange-CrossTenant-AuthSource: LO2P265MB5183.GBRP265.PROD.OUTLOOK.COM
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 30 Jan 2023 18:49:38.6544
 (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: iTyIRnz9MZr7M2IpixsUBbo/ZTIlLGVg0Jxzdri/0XLGqls5qiuUZhg1XaDphB0kBVaYWk0LI21DQ+mSwQoDMg==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CWLP265MB6050
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Mon, 30 Jan 2023 03:44:01 -0300
Wedson Almeida Filho <wedsonaf@gmail.com> wrote:

> It was originally called `PointerWrapper`. It is used to convert
> a Rust object to a pointer representation (void *) that can be
> stored on the C side, used, and eventually returned to Rust.
> 
> Signed-off-by: Wedson Almeida Filho <wedsonaf@gmail.com>
> Reviewed-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>

Reviewed-by: Gary Guo <gary@garyguo.net>

> ---
> v1 -> v2: Use `Self` instead of generic type in `borrow_mut`
> 
>  rust/kernel/lib.rs   |  1 +
>  rust/kernel/types.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 55 insertions(+)
> 
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index e0b0e953907d..223564f9f0cc 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -16,6 +16,7 @@
>  #![feature(coerce_unsized)]
>  #![feature(core_ffi_c)]
>  #![feature(dispatch_from_dyn)]
> +#![feature(generic_associated_types)]
>  #![feature(receiver_trait)]
>  #![feature(unsize)]
>  
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index dd834bfcb57b..72710b7442a3 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -8,6 +8,60 @@ use core::{
>      ops::{Deref, DerefMut},
>  };
>  
> +/// Used to transfer ownership to and from foreign (non-Rust) languages.
> +///
> +/// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and
> +/// later may be transferred back to Rust by calling [`Self::from_foreign`].
> +///
> +/// This trait is meant to be used in cases when Rust objects are stored in C objects and
> +/// eventually "freed" back to Rust.
> +pub trait ForeignOwnable: Sized {
> +    /// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and
> +    /// [`ForeignOwnable::from_foreign`].
> +    type Borrowed<'a>;
> +
> +    /// Converts a Rust-owned object to a foreign-owned one.
> +    ///
> +    /// The foreign representation is a pointer to void.
> +    fn into_foreign(self) -> *const core::ffi::c_void;
> +
> +    /// Borrows a foreign-owned object.
> +    ///
> +    /// # Safety
> +    ///
> +    /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
> +    /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
> +    /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow_mut`]
> +    /// for this object must have been dropped.
> +    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
> +
> +    /// Mutably borrows a foreign-owned object.
> +    ///
> +    /// # Safety
> +    ///
> +    /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
> +    /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
> +    /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] and
> +    /// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.
> +    unsafe fn borrow_mut(ptr: *const core::ffi::c_void) -> ScopeGuard<Self, fn(Self)> {
> +        // SAFETY: The safety requirements ensure that `ptr` came from a previous call to
> +        // `into_foreign`.
> +        ScopeGuard::new_with_data(unsafe { Self::from_foreign(ptr) }, |d| {
> +            d.into_foreign();
> +        })
> +    }
> +
> +    /// Converts a foreign-owned object back to a Rust-owned one.
> +    ///
> +    /// # Safety
> +    ///
> +    /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
> +    /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
> +    /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] and
> +    /// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.
> +    unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
> +}
> +
>  /// Runs a cleanup function/closure when dropped.
>  ///
>  /// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.