[PATCH v2] rust: error: clarify that `from_err_ptr` can return `Ok(NULL)`

[Mirko Adzic]

Improve the doc comment of `from_err_ptr` by explicitly stating that it
will return `Ok(NULL)` when passed a null pointer, as it isn't an error
value.

Add a doctest case that tests the behavior described above, as well as
other scenarios (non-null/non-error pointer, error value).

Suggested-by: Miguel Ojeda <ojeda@xxxxxxxxxx>
Link: https://lore.kernel.org/rust-for-linux/20260322193830.89324-1-ojeda@xxxxxxxxxx/
Link: https://github.com/Rust-for-Linux/linux/issues/1231
Signed-off-by: Mirko Adzic <adzicmirko97@xxxxxxxxx>
---
v1 -> v2:
    - Move the doctest code outside of functions so that it actually
      gets executed.
    - Instead of asserting a magic pointer value that comes from a
      hidden module, simply assert it isn't null.

v1: https://lore.kernel.org/all/20260328114005.125617-1-adzicmirko97@xxxxxxxxx/

 rust/kernel/error.rs | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs
index 935787c2a91c..e3e8ff775e0d 100644
--- a/rust/kernel/error.rs
+++ b/rust/kernel/error.rs
@@ -452,6 +452,9 @@ pub fn to_result(err: crate::ffi::c_int) -> Result {
 /// for errors. This function performs the check and converts the "error pointer"
 /// to a normal pointer in an idiomatic fashion.
 ///
+/// Note that a `NULL` pointer is not considered an error pointer, and is returned
+/// as-is, wrapped in `Ok`.
+///
 /// # Examples
 ///
 /// ```ignore
@@ -466,6 +469,35 @@ pub fn to_result(err: crate::ffi::c_int) -> Result {
 ///     from_err_ptr(unsafe { bindings::devm_platform_ioremap_resource(pdev.to_ptr(), index) })
 /// }
 /// ```
+///
+/// ```
+/// # use kernel::error::from_err_ptr;
+/// # mod bindings {
+/// #     use kernel::prelude::*;
+/// #     pub(super) unsafe fn einval_err_ptr() -> *mut kernel::ffi::c_void {
+/// #         let einval = -(kernel::bindings::EINVAL as isize);
+/// #         // SAFETY: `einval` is a valid error.
+/// #         unsafe { kernel::bindings::ERR_PTR(einval) }
+/// #     }
+/// #     pub(super) unsafe fn null_ptr() -> *mut kernel::ffi::c_void {
+/// #         core::ptr::null_mut()
+/// #     }
+/// #     pub(super) unsafe fn non_null_ptr() -> *mut kernel::ffi::c_void {
+/// #         0x1234 as *mut kernel::ffi::c_void
+/// #     }
+/// # }
+/// // SAFETY: ...
+/// let einval_err = from_err_ptr(unsafe { bindings::einval_err_ptr() });
+/// assert_eq!(einval_err, Err(EINVAL));
+///
+/// // SAFETY: ...
+/// let null_ok = from_err_ptr(unsafe { bindings::null_ptr() });
+/// assert_eq!(null_ok, Ok(core::ptr::null_mut()));
+///
+/// // SAFETY: ...
+/// let non_null = from_err_ptr(unsafe { bindings::non_null_ptr() }).unwrap();
+/// assert_ne!(non_null, core::ptr::null_mut());
+/// ```
 pub fn from_err_ptr<T>(ptr: *mut T) -> Result<*mut T> {
     // CAST: Casting a pointer to `*const crate::ffi::c_void` is always valid.
     let const_ptr: *const crate::ffi::c_void = ptr.cast();
-- 
2.53.0