Skip to contentSkip to conversation

Initial rust bindings for device property reads

RFC PATCH In review Rob Herring (Arm) 6 participants 28 messages Oct 25, 2024 – Nov 15, 2024

Subsystems (3)
lore
Share & tools
lore

Rob Herring (Arm)

author maintainer
#0 lore raw

cover Initial rust bindings for device property reads

I got asked about upstreaming DT rust bindings, so I decided to take a stab at it. This series adds rust bindings for the device property API which is a firmware agnostic interface for reading firmware properties. There are "DT rust bindings" patches floating around, but for many drivers they don't need to know any DT specifics nor deal with struct device_node (and its refcounts). And reading firmware properties are simple enough for my feeble rust abilities.

This series is based on top of Danilo's PCI and platform device series[1], though that's really only for the sample driver.

Please tell me how my rust code sucks before I spend more time beating my head against the wall^W^W^W^W^W^W learning rust.

Rob

[1] https://lore.kernel.org/all/[email protected]/

---
Rob Herring (Arm) (3):
of: unittest: Add a platform device node for rust platform driver sample
rust: Add bindings for device properties
samples: rust: platform: Add property read examples

 drivers/of/unittest-data/tests-platform.dtsi |   8 ++
 rust/bindings/bindings_helper.h              |   1 +
 rust/kernel/device.rs                        | 145 ++++++++++++++++++++++++++-
 samples/rust/rust_driver_platform.rs         |  24 ++++-
 4 files changed, 176 insertions(+), 2 deletions(-)

---
base-commit: eeb31b3e7e9e1b485763ecc66ece8afba1416b2a
change-id: 20241025-rust-platform-dev-0e89debcbba5

Best regards,

Signature · 1 line
Rob Herring (Arm) <[email protected]>
author maintainer
#1 lore raw

RFC PATCH 1/3 of: unittest: Add a platform device node for rust platform driver sample

---
 drivers/of/unittest-data/tests-platform.dtsi | 5 +++++
 samples/rust/rust_driver_platform.rs         | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)
drivers/of/unittest-data/tests-platform.dtsi +5 -0
index fa39611071b3..2caaf1c10ee6 100644
@@ -33,6 +33,11 @@ dev@100 {
 					reg = <0x100>;
 				};
 			};
+
+			test-device@2 {
+				compatible = "test,rust-device";
+				reg = <0x2>;
+			};
 		};
 	};
 };
samples/rust/rust_driver_platform.rs +1 -1
index 55caaaa4f216..5cf4a8f86c13 100644
@@ -15,7 +15,7 @@ struct SampleDriver {
     MODULE_OF_TABLE,
     <SampleDriver as platform::Driver>::IdInfo,
     [(
-        of::DeviceId::new(c_str!("redhat,rust-sample-platform-driver")),
+        of::DeviceId::new(c_str!("test,rust-device")),
         Info(42)
     )]
 );
Signature · 1 line
2.45.2
Reviewed-by on v1 1/3
#2 lore raw

Re: [PATCH RFC 1/3] of: unittest: Add a platform device node for rust platform driver sample

Quoted 28 lines · Rob Herring (Arm)
---
  drivers/of/unittest-data/tests-platform.dtsi | 5 +++++
  samples/rust/rust_driver_platform.rs         | 2 +-
  2 files changed, 6 insertions(+), 1 deletion(-)
drivers/of/unittest-data/tests-platform.dtsi +5 -0
index fa39611071b3..2caaf1c10ee6 100644
@@ -33,6 +33,11 @@ dev@100 {
  					reg = <0x100>;
  				};
  			};
+
+			test-device@2 {
+				compatible = "test,rust-device";
+				reg = <0x2>;
+			};
  		};
  	};
  };
samples/rust/rust_driver_platform.rs +0 -0
index 55caaaa4f216..5cf4a8f86c13 100644

samples/rust/rust_driver_platform.rs struct SampleDriver { · line 21

Quoted 8 lines
samples/rust/rust_driver_platform.rs +1 -1
@@ -15,7 +15,7 @@ struct SampleDriver {
      MODULE_OF_TABLE,
      <SampleDriver as platform::Driver>::IdInfo,
      [(
-        of::DeviceId::new(c_str!("redhat,rust-sample-platform-driver")),
+        of::DeviceId::new(c_str!("test,rust-device")),
          Info(42)
      )]
  );

I'm not sure if parts or all of this should be squashed into Danilo's patches. Anyway:

Best regards

Dirk

author maintainer
#3 lore raw

RFC PATCH 2/3 rust: Add bindings for device properties

In reply to Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
 #include <linux/pci.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/refcount.h>
 #include <linux/sched.h>
 #include <linux/slab.h>
rust/kernel/device.rs +144 -1

160 lines not on this page · raw message

Signature · 1 line
2.45.2
#4 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 83 lines · Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
 #include <linux/pci.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/refcount.h>
 #include <linux/sched.h>
 #include <linux/slab.h>
rust/kernel/device.rs +24 -1
index 0c28b1e6b004..bb66a28df890 100644
@@ -5,10 +5,14 @@
 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
 
 use crate::{
+    alloc::KVec,
     bindings,
+    error::{to_result, Result},
+    prelude::*,
+    str::CStr,
     types::{ARef, Opaque},
 };
-use core::{fmt, ptr};
+use core::{fmt, mem::size_of, ptr};
 
 #[cfg(CONFIG_PRINTK)]
 use crate::c_str;
@@ -189,6 +193,145 @@ unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
             )
         };
     }
+
+    /// Returns if a firmware property `name` is true or false
+    pub fn property_read_bool(&self, name: &CStr) -> bool {
+        unsafe { bindings::device_property_present(self.as_raw(), name.as_ptr() as *const i8) }
+    }
+
+    /// Returns if a firmware string property `name` has match for `match_str`
+    pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
+        let ret = unsafe {
+            bindings::device_property_match_string(
+                self.as_raw(),
+                name.as_ptr() as *const i8,
+                match_str.as_ptr() as *const i8,
+            )
+        };
+        to_result(ret)?;
+        Ok(ret as usize)
+    }
+

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 224

Quoted 10 lines
rust/kernel/device.rs +10 -0
+    /// Returns firmware property `name` scalar value
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+        let mut val: [T; 1] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(&self, name, &mut val)?;
+        Ok(val[0])
+    }
+

This, and several of the other methods are unsound, because they can be used to construct arbitrary types for which may not allow all bit patterns. You can use:
https://rust.docs.kernel.org/kernel/types/trait.FromBytes.html as the bound to ensure only valid types are used.

