| # | Module Path | API Name | Type | Full Doc | Safety Doc | Confirmed |
|---|---|---|---|---|---|---|
| 1 | crate::alloc | Allocator | trait | The kernel's [`Allocator`] trait. An implementation of [`Allocator`] can allocate, re-allocate and free memory buffers described via [`Layout`]. [`Allocator`] is designed to be implemented as a ZST; [`Allocator`] functions do not operate on an object instance. In order to be able to support `#[derive(CoercePointee)]` later on, we need to avoid a design that requires an `Allocator` to be instantiated, hence its functions must not contain any kind of `self` parameter. # Safety - A memory allocation returned from an allocator must remain valid until it is explicitly freed. - Any pointer to a valid memory allocation must be valid to be passed to any other [`Allocator`] function of the same type. - Implementers must ensure that all trait functions abide by the guarantees documented in the `# Guarantees` sections. | # Safety - A memory allocation returned from an allocator must remain valid until it is explicitly freed. - Any pointer to a valid memory allocation must be valid to be passed to any other [`Allocator`] function of the same type. - Implementers must ensure that all trait functions abide by the guarantees documented in the `# Guarantees` sections. | |
| 2 | crate::alloc | Allocator::free | trait_method | Free an existing memory allocation. # Safety - `ptr` must point to an existing and valid memory allocation created by this [`Allocator`]; if `old_layout` is zero-sized `p` does not need to be a pointer returned by this [`Allocator`]. - `layout` must match the `Layout` the allocation has been created with. - The memory allocation at `ptr` must never again be read from or written to. | # Safety - `ptr` must point to an existing and valid memory allocation created by this [`Allocator`]; if `old_layout` is zero-sized `p` does not need to be a pointer returned by this [`Allocator`]. - `layout` must match the `Layout` the allocation has been created with. - The memory allocation at `ptr` must never again be read from or written to. | |
| 3 | crate::alloc | Allocator::realloc | trait_method | Re-allocate an existing memory allocation to satisfy the requested `layout` and a specific NUMA node request to allocate the memory for. Systems employing a Non Uniform Memory Access (NUMA) architecture contain collections of hardware resources including processors, memory, and I/O buses, that comprise what is commonly known as a NUMA node. `nid` stands for NUMA id, i. e. NUMA node identifier, which is a non-negative integer if a node needs to be specified, or [`NumaNode::NO_NODE`] if the caller doesn't care. If the requested size is zero, `realloc` behaves equivalent to `free`. If the requested size is larger than the size of the existing allocation, a successful call to `realloc` guarantees that the new or grown buffer has at least `Layout::size` bytes, but may also be larger. If the requested size is smaller than the size of the existing allocation, `realloc` may or may not shrink the buffer; this is implementation specific to the allocator. On allocation failure, the existing buffer, if any, remains valid. The buffer is represented as `NonNull<[u8]>`. # Safety - If `ptr == Some(p)`, then `p` must point to an existing and valid memory allocation created by this [`Allocator`]; if `old_layout` is zero-sized `p` does not need to be a pointer returned by this [`Allocator`]. - `ptr` is allowed to be `None`; in this case a new memory allocation is created and `old_layout` is ignored. - `old_layout` must match the `Layout` the allocation has been created with. # Guarantees This function has the same guarantees as [`Allocator::alloc`]. When `ptr == Some(p)`, then it additionally guarantees that: - the contents of the memory pointed to by `p` are preserved up to the lesser of the new and old size, i.e. `ret_ptr[0..min(layout.size(), old_layout.size())] == p[0..min(layout.size(), old_layout.size())]`. - when the return value is `Err(AllocError)`, then `ptr` is still valid. | # Safety - If `ptr == Some(p)`, then `p` must point to an existing and valid memory allocation created by this [`Allocator`]; if `old_layout` is zero-sized `p` does not need to be a pointer returned by this [`Allocator`]. - `ptr` is allowed to be `None`; in this case a new memory allocation is created and `old_layout` is ignored. - `old_layout` must match the `Layout` the allocation has been created with. | |
| 4 | crate::alloc::allocator | to_page | method | Convert a pointer to a [`Vmalloc`] allocation to a [`page::BorrowedPage`]. # Examples ``` # use core::ptr::{NonNull, from_mut}; # use kernel::{page, prelude::*}; use kernel::alloc::allocator::Vmalloc; let mut vbox = VBox::<[u8; page::PAGE_SIZE]>::new_uninit(GFP_KERNEL)?; { // SAFETY: By the type invariant of `Box` the inner pointer of `vbox` is non-null. let ptr = unsafe { NonNull::new_unchecked(from_mut(&mut *vbox)) }; // SAFETY: // `ptr` is a valid pointer to a `Vmalloc` allocation. // `ptr` is valid for the entire lifetime of `page`. let page = unsafe { Vmalloc::to_page(ptr.cast()) }; // SAFETY: There is no concurrent read or write to the same page. unsafe { page.fill_zero_raw(0, page::PAGE_SIZE)? }; } # Ok::<(), Error>(()) ``` # Safety - `ptr` must be a valid pointer to a [`Vmalloc`] allocation. - `ptr` must remain valid for the entire duration of `'a`. | # Safety - `ptr` must be a valid pointer to a [`Vmalloc`] allocation. - `ptr` must remain valid for the entire duration of `'a`. | |
| 5 | crate::alloc::allocator::iter | new | method | Creates a new [`VmallocPageIter`] instance. # Safety - `buf` must be a [`page::PAGE_SIZE`] aligned pointer into a [`Vmalloc`] allocation. - `buf` must be valid for at least the lifetime of `'a`. - `size` must be the number of bytes from `buf` until the end of the [`Vmalloc`] allocation `buf` points to. | # Safety - `buf` must be a [`page::PAGE_SIZE`] aligned pointer into a [`Vmalloc`] allocation. - `buf` must be valid for at least the lifetime of `'a`. - `size` must be the number of bytes from `buf` until the end of the [`Vmalloc`] allocation `buf` points to. | |
| 6 | crate::alloc::kbox | assume_init | method | Converts a `Box<MaybeUninit<T>, A>` to a `Box<T, A>`. It is undefined behavior to call this function while the value inside of `b` is not yet fully initialized. # Safety Callers must ensure that the value inside of `b` is in an initialized state. | # Safety Callers must ensure that the value inside of `b` is in an initialized state. | |
| 7 | crate::alloc::kvec | from_raw_parts | method | Creates a `Vec<T, A>` from a pointer, a length and a capacity using the allocator `A`. # Examples ``` let mut v = kernel::kvec![1, 2, 3]?; v.reserve(1, GFP_KERNEL)?; let (mut ptr, mut len, cap) = v.into_raw_parts(); // SAFETY: We've just reserved memory for another element. unsafe { ptr.add(len).write(4) }; len += 1; // SAFETY: We only wrote an additional element at the end of the `KVec`'s buffer and // correspondingly increased the length of the `KVec` by one. Otherwise, we construct it // from the exact same raw parts. let v = unsafe { KVec::from_raw_parts(ptr, len, cap) }; assert_eq!(v, [1, 2, 3, 4]); # Ok::<(), Error>(()) ``` # Safety If `T` is a ZST: - `ptr` must be a dangling, well aligned pointer. Otherwise: - `ptr` must have been allocated with the allocator `A`. - `ptr` must satisfy or exceed the alignment requirements of `T`. - `ptr` must point to memory with a size of at least `size_of::<T>() * capacity` bytes. - The allocated size in bytes must not be larger than `isize::MAX`. - `length` must be less than or equal to `capacity`. - The first `length` elements must be initialized values of type `T`. It is also valid to create an empty `Vec` passing a dangling pointer for `ptr` and zero for `cap` and `len`. | # Safety If `T` is a ZST: - `ptr` must be a dangling, well aligned pointer. Otherwise: - `ptr` must have been allocated with the allocator `A`. - `ptr` must satisfy or exceed the alignment requirements of `T`. - `ptr` must point to memory with a size of at least `size_of::<T>() * capacity` bytes. - The allocated size in bytes must not be larger than `isize::MAX`. - `length` must be less than or equal to `capacity`. - The first `length` elements must be initialized values of type `T`. It is also valid to create an empty `Vec` passing a dangling pointer for `ptr` and zero for `cap` and `len`. | |
| 8 | crate::bitmap | from_raw | method | Borrows a C bitmap. # Safety * `ptr` holds a non-null address of an initialized array of `unsigned long` that is large enough to hold `nbits` bits. * the array must not be freed for the lifetime of this [`Bitmap`] * concurrent access only happens through atomic operations | # Safety * `ptr` holds a non-null address of an initialized array of `unsigned long` that is large enough to hold `nbits` bits. * the array must not be freed for the lifetime of this [`Bitmap`] * concurrent access only happens through atomic operations | |
| 9 | crate::bitmap | from_raw_mut | method | Borrows a C bitmap exclusively. # Safety * `ptr` holds a non-null address of an initialized array of `unsigned long` that is large enough to hold `nbits` bits. * the array must not be freed for the lifetime of this [`Bitmap`] * no concurrent access may happen. | # Safety * `ptr` holds a non-null address of an initialized array of `unsigned long` that is large enough to hold `nbits` bits. * the array must not be freed for the lifetime of this [`Bitmap`] * no concurrent access may happen. | |
| 10 | crate::configfs | HasGroup | trait | Trait that allows offset calculations for structs that embed a `bindings::config_group`. Users of the configfs API should not need to implement this trait. # Safety - Implementers of this trait must embed a `bindings::config_group`. - Methods must be implemented according to method documentation. | # Safety - Implementers of this trait must embed a `bindings::config_group`. - Methods must be implemented according to method documentation. | |
| 11 | crate::configfs | HasGroup::container_of | trait_method | Return the address of the [`Self`] that `group` is embedded in. # Safety - `group` must point to the `bindings::config_group` that is embedded in [`Self`]. | # Safety - `group` must point to the `bindings::config_group` that is embedded in [`Self`]. | |
| 12 | crate::configfs | HasGroup::group | trait_method | Return the address of the `bindings::config_group` embedded in [`Self`]. # Safety - `this` must be a valid allocation of at least the size of [`Self`]. | # Safety - `this` must be a valid allocation of at least the size of [`Self`]. | |
| 13 | crate::cpu | from_cpu | function | Creates a new instance of CPU's device. # Safety Reference counting is not implemented for the CPU device in the C code. When a CPU is hot-unplugged, the corresponding CPU device is unregistered, but its associated memory is not freed. Callers must ensure that the CPU device is not used after it has been unregistered. This can be achieved, for example, by registering a CPU hotplug notifier and removing any references to the CPU device within the notifier's callback. | # Safety Reference counting is not implemented for the CPU device in the C code. When a CPU is hot-unplugged, the corresponding CPU device is unregistered, but its associated memory is not freed. Callers must ensure that the CPU device is not used after it has been unregistered. This can be achieved, for example, by registering a CPU hotplug notifier and removing any references to the CPU device within the notifier's callback. | |
| 14 | crate::cpu | from_i32_unchecked | method | Creates a new [`CpuId`] from the given `id` without checking bounds. # Safety The caller must ensure that `id` is a valid CPU ID (i.e., `0 <= id < nr_cpu_ids()`). | # Safety The caller must ensure that `id` is a valid CPU ID (i.e., `0 <= id < nr_cpu_ids()`). | |
| 15 | crate::cpu | from_u32_unchecked | method | Creates a new [`CpuId`] from the given `id` without checking bounds. # Safety The caller must ensure that `id` is a valid CPU ID (i.e., `0 <= id < nr_cpu_ids()`). | # Safety The caller must ensure that `id` is a valid CPU ID (i.e., `0 <= id < nr_cpu_ids()`). | |
| 16 | crate::cpufreq | from_raw | method | Creates a reference to an existing C `struct cpufreq_frequency_table` pointer. # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | |
| 17 | crate::cpufreq | from_raw | method | Creates a reference to an existing `struct cpufreq_policy` pointer. # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | |
| 18 | crate::cpufreq | from_raw_mut | method | Creates a mutable reference to an existing `struct cpufreq_policy_data` pointer. # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | |
| 19 | crate::cpufreq | from_raw_mut | method | Creates a mutable reference to an existing `struct cpufreq_policy` pointer. # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | |
| 20 | crate::cpufreq | new | method | Creates an instance of [`TableIndex`]. # Safety The caller must ensure that `index` correspond to a valid entry in the [`Table`] it is used for. | # Safety The caller must ensure that `index` correspond to a valid entry in the [`Table`] it is used for. | |
| 21 | crate::cpufreq | set_clk | method | Sets clock for the [`Policy`]. # Safety The caller must guarantee that the returned [`Clk`] is not dropped while it is getting used by the C code. | # Safety The caller must guarantee that the returned [`Clk`] is not dropped while it is getting used by the C code. | |
| 22 | crate::cpufreq | set_freq_table | method | Sets the CPU frequency [`Table`] for the [`Policy`]. # Safety The caller must guarantee that the [`Table`] is not dropped while it is getting used by the C code. | # Safety The caller must guarantee that the [`Table`] is not dropped while it is getting used by the C code. | |
| 23 | crate::cpumask | from_raw | method | Creates a reference from an existing `struct cpumask` pointer. # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | |
| 24 | crate::cpumask | from_raw | method | Creates a reference to an existing `struct cpumask_var_t` pointer. # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime of the returned reference. | |
| 25 | crate::cpumask | from_raw_mut | method | Creates a mutable reference from an existing `struct cpumask` pointer. # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | |
| 26 | crate::cpumask | from_raw_mut | method | Creates a mutable reference to an existing `struct cpumask_var_t` pointer. # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | # Safety The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime of the returned reference. | |
| 27 | crate::cpumask | new | method | Creates an instance of the [`CpumaskVar`]. # Safety The caller must ensure that the returned [`CpumaskVar`] is properly initialized before getting used. | # Safety The caller must ensure that the returned [`CpumaskVar`] is properly initialized before getting used. | |
| 28 | crate::cred | from_ptr | method | Creates a reference to a [`Credential`] from a valid pointer. # Safety The caller must ensure that `ptr` is valid and remains valid for the lifetime of the returned [`Credential`] reference. | # Safety The caller must ensure that `ptr` is valid and remains valid for the lifetime of the returned [`Credential`] reference. | |
| 29 | crate::device | as_bound | method | Convert a [`&Device`](Device) into a [`&Device<Bound>`](Device<Bound>). # Safety The caller is responsible to ensure that the returned [`&Device<Bound>`](Device<Bound>) only lives as long as it can be guaranteed that the [`Device`] is actually bound. | # Safety The caller is responsible to ensure that the returned [`&Device<Bound>`](Device<Bound>) only lives as long as it can be guaranteed that the [`Device`] is actually bound. | |
| 30 | crate::device | drvdata_borrow | method | Borrow the driver's private data bound to this [`Device`]. # Safety - Must only be called after a preceding call to [`Device::set_drvdata`] and before the device is fully unbound. - The type `T` must match the type of the `ForeignOwnable` previously stored by [`Device::set_drvdata`]. | # Safety - Must only be called after a preceding call to [`Device::set_drvdata`] and before the device is fully unbound. - The type `T` must match the type of the `ForeignOwnable` previously stored by [`Device::set_drvdata`]. | |
| 31 | crate::device | from_raw | method | Convert a raw C `struct device` pointer to a `&'a Device`. # Safety Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to can't drop to zero, for the duration of this function call and the entire duration when the returned reference exists. | # Safety Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to can't drop to zero, for the duration of this function call and the entire duration when the returned reference exists. | |
| 32 | crate::device | get_device | method | Creates a new reference-counted abstraction instance of an existing `struct device` pointer. # Safety Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to can't drop to zero, for the duration of this function call. It must also be ensured that `bindings::device::release` can be called from any thread. While not officially documented, this should be the case for any `struct device`. | # Safety Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to can't drop to zero, for the duration of this function call. It must also be ensured that `bindings::device::release` can be called from any thread. While not officially documented, this should be the case for any `struct device`. | |
| 33 | crate::device | AsBusDevice | trait | Convert device references to bus device references. Bus devices can implement this trait to allow abstractions to provide the bus device in class device callbacks. This must not be used by drivers and is intended for bus and class device abstractions only. # Safety `AsBusDevice::OFFSET` must be the offset of the embedded base `struct device` field within a bus device structure. | # Safety `AsBusDevice::OFFSET` must be the offset of the embedded base `struct device` field within a bus device structure. | |
| 34 | crate::device | AsBusDevice::from_device | trait_method | Convert a reference to [`Device`] into `Self`. # Safety `dev` must be contained in `Self`. | # Safety `dev` must be contained in `Self`. | |
| 35 | crate::device_id | RawDeviceId | trait | Marker trait to indicate a Rust device ID type represents a corresponding C device ID type. This is meant to be implemented by buses/subsystems so that they can use [`IdTable`] to guarantee (at compile-time) zero-termination of device id tables provided by drivers. # Safety Implementers must ensure that `Self` is layout-compatible with [`RawDeviceId::RawType`]; i.e. it's safe to transmute to `RawType`. This requirement is needed so `IdArray::new` can convert `Self` to `RawType` when building the ID table. Ideally, this should be achieved using a const function that does conversion instead of transmute; however, const trait functions relies on `const_trait_impl` unstable feature, which is broken/gone in Rust 1.73. | # Safety Implementers must ensure that `Self` is layout-compatible with [`RawDeviceId::RawType`]; i.e. it's safe to transmute to `RawType`. This requirement is needed so `IdArray::new` can convert `Self` to `RawType` when building the ID table. Ideally, this should be achieved using a const function that does conversion instead of transmute; however, const trait functions relies on `const_trait_impl` unstable feature, which is broken/gone in Rust 1.73. | |
| 36 | crate::device_id | RawDeviceIdIndex | trait | Extension trait for [`RawDeviceId`] for devices that embed an index or context value. This is typically used when the device ID struct includes a field like `driver_data` that is used to store a pointer-sized value (e.g., an index or context pointer). # Safety Implementers must ensure that `DRIVER_DATA_OFFSET` is the correct offset (in bytes) to the context/data field (e.g., the `driver_data` field) within the raw device ID structure. This field must be correctly sized to hold a `usize`. Ideally, the data should be added during `Self` to `RawType` conversion, but there's currently no way to do it when using traits in const. | # Safety Implementers must ensure that `DRIVER_DATA_OFFSET` is the correct offset (in bytes) to the context/data field (e.g., the `driver_data` field) within the raw device ID structure. This field must be correctly sized to hold a `usize`. Ideally, the data should be added during `Self` to `RawType` conversion, but there's currently no way to do it when using traits in const. | |
| 37 | crate::dma | as_slice | method | Returns the data from the region starting from `offset` as a slice. `offset` and `count` are in units of `T`, not the number of bytes. For ringbuffer type of r/w access or use-cases where the pointer to the live data is needed, [`CoherentAllocation::start_ptr`] or [`CoherentAllocation::start_ptr_mut`] could be used instead. # Safety * Callers must ensure that the device does not read/write to/from memory while the returned slice is live. * Callers must ensure that this call does not race with a write to the same region while the returned slice is live. | # Safety * Callers must ensure that the device does not read/write to/from memory while the returned slice is live. * Callers must ensure that this call does not race with a write to the same region while the returned slice is live. | |
| 38 | crate::dma | as_slice_mut | method | Performs the same functionality as [`CoherentAllocation::as_slice`], except that a mutable slice is returned. # Safety * Callers must ensure that the device does not read/write to/from memory while the returned slice is live. * Callers must ensure that this call does not race with a read or write to the same region while the returned slice is live. | # Safety * Callers must ensure that the device does not read/write to/from memory while the returned slice is live. * Callers must ensure that this call does not race with a read or write to the same region while the returned slice is live. | |
| 39 | crate::dma | field_read | method | Reads the value of `field` and ensures that its type is [`FromBytes`]. # Safety This must be called from the [`dma_read`] macro which ensures that the `field` pointer is validated beforehand. Public but hidden since it should only be used from [`dma_read`] macro. | # Safety This must be called from the [`dma_read`] macro which ensures that the `field` pointer is validated beforehand. Public but hidden since it should only be used from [`dma_read`] macro. | |
| 40 | crate::dma | field_write | method | Writes a value to `field` and ensures that its type is [`AsBytes`]. # Safety This must be called from the [`dma_write`] macro which ensures that the `field` pointer is validated beforehand. Public but hidden since it should only be used from [`dma_write`] macro. | # Safety This must be called from the [`dma_write`] macro which ensures that the `field` pointer is validated beforehand. Public but hidden since it should only be used from [`dma_write`] macro. | |
| 41 | crate::dma | write | method | Writes data to the region starting from `offset`. `offset` is in units of `T`, not the number of bytes. # Safety * Callers must ensure that this call does not race with a read or write to the same region that overlaps with this write. # Examples ``` # fn test(alloc: &mut kernel::dma::CoherentAllocation<u8>) -> Result { let somedata: [u8; 4] = [0xf; 4]; let buf: &[u8] = &somedata; // SAFETY: There is no concurrent HW operation on the device and no other R/W access to the // region. unsafe { alloc.write(buf, 0)?; } # Ok::<(), Error>(()) } ``` | # Safety * Callers must ensure that this call does not race with a read or write to the same region that overlaps with this write. | |
| 42 | crate::driver | DriverLayout | trait | Trait describing the layout of a specific device driver. This trait describes the layout of a specific driver structure, such as `struct pci_driver` or `struct platform_driver`. # Safety Implementors must guarantee that: - `DriverType` is `repr(C)`, - `DriverData` is the type of the driver's device private data. - `DriverType` embeds a valid `struct device_driver` at byte offset `DEVICE_DRIVER_OFFSET`. | # Safety Implementors must guarantee that: - `DriverType` is `repr(C)`, - `DriverData` is the type of the driver's device private data. - `DriverType` embeds a valid `struct device_driver` at byte offset `DEVICE_DRIVER_OFFSET`. | |
| 43 | crate::driver | RegistrationOps | trait | The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform, Amba, etc.) to provide the corresponding subsystem specific implementation to register / unregister a driver of the particular type (`DriverType`). For instance, the PCI subsystem would set `DriverType` to `bindings::pci_driver` and call `bindings::__pci_register_driver` from `RegistrationOps::register` and `bindings::pci_unregister_driver` from `RegistrationOps::unregister`. # Safety A call to [`RegistrationOps::unregister`] for a given instance of `DriverType` is only valid if a preceding call to [`RegistrationOps::register`] has been successful. | # Safety A call to [`RegistrationOps::unregister`] for a given instance of `DriverType` is only valid if a preceding call to [`RegistrationOps::register`] has been successful. | |
| 44 | crate::driver | RegistrationOps::register | trait_method | Registers a driver. # Safety On success, `reg` must remain pinned and valid until the matching call to [`RegistrationOps::unregister`]. | # Safety On success, `reg` must remain pinned and valid until the matching call to [`RegistrationOps::unregister`]. | |
| 45 | crate::driver | RegistrationOps::unregister | trait_method | Unregisters a driver previously registered with [`RegistrationOps::register`]. # Safety Must only be called after a preceding successful call to [`RegistrationOps::register`] for the same `reg`. | # Safety Must only be called after a preceding successful call to [`RegistrationOps::register`] for the same `reg`. | |
| 46 | crate::drm::device | from_raw | method | Not intended to be called externally, except via declare_drm_ioctls!() # Safety Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C `struct drm_device` `ptr` points to can't drop to zero, for the duration of this function call and the entire duration when the returned reference exists. Additionally, callers must ensure that the `struct device`, `ptr` is pointing to, is embedded in `Self`. | # Safety Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C `struct drm_device` `ptr` points to can't drop to zero, for the duration of this function call and the entire duration when the returned reference exists. Additionally, callers must ensure that the `struct device`, `ptr` is pointing to, is embedded in `Self`. | |
| 47 | crate::drm::file | from_raw | method | Not intended to be called externally, except via declare_drm_ioctls!() # Safety `raw_file` must be a valid pointer to an open `struct drm_file`, opened through `T::open`. | # Safety `raw_file` must be a valid pointer to an open `struct drm_file`, opened through `T::open`. | |
| 48 | crate::fs::file | assume_no_fdget_pos | method | Assume that there are no active `fdget_pos` calls that prevent us from sharing this file. This makes it safe to transfer this file to other threads. No checks are performed, and using it incorrectly may lead to a data race on the file position if the file is shared with another thread. This method is intended to be used together with [`LocalFile::fget`] when the caller knows statically that there are no `fdget_pos` calls on the current thread. For example, you might use it when calling `fget` from an ioctl, since ioctls usually do not touch the file position. # Safety There must not be any active `fdget_pos` calls on the current thread. | # Safety There must not be any active `fdget_pos` calls on the current thread. | |
| 49 | crate::fs::file | from_raw_file | method | Creates a reference to a [`LocalFile`] from a valid pointer. # Safety * The caller must ensure that `ptr` points at a valid file and that the file's refcount is positive for the duration of `'a`. * The caller must ensure that if there is an active call to `fdget_pos` that did not take the `f_pos_lock` mutex, then that call is on the current thread. | # Safety * The caller must ensure that `ptr` points at a valid file and that the file's refcount is positive for the duration of `'a`. * The caller must ensure that if there is an active call to `fdget_pos` that did not take the `f_pos_lock` mutex, then that call is on the current thread. | |
| 50 | crate::fs::file | from_raw_file | method | Creates a reference to a [`File`] from a valid pointer. # Safety * The caller must ensure that `ptr` points at a valid file and that the file's refcount is positive for the duration of `'a`. * The caller must ensure that if there are active `fdget_pos` calls on this file, then they took the `f_pos_lock` mutex. | # Safety * The caller must ensure that `ptr` points at a valid file and that the file's refcount is positive for the duration of `'a`. * The caller must ensure that if there are active `fdget_pos` calls on this file, then they took the `f_pos_lock` mutex. | |
| 51 | crate::fs::kiocb | from_raw | method | Create a `Kiocb` from a raw pointer. # Safety The pointer must reference a valid `struct kiocb` for the duration of `'a`. The private data of the file must be `T`. | # Safety The pointer must reference a valid `struct kiocb` for the duration of `'a`. The private data of the file must be `T`. | |
| 52 | crate::io | from_raw | method | Converts an `MmioRaw` into an `Mmio` instance, providing the accessors to the MMIO mapping. # Safety Callers must ensure that `addr` is the start of a valid I/O mapped memory region of size `maxsize`. | # Safety Callers must ensure that `addr` is the start of a valid I/O mapped memory region of size `maxsize`. | |
| 53 | crate::iommu::pgtable | map_pages | method | Map a physically contiguous range of pages of the same size. Even if successful, this operation may not map the entire range. In that case, only a prefix of the range is mapped, and the returned integer indicates its length in bytes. In this case, the caller will usually call `map_pages` again for the remaining range. The returned [`Result`] indicates whether an error was encountered while mapping pages. Note that this may return a non-zero length even if an error was encountered. The caller will usually [unmap the relevant pages](Self::unmap_pages) on error. The caller must flush the TLB before using the pgtable to access the newly created mapping. # Safety * No other io-pgtable operation may access the range `iova .. iova+pgsize*pgcount` while this `map_pages` operation executes. * This page table must not contain any mapping that overlaps with the mapping created by this call. * If this page table is live, then the caller must ensure that it's okay to access the physical address being mapped for the duration in which it is mapped. | # Safety * No other io-pgtable operation may access the range `iova .. iova+pgsize*pgcount` while this `map_pages` operation executes. * This page table must not contain any mapping that overlaps with the mapping created by this call. * If this page table is live, then the caller must ensure that it's okay to access the physical address being mapped for the duration in which it is mapped. | |
| 54 | crate::iommu::pgtable | new_raw | method | Create a new `IoPageTable`. # Safety If successful, then the returned `IoPageTable` must be dropped before the device is unbound. | # Safety If successful, then the returned `IoPageTable` must be dropped before the device is unbound. | |
| 55 | crate::iommu::pgtable | ttbr | method | Access the `ttbr` field of the configuration. This is the physical address of the page table, which may be passed to the device that needs to use it. # Safety The caller must ensure that the device stops using the page table before dropping it. | # Safety The caller must ensure that the device stops using the page table before dropping it. | |
| 56 | crate::iommu::pgtable | unmap_pages | method | Unmap a range of virtually contiguous pages of the same size. This may not unmap the entire range, and returns the length of the unmapped prefix in bytes. # Safety * No other io-pgtable operation may access the range `iova .. iova+pgsize*pgcount` while this `unmap_pages` operation executes. * This page table must contain one or more consecutive mappings starting at `iova` whose total size is `pgcount * pgsize`. | # Safety * No other io-pgtable operation may access the range `iova .. iova+pgsize*pgcount` while this `unmap_pages` operation executes. * This page table must contain one or more consecutive mappings starting at `iova` whose total size is `pgcount * pgsize`. | |
| 57 | crate::iov | from_raw | method | Obtain an `IovIterSource` from a raw pointer. # Safety * The referenced `struct iov_iter` must be valid and must only be accessed through the returned reference for the duration of `'iov`. * The referenced `struct iov_iter` must have `data_source` set to `ITER_SOURCE`. * For the duration of `'data`, it must be safe to read from this IO vector using the standard C methods for this purpose. | # Safety * The referenced `struct iov_iter` must be valid and must only be accessed through the returned reference for the duration of `'iov`. * The referenced `struct iov_iter` must have `data_source` set to `ITER_SOURCE`. * For the duration of `'data`, it must be safe to read from this IO vector using the standard C methods for this purpose. | |
| 58 | crate::iov | from_raw | method | Obtain an `IovIterDest` from a raw pointer. # Safety * The referenced `struct iov_iter` must be valid and must only be accessed through the returned reference for the duration of `'iov`. * The referenced `struct iov_iter` must have `data_source` set to `ITER_DEST`. * For the duration of `'data`, it must be safe to write to this IO vector using the standard C methods for this purpose. | # Safety * The referenced `struct iov_iter` must be valid and must only be accessed through the returned reference for the duration of `'iov`. * The referenced `struct iov_iter` must have `data_source` set to `ITER_DEST`. * For the duration of `'data`, it must be safe to write to this IO vector using the standard C methods for this purpose. | |
| 59 | crate::iov | revert | method | Advance this IO vector backwards by `bytes` bytes. # Safety The IO vector must not be reverted to before its beginning. | # Safety The IO vector must not be reverted to before its beginning. | |
| 60 | crate::iov | revert | method | Advance this IO vector backwards by `bytes` bytes. # Safety The IO vector must not be reverted to before its beginning. | # Safety The IO vector must not be reverted to before its beginning. | |
| 61 | crate::list | raw_get_self_ptr | method | Returns a pointer to the self pointer. # Safety The provided pointer must point at a valid struct of type `Self`. | # Safety The provided pointer must point at a valid struct of type `Self`. | |
| 62 | crate::list | remove | method | Removes the provided item from this list and returns it. This returns `None` if the item is not in the list. (Note that by the safety requirements, this means that the item is not in any list.) When using this method, be careful with using `mem::take` on the same list as that may result in violating the safety requirements of this method. # Safety `item` must not be in a different linked list (with the same id). | # Safety `item` must not be in a different linked list (with the same id). | |
| 63 | crate::list | ListItem | trait | Implemented by types where a [`ListArc<Self>`] can be inserted into a [`List`]. # Safety Implementers must ensure that they provide the guarantees documented on methods provided by this trait. [`ListArc<Self>`]: ListArc | # Safety Implementers must ensure that they provide the guarantees documented on methods provided by this trait. [`ListArc<Self>`]: ListArc | |
| 64 | crate::list | ListItem::post_remove | trait_method | This undoes a previous call to `prepare_to_insert`. # Guarantees The returned pointer is the pointer that was originally passed to `prepare_to_insert`. # Safety The provided pointer must be the pointer returned by the most recent call to `prepare_to_insert`. | # Safety The provided pointer must be the pointer returned by the most recent call to `prepare_to_insert`. | |
| 65 | crate::list | ListItem::prepare_to_insert | trait_method | This is called when an item is inserted into a [`List`]. # Guarantees The caller is granted exclusive access to the returned [`ListLinks`] until `post_remove` is called. # Safety * The provided pointer must point at a valid value in an [`Arc`]. * Calls to `prepare_to_insert` and `post_remove` on the same value must alternate. * The caller must own the [`ListArc`] for this value. * The caller must not give up ownership of the [`ListArc`] unless `post_remove` has been called after this call to `prepare_to_insert`. [`Arc`]: crate::sync::Arc | # Safety * The provided pointer must point at a valid value in an [`Arc`]. * Calls to `prepare_to_insert` and `post_remove` on the same value must alternate. * The caller must own the [`ListArc`] for this value. * The caller must not give up ownership of the [`ListArc`] unless `post_remove` has been called after this call to `prepare_to_insert`. [`Arc`]: crate::sync::Arc | |
| 66 | crate::list | ListItem::view_links | trait_method | Views the [`ListLinks`] for this value. # Guarantees If there is a previous call to `prepare_to_insert` and there is no call to `post_remove` since the most recent such call, then this returns the same pointer as the one returned by the most recent call to `prepare_to_insert`. Otherwise, the returned pointer points at a read-only [`ListLinks`] with two null pointers. # Safety The provided pointer must point at a valid value. (It need not be in an `Arc`.) | # Safety The provided pointer must point at a valid value. (It need not be in an `Arc`.) | |
| 67 | crate::list | ListItem::view_value | trait_method | View the full value given its [`ListLinks`] field. Can only be used when the value is in a list. # Guarantees * Returns the same pointer as the one passed to the most recent call to `prepare_to_insert`. * The returned pointer is valid until the next call to `post_remove`. # Safety * The provided pointer must originate from the most recent call to `prepare_to_insert`, or from a call to `view_links` that happened after the most recent call to `prepare_to_insert`. * Since the most recent call to `prepare_to_insert`, the `post_remove` method must not have been called. | # Safety * The provided pointer must originate from the most recent call to `prepare_to_insert`, or from a call to `view_links` that happened after the most recent call to `prepare_to_insert`. * Since the most recent call to `prepare_to_insert`, the `post_remove` method must not have been called. | |
| 68 | crate::list::arc | from_raw | method | Take ownership of the `ListArc` from a raw pointer. # Safety * `ptr` must satisfy the safety requirements of [`Arc::from_raw`]. * The value must not already have a `ListArc` reference. * The tracking inside `T` must think that there is a `ListArc` reference. | # Safety * `ptr` must satisfy the safety requirements of [`Arc::from_raw`]. * The value must not already have a `ListArc` reference. * The tracking inside `T` must think that there is a `ListArc` reference. | |
| 69 | crate::list::arc | TryNewListArc | trait | Declares that this type is able to safely attempt to create `ListArc`s at any time. # Safety The guarantees of `try_new_list_arc` must be upheld. | # Safety The guarantees of `try_new_list_arc` must be upheld. | |
| 70 | crate::list::arc_field | assert_mut | method | Unsafely assert that you have mutable access to the `ListArc` for this field. # Safety The caller must have mutable access to the `ListArc<ID>` containing the struct with this field for the duration of the returned reference. | # Safety The caller must have mutable access to the `ListArc<ID>` containing the struct with this field for the duration of the returned reference. | |
| 71 | crate::list::arc_field | assert_ref | method | Unsafely assert that you have shared access to the `ListArc` for this field. # Safety The caller must have shared access to the `ListArc<ID>` containing the struct with this field for the duration of the returned reference. | # Safety The caller must have shared access to the `ListArc<ID>` containing the struct with this field for the duration of the returned reference. | |
| 72 | crate::list::impl_list_item_mod | HasListLinks | trait | SPDX-License-Identifier: GPL-2.0 Copyright (C) 2024 Google LLC. Helpers for implementing list traits safely. Declares that this type has a [`ListLinks<ID>`] field. This trait is only used to help implement [`ListItem`] safely. If [`ListItem`] is implemented manually, then this trait is not needed. Use the [`impl_has_list_links!`] macro to implement this trait. # Safety The methods on this trait must have exactly the behavior that the definitions given below have. [`ListLinks<ID>`]: crate::list::ListLinks [`ListItem`]: crate::list::ListItem | # Safety The methods on this trait must have exactly the behavior that the definitions given below have. [`ListLinks<ID>`]: crate::list::ListLinks [`ListItem`]: crate::list::ListItem | |
| 73 | crate::list::impl_list_item_mod | HasSelfPtr | trait | Declares that the [`ListLinks<ID>`] field in this struct is inside a [`ListLinksSelfPtr<T, ID>`]. # Safety The [`ListLinks<ID>`] field of this struct at [`HasListLinks<ID>::raw_get_list_links`] must be inside a [`ListLinksSelfPtr<T, ID>`]. [`ListLinks<ID>`]: crate::list::ListLinks [`ListLinksSelfPtr<T, ID>`]: crate::list::ListLinksSelfPtr | # Safety The [`ListLinks<ID>`] field of this struct at [`HasListLinks<ID>::raw_get_list_links`] must be inside a [`ListLinksSelfPtr<T, ID>`]. [`ListLinks<ID>`]: crate::list::ListLinks [`ListLinksSelfPtr<T, ID>`]: crate::list::ListLinksSelfPtr | |
| 74 | crate::list::impl_list_item_mod | HasListLinks::raw_get_list_links | trait_method | Returns a pointer to the [`ListLinks<ID>`] field. # Safety The provided pointer must point at a valid struct of type `Self`. [`ListLinks<ID>`]: crate::list::ListLinks | # Safety The provided pointer must point at a valid struct of type `Self`. [`ListLinks<ID>`]: crate::list::ListLinks | |
| 75 | crate::mm | from_raw | method | Obtain a reference from a raw pointer. # Safety The caller must ensure that `ptr` points at an `mm_struct`, and that it is not deallocated during the lifetime 'a. | # Safety The caller must ensure that `ptr` points at an `mm_struct`, and that it is not deallocated during the lifetime 'a. | |
| 76 | crate::mm | from_raw | method | Obtain a reference from a raw pointer. # Safety The caller must ensure that `ptr` points at an `mm_struct`, and that `mm_users` remains non-zero for the duration of the lifetime 'a. | # Safety The caller must ensure that `ptr` points at an `mm_struct`, and that `mm_users` remains non-zero for the duration of the lifetime 'a. | |
| 77 | crate::mm::virt | from_raw | method | Access a virtual memory area given a raw pointer. # Safety Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap or vma read lock (or stronger) is held for at least the duration of 'a. | # Safety Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap or vma read lock (or stronger) is held for at least the duration of 'a. | |
| 78 | crate::mm::virt | from_raw | method | Access a virtual memory area given a raw pointer. # Safety Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock (or stronger) is held for at least the duration of 'a. The `VM_MIXEDMAP` flag must be set. | # Safety Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock (or stronger) is held for at least the duration of 'a. The `VM_MIXEDMAP` flag must be set. | |
| 79 | crate::mm::virt | from_raw | method | Access a virtual memory area given a raw pointer. # Safety Callers must ensure that `vma` is undergoing initial vma setup for the duration of 'a. | # Safety Callers must ensure that `vma` is undergoing initial vma setup for the duration of 'a. | |
| 80 | crate::opp | from_raw_opp | method | Creates a reference to a [`OPP`] from a valid pointer. The refcount is not updated by the Rust API unless the returned reference is converted to an [`ARef`] object. # Safety The caller must ensure that `ptr` is valid and remains valid for the duration of `'a`. | # Safety The caller must ensure that `ptr` is valid and remains valid for the duration of `'a`. | |
| 81 | crate::opp | from_raw_opp_owned | method | Creates an owned reference to a [`OPP`] from a valid pointer. The refcount is incremented by the C code and will be decremented by `dec_ref` when the [`ARef`] object is dropped. # Safety The caller must ensure that `ptr` is valid and the refcount of the [`OPP`] is incremented. The caller must also ensure that it doesn't explicitly drop the refcount of the [`OPP`], as the returned [`ARef`] object takes over the refcount increment on the underlying object and the same will be dropped along with it. | # Safety The caller must ensure that `ptr` is valid and the refcount of the [`OPP`] is incremented. The caller must also ensure that it doesn't explicitly drop the refcount of the [`OPP`], as the returned [`ARef`] object takes over the refcount increment on the underlying object and the same will be dropped along with it. | |
| 82 | crate::page | copy_from_user_slice_raw | method | Copies data from userspace into this page. This method will perform bounds checks on the page offset. If `offset .. offset+len` goes outside of the page, then this call returns [`EINVAL`]. Like the other `UserSliceReader` methods, data races are allowed on the userspace address. However, they are not allowed on the page you are copying into. # Safety Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write. | # Safety Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write. | |
| 83 | crate::page | fill_zero_raw | method | Maps the page and zeroes the given slice. This method will perform bounds checks on the page offset. If `offset .. offset+len` goes outside of the page, then this call returns [`EINVAL`]. # Safety Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write. | # Safety Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write. | |
| 84 | crate::page | from_raw | method | Constructs a [`BorrowedPage`] from a raw pointer to a `struct page`. # Safety - `ptr` must point to a valid `bindings::page`. - `ptr` must remain valid for the entire lifetime `'a`. | # Safety - `ptr` must point to a valid `bindings::page`. - `ptr` must remain valid for the entire lifetime `'a`. | |
| 85 | crate::page | read_raw | method | Maps the page and reads from it into the given buffer. This method will perform bounds checks on the page offset. If `offset .. offset+len` goes outside of the page, then this call returns [`EINVAL`]. # Safety * Callers must ensure that `dst` is valid for writing `len` bytes. * Callers must ensure that this call does not race with a write to the same page that overlaps with this read. | # Safety * Callers must ensure that `dst` is valid for writing `len` bytes. * Callers must ensure that this call does not race with a write to the same page that overlaps with this read. | |
| 86 | crate::page | write_raw | method | Maps the page and writes into it from the given buffer. This method will perform bounds checks on the page offset. If `offset .. offset+len` goes outside of the page, then this call returns [`EINVAL`]. # Safety * Callers must ensure that `src` is valid for reading `len` bytes. * Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write. | # Safety * Callers must ensure that `src` is valid for reading `len` bytes. * Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write. | |
| 87 | crate::pid_namespace | from_ptr | method | Creates a reference to a [`PidNamespace`] from a valid pointer. # Safety The caller must ensure that `ptr` is valid and remains valid for the lifetime of the returned [`PidNamespace`] reference. | # Safety The caller must ensure that `ptr` is valid and remains valid for the lifetime of the returned [`PidNamespace`] reference. | |
| 88 | crate::print | call_printk | function | Prints a message via the kernel's [`_printk`]. Public but hidden since it should only be used from public macros. # Safety The format string must be one of the ones in [`format_strings`], and the module name must be null-terminated. [`_printk`]: srctree/include/linux/_printk.h | # Safety The format string must be one of the ones in [`format_strings`], and the module name must be null-terminated. [`_printk`]: srctree/include/linux/_printk.h | |
| 89 | crate::revocable | access | method | Directly access the revocable wrapped object. # Safety The caller must ensure this [`Revocable`] instance hasn't been revoked and won't be revoked as long as the returned `&T` lives. | # Safety The caller must ensure this [`Revocable`] instance hasn't been revoked and won't be revoked as long as the returned `&T` lives. | |
| 90 | crate::revocable | revoke_nosync | method | Revokes access to and drops the wrapped object. Access to the object is revoked immediately to new callers of [`Revocable::try_access`], expecting that there are no concurrent users of the object. Returns `true` if `&self` has been revoked with this call, `false` if it was revoked already. # Safety Callers must ensure that there are no more concurrent users of the revocable object. | # Safety Callers must ensure that there are no more concurrent users of the revocable object. | |
| 91 | crate::scatterlist | from_raw | method | Creates a borrowed `&'a SGTable` from a raw `struct sg_table` pointer. This allows safe access to an `sg_table` that is managed elsewhere (for example, in C code). # Safety Callers must ensure that: - the `struct sg_table` pointed to by `ptr` is valid for the entire lifetime of `'a`, - the data behind `ptr` is not modified concurrently for the duration of `'a`. | # Safety Callers must ensure that: - the `struct sg_table` pointed to by `ptr` is valid for the entire lifetime of `'a`, - the data behind `ptr` is not modified concurrently for the duration of `'a`. | |
| 92 | crate::seq_file | from_raw | method | Creates a new [`SeqFile`] from a raw pointer. # Safety The caller must ensure that for the duration of `'a` the following is satisfied: * The pointer points at a valid `struct seq_file`. * The `struct seq_file` is not accessed from any other thread. | # Safety The caller must ensure that for the duration of `'a` the following is satisfied: * The pointer points at a valid `struct seq_file`. * The `struct seq_file` is not accessed from any other thread. | |
| 93 | crate::sync::arc | assume_init | method | Unsafely assume that `self` is initialized. # Safety The caller guarantees that the value behind this pointer has been initialized. It is *immediate* UB to call this when the value is not initialized. | # Safety The caller guarantees that the value behind this pointer has been initialized. It is *immediate* UB to call this when the value is not initialized. | |
| 94 | crate::sync::arc | from_raw | method | Recreates an [`Arc`] instance previously deconstructed via [`Arc::into_raw`]. # Safety `ptr` must have been returned by a previous call to [`Arc::into_raw`]. Additionally, it must not be called more than once for each previous call to [`Arc::into_raw`]. | # Safety `ptr` must have been returned by a previous call to [`Arc::into_raw`]. Additionally, it must not be called more than once for each previous call to [`Arc::into_raw`]. | |
| 95 | crate::sync::arc | from_raw | method | Creates an [`ArcBorrow`] to an [`Arc`] that has previously been deconstructed with [`Arc::into_raw`] or [`Arc::as_ptr`]. # Safety * The provided pointer must originate from a call to [`Arc::into_raw`] or [`Arc::as_ptr`]. * For the duration of the lifetime annotated on this `ArcBorrow`, the reference count must not hit zero. * For the duration of the lifetime annotated on this `ArcBorrow`, there must not be a [`UniqueArc`] reference to this value. | # Safety * The provided pointer must originate from a call to [`Arc::into_raw`] or [`Arc::as_ptr`]. * For the duration of the lifetime annotated on this `ArcBorrow`, the reference count must not hit zero. * For the duration of the lifetime annotated on this `ArcBorrow`, there must not be a [`UniqueArc`] reference to this value. | |
| 96 | crate::sync::aref | from_raw | method | Creates a new instance of [`ARef`]. It takes over an increment of the reference count on the underlying object. # Safety Callers must ensure that the reference count was incremented at least once, and that they are properly relinquishing one increment. That is, if there is only one increment, callers must not use the underlying object anymore -- it is only safe to do so via the newly created [`ARef`]. | # Safety Callers must ensure that the reference count was incremented at least once, and that they are properly relinquishing one increment. That is, if there is only one increment, callers must not use the underlying object anymore -- it is only safe to do so via the newly created [`ARef`]. | |
| 97 | crate::sync::aref | AlwaysRefCounted | trait | Types that are _always_ reference counted. It allows such types to define their own custom ref increment and decrement functions. Additionally, it allows users to convert from a shared reference `&T` to an owned reference [`ARef<T>`]. This is usually implemented by wrappers to existing structures on the C side of the code. For Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted instances of a type. # Safety Implementers must ensure that increments to the reference count keep the object alive in memory at least until matching decrements are performed. Implementers must also ensure that all instances are reference-counted. (Otherwise they won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object alive.) | # Safety Implementers must ensure that increments to the reference count keep the object alive in memory at least until matching decrements are performed. Implementers must also ensure that all instances are reference-counted. (Otherwise they won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object alive.) | |
| 98 | crate::sync::aref | AlwaysRefCounted::dec_ref | trait_method | Decrements the reference count on the object. Frees the object when the count reaches zero. # Safety Callers must ensure that there was a previous matching increment to the reference count, and that the object is no longer used after its reference count is decremented (as it may result in the object being freed), unless the caller owns another increment on the refcount (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls [`AlwaysRefCounted::dec_ref`] once). | # Safety Callers must ensure that there was a previous matching increment to the reference count, and that the object is no longer used after its reference count is decremented (as it may result in the object being freed), unless the caller owns another increment on the refcount (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls [`AlwaysRefCounted::dec_ref`] once). | |
| 99 | crate::sync::atomic | from_ptr | method | Creates a reference to an atomic `T` from a pointer of `T`. This usually is used when communicating with C side or manipulating a C struct, see examples below. # Safety - `ptr` is aligned to `align_of::<T>()`. - `ptr` is valid for reads and writes for `'a`. - For the duration of `'a`, other accesses to `*ptr` must not cause data races (defined by [`LKMM`]) against atomic operations on the returned reference. Note that if all other accesses are atomic, then this safety requirement is trivially fulfilled. [`LKMM`]: srctree/tools/memory-model # Examples Using [`Atomic::from_ptr()`] combined with [`Atomic::load()`] or [`Atomic::store()`] can achieve the same functionality as `READ_ONCE()`/`smp_load_acquire()` or `WRITE_ONCE()`/`smp_store_release()` in C side: ``` # use kernel::types::Opaque; use kernel::sync::atomic::{Atomic, Relaxed, Release}; // Assume there is a C struct `foo`. mod cbindings { #[repr(C)] pub(crate) struct foo { pub(crate) a: i32, pub(crate) b: i32 } } let tmp = Opaque::new(cbindings::foo { a: 1, b: 2 }); // struct foo *foo_ptr = ..; let foo_ptr = tmp.get(); // SAFETY: `foo_ptr` is valid, and `.a` is in bounds. let foo_a_ptr = unsafe { &raw mut (*foo_ptr).a }; // a = READ_ONCE(foo_ptr->a); // // SAFETY: `foo_a_ptr` is valid for read, and all other accesses on it is atomic, so no // data race. let a = unsafe { Atomic::from_ptr(foo_a_ptr) }.load(Relaxed); # assert_eq!(a, 1); // smp_store_release(&foo_ptr->a, 2); // // SAFETY: `foo_a_ptr` is valid for writes, and all other accesses on it is atomic, so // no data race. unsafe { Atomic::from_ptr(foo_a_ptr) }.store(2, Release); ``` | # Safety - `ptr` is aligned to `align_of::<T>()`. - `ptr` is valid for reads and writes for `'a`. - For the duration of `'a`, other accesses to `*ptr` must not cause data races (defined by [`LKMM`]) against atomic operations on the returned reference. Note that if all other accesses are atomic, then this safety requirement is trivially fulfilled. [`LKMM`]: srctree/tools/memory-model | |
| 100 | crate::sync::atomic | AtomicAdd | trait | Types that support atomic add operations. # Safety TODO: Properly defines `wrapping_add` in the following comment. `wrapping_add` any value of type `Self::Repr::Delta` obtained by [`Self::rhs_into_delta()`] to any value of type `Self::Repr` obtained through transmuting a value of type `Self` to must yield a value with a bit pattern also valid for `Self`. | # Safety TODO: Properly defines `wrapping_add` in the following comment. `wrapping_add` any value of type `Self::Repr::Delta` obtained by [`Self::rhs_into_delta()`] to any value of type `Self::Repr` obtained through transmuting a value of type `Self` to must yield a value with a bit pattern also valid for `Self`. | |
| 101 | crate::sync::atomic | AtomicType | trait | Types that support basic atomic operations. # Round-trip transmutability `T` is round-trip transmutable to `U` if and only if both of these properties hold: - Any valid bit pattern for `T` is also a valid bit pattern for `U`. - Transmuting (e.g. using [`transmute()`]) a value of type `T` to `U` and then to `T` again yields a value that is in all aspects equivalent to the original value. # Safety - [`Self`] must have the same size and alignment as [`Self::Repr`]. - [`Self`] must be [round-trip transmutable] to [`Self::Repr`]. Note that this is more relaxed than requiring the bi-directional transmutability (i.e. [`transmute()`] is always sound between `U` and `T`) because of the support for atomic variables over unit-only enums, see [Examples]. # Limitations Because C primitives are used to implement the atomic operations, and a C function requires a valid object of a type to operate on (i.e. no `MaybeUninit<_>`), hence at the Rust <-> C surface, only types with all the bits initialized can be passed. As a result, types like `(u8, u16)` (padding bytes are uninitialized) are currently not supported. # Examples A unit-only enum that implements [`AtomicType`]: ``` use kernel::sync::atomic::{AtomicType, Atomic, Relaxed}; #[derive(Clone, Copy, PartialEq, Eq)] #[repr(i32)] enum State { Uninit = 0, Working = 1, Done = 2, }; // SAFETY: `State` and `i32` has the same size and alignment, and it's round-trip // transmutable to `i32`. unsafe impl AtomicType for State { type Repr = i32; } let s = Atomic::new(State::Uninit); assert_eq!(State::Uninit, s.load(Relaxed)); ``` [`transmute()`]: core::mem::transmute [round-trip transmutable]: AtomicType#round-trip-transmutability [Examples]: AtomicType#examples | # Safety - [`Self`] must have the same size and alignment as [`Self::Repr`]. - [`Self`] must be [round-trip transmutable] to [`Self::Repr`]. Note that this is more relaxed than requiring the bi-directional transmutability (i.e. [`transmute()`] is always sound between `U` and `T`) because of the support for atomic variables over unit-only enums, see [Examples]. | |
| 102 | crate::sync::lock | from_raw | method | Constructs a [`Lock`] from a raw pointer. This can be useful for interacting with a lock which was initialised outside of Rust. # Safety The caller promises that `ptr` points to a valid initialised instance of [`State`] during the whole lifetime of `'a`. [`State`]: Backend::State | # Safety The caller promises that `ptr` points to a valid initialised instance of [`State`] during the whole lifetime of `'a`. [`State`]: Backend::State | |
| 103 | crate::sync::lock | new | method | Constructs a new immutable lock guard. # Safety The caller must ensure that it owns the lock. | # Safety The caller must ensure that it owns the lock. | |
| 104 | crate::sync::lock | Backend | trait | The "backend" of a lock. It is the actual implementation of the lock, without the need to repeat patterns used in all locks. # Safety - Implementers must ensure that only one thread/CPU may access the protected data once the lock is owned, that is, between calls to [`lock`] and [`unlock`]. - Implementers must also ensure that [`relock`] uses the same locking method as the original lock operation. [`lock`]: Backend::lock [`unlock`]: Backend::unlock [`relock`]: Backend::relock | # Safety - Implementers must ensure that only one thread/CPU may access the protected data once the lock is owned, that is, between calls to [`lock`] and [`unlock`]. - Implementers must also ensure that [`relock`] uses the same locking method as the original lock operation. [`lock`]: Backend::lock [`unlock`]: Backend::unlock [`relock`]: Backend::relock | |
| 105 | crate::sync::lock | Backend::assert_is_held | trait_method | Asserts that the lock is held using lockdep. # Safety Callers must ensure that [`Backend::init`] has been previously called. | # Safety Callers must ensure that [`Backend::init`] has been previously called. | |
| 106 | crate::sync::lock | Backend::init | trait_method | Initialises the lock. # Safety `ptr` must be valid for write for the duration of the call, while `name` and `key` must remain valid for read indefinitely. | # Safety `ptr` must be valid for write for the duration of the call, while `name` and `key` must remain valid for read indefinitely. | |
| 107 | crate::sync::lock | Backend::lock | trait_method | Acquires the lock, making the caller its owner. # Safety Callers must ensure that [`Backend::init`] has been previously called. | # Safety Callers must ensure that [`Backend::init`] has been previously called. | |
| 108 | crate::sync::lock | Backend::relock | trait_method | Reacquires the lock, making the caller its owner. # Safety Callers must ensure that `guard_state` comes from a previous call to [`Backend::lock`] (or variant) that has been unlocked with [`Backend::unlock`] and will be relocked now. | # Safety Callers must ensure that `guard_state` comes from a previous call to [`Backend::lock`] (or variant) that has been unlocked with [`Backend::unlock`] and will be relocked now. | |
| 109 | crate::sync::lock | Backend::try_lock | trait_method | Tries to acquire the lock. # Safety Callers must ensure that [`Backend::init`] has been previously called. | # Safety Callers must ensure that [`Backend::init`] has been previously called. | |
| 110 | crate::sync::lock | Backend::unlock | trait_method | Releases the lock, giving up its ownership. # Safety It must only be called by the current owner of the lock. | # Safety It must only be called by the current owner of the lock. | |
| 111 | crate::sync::lock::global | init | method | Initializes a global lock. # Safety Must not be called more than once on a given lock. | # Safety Must not be called more than once on a given lock. | |
| 112 | crate::sync::poll | from_raw | method | Creates a [`PollTable`] from a valid pointer. # Safety The pointer must be null or reference a valid `poll_table` for the duration of `'a`. | # Safety The pointer must be null or reference a valid `poll_table` for the duration of `'a`. | |
| 113 | crate::task | current | method | Returns a task reference for the currently executing task/thread. The recommended way to get the current task/thread is to use the [`current`] macro because it is safe. # Safety Callers must ensure that the returned object is only used to access a [`CurrentTask`] within the task context that was active when this function was called. For more details, see the invariants section for [`CurrentTask`]. | # Safety Callers must ensure that the returned object is only used to access a [`CurrentTask`] within the task context that was active when this function was called. For more details, see the invariants section for [`CurrentTask`]. | |
| 114 | crate::time::hrtimer | HasHrTimer | trait | Implemented by structs that contain timer nodes. Clients of the timer API would usually safely implement this trait by using the [`crate::impl_has_hr_timer`] macro. # Safety Implementers of this trait must ensure that the implementer has a [`HrTimer`] field and that all trait methods are implemented according to their documentation. All the methods of this trait must operate on the same field. | # Safety Implementers of this trait must ensure that the implementer has a [`HrTimer`] field and that all trait methods are implemented according to their documentation. All the methods of this trait must operate on the same field. | |
| 115 | crate::time::hrtimer | HrTimerHandle | trait | A handle representing a potentially running timer. More than one handle representing the same timer might exist. # Safety When dropped, the timer represented by this handle must be cancelled, if it is running. If the timer handler is running when the handle is dropped, the drop method must wait for the handler to return before returning. Note: One way to satisfy the safety requirement is to call `Self::cancel` in the drop implementation for `Self.` | # Safety When dropped, the timer represented by this handle must be cancelled, if it is running. If the timer handler is running when the handle is dropped, the drop method must wait for the handler to return before returning. Note: One way to satisfy the safety requirement is to call `Self::cancel` in the drop implementation for `Self.` | |
| 116 | crate::time::hrtimer | ScopedHrTimerPointer | trait | A trait for stack allocated timers. # Safety Implementers must ensure that `start_scoped` does not return until the timer is dead and the timer handler is not running. | # Safety Implementers must ensure that `start_scoped` does not return until the timer is dead and the timer handler is not running. | |
| 117 | crate::time::hrtimer | UnsafeHrTimerPointer | trait | Unsafe version of [`HrTimerPointer`] for situations where leaking the [`HrTimerHandle`] returned by `start` would be unsound. This is the case for stack allocated timers. Typical implementers are pinned references such as [`Pin<&T>`]. # Safety Implementers of this trait must ensure that instances of types implementing [`UnsafeHrTimerPointer`] outlives any associated [`HrTimerPointer::TimerHandle`] instances. | # Safety Implementers of this trait must ensure that instances of types implementing [`UnsafeHrTimerPointer`] outlives any associated [`HrTimerPointer::TimerHandle`] instances. | |
| 118 | crate::time::hrtimer | HasHrTimer::c_timer_ptr | trait_method | Get pointer to the contained `bindings::hrtimer` struct. This function is useful to get access to the value without creating intermediate references. # Safety `this` must be a valid pointer. | # Safety `this` must be a valid pointer. | |
| 119 | crate::time::hrtimer | HasHrTimer::raw_get_timer | trait_method | Return a pointer to the [`HrTimer`] within `Self`. This function is useful to get access to the value without creating intermediate references. # Safety `this` must be a valid pointer. | # Safety `this` must be a valid pointer. | |
| 120 | crate::time::hrtimer | HasHrTimer::start | trait_method | Start the timer contained in the `Self` pointed to by `self_ptr`. If it is already running it is removed and inserted. # Safety - `this` must point to a valid `Self`. - Caller must ensure that the pointee of `this` lives until the timer fires or is canceled. | # Safety - `this` must point to a valid `Self`. - Caller must ensure that the pointee of `this` lives until the timer fires or is canceled. | |
| 121 | crate::time::hrtimer | HasHrTimer::timer_container_of | trait_method | Return a pointer to the struct that is containing the [`HrTimer`] pointed to by `ptr`. This function is useful to get access to the value without creating intermediate references. # Safety `ptr` must point to a [`HrTimer<T>`] field in a struct of type `Self`. | # Safety `ptr` must point to a [`HrTimer<T>`] field in a struct of type `Self`. | |
| 122 | crate::time::hrtimer | UnsafeHrTimerPointer::start | trait_method | Start the timer after `expires` time units. If the timer was already running, it is restarted at the new expiry time. # Safety Caller promises keep the timer structure alive until the timer is dead. Caller can ensure this by not leaking the returned [`Self::TimerHandle`]. | # Safety Caller promises keep the timer structure alive until the timer is dead. Caller can ensure this by not leaking the returned [`Self::TimerHandle`]. | |
| 123 | crate::transmute | AsBytes | trait | Types that can be viewed as an immutable slice of initialized bytes. If a struct implements this trait, then it is okay to copy it byte-for-byte to userspace. This means that it should not have any padding, as padding bytes are uninitialized. Reading uninitialized memory is not just undefined behavior, it may even lead to leaking sensitive information on the stack to userspace. The struct should also not hold kernel pointers, as kernel pointer addresses are also considered sensitive. However, leaking kernel pointers is not considered undefined behavior by Rust, so this is a correctness requirement, but not a safety requirement. # Safety Values of this type may not contain any uninitialized bytes. This type must not have interior mutability. | # Safety Values of this type may not contain any uninitialized bytes. This type must not have interior mutability. | |
| 124 | crate::transmute | FromBytes | trait | Types for which any bit pattern is valid. Not all types are valid for all values. For example, a `bool` must be either zero or one, so reading arbitrary bytes into something that contains a `bool` is not okay. It's okay for the type to have padding, as initializing those bytes has no effect. # Examples ``` use kernel::transmute::FromBytes; # fn test() -> Option<()> { let raw = [1, 2, 3, 4]; let result = u32::from_bytes(&raw)?; #[cfg(target_endian = "little")] assert_eq!(*result, 0x4030201); #[cfg(target_endian = "big")] assert_eq!(*result, 0x1020304); # Some(()) } # test().ok_or(EINVAL)?; # Ok::<(), Error>(()) ``` # Safety All bit-patterns must be valid for this type. This type must not have interior mutability. | # Safety All bit-patterns must be valid for this type. This type must not have interior mutability. | |
| 125 | crate::types | ForeignOwnable | trait | 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. # Safety - Implementations must satisfy the guarantees of [`Self::into_foreign`]. | # Safety - Implementations must satisfy the guarantees of [`Self::into_foreign`]. | |
| 126 | crate::types | ForeignOwnable::borrow | trait_method | Borrows a foreign-owned object immutably. This method provides a way to access a foreign-owned value from Rust immutably. It provides you with exactly the same abilities as an `&Self` when the value is Rust-owned. # Safety The provided pointer must have been returned by a previous call to [`into_foreign`], and if the pointer is ever passed to [`from_foreign`], then that call must happen after the end of the lifetime `'a`. [`into_foreign`]: Self::into_foreign [`from_foreign`]: Self::from_foreign | # Safety The provided pointer must have been returned by a previous call to [`into_foreign`], and if the pointer is ever passed to [`from_foreign`], then that call must happen after the end of the lifetime `'a`. [`into_foreign`]: Self::into_foreign [`from_foreign`]: Self::from_foreign | |
| 127 | crate::types | ForeignOwnable::borrow_mut | trait_method | Borrows a foreign-owned object mutably. This method provides a way to access a foreign-owned value from Rust mutably. It provides you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except that the address of the object must not be changed. Note that for types like [`Arc`], an `&mut Arc<T>` only gives you immutable access to the inner value, so this method also only provides immutable access in that case. In the case of `Box<T>`, this method gives you the ability to modify the inner `T`, but it does not let you change the box itself. That is, you cannot change which allocation the box points at. # Safety The provided pointer must have been returned by a previous call to [`into_foreign`], and if the pointer is ever passed to [`from_foreign`], then that call must happen after the end of the lifetime `'a`. The lifetime `'a` must not overlap with the lifetime of any other call to [`borrow`] or `borrow_mut` on the same object. [`into_foreign`]: Self::into_foreign [`from_foreign`]: Self::from_foreign [`borrow`]: Self::borrow [`Arc`]: crate::sync::Arc | # Safety The provided pointer must have been returned by a previous call to [`into_foreign`], and if the pointer is ever passed to [`from_foreign`], then that call must happen after the end of the lifetime `'a`. The lifetime `'a` must not overlap with the lifetime of any other call to [`borrow`] or `borrow_mut` on the same object. [`into_foreign`]: Self::into_foreign [`from_foreign`]: Self::from_foreign [`borrow`]: Self::borrow [`Arc`]: crate::sync::Arc | |
| 128 | crate::types | ForeignOwnable::from_foreign | trait_method | Converts a foreign-owned object back to a Rust-owned one. # Safety The provided pointer must have been returned by a previous call to [`into_foreign`], and it must not be passed to `from_foreign` more than once. [`into_foreign`]: Self::into_foreign | # Safety The provided pointer must have been returned by a previous call to [`into_foreign`], and it must not be passed to `from_foreign` more than once. [`into_foreign`]: Self::into_foreign | |
| 129 | crate::types | ForeignOwnable::try_from_foreign | trait_method | Tries to convert a foreign-owned object back to a Rust-owned one. A convenience wrapper over [`ForeignOwnable::from_foreign`] that returns [`None`] if `ptr` is null. # Safety `ptr` must either be null or satisfy the safety requirements for [`from_foreign`]. [`from_foreign`]: Self::from_foreign | # Safety `ptr` must either be null or satisfy the safety requirements for [`from_foreign`]. [`from_foreign`]: Self::from_foreign | |
| 130 | crate::workqueue | from_raw | method | Use the provided `struct workqueue_struct` with Rust. # Safety The caller must ensure that the provided raw pointer is not dangling, that it points at a valid workqueue, and that it remains valid until the end of `'a`. | # Safety The caller must ensure that the provided raw pointer is not dangling, that it points at a valid workqueue, and that it remains valid until the end of `'a`. | |
| 131 | crate::workqueue | raw_as_work | method | Get a pointer to the inner `delayed_work`. # Safety The provided pointer must not be dangling and must be properly aligned. (But the memory need not be initialized.) | # Safety The provided pointer must not be dangling and must be properly aligned. (But the memory need not be initialized.) | |
| 132 | crate::workqueue | raw_get | method | Get a pointer to the inner `work_struct`. # Safety The provided pointer must not be dangling and must be properly aligned. (But the memory need not be initialized.) | # Safety The provided pointer must not be dangling and must be properly aligned. (But the memory need not be initialized.) | |
| 133 | crate::workqueue | HasDelayedWork | trait | Declares that a type contains a [`DelayedWork<T, ID>`]. # Safety The `HasWork<T, ID>` implementation must return a `work_struct` that is stored in the `work` field of a `delayed_work` with the same access rules as the `work_struct`. | # Safety The `HasWork<T, ID>` implementation must return a `work_struct` that is stored in the `work` field of a `delayed_work` with the same access rules as the `work_struct`. | |
| 134 | crate::workqueue | HasWork | trait | Declares that a type contains a [`Work<T, ID>`]. The intended way of using this trait is via the [`impl_has_work!`] macro. You can use the macro like this: ```no_run use kernel::workqueue::{impl_has_work, Work}; struct MyWorkItem { work_field: Work<MyWorkItem, 1>, } impl_has_work! { impl HasWork<MyWorkItem, 1> for MyWorkItem { self.work_field } } ``` Note that since the [`Work`] type is annotated with an id, you can have several `work_struct` fields by using a different id for each one. # Safety The methods [`raw_get_work`] and [`work_container_of`] must return valid pointers and must be true inverses of each other; that is, they must satisfy the following invariants: - `work_container_of(raw_get_work(ptr)) == ptr` for any `ptr: *mut Self`. - `raw_get_work(work_container_of(ptr)) == ptr` for any `ptr: *mut Work<T, ID>`. [`impl_has_work!`]: crate::impl_has_work [`raw_get_work`]: HasWork::raw_get_work [`work_container_of`]: HasWork::work_container_of | # Safety The methods [`raw_get_work`] and [`work_container_of`] must return valid pointers and must be true inverses of each other; that is, they must satisfy the following invariants: - `work_container_of(raw_get_work(ptr)) == ptr` for any `ptr: *mut Self`. - `raw_get_work(work_container_of(ptr)) == ptr` for any `ptr: *mut Work<T, ID>`. [`impl_has_work!`]: crate::impl_has_work [`raw_get_work`]: HasWork::raw_get_work [`work_container_of`]: HasWork::work_container_of | |
| 135 | crate::workqueue | RawDelayedWorkItem | trait | A raw delayed work item. # Safety If the `__enqueue` method in the `RawWorkItem` implementation calls the closure, then the provided pointer must point at the `work` field of a valid `delayed_work`, and the guarantees that `__enqueue` provides about accessing the `work_struct` must also apply to the rest of the `delayed_work` struct. | # Safety If the `__enqueue` method in the `RawWorkItem` implementation calls the closure, then the provided pointer must point at the `work` field of a valid `delayed_work`, and the guarantees that `__enqueue` provides about accessing the `work_struct` must also apply to the rest of the `delayed_work` struct. | |
| 136 | crate::workqueue | RawWorkItem | trait | A raw work item. This is the low-level trait that is designed for being as general as possible. The `ID` parameter to this trait exists so that a single type can provide multiple implementations of this trait. For example, if a struct has multiple `work_struct` fields, then you will implement this trait once for each field, using a different id for each field. The actual value of the id is not important as long as you use different ids for different fields of the same struct. (Fields of different structs need not use different ids.) Note that the id is used only to select the right method to call during compilation. It won't be part of the final executable. # Safety Implementers must ensure that any pointers passed to a `queue_work_on` closure by [`__enqueue`] remain valid for the duration specified in the guarantees section of the documentation for [`__enqueue`]. [`__enqueue`]: RawWorkItem::__enqueue | # Safety Implementers must ensure that any pointers passed to a `queue_work_on` closure by [`__enqueue`] remain valid for the duration specified in the guarantees section of the documentation for [`__enqueue`]. [`__enqueue`]: RawWorkItem::__enqueue | |
| 137 | crate::workqueue | WorkItemPointer | trait | Defines the method that should be called directly when a work item is executed. This trait is implemented by `Pin<KBox<T>>` and [`Arc<T>`], and is mainly intended to be implemented for smart pointer types. For your own structs, you would implement [`WorkItem`] instead. The [`run`] method on this trait will usually just perform the appropriate `container_of` translation and then call into the [`run`][WorkItem::run] method from the [`WorkItem`] trait. This trait is used when the `work_struct` field is defined using the [`Work`] helper. # Safety Implementers must ensure that [`__enqueue`] uses a `work_struct` initialized with the [`run`] method of this trait as the function pointer. [`__enqueue`]: RawWorkItem::__enqueue [`run`]: WorkItemPointer::run | # Safety Implementers must ensure that [`__enqueue`] uses a `work_struct` initialized with the [`run`] method of this trait as the function pointer. [`__enqueue`]: RawWorkItem::__enqueue [`run`]: WorkItemPointer::run | |
| 138 | crate::workqueue | HasWork::raw_get_work | trait_method | Returns a pointer to the [`Work<T, ID>`] field. # Safety The provided pointer must point at a valid struct of type `Self`. | # Safety The provided pointer must point at a valid struct of type `Self`. | |
| 139 | crate::workqueue | HasWork::work_container_of | trait_method | Returns a pointer to the struct containing the [`Work<T, ID>`] field. # Safety The pointer must point at a [`Work<T, ID>`] field in a struct of type `Self`. | # Safety The pointer must point at a [`Work<T, ID>`] field in a struct of type `Self`. | |
| 140 | crate::workqueue | RawWorkItem::__enqueue | trait_method | Enqueues this work item on a queue using the provided `queue_work_on` method. # Guarantees If this method calls the provided closure, then the raw pointer is guaranteed to point at a valid `work_struct` for the duration of the call to the closure. If the closure returns true, then it is further guaranteed that the pointer remains valid until someone calls the function pointer stored in the `work_struct`. # Safety The provided closure may only return `false` if the `work_struct` is already in a workqueue. If the work item type is annotated with any lifetimes, then you must not call the function pointer after any such lifetime expires. (Never calling the function pointer is okay.) If the work item type is not [`Send`], then the function pointer must be called on the same thread as the call to `__enqueue`. | # Safety The provided closure may only return `false` if the `work_struct` is already in a workqueue. If the work item type is annotated with any lifetimes, then you must not call the function pointer after any such lifetime expires. (Never calling the function pointer is okay.) If the work item type is not [`Send`], then the function pointer must be called on the same thread as the call to `__enqueue`. |