Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 1 | // SPDX-License-Identifier: GPL-2.0 |
| 2 | |
| 3 | //! Kernel errors. |
| 4 | //! |
Miguel Ojeda | bc2e7d5 | 2023-12-16 00:54:28 +0100 | [diff] [blame] | 5 | //! C header: [`include/uapi/asm-generic/errno-base.h`](srctree/include/uapi/asm-generic/errno-base.h) |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 6 | |
Wedson Almeida Filho | 2c10928 | 2024-03-27 22:36:03 -0300 | [diff] [blame] | 7 | use crate::{alloc::AllocError, str::CStr}; |
Gary Guo | d2e3115 | 2023-05-31 17:44:50 +0000 | [diff] [blame] | 8 | |
Wedson Almeida Filho | 2c10928 | 2024-03-27 22:36:03 -0300 | [diff] [blame] | 9 | use alloc::alloc::LayoutError; |
Wedson Almeida Filho | 76e2c2d | 2022-11-10 17:41:22 +0100 | [diff] [blame] | 10 | |
Gary Guo | d2e3115 | 2023-05-31 17:44:50 +0000 | [diff] [blame] | 11 | use core::fmt; |
Wedson Almeida Filho | 76e2c2d | 2022-11-10 17:41:22 +0100 | [diff] [blame] | 12 | use core::num::TryFromIntError; |
| 13 | use core::str::Utf8Error; |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 14 | |
| 15 | /// Contains the C-compatible error codes. |
Alice Ryhl | e37b654 | 2023-05-04 06:48:54 +0000 | [diff] [blame] | 16 | #[rustfmt::skip] |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 17 | pub mod code { |
Finn Behrens | 4b0c68b | 2022-11-10 17:41:20 +0100 | [diff] [blame] | 18 | macro_rules! declare_err { |
| 19 | ($err:tt $(,)? $($doc:expr),+) => { |
| 20 | $( |
| 21 | #[doc = $doc] |
| 22 | )* |
| 23 | pub const $err: super::Error = super::Error(-(crate::bindings::$err as i32)); |
| 24 | }; |
| 25 | } |
| 26 | |
Viktor Garske | 266def2 | 2022-11-10 17:41:21 +0100 | [diff] [blame] | 27 | declare_err!(EPERM, "Operation not permitted."); |
| 28 | declare_err!(ENOENT, "No such file or directory."); |
| 29 | declare_err!(ESRCH, "No such process."); |
| 30 | declare_err!(EINTR, "Interrupted system call."); |
| 31 | declare_err!(EIO, "I/O error."); |
| 32 | declare_err!(ENXIO, "No such device or address."); |
| 33 | declare_err!(E2BIG, "Argument list too long."); |
| 34 | declare_err!(ENOEXEC, "Exec format error."); |
| 35 | declare_err!(EBADF, "Bad file number."); |
Wedson Almeida Filho | 17bfcd6 | 2023-09-30 11:49:58 -0300 | [diff] [blame] | 36 | declare_err!(ECHILD, "No child processes."); |
Viktor Garske | 266def2 | 2022-11-10 17:41:21 +0100 | [diff] [blame] | 37 | declare_err!(EAGAIN, "Try again."); |
Finn Behrens | 4b0c68b | 2022-11-10 17:41:20 +0100 | [diff] [blame] | 38 | declare_err!(ENOMEM, "Out of memory."); |
Viktor Garske | 266def2 | 2022-11-10 17:41:21 +0100 | [diff] [blame] | 39 | declare_err!(EACCES, "Permission denied."); |
| 40 | declare_err!(EFAULT, "Bad address."); |
| 41 | declare_err!(ENOTBLK, "Block device required."); |
| 42 | declare_err!(EBUSY, "Device or resource busy."); |
| 43 | declare_err!(EEXIST, "File exists."); |
| 44 | declare_err!(EXDEV, "Cross-device link."); |
| 45 | declare_err!(ENODEV, "No such device."); |
| 46 | declare_err!(ENOTDIR, "Not a directory."); |
| 47 | declare_err!(EISDIR, "Is a directory."); |
| 48 | declare_err!(EINVAL, "Invalid argument."); |
| 49 | declare_err!(ENFILE, "File table overflow."); |
| 50 | declare_err!(EMFILE, "Too many open files."); |
| 51 | declare_err!(ENOTTY, "Not a typewriter."); |
| 52 | declare_err!(ETXTBSY, "Text file busy."); |
| 53 | declare_err!(EFBIG, "File too large."); |
| 54 | declare_err!(ENOSPC, "No space left on device."); |
| 55 | declare_err!(ESPIPE, "Illegal seek."); |
| 56 | declare_err!(EROFS, "Read-only file system."); |
| 57 | declare_err!(EMLINK, "Too many links."); |
| 58 | declare_err!(EPIPE, "Broken pipe."); |
| 59 | declare_err!(EDOM, "Math argument out of domain of func."); |
| 60 | declare_err!(ERANGE, "Math result not representable."); |
Alice Ryhl | e37b654 | 2023-05-04 06:48:54 +0000 | [diff] [blame] | 61 | declare_err!(ERESTARTSYS, "Restart the system call."); |
| 62 | declare_err!(ERESTARTNOINTR, "System call was interrupted by a signal and will be restarted."); |
| 63 | declare_err!(ERESTARTNOHAND, "Restart if no handler."); |
| 64 | declare_err!(ENOIOCTLCMD, "No ioctl command."); |
| 65 | declare_err!(ERESTART_RESTARTBLOCK, "Restart by calling sys_restart_syscall."); |
| 66 | declare_err!(EPROBE_DEFER, "Driver requests probe retry."); |
| 67 | declare_err!(EOPENSTALE, "Open found a stale dentry."); |
| 68 | declare_err!(ENOPARAM, "Parameter not supported."); |
| 69 | declare_err!(EBADHANDLE, "Illegal NFS file handle."); |
| 70 | declare_err!(ENOTSYNC, "Update synchronization mismatch."); |
| 71 | declare_err!(EBADCOOKIE, "Cookie is stale."); |
| 72 | declare_err!(ENOTSUPP, "Operation is not supported."); |
| 73 | declare_err!(ETOOSMALL, "Buffer or request is too small."); |
| 74 | declare_err!(ESERVERFAULT, "An untranslatable error occurred."); |
| 75 | declare_err!(EBADTYPE, "Type not supported by server."); |
| 76 | declare_err!(EJUKEBOX, "Request initiated, but will not complete before timeout."); |
| 77 | declare_err!(EIOCBQUEUED, "iocb queued, will get completion event."); |
| 78 | declare_err!(ERECALLCONFLICT, "Conflict with recalled state."); |
| 79 | declare_err!(ENOGRACE, "NFS file lock reclaim refused."); |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 80 | } |
| 81 | |
| 82 | /// Generic integer kernel error. |
| 83 | /// |
| 84 | /// The kernel defines a set of integer generic error codes based on C and |
| 85 | /// POSIX ones. These codes may have a more specific meaning in some contexts. |
| 86 | /// |
| 87 | /// # Invariants |
| 88 | /// |
| 89 | /// The value is a valid `errno` (i.e. `>= -MAX_ERRNO && < 0`). |
| 90 | #[derive(Clone, Copy, PartialEq, Eq)] |
| 91 | pub struct Error(core::ffi::c_int); |
| 92 | |
| 93 | impl Error { |
Miguel Ojeda | 6551a7f | 2023-04-03 18:48:12 +0900 | [diff] [blame] | 94 | /// Creates an [`Error`] from a kernel error code. |
| 95 | /// |
| 96 | /// It is a bug to pass an out-of-range `errno`. `EINVAL` would |
| 97 | /// be returned in such a case. |
Miguel Ojeda | 6551a7f | 2023-04-03 18:48:12 +0900 | [diff] [blame] | 98 | pub(crate) fn from_errno(errno: core::ffi::c_int) -> Error { |
| 99 | if errno < -(bindings::MAX_ERRNO as i32) || errno >= 0 { |
| 100 | // TODO: Make it a `WARN_ONCE` once available. |
| 101 | crate::pr_warn!( |
| 102 | "attempted to create `Error` with out of range `errno`: {}", |
| 103 | errno |
| 104 | ); |
| 105 | return code::EINVAL; |
| 106 | } |
| 107 | |
| 108 | // INVARIANT: The check above ensures the type invariant |
| 109 | // will hold. |
| 110 | Error(errno) |
| 111 | } |
| 112 | |
| 113 | /// Creates an [`Error`] from a kernel error code. |
| 114 | /// |
| 115 | /// # Safety |
| 116 | /// |
| 117 | /// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`). |
Miguel Ojeda | 6551a7f | 2023-04-03 18:48:12 +0900 | [diff] [blame] | 118 | unsafe fn from_errno_unchecked(errno: core::ffi::c_int) -> Error { |
| 119 | // INVARIANT: The contract ensures the type invariant |
| 120 | // will hold. |
| 121 | Error(errno) |
| 122 | } |
| 123 | |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 124 | /// Returns the kernel error code. |
Asahi Lina | 46384d0 | 2023-04-03 18:48:10 +0900 | [diff] [blame] | 125 | pub fn to_errno(self) -> core::ffi::c_int { |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 126 | self.0 |
| 127 | } |
Asahi Lina | c7e20fa | 2023-04-03 18:48:11 +0900 | [diff] [blame] | 128 | |
Andreas Hindborg | 3253aba | 2024-06-11 13:45:49 +0200 | [diff] [blame] | 129 | #[cfg(CONFIG_BLOCK)] |
| 130 | pub(crate) fn to_blk_status(self) -> bindings::blk_status_t { |
| 131 | // SAFETY: `self.0` is a valid error due to its invariant. |
| 132 | unsafe { bindings::errno_to_blk_status(self.0) } |
| 133 | } |
| 134 | |
Asahi Lina | c7e20fa | 2023-04-03 18:48:11 +0900 | [diff] [blame] | 135 | /// Returns the error encoded as a pointer. |
| 136 | #[allow(dead_code)] |
| 137 | pub(crate) fn to_ptr<T>(self) -> *mut T { |
Miguel Ojeda | 7bc1867 | 2024-07-30 17:57:02 +0200 | [diff] [blame] | 138 | #[cfg_attr(target_pointer_width = "32", allow(clippy::useless_conversion))] |
Manmohan Shukla | 2a7e0a5 | 2023-09-07 02:18:57 +0530 | [diff] [blame] | 139 | // SAFETY: `self.0` is a valid error due to its invariant. |
Miguel Ojeda | 7bc1867 | 2024-07-30 17:57:02 +0200 | [diff] [blame] | 140 | unsafe { |
| 141 | bindings::ERR_PTR(self.0.into()) as *mut _ |
| 142 | } |
Asahi Lina | c7e20fa | 2023-04-03 18:48:11 +0900 | [diff] [blame] | 143 | } |
Gary Guo | d2e3115 | 2023-05-31 17:44:50 +0000 | [diff] [blame] | 144 | |
| 145 | /// Returns a string representing the error, if one exists. |
| 146 | #[cfg(not(testlib))] |
| 147 | pub fn name(&self) -> Option<&'static CStr> { |
| 148 | // SAFETY: Just an FFI call, there are no extra safety requirements. |
| 149 | let ptr = unsafe { bindings::errname(-self.0) }; |
| 150 | if ptr.is_null() { |
| 151 | None |
| 152 | } else { |
| 153 | // SAFETY: The string returned by `errname` is static and `NUL`-terminated. |
| 154 | Some(unsafe { CStr::from_char_ptr(ptr) }) |
| 155 | } |
| 156 | } |
| 157 | |
| 158 | /// Returns a string representing the error, if one exists. |
| 159 | /// |
| 160 | /// When `testlib` is configured, this always returns `None` to avoid the dependency on a |
| 161 | /// kernel function so that tests that use this (e.g., by calling [`Result::unwrap`]) can still |
| 162 | /// run in userspace. |
| 163 | #[cfg(testlib)] |
| 164 | pub fn name(&self) -> Option<&'static CStr> { |
| 165 | None |
| 166 | } |
| 167 | } |
| 168 | |
| 169 | impl fmt::Debug for Error { |
| 170 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 171 | match self.name() { |
| 172 | // Print out number if no name can be found. |
| 173 | None => f.debug_tuple("Error").field(&-self.0).finish(), |
| 174 | // SAFETY: These strings are ASCII-only. |
| 175 | Some(name) => f |
| 176 | .debug_tuple(unsafe { core::str::from_utf8_unchecked(name) }) |
| 177 | .finish(), |
| 178 | } |
| 179 | } |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 180 | } |
| 181 | |
Wedson Almeida Filho | 76e2c2d | 2022-11-10 17:41:22 +0100 | [diff] [blame] | 182 | impl From<AllocError> for Error { |
| 183 | fn from(_: AllocError) -> Error { |
| 184 | code::ENOMEM |
| 185 | } |
| 186 | } |
| 187 | |
| 188 | impl From<TryFromIntError> for Error { |
| 189 | fn from(_: TryFromIntError) -> Error { |
| 190 | code::EINVAL |
| 191 | } |
| 192 | } |
| 193 | |
| 194 | impl From<Utf8Error> for Error { |
| 195 | fn from(_: Utf8Error) -> Error { |
| 196 | code::EINVAL |
| 197 | } |
| 198 | } |
| 199 | |
Wedson Almeida Filho | 76e2c2d | 2022-11-10 17:41:22 +0100 | [diff] [blame] | 200 | impl From<LayoutError> for Error { |
| 201 | fn from(_: LayoutError) -> Error { |
| 202 | code::ENOMEM |
| 203 | } |
| 204 | } |
| 205 | |
| 206 | impl From<core::fmt::Error> for Error { |
| 207 | fn from(_: core::fmt::Error) -> Error { |
| 208 | code::EINVAL |
| 209 | } |
| 210 | } |
| 211 | |
| 212 | impl From<core::convert::Infallible> for Error { |
| 213 | fn from(e: core::convert::Infallible) -> Error { |
| 214 | match e {} |
| 215 | } |
| 216 | } |
| 217 | |
Wedson Almeida Filho | 247b365 | 2022-02-11 20:25:34 +0100 | [diff] [blame] | 218 | /// A [`Result`] with an [`Error`] error type. |
| 219 | /// |
| 220 | /// To be used as the return type for functions that may fail. |
| 221 | /// |
| 222 | /// # Error codes in C and Rust |
| 223 | /// |
| 224 | /// In C, it is common that functions indicate success or failure through |
| 225 | /// their return value; modifying or returning extra data through non-`const` |
| 226 | /// pointer parameters. In particular, in the kernel, functions that may fail |
| 227 | /// typically return an `int` that represents a generic error code. We model |
| 228 | /// those as [`Error`]. |
| 229 | /// |
| 230 | /// In Rust, it is idiomatic to model functions that may fail as returning |
| 231 | /// a [`Result`]. Since in the kernel many functions return an error code, |
| 232 | /// [`Result`] is a type alias for a [`core::result::Result`] that uses |
| 233 | /// [`Error`] as its error type. |
| 234 | /// |
| 235 | /// Note that even if a function does not return anything when it succeeds, |
| 236 | /// it should still be modeled as returning a `Result` rather than |
| 237 | /// just an [`Error`]. |
Alice Ryhl | 4a59081 | 2023-05-02 12:40:15 +0000 | [diff] [blame] | 238 | pub type Result<T = (), E = Error> = core::result::Result<T, E>; |
Wedson Almeida Filho | 086fbfa | 2023-04-03 18:48:13 +0900 | [diff] [blame] | 239 | |
| 240 | /// Converts an integer as returned by a C kernel function to an error if it's negative, and |
| 241 | /// `Ok(())` otherwise. |
| 242 | pub fn to_result(err: core::ffi::c_int) -> Result { |
| 243 | if err < 0 { |
| 244 | Err(Error::from_errno(err)) |
| 245 | } else { |
| 246 | Ok(()) |
| 247 | } |
| 248 | } |
Sven Van Asbroeck | 752417b | 2023-04-03 18:48:14 +0900 | [diff] [blame] | 249 | |
| 250 | /// Transform a kernel "error pointer" to a normal pointer. |
| 251 | /// |
| 252 | /// Some kernel C API functions return an "error pointer" which optionally |
| 253 | /// embeds an `errno`. Callers are supposed to check the returned pointer |
| 254 | /// for errors. This function performs the check and converts the "error pointer" |
| 255 | /// to a normal pointer in an idiomatic fashion. |
| 256 | /// |
| 257 | /// # Examples |
| 258 | /// |
| 259 | /// ```ignore |
| 260 | /// # use kernel::from_err_ptr; |
| 261 | /// # use kernel::bindings; |
| 262 | /// fn devm_platform_ioremap_resource( |
| 263 | /// pdev: &mut PlatformDevice, |
| 264 | /// index: u32, |
| 265 | /// ) -> Result<*mut core::ffi::c_void> { |
Valentin Obst | 69d5fbb | 2024-01-31 21:23:24 +0100 | [diff] [blame] | 266 | /// // SAFETY: `pdev` points to a valid platform device. There are no safety requirements |
| 267 | /// // on `index`. |
| 268 | /// from_err_ptr(unsafe { bindings::devm_platform_ioremap_resource(pdev.to_ptr(), index) }) |
Sven Van Asbroeck | 752417b | 2023-04-03 18:48:14 +0900 | [diff] [blame] | 269 | /// } |
| 270 | /// ``` |
| 271 | // TODO: Remove `dead_code` marker once an in-kernel client is available. |
| 272 | #[allow(dead_code)] |
| 273 | pub(crate) fn from_err_ptr<T>(ptr: *mut T) -> Result<*mut T> { |
| 274 | // CAST: Casting a pointer to `*const core::ffi::c_void` is always valid. |
| 275 | let const_ptr: *const core::ffi::c_void = ptr.cast(); |
| 276 | // SAFETY: The FFI function does not deref the pointer. |
| 277 | if unsafe { bindings::IS_ERR(const_ptr) } { |
| 278 | // SAFETY: The FFI function does not deref the pointer. |
| 279 | let err = unsafe { bindings::PTR_ERR(const_ptr) }; |
| 280 | // CAST: If `IS_ERR()` returns `true`, |
| 281 | // then `PTR_ERR()` is guaranteed to return a |
| 282 | // negative value greater-or-equal to `-bindings::MAX_ERRNO`, |
| 283 | // which always fits in an `i16`, as per the invariant above. |
| 284 | // And an `i16` always fits in an `i32`. So casting `err` to |
| 285 | // an `i32` can never overflow, and is always valid. |
| 286 | // |
| 287 | // SAFETY: `IS_ERR()` ensures `err` is a |
| 288 | // negative value greater-or-equal to `-bindings::MAX_ERRNO`. |
| 289 | #[allow(clippy::unnecessary_cast)] |
| 290 | return Err(unsafe { Error::from_errno_unchecked(err as core::ffi::c_int) }); |
| 291 | } |
| 292 | Ok(ptr) |
| 293 | } |
Wedson Almeida Filho | ef4dc4c | 2023-04-03 18:48:15 +0900 | [diff] [blame] | 294 | |
| 295 | /// Calls a closure returning a [`crate::error::Result<T>`] and converts the result to |
| 296 | /// a C integer result. |
| 297 | /// |
| 298 | /// This is useful when calling Rust functions that return [`crate::error::Result<T>`] |
| 299 | /// from inside `extern "C"` functions that need to return an integer error result. |
| 300 | /// |
| 301 | /// `T` should be convertible from an `i16` via `From<i16>`. |
| 302 | /// |
| 303 | /// # Examples |
| 304 | /// |
| 305 | /// ```ignore |
| 306 | /// # use kernel::from_result; |
| 307 | /// # use kernel::bindings; |
| 308 | /// unsafe extern "C" fn probe_callback( |
| 309 | /// pdev: *mut bindings::platform_device, |
| 310 | /// ) -> core::ffi::c_int { |
| 311 | /// from_result(|| { |
| 312 | /// let ptr = devm_alloc(pdev)?; |
| 313 | /// bindings::platform_set_drvdata(pdev, ptr); |
| 314 | /// Ok(0) |
| 315 | /// }) |
| 316 | /// } |
| 317 | /// ``` |
| 318 | // TODO: Remove `dead_code` marker once an in-kernel client is available. |
| 319 | #[allow(dead_code)] |
| 320 | pub(crate) fn from_result<T, F>(f: F) -> T |
| 321 | where |
| 322 | T: From<i16>, |
| 323 | F: FnOnce() -> Result<T>, |
| 324 | { |
| 325 | match f() { |
| 326 | Ok(v) => v, |
| 327 | // NO-OVERFLOW: negative `errno`s are no smaller than `-bindings::MAX_ERRNO`, |
| 328 | // `-bindings::MAX_ERRNO` fits in an `i16` as per invariant above, |
| 329 | // therefore a negative `errno` always fits in an `i16` and will not overflow. |
| 330 | Err(e) => T::from(e.to_errno() as i16), |
| 331 | } |
| 332 | } |
Benno Lossin | 88c2e11 | 2023-10-26 20:19:33 +0000 | [diff] [blame] | 333 | |
| 334 | /// Error message for calling a default function of a [`#[vtable]`](macros::vtable) trait. |
| 335 | pub const VTABLE_DEFAULT_ERROR: &str = |
| 336 | "This function must not be called, see the #[vtable] documentation."; |