Also, instead of using mem::zeroed(), you should use MaybeUnininit
(https://doc.rust-lang.org/stable/core/mem/union.MaybeUninit.html)
which allows you to avoid needing to zero initialize.

Quoted 117 lines
rust/kernel/device.rs +110 -1
+    /// Returns firmware property `name` array values
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read_array<T, const N: usize>(&self, name: &CStr) -> Result<[T; N]> {
+        let mut val: [T; N] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(self, name, &mut val)?;
+        Ok(val)
+    }
+
+    fn _property_read_array<T>(&self, name: &CStr, val: &mut [T]) -> Result {
+        match size_of::<T>() {
+            1 => to_result(unsafe {
+                bindings::device_property_read_u8_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u8,
+                    val.len(),
+                )
+            })?,
+            2 => to_result(unsafe {
+                bindings::device_property_read_u16_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u16,
+                    val.len(),
+                )
+            })?,
+            4 => to_result(unsafe {
+                bindings::device_property_read_u32_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u32,
+                    val.len(),
+                )
+            })?,
+            8 => to_result(unsafe {
+                bindings::device_property_read_u64_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u64,
+                    val.len(),
+                )
+            })?,
+            _ => return Err(EINVAL),
+        }
+        Ok(())
+    }
+
+    pub fn property_read_array_vec<T>(&self, name: &CStr, len: usize) -> Result<KVec<T>> {
+        let mut val: KVec<T> = KVec::with_capacity(len, GFP_KERNEL)?;
+
+        // SAFETY: len always matches capacity
+        unsafe { val.set_len(len) }
+        Self::_property_read_array::<T>(&self, name, val.as_mut_slice())?;
+        Ok(val)
+    }
+
+    /// Returns array length for firmware property `name`
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {
+        let ret;
+
+        match size_of::<T>() {
+            1 => {
+                ret = unsafe {
+                    bindings::device_property_read_u8_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            2 => {
+                ret = unsafe {
+                    bindings::device_property_read_u16_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            4 => {
+                ret = unsafe {
+                    bindings::device_property_read_u32_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            8 => {
+                ret = unsafe {
+                    bindings::device_property_read_u64_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            _ => return Err(EINVAL),
+        }
+        to_result(ret)?;
+        Ok(ret.try_into().unwrap())
+    }
 }
 
 // SAFETY: Instances of `Device` are always reference-counted.
 
--

2.45.2

Signature · 1 line
All that is necessary for evil to succeed is for good people to do nothing.
author maintainer
#5 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 93 lines · Alex Gaynor
Quoted 91 lines · Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
 #include <linux/pci.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/refcount.h>
 #include <linux/sched.h>
 #include <linux/slab.h>
rust/kernel/device.rs +32 -1
index 0c28b1e6b004..bb66a28df890 100644
@@ -5,10 +5,14 @@
 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
 
 use crate::{
+    alloc::KVec,
     bindings,
+    error::{to_result, Result},
+    prelude::*,
+    str::CStr,
     types::{ARef, Opaque},
 };
-use core::{fmt, ptr};
+use core::{fmt, mem::size_of, ptr};
 
 #[cfg(CONFIG_PRINTK)]
 use crate::c_str;
@@ -189,6 +193,145 @@ unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
             )
         };
     }
+
+    /// Returns if a firmware property `name` is true or false
+    pub fn property_read_bool(&self, name: &CStr) -> bool {
+        unsafe { bindings::device_property_present(self.as_raw(), name.as_ptr() as *const i8) }
+    }
+
+    /// Returns if a firmware string property `name` has match for `match_str`
+    pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
+        let ret = unsafe {
+            bindings::device_property_match_string(
+                self.as_raw(),
+                name.as_ptr() as *const i8,
+                match_str.as_ptr() as *const i8,
+            )
+        };
+        to_result(ret)?;
+        Ok(ret as usize)
+    }
+
+    /// Returns firmware property `name` scalar value
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+        let mut val: [T; 1] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(&self, name, &mut val)?;
+        Ok(val[0])
Quoted 8 lines

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 224

Quoted 2 lines
rust/kernel/device.rs +2 -0
+    }
+

This, and several of the other methods are unsound, because they can be used to construct arbitrary types for which may not allow all bit patterns. You can use:
https://rust.docs.kernel.org/kernel/types/trait.FromBytes.html as the bound to ensure only valid types are used.

I meant to ask a question on this. FromBytes is probably still too permissive for what is supported in DT. I think floating point types would be allowed which is not valid in DT (though asahi linux has some downstream patches adding FP data support). What I really need is the Integer trait from the num crate or some way to define the exact types supported. I tried Into<u32>, etc., but that didn't work.

Quoted 4 lines

Also, instead of using mem::zeroed(), you should use MaybeUnininit
(https://doc.rust-lang.org/stable/core/mem/union.MaybeUninit.html)
which allows you to avoid needing to zero initialize.

Okay, thanks. Being new to rust, I find this a bit complicated compared to C (perhaps it has to be to avoid this class of bugs). Maybe that's because this stuff seems to have been evolving some with the kernel rust support. In any case, some examples of how (and perhaps) to do uninitialized and zero-initialized allocations would be helpful as both are common in the kernel.

Rob

author maintainer
#6 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

In reply to Alex Gaynor
Quoted 102 lines · Alex Gaynor
Quoted 83 lines · Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
 #include <linux/pci.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/refcount.h>
 #include <linux/sched.h>
 #include <linux/slab.h>
rust/kernel/device.rs +24 -1
index 0c28b1e6b004..bb66a28df890 100644
@@ -5,10 +5,14 @@
 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
 
 use crate::{
+    alloc::KVec,
     bindings,
+    error::{to_result, Result},
+    prelude::*,
+    str::CStr,
     types::{ARef, Opaque},
 };
-use core::{fmt, ptr};
+use core::{fmt, mem::size_of, ptr};
 
 #[cfg(CONFIG_PRINTK)]
 use crate::c_str;
@@ -189,6 +193,145 @@ unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
             )
         };
     }
+
+    /// Returns if a firmware property `name` is true or false
+    pub fn property_read_bool(&self, name: &CStr) -> bool {
+        unsafe { bindings::device_property_present(self.as_raw(), name.as_ptr() as *const i8) }
+    }
+
+    /// Returns if a firmware string property `name` has match for `match_str`
+    pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
+        let ret = unsafe {
+            bindings::device_property_match_string(
+                self.as_raw(),
+                name.as_ptr() as *const i8,
+                match_str.as_ptr() as *const i8,
+            )
+        };
+        to_result(ret)?;
+        Ok(ret as usize)
+    }
+

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 224

Quoted 10 lines
rust/kernel/device.rs +10 -0
+    /// Returns firmware property `name` scalar value
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+        let mut val: [T; 1] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(&self, name, &mut val)?;
+        Ok(val[0])
+    }
+

This, and several of the other methods are unsound, because they can be used to construct arbitrary types for which may not allow all bit patterns. You can use:
https://rust.docs.kernel.org/kernel/types/trait.FromBytes.html as the bound to ensure only valid types are used.

Quoted 3 lines

Also, instead of using mem::zeroed(), you should use MaybeUnininit
(https://doc.rust-lang.org/stable/core/mem/union.MaybeUninit.html)
which allows you to avoid needing to zero initialize.

Something like this what you had in mind?:

pub fn property_read_array<T, const N: usize>(&self, name: &CStr) ->

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

    Self::_property_read_array(self, name, &mut val)?;

    // SAFETY: On success, _property_read_array has filled in the array
    let val = unsafe { mem::transmute_copy(&val) };
    Ok(val)
}
#7 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 111 lines · Rob Herring
Quoted 102 lines · Alex Gaynor
Quoted 83 lines · Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
 #include <linux/pci.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/refcount.h>
 #include <linux/sched.h>
 #include <linux/slab.h>
rust/kernel/device.rs +24 -1
index 0c28b1e6b004..bb66a28df890 100644
@@ -5,10 +5,14 @@
 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
 
 use crate::{
+    alloc::KVec,
     bindings,
+    error::{to_result, Result},
+    prelude::*,
+    str::CStr,
     types::{ARef, Opaque},
 };
-use core::{fmt, ptr};
+use core::{fmt, mem::size_of, ptr};
 
 #[cfg(CONFIG_PRINTK)]
 use crate::c_str;
@@ -189,6 +193,145 @@ unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
             )
         };
     }
+
+    /// Returns if a firmware property `name` is true or false
+    pub fn property_read_bool(&self, name: &CStr) -> bool {
+        unsafe { bindings::device_property_present(self.as_raw(), name.as_ptr() as *const i8) }
+    }
+
+    /// Returns if a firmware string property `name` has match for `match_str`
+    pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
+        let ret = unsafe {
+            bindings::device_property_match_string(
+                self.as_raw(),
+                name.as_ptr() as *const i8,
+                match_str.as_ptr() as *const i8,
+            )
+        };
+        to_result(ret)?;
+        Ok(ret as usize)
+    }
+

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 224

Quoted 10 lines
rust/kernel/device.rs +10 -0
+    /// Returns firmware property `name` scalar value
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+        let mut val: [T; 1] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(&self, name, &mut val)?;
+        Ok(val[0])
+    }
+

This, and several of the other methods are unsound, because they can be used to construct arbitrary types for which may not allow all bit patterns. You can use:
https://rust.docs.kernel.org/kernel/types/trait.FromBytes.html as the bound to ensure only valid types are used.

Quoted 3 lines

