Commit 8d84b320 authored by FUJITA Tomonori's avatar FUJITA Tomonori Committed by Danilo Krummrich
Browse files

rust: device_id: split out index support into a separate trait 



Introduce a new trait `RawDeviceIdIndex`, which extends `RawDeviceId`
to provide support for device ID types that include an index or
context field (e.g., `driver_data`). This separates the concerns of
layout compatibility and index-based data embedding, and allows
`RawDeviceId` to be implemented for types that do not contain a
`driver_data` field. Several such structures are defined in
include/linux/mod_devicetable.h.

Refactor `IdArray::new()` into a generic `build()` function, which
takes an optional offset. Based on the presence of `RawDeviceIdIndex`,
index writing is conditionally enabled. A new `new_without_index()`
constructor is also provided for use cases where no index should be
written.

This refactoring is a preparation for enabling the PHY abstractions to
use the RawDeviceId trait.

The changes to acpi.rs and driver.rs were made by Danilo.

Reviewed-by: default avatarTrevor Gross <tmgross@umich.edu>
Signed-off-by: default avatarFUJITA Tomonori <fujita.tomonori@gmail.com>
Acked-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/20250711040947.1252162-2-fujita.tomonori@gmail.com


Signed-off-by: default avatarDanilo Krummrich <dakr@kernel.org>
parent 2f5606af

rust/kernel/acpi.rs

+10 −5
Original line number Diff line number Diff line
@@ -2,7 +2,11 @@ 


//! Advanced Configuration and Power Interface abstractions.



use crate::{bindings, device_id::RawDeviceId, prelude::*};

use crate::{

    bindings,

    device_id::{RawDeviceId, RawDeviceIdIndex},

    prelude::*,

};



/// IdTable type for ACPI drivers.

pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;
@@ -12,13 +16,14 @@ 
#[derive(Clone, Copy)]

pub struct DeviceId(bindings::acpi_device_id);



// SAFETY:

// * `DeviceId` is a `#[repr(transparent)` wrapper of `struct acpi_device_id` and does not add

// SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `acpi_device_id` and does not add

// additional invariants, so it's safe to transmute to `RawType`.

// * `DRIVER_DATA_OFFSET` is the offset to the `data` field.

unsafe impl RawDeviceId for DeviceId {

    type RawType = bindings::acpi_device_id;

}



// SAFETY: `DRIVER_DATA_OFFSET` is the offset to the `driver_data` field.

unsafe impl RawDeviceIdIndex for DeviceId {

    const DRIVER_DATA_OFFSET: usize = core::mem::offset_of!(bindings::acpi_device_id, driver_data);



