rust/kernel/soc.rs

Source file repositories/reference/linux-study-clean/rust/kernel/soc.rs

File Facts

System
Linux kernel
Corpus path
rust/kernel/soc.rs
Extension
.rs
Size
5248 bytes
Lines
136
Domain
Rust Kernel Layer
Bucket
Rust API Membrane
Inferred role
Rust Kernel Layer: implementation source
Status
source implementation candidate

Why This File Exists

Rust-side wrappers and abstractions around kernel C APIs, ownership contracts, allocation, synchronization, and module integration.

Dependency Surface

Detected Declarations

Annotated Snippet

struct BuiltAttributes {
    // While `inner` has pointers to `_backing`, it is to the interior of the `CStrings`, not
    // `backing` itself, so it does not need to be pinned.
    _backing: Attributes,
    // `Opaque` makes us `!Unpin`, as the registration holds a pointer to `inner` when used.
    inner: Opaque<bindings::soc_device_attribute>,
}

fn cstring_to_c(mcs: &Option<CString>) -> *const kernel::ffi::c_char {
    mcs.as_ref()
        .map(|cs| cs.as_char_ptr())
        .unwrap_or(core::ptr::null())
}

impl BuiltAttributes {
    fn as_mut_ptr(&self) -> *mut bindings::soc_device_attribute {
        self.inner.get()
    }
}

impl Attributes {
    fn build(self) -> BuiltAttributes {
        BuiltAttributes {
            inner: Opaque::new(bindings::soc_device_attribute {
                machine: cstring_to_c(&self.machine),
                family: cstring_to_c(&self.family),
                revision: cstring_to_c(&self.revision),
                serial_number: cstring_to_c(&self.serial_number),
                soc_id: cstring_to_c(&self.soc_id),
                data: core::ptr::null(),
                custom_attr_group: core::ptr::null(),
            }),
            _backing: self,
        }
    }
}

#[pin_data(PinnedDrop)]
/// Registration handle for your soc_dev. If you let it go out of scope, your soc_dev will be
/// unregistered.
pub struct Registration {
    #[pin]
    attr: BuiltAttributes,
    soc_dev: NonNull<bindings::soc_device>,
}

// SAFETY: We provide no operations through `&Registration`.
unsafe impl Sync for Registration {}

// SAFETY: All pointers are normal allocations, not thread-specific.
unsafe impl Send for Registration {}

#[pinned_drop]
impl PinnedDrop for Registration {
    fn drop(self: Pin<&mut Self>) {
        // SAFETY: Device always contains a live pointer to a soc_device that can be unregistered
        unsafe { bindings::soc_device_unregister(self.soc_dev.as_ptr()) }
    }
}

impl Registration {
    /// Register a new SoC device
    pub fn new(attr: Attributes) -> impl PinInit<Self, Error> {
        try_pin_init!(Self {
            attr: attr.build(),
            soc_dev: {
                // SAFETY:
                // * The struct provided through attr is backed by pinned data next to it,
                //   so as long as attr lives, the strings pointed to by the struct will too.
                // * `attr` is pinned, so the pinned data won't move.
                // * If it returns a device, and so others may try to read this data, by
                //   caller invariant, `attr` won't be released until the device is.
                let raw_soc = error::from_err_ptr(unsafe {
                    bindings::soc_device_register(attr.as_mut_ptr())
                })?;

                NonNull::new(raw_soc).ok_or(EINVAL)?
            },
        }? Error)
    }
}

Annotation

Implementation Notes