Also, instead of using mem::zeroed(), you should use MaybeUnininit
(https://doc.rust-lang.org/stable/core/mem/union.MaybeUninit.html)
which allows you to avoid needing to zero initialize.

Something like this what you had in mind?:

pub fn property_read_array<T, const N: usize>(&self, name: &CStr) ->

Quoted 9 lines
Result<[T; N]> {
    let mut val: [MaybeUninit<T>; N] = [const { MaybeUninit::uninit() }; N];

    Self::_property_read_array(self, name, &mut val)?;

    // SAFETY: On success, _property_read_array has filled in the array
    let val = unsafe { mem::transmute_copy(&val) };
    Ok(val)
}

Yes, that's right. Ideally you could use
https://doc.rust-lang.org/stable/core/mem/union.MaybeUninit.html#method.array_assume_init
instead of transmute, but it's not yet stable.

Alex

Signature · 1 line
All that is necessary for evil to succeed is for good people to do nothing.
#8 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

In reply to Rob Herring (Arm)
Quoted 9 lines · Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

Building this on rust-next with CLIPPY=1 there are some improvement requests:

* Function documentation for property_read_array_vec
* SAFETY comments for all unsafe{} blocks
* Different ret usage for match size_of::<T>()
* Use self instead of &self

See [1] below (without the SAFETY comments).

Best regards

Dirk

Quoted 185 lines

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
  rust/bindings/bindings_helper.h |   1 +
  rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
  2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
  #include <linux/pci.h>
  #include <linux/phy.h>
  #include <linux/platform_device.h>
+#include <linux/property.h>
  #include <linux/refcount.h>
  #include <linux/sched.h>
  #include <linux/slab.h>
rust/kernel/device.rs +136 -1
index 0c28b1e6b004..bb66a28df890 100644
@@ -5,10 +5,14 @@
  //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
 
  use crate::{
+    alloc::KVec,
      bindings,
+    error::{to_result, Result},
+    prelude::*,
+    str::CStr,
      types::{ARef, Opaque},
  };
-use core::{fmt, ptr};
+use core::{fmt, mem::size_of, ptr};
 
  #[cfg(CONFIG_PRINTK)]
  use crate::c_str;
@@ -189,6 +193,145 @@ unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
              )
          };
      }