    fn index(&self) -> usize {

rust/kernel/auxiliary.rs

+6 −5
Original line number Diff line number Diff line
@@ -6,7 +6,7 @@ 


use crate::{

    bindings, container_of, device,

    device_id::RawDeviceId,

    device_id::{RawDeviceId, RawDeviceIdIndex},

    driver,

    error::{from_result, to_result, Result},

    prelude::*,
@@ -134,13 +134,14 @@ pub const fn new(modname: &'static CStr, name: &'static CStr) -> Self { 
    }

}



// SAFETY:

// * `DeviceId` is a `#[repr(transparent)`] wrapper of `auxiliary_device_id` and does not add

// SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `auxiliary_device_id` and does not add

// additional invariants, so it's safe to transmute to `RawType`.

// * `DRIVER_DATA_OFFSET` is the offset to the `driver_data` field.

unsafe impl RawDeviceId for DeviceId {

    type RawType = bindings::auxiliary_device_id;

}



// SAFETY: `DRIVER_DATA_OFFSET` is the offset to the `driver_data` field.

unsafe impl RawDeviceIdIndex for DeviceId {

    const DRIVER_DATA_OFFSET: usize =

        core::mem::offset_of!(bindings::auxiliary_device_id, driver_data);

rust/kernel/device_id.rs

+66 −25
Original line number Diff line number Diff line
@@ -14,9 +14,8 @@ 
///

/// # Safety

///

/// Implementers must ensure that:

///   - `Self` is layout-compatible with [`RawDeviceId::RawType`]; i.e. it's safe to transmute to

///     `RawDeviceId`.

/// Implementers must ensure that `Self` is layout-compatible with [`RawDeviceId::RawType`];

/// i.e. it's safe to transmute to `RawDeviceId`.

///

/// This requirement is needed so `IdArray::new` can convert `Self` to `RawType` when building

/// the ID table.
@@ -24,22 +23,32 @@ 
/// 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.

///

///   - `DRIVER_DATA_OFFSET` is the offset of context/data field of the device ID (usually named

///     `driver_data`) of the device ID, the field is suitable sized to write a `usize` value.

///

///     Similar to the previous requirement, the data should ideally be added during `Self` to

///     `RawType` conversion, but there's currently no way to do it when using traits in const.

pub unsafe trait RawDeviceId {

    /// The raw type that holds the device id.

    ///

    /// Id tables created from [`Self`] are going to hold this type in its zero-terminated array.

    type RawType: Copy;

}



    /// The offset to the context/data field.

/// 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.

pub unsafe trait RawDeviceIdIndex: RawDeviceId {

    /// The offset (in bytes) to the context/data field in the raw device ID.

    const DRIVER_DATA_OFFSET: usize;



    /// The index stored at `DRIVER_DATA_OFFSET` of the implementor of the [`RawDeviceId`] trait.

    /// The index stored at `DRIVER_DATA_OFFSET` of the implementor of the [`RawDeviceIdIndex`]

    /// trait.

    fn index(&self) -> usize;

}
@@ -68,7 +77,15 @@ impl<T: RawDeviceId, U, const N: usize> IdArray<T, U, N> { 
    /// Creates a new instance of the array.

    ///

    /// The contents are derived from the given identifiers and context information.

    pub const fn new(ids: [(T, U); N]) -> Self {

    ///

    /// # Safety

    ///

    /// `data_offset` as `None` is always safe.

    /// If `data_offset` is `Some(data_offset)`, then:

    /// - `data_offset` must be the correct offset (in bytes) to the context/data field

    ///   (e.g., the `driver_data` field) within the raw device ID structure.

    /// - The field at `data_offset` must be correctly sized to hold a `usize`.

    const unsafe fn build(ids: [(T, U); N], data_offset: Option<usize>) -> Self {

        let mut raw_ids = [const { MaybeUninit::<T::RawType>::uninit() }; N];

        let mut infos = [const { MaybeUninit::uninit() }; N];
@@ -77,15 +94,17 @@ impl<T: RawDeviceId, U, const N: usize> IdArray<T, U, N> { 
            // SAFETY: by the safety requirement of `RawDeviceId`, we're guaranteed that `T` is

            // layout-wise compatible with `RawType`.

            raw_ids[i] = unsafe { core::mem::transmute_copy(&ids[i].0) };

            // SAFETY: by the safety requirement of `RawDeviceId`, this would be effectively

            if let Some(data_offset) = data_offset {

                // SAFETY: by the safety requirement of this function, this would be effectively

                // `raw_ids[i].driver_data = i;`.

                unsafe {

                    raw_ids[i]

                        .as_mut_ptr()

                    .byte_offset(T::DRIVER_DATA_OFFSET as _)

                        .byte_offset(data_offset as _)

                        .cast::<usize>()

                        .write(i);

                }

            }



            // SAFETY: this is effectively a move: `infos[i] = ids[i].1`. We make a copy here but

            // later forget `ids`.
@@ -109,12 +128,34 @@ impl<T: RawDeviceId, U, const N: usize> IdArray<T, U, N> { 
        }

    }



    /// Creates a new instance of the array without writing index values.

    ///

    /// The contents are derived from the given identifiers and context information.

    /// If the device implements [`RawDeviceIdIndex`], consider using [`IdArray::new`] instead.

    pub const fn new_without_index(ids: [(T, U); N]) -> Self {

        // SAFETY: Calling `Self::build` with `offset = None` is always safe,

        // because no raw memory writes are performed in this case.

        unsafe { Self::build(ids, None) }

    }



    /// Reference to the contained [`RawIdArray`].

    pub const fn raw_ids(&self) -> &RawIdArray<T, N> {

        &self.raw_ids

    }

}



impl<T: RawDeviceId + RawDeviceIdIndex, U, const N: usize> IdArray<T, U, N> {

    /// Creates a new instance of the array.

    ///

    /// The contents are derived from the given identifiers and context information.

    pub const fn new(ids: [(T, U); N]) -> Self {

        // SAFETY: by the safety requirement of `RawDeviceIdIndex`,

        // `T::DRIVER_DATA_OFFSET` is guaranteed to be the correct offset (in bytes) to

        // a field within `T::RawType`.

        unsafe { Self::build(ids, Some(T::DRIVER_DATA_OFFSET)) }

    }

}



/// A device id table.

///

/// This trait is only implemented by `IdArray`.

rust/kernel/driver.rs

+6 −2
Original line number Diff line number Diff line
@@ -170,7 +170,7 @@ fn acpi_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> { 
                // and does not add additional invariants, so it's safe to transmute.

                let id = unsafe { &*raw_id.cast::<acpi::DeviceId>() };



                Some(table.info(<acpi::DeviceId as crate::device_id::RawDeviceId>::index(id)))

                Some(table.info(<acpi::DeviceId as crate::device_id::RawDeviceIdIndex>::index(id)))

            }

        }

    }
@@ -204,7 +204,11 @@ fn of_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> { 
                // and does not add additional invariants, so it's safe to transmute.

                let id = unsafe { &*raw_id.cast::<of::DeviceId>() };



                Some(table.info(<of::DeviceId as crate::device_id::RawDeviceId>::index(id)))

                Some(

                    table.info(<of::DeviceId as crate::device_id::RawDeviceIdIndex>::index(

                        id,

                    )),

                )

            }

        }

    }

rust/kernel/of.rs

+10 −5
Original line number Diff line number Diff line
@@ -2,7 +2,11 @@ 


//! Device Tree / Open Firmware abstractions.



use crate::{bindings, device_id::RawDeviceId, prelude::*};

use crate::{

    bindings,

    device_id::{RawDeviceId, RawDeviceIdIndex},

    prelude::*,

};



/// IdTable type for OF drivers.

pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;
@@ -12,13 +16,14 @@ 
#[derive(Clone, Copy)]

pub struct DeviceId(bindings::of_device_id);



// SAFETY:

// * `DeviceId` is a `#[repr(transparent)]` wrapper of `struct of_device_id` and does not add

//   additional invariants, so it's safe to transmute to `RawType`.

// * `DRIVER_DATA_OFFSET` is the offset to the `data` field.

// SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct of_device_id` and

// does not add additional invariants, so it's safe to transmute to `RawType`.

unsafe impl RawDeviceId for DeviceId {

    type RawType = bindings::of_device_id;

}



// SAFETY: `DRIVER_DATA_OFFSET` is the offset to the `data` field.

unsafe impl RawDeviceIdIndex for DeviceId {

    const DRIVER_DATA_OFFSET: usize = core::mem::offset_of!(bindings::of_device_id, data);



    fn index(&self) -> usize {