+
+    /// Returns if a firmware property `name` is true or false
+    pub fn property_read_bool(&self, name: &CStr) -> bool {
+        unsafe { bindings::device_property_present(self.as_raw(), name.as_ptr() as *const i8) }
+    }
+
+    /// Returns if a firmware string property `name` has match for `match_str`
+    pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
+        let ret = unsafe {
+            bindings::device_property_match_string(
+                self.as_raw(),
+                name.as_ptr() as *const i8,
+                match_str.as_ptr() as *const i8,
+            )
+        };
+        to_result(ret)?;
+        Ok(ret as usize)
+    }
+
+    /// Returns firmware property `name` scalar value
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+        let mut val: [T; 1] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(&self, name, &mut val)?;
+        Ok(val[0])
+    }
+
+    /// Returns firmware property `name` array values
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read_array<T, const N: usize>(&self, name: &CStr) -> Result<[T; N]> {
+        let mut val: [T; N] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(self, name, &mut val)?;
+        Ok(val)
+    }
+
+    fn _property_read_array<T>(&self, name: &CStr, val: &mut [T]) -> Result > +        match size_of::<T>() {
+            1 => to_result(unsafe {
+                bindings::device_property_read_u8_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u8,
+                    val.len(),
+                )
+            })?,
+            2 => to_result(unsafe {
+                bindings::device_property_read_u16_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u16,
+                    val.len(),
+                )
+            })?,
+            4 => to_result(unsafe {
+                bindings::device_property_read_u32_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u32,
+                    val.len(),
+                )
+            })?,
+            8 => to_result(unsafe {
+                bindings::device_property_read_u64_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u64,
+                    val.len(),
+                )
+            })?,
+            _ => return Err(EINVAL),
+        }
+        Ok(())
+    }
+
+    pub fn property_read_array_vec<T>(&self, name: &CStr, len: usize) -> Result<KVec<T>> {
+        let mut val: KVec<T> = KVec::with_capacity(len, GFP_KERNEL)?;
+
+        // SAFETY: len always matches capacity
+        unsafe { val.set_len(len) }
+        Self::_property_read_array::<T>(&self, name, val.as_mut_slice())?;
+        Ok(val)
+    }
+
+    /// Returns array length for firmware property `name`
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {
+        let ret;
+
+        match size_of::<T>() {
+            1 => {
+                ret = unsafe {
+                    bindings::device_property_read_u8_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            2 => {
+                ret = unsafe {
+                    bindings::device_property_read_u16_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            4 => {
+                ret = unsafe {
+                    bindings::device_property_read_u32_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            8 => {
+                ret = unsafe {
+                    bindings::device_property_read_u64_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 336

Quoted 10 lines
rust/kernel/device.rs +7 -0
+                }
+            }
+            _ => return Err(EINVAL),
+        }
+        to_result(ret)?;
+        Ok(ret.try_into().unwrap())
+    }
  }
 
  // SAFETY: Instances of `Device` are always reference-counted.

[1]

rust/kernel/device.rs +3 -3
index bb66a28df890..3c461b1602d5 100644
@@ -218,7 +218,7 @@ pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usi
     pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
         let mut val: [T; 1] = unsafe { core::mem::zeroed() };
 
-        Self::_property_read_array(&self, name, &mut val)?;
+        Self::_property_read_array(self, name, &mut val)?;
         Ok(val[0])
     }
 
@@ -271,12 +271,13 @@ fn _property_read_array<T>(&self, name: &CStr, val: &mut [T]) -> Result {
         Ok(())
     }
 
+    /// ToDo
     pub fn property_read_array_vec<T>(&self, name: &CStr, len: usize) 
-> Result<KVec<T>> {
         let mut val: KVec<T> = KVec::with_capacity(len, GFP_KERNEL)?;
 
         // SAFETY: len always matches capacity
         unsafe { val.set_len(len) }
-        Self::_property_read_array::<T>(&self, name, val.as_mut_slice())?;
+        Self::_property_read_array::<T>(self, name, val.as_mut_slice())?;
         Ok(val)
     }

@@ -284,11 +285,10 @@ pub fn property_read_array_vec<T>(&self, name: &CStr, len: usize) -> Result<KVec

     ///
     /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
     pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {

- let ret;

- match size_of::<T>() {

+        let ret = match size_of::<T>() {
             1 => {
-                ret = unsafe {
+                unsafe {
                     bindings::device_property_read_u8_array(
                         self.as_raw(),
                         name.as_ptr() as *const i8,
@@ -298,7 +298,7 @@ pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {
                 }
             }
             2 => {
-                ret = unsafe {
+                unsafe {
                     bindings::device_property_read_u16_array(
                         self.as_raw(),
                         name.as_ptr() as *const i8,
@@ -308,7 +308,7 @@ pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {
                 }
             }
             4 => {
-                ret = unsafe {
+                unsafe {
                     bindings::device_property_read_u32_array(
                         self.as_raw(),
                         name.as_ptr() as *const i8,
@@ -318,7 +318,7 @@ pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {
                 }
             }
             8 => {
-                ret = unsafe {
+                unsafe {
                     bindings::device_property_read_u64_array(
                         self.as_raw(),
                         name.as_ptr() as *const i8,
@@ -328,7 +328,7 @@ pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {
                 }
             }
             _ => return Err(EINVAL),
-        }
+        };
         to_result(ret)?;
         Ok(ret.try_into().unwrap())
     }
reviewer
#9 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

In reply to Rob Herring (Arm)
Quoted 145 lines · Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
 #include <linux/pci.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/refcount.h>
 #include <linux/sched.h>
 #include <linux/slab.h>
rust/kernel/device.rs +86 -1
index 0c28b1e6b004..bb66a28df890 100644
@@ -5,10 +5,14 @@
 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
 
 use crate::{
+    alloc::KVec,
     bindings,
+    error::{to_result, Result},
+    prelude::*,
+    str::CStr,
     types::{ARef, Opaque},
 };
-use core::{fmt, ptr};
+use core::{fmt, mem::size_of, ptr};
 
 #[cfg(CONFIG_PRINTK)]
 use crate::c_str;
@@ -189,6 +193,145 @@ unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
             )
         };
     }
+
+    /// Returns if a firmware property `name` is true or false
+    pub fn property_read_bool(&self, name: &CStr) -> bool {
+        unsafe { bindings::device_property_present(self.as_raw(), name.as_ptr() as *const i8) }
+    }
+
+    /// Returns if a firmware string property `name` has match for `match_str`
+    pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
+        let ret = unsafe {
+            bindings::device_property_match_string(
+                self.as_raw(),
+                name.as_ptr() as *const i8,
+                match_str.as_ptr() as *const i8,
+            )
+        };
+        to_result(ret)?;
+        Ok(ret as usize)
+    }
+
+    /// Returns firmware property `name` scalar value
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+        let mut val: [T; 1] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(&self, name, &mut val)?;
+        Ok(val[0])
+    }
+
+    /// Returns firmware property `name` array values
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read_array<T, const N: usize>(&self, name: &CStr) -> Result<[T; N]> {
+        let mut val: [T; N] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(self, name, &mut val)?;
+        Ok(val)
+    }
+
+    fn _property_read_array<T>(&self, name: &CStr, val: &mut [T]) -> Result {
+        match size_of::<T>() {
+            1 => to_result(unsafe {
+                bindings::device_property_read_u8_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u8,
+                    val.len(),
+                )
+            })?,
+            2 => to_result(unsafe {
+                bindings::device_property_read_u16_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u16,
+                    val.len(),
+                )
+            })?,
+            4 => to_result(unsafe {
+                bindings::device_property_read_u32_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u32,
+                    val.len(),
+                )
+            })?,
+            8 => to_result(unsafe {
+                bindings::device_property_read_u64_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u64,
+                    val.len(),
+                )
+            })?,
+            _ => return Err(EINVAL),
+        }
+        Ok(())
+    }
+
+    pub fn property_read_array_vec<T>(&self, name: &CStr, len: usize) -> Result<KVec<T>> {
+        let mut val: KVec<T> = KVec::with_capacity(len, GFP_KERNEL)?;
+

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 286

Quoted 10 lines
rust/kernel/device.rs +10 -0
+        // SAFETY: len always matches capacity
+        unsafe { val.set_len(len) }
+        Self::_property_read_array::<T>(&self, name, val.as_mut_slice())?;
+        Ok(val)
+    }
+
+    /// Returns array length for firmware property `name`
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {

This always returns usize? I'm a bit confused ...

Quoted 32 lines
rust/kernel/device.rs +32 -0
+        match size_of::<T>() {
+            1 => {
+                ret = unsafe {
+                    bindings::device_property_read_u8_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            2 => {
+                ret = unsafe {
+                    bindings::device_property_read_u16_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            4 => {
+                ret = unsafe {
+                    bindings::device_property_read_u32_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            8 => {

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 330

Quoted 10 lines
rust/kernel/device.rs +10 -0
+                ret = unsafe {
+                    bindings::device_property_read_u64_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            _ => return Err(EINVAL),

You can use kernel::build_error! here to trigger a build failure if the size is wrong.

Alice

author maintainer
#10 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 151 lines · Alice Ryhl
Quoted 149 lines · Rob Herring (Arm)

The device property API is a firmware agnostic API for reading properties from firmware (DT/ACPI) devices nodes and swnodes.

While the C API takes a pointer to a caller allocated variable/buffer, the rust API is designed to return a value and can be used in struct initialization. Rust generics are also utilized to support different sizes of properties (e.g. u8, u16, u32).

---
Not sure if we need the KVec variant, but I kept it as that was my first pass attempt. Most callers are filling in some value in a driver data struct. Sometimes the number of elements is not known, so the caller calls to get the array size, allocs the correct size buffer, and then reads the property again to fill in the buffer.

I have not implemented a wrapper for device_property_read_string(_array) because that API is problematic for dynamic DT nodes. The API just returns pointer(s) into the raw DT data. We probably need to return a copy of the string(s) instead for rust.

After property accessors, next up is child node accessors/iterators.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/device.rs           | 145 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 145 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 217c776615b9..65717cc20a23 100644
@@ -19,6 +19,7 @@
 #include <linux/pci.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/refcount.h>
 #include <linux/sched.h>
 #include <linux/slab.h>
rust/kernel/device.rs +90 -1
index 0c28b1e6b004..bb66a28df890 100644
@@ -5,10 +5,14 @@
 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
 
 use crate::{
+    alloc::KVec,
     bindings,
+    error::{to_result, Result},
+    prelude::*,
+    str::CStr,
     types::{ARef, Opaque},
 };
-use core::{fmt, ptr};
+use core::{fmt, mem::size_of, ptr};
 
 #[cfg(CONFIG_PRINTK)]
 use crate::c_str;
@@ -189,6 +193,145 @@ unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
             )
         };
     }
+
+    /// Returns if a firmware property `name` is true or false
+    pub fn property_read_bool(&self, name: &CStr) -> bool {
+        unsafe { bindings::device_property_present(self.as_raw(), name.as_ptr() as *const i8) }
+    }
+
+    /// Returns if a firmware string property `name` has match for `match_str`
+    pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
+        let ret = unsafe {
+            bindings::device_property_match_string(
+                self.as_raw(),
+                name.as_ptr() as *const i8,
+                match_str.as_ptr() as *const i8,
+            )
+        };
+        to_result(ret)?;
+        Ok(ret as usize)
+    }
+
+    /// Returns firmware property `name` scalar value
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+        let mut val: [T; 1] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(&self, name, &mut val)?;
+        Ok(val[0])
+    }
+
+    /// Returns firmware property `name` array values
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_read_array<T, const N: usize>(&self, name: &CStr) -> Result<[T; N]> {
+        let mut val: [T; N] = unsafe { core::mem::zeroed() };
+
+        Self::_property_read_array(self, name, &mut val)?;
+        Ok(val)
+    }
+
+    fn _property_read_array<T>(&self, name: &CStr, val: &mut [T]) -> Result {
+        match size_of::<T>() {
+            1 => to_result(unsafe {
+                bindings::device_property_read_u8_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u8,
+                    val.len(),
+                )
+            })?,
+            2 => to_result(unsafe {
+                bindings::device_property_read_u16_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u16,
+                    val.len(),
+                )
+            })?,
+            4 => to_result(unsafe {
+                bindings::device_property_read_u32_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u32,
+                    val.len(),
+                )
+            })?,
+            8 => to_result(unsafe {
+                bindings::device_property_read_u64_array(
+                    self.as_raw(),
+                    name.as_ptr() as *const i8,
+                    val.as_ptr() as *mut u64,
+                    val.len(),
+                )
+            })?,
+            _ => return Err(EINVAL),
+        }
+        Ok(())
+    }
+
+    pub fn property_read_array_vec<T>(&self, name: &CStr, len: usize) -> Result<KVec<T>> {
+        let mut val: KVec<T> = KVec::with_capacity(len, GFP_KERNEL)?;
+
+        // SAFETY: len always matches capacity
+        unsafe { val.set_len(len) }
+        Self::_property_read_array::<T>(&self, name, val.as_mut_slice())?;
+        Ok(val)
Quoted 8 lines

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 286

Quoted 6 lines
rust/kernel/device.rs +6 -0
+    }
+
+    /// Returns array length for firmware property `name`
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {

This always returns usize? I'm a bit confused ...

The C version returned an int so we could return an errno or positive count. With Result, we don't need negative values and isn't usize generally used for counts of things like size_t in C?

Quoted 43 lines
Quoted 32 lines
rust/kernel/device.rs +32 -0
+        match size_of::<T>() {
+            1 => {
+                ret = unsafe {
+                    bindings::device_property_read_u8_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            2 => {
+                ret = unsafe {
+                    bindings::device_property_read_u16_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            4 => {
+                ret = unsafe {
+                    bindings::device_property_read_u32_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            8 => {

rust/kernel/device.rs unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) { · line 330

Quoted 10 lines
rust/kernel/device.rs +10 -0
+                ret = unsafe {
+                    bindings::device_property_read_u64_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            _ => return Err(EINVAL),
Quoted 2 lines

You can use kernel::build_error! here to trigger a build failure if the size is wrong.

I really want a build error if the type is wrong, then the _ case would be unreachable. No way to do that?

Rob

#11 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 3 lines · Rob Herring

I really want a build error if the type is wrong, then the _ case would be unreachable. No way to do that?

When you need to work with a set of types, you would normally define a trait and implement it only for those traits, e.g. see rust/kernel/transmute.rs. Then it is a build error if you don't satisfy bounds etc.

Cheers,
Miguel

#12 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 2 lines · Miguel Ojeda

trait and implement it only for those traits, e.g. see

"for those types"

Cheers,
Miguel

reviewer
#13 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

In reply to Rob Herring
Quoted 10 lines · Rob Herring
Quoted 8 lines · Alice Ryhl
Quoted 5 lines · Rob Herring (Arm)
rust/kernel/device.rs +5 -0
+
+    /// Returns array length for firmware property `name`
+    ///
+    /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
+    pub fn property_count_elem<T>(&self, name: &CStr) -> Result<usize> {
Quoted 5 lines
Quoted 1 line

This always returns usize? I'm a bit confused ...

The C version returned an int so we could return an errno or positive count. With Result, we don't need negative values and isn't usize generally used for counts of things like size_t in C?

Ok, I think I misunderstood what this does. usize is fine.

Quoted 43 lines
Quoted 43 lines
Quoted 42 lines
rust/kernel/device.rs +42 -0
+        match size_of::<T>() {
+            1 => {
+                ret = unsafe {
+                    bindings::device_property_read_u8_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            2 => {
+                ret = unsafe {
+                    bindings::device_property_read_u16_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            4 => {
+                ret = unsafe {
+                    bindings::device_property_read_u32_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            8 => {
+                ret = unsafe {
+                    bindings::device_property_read_u64_array(
+                        self.as_raw(),
+                        name.as_ptr() as *const i8,
+                        ptr::null_mut(),
+                        0,
+                    )
+                }
+            }
+            _ => return Err(EINVAL),
Quoted 5 lines
Quoted 2 lines

You can use kernel::build_error! here to trigger a build failure if the size is wrong.

I really want a build error if the type is wrong, then the _ case would be unreachable. No way to do that?

One option is to define a trait for integers:

trait Integer: FromBytes + AsBytes + Copy {

    const SIZE: IntSize;
}
enum IntSize {
    S8,
    S16,
    S32,
    S64,
}
macro_rules! impl_int {
    ($($typ:ty),* $(,)?) => {$(
        impl Integer for $typ {
            const SIZE: IntSize = match size_of::<Self>() {
                1 => IntSize::S8,
                2 => IntSize::S16,
                4 => IntSize::S32,
                8 => IntSize::S64,
                _ => panic!("invalid size"),
            };
        }
    )*};
}
impl_int! {
    u8, u16, u32, u64, usize,
    i8, i16, i32, i64, isize,
}

Using the above trait, you can match on the IntSize.

pub fn property_count_elem<T: Integer>(&self, name: &CStr) -> Result<usize> {

match T::SIZE {
    IntSize::S8 => ...,
    IntSize::S16 => ...,
    IntSize::S32 => ...,
    IntSize::S64 => ...,
}

this leaves no catch-all case and calling it with non-integer types will not compile.

Alice

#14 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 2 lines · Alice Ryhl

One option is to define a trait for integers:

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Cheers,
Miguel

author maintainer
#15 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 4 lines · Miguel Ojeda
Quoted 2 lines · Alice Ryhl

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Quoted 5 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

Rob

author maintainer
#16 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Looking a bit closer at FromBytes, that's almost what I need. I'm not worried if it also includes usize and isize. However, since the trait also is provided for arrays/slices, the following happens to work:

let prop: [i16; 4] = dev.property_read(c_str!("test,i16-array"))?;

Which is a typo meant to be:

let prop: [i16; 4] = dev.property_read_array(c_str!("test,i16-array"))?;

And it doesn't really work. It reads all the data, but reads it as a u64 (DT data is BE), so the order is wrong.

And now my dreams of "if it compiles, it works" are shattered. ;)

Rob

reviewer
#17 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 22 lines · Rob Herring
Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Looking a bit closer at FromBytes, that's almost what I need. I'm not worried if it also includes usize and isize. However, since the trait also is provided for arrays/slices, the following happens to work:

let prop: [i16; 4] = dev.property_read(c_str!("test,i16-array"))?;

Quoted 8 lines

Which is a typo meant to be:

let prop: [i16; 4] = dev.property_read_array(c_str!("test,i16-array"))?;

And it doesn't really work. It reads all the data, but reads it as a u64 (DT data is BE), so the order is wrong.

And now my dreams of "if it compiles, it works" are shattered. ;)

It sounds like FromBytes isn't the right way to go, then.

Alice

reviewer
#18 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

In reply to Rob Herring
Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

You can design the trait to look similar to traits in external crates. We did that for FromBytes/AsBytes.

I assume you're referring to the PrimInt trait [1]? That trait doesn't really let you get rid of the catch-all case, and it's not even unreachable due to the u128 type.

[1]: https://docs.rs/num-traits/0.2.19/num_traits/int/trait.PrimInt.html

Quoted 7 lines
Quoted 5 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

No. What should it do if you pass it something that implements both traits?

If you want a single function name, you'll need one trait.

Alice

author maintainer
#19 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 16 lines · Alice Ryhl
Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Quoted 6 lines

You can design the trait to look similar to traits in external crates. We did that for FromBytes/AsBytes.

I assume you're referring to the PrimInt trait [1]? That trait doesn't really let you get rid of the catch-all case, and it's not even unreachable due to the u128 type.

It was num::Integer which seems to be similar.

Quoted 7 lines

[1]: https://docs.rs/num-traits/0.2.19/num_traits/int/trait.PrimInt.html

Quoted 4 lines
Quoted 4 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

No. What should it do if you pass it something that implements both traits?

If you want a single function name, you'll need one trait.

I'm not sure I want that actually.

DT boolean is a bit special. A property not present is false. Everything else is true. For example, 'prop = <0>' or 'prop = "string"' are both true. I'm moving things in the kernel to be stricter so that those cases are errors. I recently introduced (of|device)_property_present() for that reason. There's no type information stored in DT. At the DT level, it's all just byte arrays. However, we now have all the type information for properties within the schema. So eventually, I want to use that to warn on accessing properties with the wrong type.

For example, I think I don't want this to work:

if dev.property_read(c_str!("test,i16-array"))? {
    // do something
}

But instead have:

if dev.property_present(c_str!("test,i16-array")) {
    // do something
}

To actually warn on property_read_bool, I'm going to have to rework the underlying C implementation to separate device_property_present and device_property_read_bool implementations.

Rob

reviewer
#20 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 18 lines · Rob Herring
Quoted 16 lines · Alice Ryhl
Quoted 13 lines · Rob Herring
Quoted 4 lines · Miguel Ojeda
Quoted 2 lines · Alice Ryhl

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Quoted 8 lines
Quoted 6 lines

You can design the trait to look similar to traits in external crates. We did that for FromBytes/AsBytes.

I assume you're referring to the PrimInt trait [1]? That trait doesn't really let you get rid of the catch-all case, and it's not even unreachable due to the u128 type.

It was num::Integer which seems to be similar.

Abstracting over a set of C functions that matches on the different integer types seems like it'll be pretty common in the kernel. I think it's perfectly fine for you to add a trait for that purpose.

Quoted 34 lines
Quoted 6 lines

[1]: https://docs.rs/num-traits/0.2.19/num_traits/int/trait.PrimInt.html

Quoted 4 lines
Quoted 4 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

No. What should it do if you pass it something that implements both traits?

If you want a single function name, you'll need one trait.

I'm not sure I want that actually.

DT boolean is a bit special. A property not present is false. Everything else is true. For example, 'prop = <0>' or 'prop = "string"' are both true. I'm moving things in the kernel to be stricter so that those cases are errors. I recently introduced (of|device)_property_present() for that reason. There's no type information stored in DT. At the DT level, it's all just byte arrays. However, we now have all the type information for properties within the schema. So eventually, I want to use that to warn on accessing properties with the wrong type.

For example, I think I don't want this to work:

if dev.property_read(c_str!("test,i16-array"))? {
    // do something
}

But instead have:

Quoted 7 lines
if dev.property_present(c_str!("test,i16-array")) {
    // do something
}

To actually warn on property_read_bool, I'm going to have to rework the underlying C implementation to separate device_property_present and device_property_read_bool implementations.

Having bool separate seems fine to me.

Alice

#21 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

In reply to Rob Herring
Quoted 59 lines · Rob Herring
Quoted 16 lines · Alice Ryhl
Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Quoted 6 lines

You can design the trait to look similar to traits in external crates. We did that for FromBytes/AsBytes.

I assume you're referring to the PrimInt trait [1]? That trait doesn't really let you get rid of the catch-all case, and it's not even unreachable due to the u128 type.

It was num::Integer which seems to be similar.

Quoted 7 lines

[1]: https://docs.rs/num-traits/0.2.19/num_traits/int/trait.PrimInt.html

Quoted 4 lines
Quoted 4 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

No. What should it do if you pass it something that implements both traits?

If you want a single function name, you'll need one trait.

I'm not sure I want that actually.

DT boolean is a bit special. A property not present is false. Everything else is true. For example, 'prop = <0>' or 'prop = "string"' are both true. I'm moving things in the kernel to be stricter so that those cases are errors. I recently introduced (of|device)_property_present() for that reason. There's no type information stored in DT. At the DT level, it's all just byte arrays. However, we now have all the type information for properties within the schema. So eventually, I want to use that to warn on accessing properties with the wrong type.

For example, I think I don't want this to work:

if dev.property_read(c_str!("test,i16-array"))? {
    // do something
}
Quoted 5 lines

But instead have:

if dev.property_present(c_str!("test,i16-array")) {
    // do something
}

I think we have "optional" properties which can be there (== true) or not (== false). Let's assume for this example "test,i16-array" is such kind of "optional" property. With what you gave above we need two device tree accesses, then? One to check if it is there and one to read the data:

let mut array = <empty_marker>;

if dev.property_present(c_str!("test,i16-array")) {
    array = dev.property_read(c_str!("test,i16-array"))?;
}

?

Instead of these two accesses, I was thinking to use the error property_read() will return if the optional property is not there to just do one access:

let mut array = <empty_marker>;

if let Ok(val) = dev.property_read(c_str!("test,i16-array")) {
       array = val;
}

(and ignore the error case as its irrelvant in the optional case)

Have I missed anything?

Best regards

Dirk

author maintainer
#22 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 67 lines · Dirk Behme
Quoted 59 lines · Rob Herring
Quoted 16 lines · Alice Ryhl
Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Quoted 6 lines

You can design the trait to look similar to traits in external crates. We did that for FromBytes/AsBytes.

I assume you're referring to the PrimInt trait [1]? That trait doesn't really let you get rid of the catch-all case, and it's not even unreachable due to the u128 type.

It was num::Integer which seems to be similar.

Quoted 7 lines

[1]: https://docs.rs/num-traits/0.2.19/num_traits/int/trait.PrimInt.html

Quoted 4 lines
Quoted 4 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

No. What should it do if you pass it something that implements both traits?

If you want a single function name, you'll need one trait.

I'm not sure I want that actually.

DT boolean is a bit special. A property not present is false. Everything else is true. For example, 'prop = <0>' or 'prop = "string"' are both true. I'm moving things in the kernel to be stricter so that those cases are errors. I recently introduced (of|device)_property_present() for that reason. There's no type information stored in DT. At the DT level, it's all just byte arrays. However, we now have all the type information for properties within the schema. So eventually, I want to use that to warn on accessing properties with the wrong type.

For example, I think I don't want this to work:

if dev.property_read(c_str!("test,i16-array"))? {
    // do something
}
Quoted 5 lines

But instead have:

if dev.property_present(c_str!("test,i16-array")) {
    // do something
}
Quoted 5 lines

I think we have "optional" properties which can be there (== true) or not (== false). Let's assume for this example "test,i16-array" is such kind of "optional" property. With what you gave above we need two device tree accesses, then? One to check if it is there and one to read the data:

Yes, lots of properties are optional especially since any new property added has to be because the DT is an ABI.

Quoted 11 lines

let mut array = <empty_marker>;

if dev.property_present(c_str!("test,i16-array")) {
    array = dev.property_read(c_str!("test,i16-array"))?;
}

?

Instead of these two accesses, I was thinking to use the error property_read() will return if the optional property is not there to just do one access:

Quoted 8 lines

let mut array = <empty_marker>;

if let Ok(val) = dev.property_read(c_str!("test,i16-array")) {
       array = val;
}

(and ignore the error case as its irrelvant in the optional case)

Have I missed anything?

If you grep "_property_present", most if not all calls never need the data. When you need the data, you read it and test for EINVAL if you want to handle "not present". The overhead of parsing the data is not nothing, so I think it is better to provide both.

The typical pattern in the C code is:

u32 val = DEFAULT_VALUE;
of_property_read_u32(node, "a-property", &val);

// val is now either the read property or the default. If the property is required, then the error code needs to be checked.

Maybe we should have:

let val: u32 = dev.property_read_optional(c_str!("test,i16-array"), DEFAULT_VALUE);

Or looks like Option<> could be used here?:

let val: u32 = dev.property_read(c_str!("test,i16-array"), Option<DEFAULT_VALUE>);

One thing I'd like to improve is having fewer driver error messages and a printk for a missing required property is a common one. We have APIs like clk_get and clk_get_optional (which parse firmware properties). The difference is the former prints an error message on error case and the latter is silent.

Rob

#23 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

Quoted 102 lines · Rob Herring
Quoted 67 lines · Dirk Behme
Quoted 59 lines · Rob Herring
Quoted 16 lines · Alice Ryhl
Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Quoted 6 lines

You can design the trait to look similar to traits in external crates. We did that for FromBytes/AsBytes.

I assume you're referring to the PrimInt trait [1]? That trait doesn't really let you get rid of the catch-all case, and it's not even unreachable due to the u128 type.

It was num::Integer which seems to be similar.

Quoted 7 lines

[1]: https://docs.rs/num-traits/0.2.19/num_traits/int/trait.PrimInt.html

Quoted 4 lines
Quoted 4 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

No. What should it do if you pass it something that implements both traits?

If you want a single function name, you'll need one trait.

I'm not sure I want that actually.

DT boolean is a bit special. A property not present is false. Everything else is true. For example, 'prop = <0>' or 'prop = "string"' are both true. I'm moving things in the kernel to be stricter so that those cases are errors. I recently introduced (of|device)_property_present() for that reason. There's no type information stored in DT. At the DT level, it's all just byte arrays. However, we now have all the type information for properties within the schema. So eventually, I want to use that to warn on accessing properties with the wrong type.

For example, I think I don't want this to work:

if dev.property_read(c_str!("test,i16-array"))? {
    // do something
}
Quoted 5 lines

But instead have:

if dev.property_present(c_str!("test,i16-array")) {
    // do something
}
Quoted 5 lines

I think we have "optional" properties which can be there (== true) or not (== false). Let's assume for this example "test,i16-array" is such kind of "optional" property. With what you gave above we need two device tree accesses, then? One to check if it is there and one to read the data:

Yes, lots of properties are optional especially since any new property added has to be because the DT is an ABI.

Quoted 11 lines

let mut array = <empty_marker>;

if dev.property_present(c_str!("test,i16-array")) {
    array = dev.property_read(c_str!("test,i16-array"))?;
}

?

Instead of these two accesses, I was thinking to use the error property_read() will return if the optional property is not there to just do one access:

Quoted 8 lines

let mut array = <empty_marker>;

if let Ok(val) = dev.property_read(c_str!("test,i16-array")) {
       array = val;
}

(and ignore the error case as its irrelvant in the optional case)

Have I missed anything?

If you grep "_property_present", most if not all calls never need the data. When you need the data, you read it and test for EINVAL if you want to handle "not present". The overhead of parsing the data is not nothing, so I think it is better to provide both.

Quoted 7 lines

The typical pattern in the C code is:

u32 val = DEFAULT_VALUE;
of_property_read_u32(node, "a-property", &val);

// val is now either the read property or the default. If the property is required, then the error code needs to be checked.

Yes :)

Quoted 9 lines

Maybe we should have:

let val: u32 = dev.property_read_optional(c_str!("test,i16-array"), DEFAULT_VALUE);

Or looks like Option<> could be used here?:

let val: u32 = dev.property_read(c_str!("test,i16-array"), Option<DEFAULT_VALUE>);

In the success case we will get back Some(val)? In the error case 'val' will get Some(DEFAULT_VALUE)? But where would we get the error value itself (e.g. EINVAL)? Or is the idea to not care about that any more then? When would we use None?

Best regards

Dirk

Quoted 7 lines

One thing I'd like to improve is having fewer driver error messages and a printk for a missing required property is a common one. We have APIs like clk_get and clk_get_optional (which parse firmware properties). The difference is the former prints an error message on error case and the latter is silent.

Rob

#24 lore raw

Re: [PATCH RFC 2/3] rust: Add bindings for device properties

In reply to Rob Herring

Hi Rob,

Quoted 117 lines · Rob Herring
Quoted 67 lines · Dirk Behme
Quoted 59 lines · Rob Herring
Quoted 16 lines · Alice Ryhl
Quoted 6 lines · Rob Herring
Quoted 3 lines · Miguel Ojeda
Quoted 1 line · Alice Ryhl
Quoted 7 lines
Quoted 1 line
Quoted 1 line

One option is to define a trait for integers:

Yeah, but that doesn't feel like something I should do here. I imagine other things might need the same thing. Perhaps the bindings for readb/readw/readl for example. And essentially the crate:num already has the trait I need. Shouldn't the kernel mirror that? I recall seeing some topic of including crates in the kernel?

Quoted 6 lines

You can design the trait to look similar to traits in external crates. We did that for FromBytes/AsBytes.

I assume you're referring to the PrimInt trait [1]? That trait doesn't really let you get rid of the catch-all case, and it's not even unreachable due to the u128 type.

It was num::Integer which seems to be similar.

Quoted 7 lines

[1]: https://docs.rs/num-traits/0.2.19/num_traits/int/trait.PrimInt.html

Quoted 4 lines
Quoted 4 lines

+1, one more thing to consider is whether it makes sense to define a DT-only trait that holds all the types that can be a device property (like bool too, not just the Integers).

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Then we can avoid e.g. property_read_bool and simply do it in property_read.

Is there no way to say must have traitA or traitB?

No. What should it do if you pass it something that implements both traits?

If you want a single function name, you'll need one trait.

I'm not sure I want that actually.

DT boolean is a bit special. A property not present is false. Everything else is true. For example, 'prop = <0>' or 'prop = "string"' are both true. I'm moving things in the kernel to be stricter so that those cases are errors. I recently introduced (of|device)_property_present() for that reason. There's no type information stored in DT. At the DT level, it's all just byte arrays. However, we now have all the type information for properties within the schema. So eventually, I want to use that to warn on accessing properties with the wrong type.

For example, I think I don't want this to work:

if dev.property_read(c_str!("test,i16-array"))? {
     // do something
}
Quoted 5 lines

But instead have:

if dev.property_present(c_str!("test,i16-array")) {
     // do something
}
Quoted 5 lines

I think we have "optional" properties which can be there (== true) or not (== false). Let's assume for this example "test,i16-array" is such kind of "optional" property. With what you gave above we need two device tree accesses, then? One to check if it is there and one to read the data:

Yes, lots of properties are optional especially since any new property added has to be because the DT is an ABI.

Quoted 11 lines

let mut array = <empty_marker>;

if dev.property_present(c_str!("test,i16-array")) {
     array = dev.property_read(c_str!("test,i16-array"))?;
}

?

Instead of these two accesses, I was thinking to use the error property_read() will return if the optional property is not there to just do one access:

Quoted 8 lines

let mut array = <empty_marker>;

if let Ok(val) = dev.property_read(c_str!("test,i16-array")) {
        array = val;
}

(and ignore the error case as its irrelvant in the optional case)

Have I missed anything?

If you grep "_property_present", most if not all calls never need the data. When you need the data, you read it and test for EINVAL if you want to handle "not present". The overhead of parsing the data is not nothing, so I think it is better to provide both.

The typical pattern in the C code is:

u32 val = DEFAULT_VALUE;
of_property_read_u32(node, "a-property", &val);

// val is now either the read property or the default. If the property is required, then the error code needs to be checked.

Maybe we should have:

let val: u32 = dev.property_read_optional(c_str!("test,i16-array"), DEFAULT_VALUE);

Or looks like Option<> could be used here?:

Quoted 8 lines

let val: u32 = dev.property_read(c_str!("test,i16-array"), Option<DEFAULT_VALUE>);

One thing I'd like to improve is having fewer driver error messages and a printk for a missing required property is a common one. We have APIs like clk_get and clk_get_optional (which parse firmware properties). The difference is the former prints an error message on error case and the latter is silent.

Maybe something like [1]?

It uses 'None' for mandatory properties and 'Some(<default>)' for optional properties. And gives an error only in case of a missing manadatory property.

Best regards

Dirk

[1]

rust/kernel/device.rs +17 -3
index 4161e7534018a..d97ec2d13a0ba 100644
@@ -214,12 +214,26 @@ pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usi
 
     /// Returns firmware property `name` scalar value
     ///
+    /// Option is None: The property is assumed to be mandatory and an error
+    /// is returned if it is not found.
+    /// Option is Some(default): The property is optional and the passed default
+    /// value is returned if it is not found.
+    ///
     /// Valid types are i8, u8, i16, u16, i32, u32, i64, u64
-    pub fn property_read<T: Copy>(&self, name: &CStr) -> Result<T> {
+    pub fn property_read<T: Copy>(&self, name: &CStr, default: Option<T>) -> Result<T> {
         let mut val: [T; 1] = unsafe { core::mem::zeroed() };
 
-        Self::_property_read_array(&self, name, &mut val)?;
-        Ok(val[0])
+        match Self::_property_read_array(&self, name, &mut val) {
+            Ok(()) => return Ok(val[0]),
+            Err(e) => match default {
+                Some(default) => return Ok(default),
+                None => {
+                    dev_err!(self, "Failed to read mandatory property '{}' with error {}\n",
+                             name, e.to_errno());
+                    Err(e)
+                }
+            },
+        }
     }
 
     /// Returns firmware property `name` array values
samples/rust/rust_driver_platform.rs +13 -2
index 95c2908068623..f8fe0f554183d 100644
@@ -50,10 +50,21 @@ fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) -> Result<Pin
         let prop = dev.property_read_bool(c_str!("test,bool-prop"));
         dev_info!(dev, "bool prop is {}\n", prop);
 
-        let _prop = dev.property_read::<u32>(c_str!("test,u32-prop"))?;
-        let prop: u32 = dev.property_read(c_str!("test,u32-prop"))?;
+        let _prop = dev.property_read::<u32>(c_str!("test,u32-prop"), None)?;
+        let prop: u32 = dev.property_read(c_str!("test,u32-prop"), None)?;
         dev_info!(dev, "'test,u32-prop' is {:#x}\n", prop);
 
+        // Assume 'test,u32-optional' is an optional property which does not exist.
+        let prop: u32 = dev.property_read(c_str!("test,u32-optional"), Some(0xdb))?;
+        // Should print the default 0xdb and give no error.
+        dev_info!(dev, "'test,u32-optional' default is {:#x}\n", prop);
+
+        // Assume 'test,u32-mandatory' is a mandatory property which does not exist.
+        // Should print an error (but ignore it in this example).
+        match dev.property_read::<u32>(c_str!("test,u32-mandatory"), None) {
+            _ => (),
+        }
+
         let prop: [i16; 4] = 
dev.property_read_array(c_str!("test,i16-array"))?;
         dev_info!(dev, "'test,i16-array' is {:?}\n", prop);
         dev_info!(
author maintainer
#25 lore raw

RFC PATCH 3/3 samples: rust: platform: Add property read examples

In reply to Rob Herring (Arm)

Add some example usage of the device property read methods for DT/ACPI/swnode properties.

---
 drivers/of/unittest-data/tests-platform.dtsi |  3 +++
 samples/rust/rust_driver_platform.rs         | 22 ++++++++++++++++++++++
 2 files changed, 25 insertions(+)
drivers/of/unittest-data/tests-platform.dtsi +3 -0
index 2caaf1c10ee6..a5369b9343b8 100644
@@ -37,6 +37,9 @@ dev@100 {
 			test-device@2 {
 				compatible = "test,rust-device";
 				reg = <0x2>;
+
+				test,u32-prop = <0xdeadbeef>;
+				test,i16-array = /bits/ 16 <1 2 (-3) (-4)>;
 			};
 		};
 	};
samples/rust/rust_driver_platform.rs +22 -0
index 5cf4a8f86c13..95c290806862 100644
@@ -41,6 +41,28 @@ fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) -> Result<Pin
             }
         };
 
+        let dev = pdev.as_ref();
+        if let Ok(idx) = dev.property_match_string(c_str!("compatible"), c_str!("test,rust-device"))
+        {
+            dev_info!(pdev.as_ref(), "matched compatible string idx = {}\n", idx);
+        }
+
+        let prop = dev.property_read_bool(c_str!("test,bool-prop"));
+        dev_info!(dev, "bool prop is {}\n", prop);
+
+        let _prop = dev.property_read::<u32>(c_str!("test,u32-prop"))?;
+        let prop: u32 = dev.property_read(c_str!("test,u32-prop"))?;
+        dev_info!(dev, "'test,u32-prop' is {:#x}\n", prop);
+
+        let prop: [i16; 4] = dev.property_read_array(c_str!("test,i16-array"))?;
+        dev_info!(dev, "'test,i16-array' is {:?}\n", prop);
+        dev_info!(
+            dev,
+            "'test,i16-array' length is {}\n",
+            dev.property_count_elem::<u16>(c_str!("test,i16-array"))
+                .unwrap()
+        );
+
         let drvdata = KBox::new(Self { pdev: pdev.clone() }, GFP_KERNEL)?;
 
         Ok(drvdata.into())
Signature · 1 line
2.45.2
#26 lore raw

Re: [PATCH RFC 3/3] samples: rust: platform: Add property read examples

Quoted 4 lines · Rob Herring (Arm)

Add some example usage of the device property read methods for DT/ACPI/swnode properties.

I think that we should mention that this works only with CONFIG_OF_UNITTEST enabled? And/or maybe wrap the whole somehow with

#[cfg(CONFIG_OF_UNITTEST)]

?

Quoted 24 lines
---
  drivers/of/unittest-data/tests-platform.dtsi |  3 +++
  samples/rust/rust_driver_platform.rs         | 22 ++++++++++++++++++++++
  2 files changed, 25 insertions(+)
drivers/of/unittest-data/tests-platform.dtsi +3 -0
index 2caaf1c10ee6..a5369b9343b8 100644
@@ -37,6 +37,9 @@ dev@100 {
  			test-device@2 {
  				compatible = "test,rust-device";
  				reg = <0x2>;
+
+				test,u32-prop = <0xdeadbeef>;
+				test,i16-array = /bits/ 16 <1 2 (-3) (-4)>;
  			};
  		};
  	};
samples/rust/rust_driver_platform.rs +0 -0
index 5cf4a8f86c13..95c290806862 100644

samples/rust/rust_driver_platform.rs fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) -> Result<Pin · line 44

Quoted 4 lines
samples/rust/rust_driver_platform.rs +1 -0
@@ -41,6 +41,28 @@ fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) -> Result<Pin
              }
          };
 
+        let dev = pdev.as_ref();

Maybe move this up and use it in Danilo's part, as well? To stay consistent?

samples/rust/rust_driver_platform.rs +2 -2
@@ -26,25 +26,25 @@ impl platform::Driver for SampleDriver {
 
     fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) 
-> Result<Pin<KBox<Self>>> {
         dev_dbg!(pdev.as_ref(), "Probe Rust Platform driver sample.\n");
+        let dev = pdev.as_ref();
 
         match (Self::of_match_device(pdev), info) {
             (Some(id), Some(info)) => {
                 dev_info!(
-                    pdev.as_ref(),
+                    dev,
                     "Probed by OF compatible match: '{}' with info: 

'{}'.\n",

                     id.compatible(),
                     info.0
                 );
             }
             _ => {
-                dev_info!(pdev.as_ref(), "Probed by name.\n");
+                dev_info!(dev, "Probed by name.\n");
             }
         };

- let dev = pdev.as_ref();
if let Ok(idx) =
dev.property_match_string(c_str!("compatible"), c_str!("test,rust-device"))

         {
-            dev_info!(pdev.as_ref(), "matched compatible string idx = {}\n", idx);
+            dev_info!(dev, "matched compatible string idx = {}\n", idx);
         }

         let prop = dev.property_read_bool(c_str!("test,bool-prop"));

@@ -56,12 +56,10 @@ fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) -> Result<Pin

samples/rust/rust_driver_platform.rs fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) -> Result<Pin · line 50

Quoted 6 lines
samples/rust/rust_driver_platform.rs +6 -0
+        if let Ok(idx) = dev.property_match_string(c_str!("compatible"), c_str!("test,rust-device"))
+        {
+            dev_info!(pdev.as_ref(), "matched compatible string idx = {}\n", idx);
+        }
+
+        let prop = dev.property_read_bool(c_str!("test,bool-prop"));

I stopped reading here with "hey, "test,bool-prop" isn't in the tests-platform.dtsi above, no?". Until I realized that this is intentional to get back false. So whats about adding a comment like

// Intentionally check for an non-existent property to get back false

?

samples/rust/rust_driver_platform.rs fn probe(pdev: &mut platform::Device, info: Option<&Self::IdInfo>) -> Result<Pin · line 63

Quoted 13 lines
samples/rust/rust_driver_platform.rs +13 -0
+        dev_info!(dev, "bool prop is {}\n", prop);
+
+        let _prop = dev.property_read::<u32>(c_str!("test,u32-prop"))?;
+        let prop: u32 = dev.property_read(c_str!("test,u32-prop"))?;
+        dev_info!(dev, "'test,u32-prop' is {:#x}\n", prop);
+
+        let prop: [i16; 4] = dev.property_read_array(c_str!("test,i16-array"))?;
+        dev_info!(dev, "'test,i16-array' is {:?}\n", prop);
+        dev_info!(
+            dev,
+            "'test,i16-array' length is {}\n",
+            dev.property_count_elem::<u16>(c_str!("test,i16-array"))
+                .unwrap()

In the error case unwrap() (or expect()) will result in panic(). Besides some very rare cases I don't see a reason why device drivers should panic. Esp. not if reading some array length from the device tree fails ;) So I don't think we should encourage using unwrap() or expect() in drivers by using them even in example code. Which most probably will be copied quite often, then ;)

What's about anything like this instead?

         let prop: [i16; 4] = 
dev.property_read_array(c_str!("test,i16-array"))?;
         dev_info!(dev, "'test,i16-array' is {:?}\n", prop);
-        dev_info!(
-            dev,
-            "'test,i16-array' length is {}\n",
-            dev.property_count_elem::<u16>(c_str!("test,i16-array"))
-                .unwrap()
-        );
+        let len = dev.property_count_elem::<u16>(c_str!("test,i16-array"));
+        if let Ok(length) = len {

+ dev_info!(dev, "'test,i16-array' length is {}\n", length);
+ }

         let drvdata = KBox::new(Self { pdev: pdev.clone() }, GFP_KERNEL)?;

Or if we want a reasonable error message in the error case, as well, we could switch to a match, instead.

Best regards

Dirk

Quoted 6 lines
samples/rust/rust_driver_platform.rs +2 -0
+        );
+
          let drvdata = KBox::new(Self { pdev: pdev.clone() }, GFP_KERNEL)?;
 
          Ok(drvdata.into())
Tested-by on the v1 series
#27 lore raw
In reply to Rob Herring (Arm)
Quoted 2 lines · Rob Herring (Arm)

I got asked about upstreaming DT rust bindings, so I decided to take a stab at it.

Many thanks for this!

Quoted 9 lines

This series adds rust bindings for the device property API which is a firmware agnostic interface for reading firmware properties. There are "DT rust bindings" patches floating around, but for many drivers they don't need to know any DT specifics nor deal with struct device_node (and its refcounts). And reading firmware properties are simple enough for my feeble rust abilities.

This series is based on top of Danilo's PCI and platform device series[1], though that's really only for the sample driver.

On x86 having CONFIG_OF_UNITTESTS enabled I get

rust_driver_platform testcase-data:platform-tests:test-device@2: Probed by OF compatible match: 'test,rust-device' with info: '42'. rust_driver_platform testcase-data:platform-tests:test-device@2: matched compatible string idx = 0 rust_driver_platform testcase-data:platform-tests:test-device@2: bool prop is false
rust_driver_platform testcase-data:platform-tests:test-device@2: 'test,u32-prop' is 0xdeadbeef rust_driver_platform testcase-data:platform-tests:test-device@2: 'test,i16-array' is [1, 2, -3, -4] rust_driver_platform testcase-data:platform-tests:test-device@2: 'test,i16-array' length is 4

with this. Looks good :)

I'm not sure if it makes sense for an RFC patch series but in case it helps:

Some comments will follow in the individual patches.

Best regards

Dirk

Quoted 24 lines

Please tell me how my rust code sucks before I spend more time beating my head against the wall^W^W^W^W^W^W learning rust.

Rob

[1] https://lore.kernel.org/all/[email protected]/

---
Rob Herring (Arm) (3):
of: unittest: Add a platform device node for rust platform driver sample
rust: Add bindings for device properties
samples: rust: platform: Add property read examples

  drivers/of/unittest-data/tests-platform.dtsi |   8 ++
  rust/bindings/bindings_helper.h              |   1 +
  rust/kernel/device.rs                        | 145 ++++++++++++++++++++++++++-
  samples/rust/rust_driver_platform.rs         |  24 ++++-
  4 files changed, 176 insertions(+), 2 deletions(-)

---
base-commit: eeb31b3e7e9e1b485763ecc66ece8afba1416b2a
change-id: 20241025-rust-platform-dev-0e89debcbba5

Best regards,