kernel/device/property.rs
1// SPDX-License-Identifier: GPL-2.0
2
3//! Unified device property interface.
4//!
5//! C header: [`include/linux/property.h`](srctree/include/linux/property.h)
6
7use core::{mem::MaybeUninit, ptr};
8
9use super::private::Sealed;
10use crate::{
11 alloc::KVec,
12 bindings,
13 error::{to_result, Result},
14 fmt,
15 prelude::*,
16 str::{CStr, CString},
17 types::{ARef, Opaque},
18};
19
20/// A reference-counted fwnode_handle.
21///
22/// This structure represents the Rust abstraction for a
23/// C `struct fwnode_handle`. This implementation abstracts the usage of an
24/// already existing C `struct fwnode_handle` within Rust code that we get
25/// passed from the C side.
26///
27/// # Invariants
28///
29/// A `FwNode` instance represents a valid `struct fwnode_handle` created by the
30/// C portion of the kernel.
31///
32/// Instances of this type are always reference-counted, that is, a call to
33/// `fwnode_handle_get` ensures that the allocation remains valid at least until
34/// the matching call to `fwnode_handle_put`.
35#[repr(transparent)]
36pub struct FwNode(Opaque<bindings::fwnode_handle>);
37
38impl FwNode {
39 /// # Safety
40 ///
41 /// Callers must ensure that:
42 /// - The reference count was incremented at least once.
43 /// - They relinquish that increment. That is, if there is only one
44 /// increment, callers must not use the underlying object anymore -- it is
45 /// only safe to do so via the newly created `ARef<FwNode>`.
46 unsafe fn from_raw(raw: *mut bindings::fwnode_handle) -> ARef<Self> {
47 // SAFETY: As per the safety requirements of this function:
48 // - `NonNull::new_unchecked`:
49 // - `raw` is not null.
50 // - `ARef::from_raw`:
51 // - `raw` has an incremented refcount.
52 // - that increment is relinquished, i.e. it won't be decremented
53 // elsewhere.
54 // CAST: It is safe to cast from a `*mut fwnode_handle` to
55 // `*mut FwNode`, because `FwNode` is defined as a
56 // `#[repr(transparent)]` wrapper around `fwnode_handle`.
57 unsafe { ARef::from_raw(ptr::NonNull::new_unchecked(raw.cast())) }
58 }
59
60 /// Obtain the raw `struct fwnode_handle *`.
61 pub(crate) fn as_raw(&self) -> *mut bindings::fwnode_handle {
62 self.0.get()
63 }
64
65 /// Returns `true` if `&self` is an OF node, `false` otherwise.
66 pub fn is_of_node(&self) -> bool {
67 // SAFETY: The type invariant of `Self` guarantees that `self.as_raw() is a pointer to a
68 // valid `struct fwnode_handle`.
69 unsafe { bindings::is_of_node(self.as_raw()) }
70 }
71
72 /// Returns an object that implements [`Display`](fmt::Display) for
73 /// printing the name of a node.
74 ///
75 /// This is an alternative to the default `Display` implementation, which
76 /// prints the full path.
77 pub fn display_name(&self) -> impl fmt::Display + '_ {
78 struct FwNodeDisplayName<'a>(&'a FwNode);
79
80 impl fmt::Display for FwNodeDisplayName<'_> {
81 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
82 // SAFETY: `self` is valid by its type invariant.
83 let name = unsafe { bindings::fwnode_get_name(self.0.as_raw()) };
84 if name.is_null() {
85 return Ok(());
86 }
87 // SAFETY:
88 // - `fwnode_get_name` returns null or a valid C string.
89 // - `name` was checked to be non-null.
90 let name = unsafe { CStr::from_char_ptr(name) };
91 fmt::Display::fmt(name, f)
92 }
93 }
94
95 FwNodeDisplayName(self)
96 }
97
98 /// Checks if property is present or not.
99 pub fn property_present(&self, name: &CStr) -> bool {
100 // SAFETY: By the invariant of `CStr`, `name` is null-terminated.
101 unsafe { bindings::fwnode_property_present(self.as_raw().cast_const(), name.as_char_ptr()) }
102 }
103
104 /// Returns firmware property `name` boolean value.
105 pub fn property_read_bool(&self, name: &CStr) -> bool {
106 // SAFETY:
107 // - `name` is non-null and null-terminated.
108 // - `self.as_raw()` is valid because `self` is valid.
109 unsafe { bindings::fwnode_property_read_bool(self.as_raw(), name.as_char_ptr()) }
110 }
111
112 /// Returns the index of matching string `match_str` for firmware string
113 /// property `name`.
114 pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
115 // SAFETY:
116 // - `name` and `match_str` are non-null and null-terminated.
117 // - `self.as_raw` is valid because `self` is valid.
118 let ret = unsafe {
119 bindings::fwnode_property_match_string(
120 self.as_raw(),
121 name.as_char_ptr(),
122 match_str.as_char_ptr(),
123 )
124 };
125 to_result(ret)?;
126 Ok(ret as usize)
127 }
128
129 /// Returns firmware property `name` integer array values in a [`KVec`].
130 pub fn property_read_array_vec<'fwnode, 'name, T: PropertyInt>(
131 &'fwnode self,
132 name: &'name CStr,
133 len: usize,
134 ) -> Result<PropertyGuard<'fwnode, 'name, KVec<T>>> {
135 let mut val: KVec<T> = KVec::with_capacity(len, GFP_KERNEL)?;
136
137 let res = T::read_array_from_fwnode_property(self, name, val.spare_capacity_mut());
138 let res = match res {
139 Ok(_) => {
140 // SAFETY:
141 // - `len` is equal to `val.capacity - val.len`, because
142 // `val.capacity` is `len` and `val.len` is zero.
143 // - All elements within the interval [`0`, `len`) were initialized
144 // by `read_array_from_fwnode_property`.
145 unsafe { val.inc_len(len) }
146 Ok(val)
147 }
148 Err(e) => Err(e),
149 };
150 Ok(PropertyGuard {
151 inner: res,
152 fwnode: self,
153 name,
154 })
155 }
156
157 /// Returns integer array length for firmware property `name`.
158 pub fn property_count_elem<T: PropertyInt>(&self, name: &CStr) -> Result<usize> {
159 T::read_array_len_from_fwnode_property(self, name)
160 }
161
162 /// Returns the value of firmware property `name`.
163 ///
164 /// This method is generic over the type of value to read. The types that
165 /// can be read are strings, integers and arrays of integers.
166 ///
167 /// Reading a [`KVec`] of integers is done with the separate
168 /// method [`Self::property_read_array_vec`], because it takes an
169 /// additional `len` argument.
170 ///
171 /// Reading a boolean is done with the separate method
172 /// [`Self::property_read_bool`], because this operation is infallible.
173 ///
174 /// For more precise documentation about what types can be read, see
175 /// the [implementors of Property][Property#implementors] and [its
176 /// implementations on foreign types][Property#foreign-impls].
177 ///
178 /// # Examples
179 ///
180 /// ```
181 /// # use kernel::{c_str, device::{Device, property::FwNode}, str::CString};
182 /// fn examples(dev: &Device) -> Result {
183 /// let fwnode = dev.fwnode().ok_or(ENOENT)?;
184 /// let b: u32 = fwnode.property_read(c_str!("some-number")).required_by(dev)?;
185 /// if let Some(s) = fwnode.property_read::<CString>(c_str!("some-str")).optional() {
186 /// // ...
187 /// }
188 /// Ok(())
189 /// }
190 /// ```
191 pub fn property_read<'fwnode, 'name, T: Property>(
192 &'fwnode self,
193 name: &'name CStr,
194 ) -> PropertyGuard<'fwnode, 'name, T> {
195 PropertyGuard {
196 inner: T::read_from_fwnode_property(self, name),
197 fwnode: self,
198 name,
199 }
200 }
201
202 /// Returns first matching named child node handle.
203 pub fn get_child_by_name(&self, name: &CStr) -> Option<ARef<Self>> {
204 // SAFETY: `self` and `name` are valid by their type invariants.
205 let child =
206 unsafe { bindings::fwnode_get_named_child_node(self.as_raw(), name.as_char_ptr()) };
207 if child.is_null() {
208 return None;
209 }
210 // SAFETY:
211 // - `fwnode_get_named_child_node` returns a pointer with its refcount
212 // incremented.
213 // - That increment is relinquished, i.e. the underlying object is not
214 // used anymore except via the newly created `ARef`.
215 Some(unsafe { Self::from_raw(child) })
216 }
217
218 /// Returns an iterator over a node's children.
219 pub fn children<'a>(&'a self) -> impl Iterator<Item = ARef<FwNode>> + 'a {
220 let mut prev: Option<ARef<FwNode>> = None;
221
222 core::iter::from_fn(move || {
223 let prev_ptr = match prev.take() {
224 None => ptr::null_mut(),
225 Some(prev) => {
226 // We will pass `prev` to `fwnode_get_next_child_node`,
227 // which decrements its refcount, so we use
228 // `ARef::into_raw` to avoid decrementing the refcount
229 // twice.
230 let prev = ARef::into_raw(prev);
231 prev.as_ptr().cast()
232 }
233 };
234 // SAFETY:
235 // - `self.as_raw()` is valid by its type invariant.
236 // - `prev_ptr` may be null, which is allowed and corresponds to
237 // getting the first child. Otherwise, `prev_ptr` is valid, as it
238 // is the stored return value from the previous invocation.
239 // - `prev_ptr` has its refount incremented.
240 // - The increment of `prev_ptr` is relinquished, i.e. the
241 // underlying object won't be used anymore.
242 let next = unsafe { bindings::fwnode_get_next_child_node(self.as_raw(), prev_ptr) };
243 if next.is_null() {
244 return None;
245 }
246 // SAFETY:
247 // - `next` is valid because `fwnode_get_next_child_node` returns a
248 // pointer with its refcount incremented.
249 // - That increment is relinquished, i.e. the underlying object
250 // won't be used anymore, except via the newly created
251 // `ARef<Self>`.
252 let next = unsafe { FwNode::from_raw(next) };
253 prev = Some(next.clone());
254 Some(next)
255 })
256 }
257
258 /// Finds a reference with arguments.
259 pub fn property_get_reference_args(
260 &self,
261 prop: &CStr,
262 nargs: NArgs<'_>,
263 index: u32,
264 ) -> Result<FwNodeReferenceArgs> {
265 let mut out_args = FwNodeReferenceArgs::default();
266
267 let (nargs_prop, nargs) = match nargs {
268 NArgs::Prop(nargs_prop) => (nargs_prop.as_char_ptr(), 0),
269 NArgs::N(nargs) => (ptr::null(), nargs),
270 };
271
272 // SAFETY:
273 // - `self.0.get()` is valid.
274 // - `prop.as_char_ptr()` is valid and zero-terminated.
275 // - `nargs_prop` is valid and zero-terminated if `nargs`
276 // is zero, otherwise it is allowed to be a null-pointer.
277 // - The function upholds the type invariants of `out_args`,
278 // namely:
279 // - It may fill the field `fwnode` with a valid pointer,
280 // in which case its refcount is incremented.
281 // - It may modify the field `nargs`, in which case it
282 // initializes at least as many elements in `args`.
283 let ret = unsafe {
284 bindings::fwnode_property_get_reference_args(
285 self.0.get(),
286 prop.as_char_ptr(),
287 nargs_prop,
288 nargs,
289 index,
290 &mut out_args.0,
291 )
292 };
293 to_result(ret)?;
294
295 Ok(out_args)
296 }
297}
298
299/// The number of arguments to request [`FwNodeReferenceArgs`].
300pub enum NArgs<'a> {
301 /// The name of the property of the reference indicating the number of
302 /// arguments.
303 Prop(&'a CStr),
304 /// The known number of arguments.
305 N(u32),
306}
307
308/// The return value of [`FwNode::property_get_reference_args`].
309///
310/// This structure represents the Rust abstraction for a C
311/// `struct fwnode_reference_args` which was initialized by the C side.
312///
313/// # Invariants
314///
315/// If the field `fwnode` is valid, it owns an increment of its refcount.
316///
317/// The field `args` contains at least as many initialized elements as indicated
318/// by the field `nargs`.
319#[repr(transparent)]
320#[derive(Default)]
321pub struct FwNodeReferenceArgs(bindings::fwnode_reference_args);
322
323impl Drop for FwNodeReferenceArgs {
324 fn drop(&mut self) {
325 if !self.0.fwnode.is_null() {
326 // SAFETY:
327 // - By the type invariants of `FwNodeReferenceArgs`, its field
328 // `fwnode` owns an increment of its refcount.
329 // - That increment is relinquished. The underlying object won't be
330 // used anymore because we are dropping it.
331 let _ = unsafe { FwNode::from_raw(self.0.fwnode) };
332 }
333 }
334}
335
336impl FwNodeReferenceArgs {
337 /// Returns the slice of reference arguments.
338 pub fn as_slice(&self) -> &[u64] {
339 // SAFETY: As per the safety invariant of `FwNodeReferenceArgs`, `nargs`
340 // is the minimum number of elements in `args` that is valid.
341 unsafe { core::slice::from_raw_parts(self.0.args.as_ptr(), self.0.nargs as usize) }
342 }
343
344 /// Returns the number of reference arguments.
345 pub fn len(&self) -> usize {
346 self.0.nargs as usize
347 }
348
349 /// Returns `true` if there are no reference arguments.
350 pub fn is_empty(&self) -> bool {
351 self.0.nargs == 0
352 }
353}
354
355impl fmt::Debug for FwNodeReferenceArgs {
356 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
357 write!(f, "{:?}", self.as_slice())
358 }
359}
360
361// SAFETY: Instances of `FwNode` are always reference-counted.
362unsafe impl crate::types::AlwaysRefCounted for FwNode {
363 fn inc_ref(&self) {
364 // SAFETY: The existence of a shared reference guarantees that the
365 // refcount is non-zero.
366 unsafe { bindings::fwnode_handle_get(self.as_raw()) };
367 }
368
369 unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
370 // SAFETY: The safety requirements guarantee that the refcount is
371 // non-zero.
372 unsafe { bindings::fwnode_handle_put(obj.cast().as_ptr()) }
373 }
374}
375
376enum Node<'a> {
377 Borrowed(&'a FwNode),
378 Owned(ARef<FwNode>),
379}
380
381impl fmt::Display for FwNode {
382 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
383 // The logic here is the same as the one in lib/vsprintf.c
384 // (fwnode_full_name_string).
385
386 // SAFETY: `self.as_raw()` is valid by its type invariant.
387 let num_parents = unsafe { bindings::fwnode_count_parents(self.as_raw()) };
388
389 for depth in (0..=num_parents).rev() {
390 let fwnode = if depth == 0 {
391 Node::Borrowed(self)
392 } else {
393 // SAFETY: `self.as_raw()` is valid.
394 let ptr = unsafe { bindings::fwnode_get_nth_parent(self.as_raw(), depth) };
395 // SAFETY:
396 // - The depth passed to `fwnode_get_nth_parent` is
397 // within the valid range, so the returned pointer is
398 // not null.
399 // - The reference count was incremented by
400 // `fwnode_get_nth_parent`.
401 // - That increment is relinquished to
402 // `FwNode::from_raw`.
403 Node::Owned(unsafe { FwNode::from_raw(ptr) })
404 };
405 // Take a reference to the owned or borrowed `FwNode`.
406 let fwnode: &FwNode = match &fwnode {
407 Node::Borrowed(f) => f,
408 Node::Owned(f) => f,
409 };
410
411 // SAFETY: `fwnode` is valid by its type invariant.
412 let prefix = unsafe { bindings::fwnode_get_name_prefix(fwnode.as_raw()) };
413 if !prefix.is_null() {
414 // SAFETY: `fwnode_get_name_prefix` returns null or a
415 // valid C string.
416 let prefix = unsafe { CStr::from_char_ptr(prefix) };
417 fmt::Display::fmt(prefix, f)?;
418 }
419 fmt::Display::fmt(&fwnode.display_name(), f)?;
420 }
421
422 Ok(())
423 }
424}
425
426/// Implemented for types that can be read as properties.
427///
428/// This is implemented for strings, integers and arrays of integers. It's used
429/// to make [`FwNode::property_read`] generic over the type of property being
430/// read. There are also two dedicated methods to read other types, because they
431/// require more specialized function signatures:
432/// - [`property_read_bool`](FwNode::property_read_bool)
433/// - [`property_read_array_vec`](FwNode::property_read_array_vec)
434///
435/// It must be public, because it appears in the signatures of other public
436/// functions, but its methods shouldn't be used outside the kernel crate.
437pub trait Property: Sized + Sealed {
438 /// Used to make [`FwNode::property_read`] generic.
439 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self>;
440}
441
442impl Sealed for CString {}
443
444impl Property for CString {
445 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self> {
446 let mut str: *mut u8 = ptr::null_mut();
447 let pstr: *mut _ = &mut str;
448
449 // SAFETY:
450 // - `name` is non-null and null-terminated.
451 // - `fwnode.as_raw` is valid because `fwnode` is valid.
452 let ret = unsafe {
453 bindings::fwnode_property_read_string(fwnode.as_raw(), name.as_char_ptr(), pstr.cast())
454 };
455 to_result(ret)?;
456
457 // SAFETY:
458 // - `pstr` is a valid pointer to a NUL-terminated C string.
459 // - It is valid for at least as long as `fwnode`, but it's only used
460 // within the current function.
461 // - The memory it points to is not mutated during that time.
462 let str = unsafe { CStr::from_char_ptr(*pstr) };
463 Ok(str.try_into()?)
464 }
465}
466
467/// Implemented for all integers that can be read as properties.
468///
469/// This helper trait is needed on top of the existing [`Property`]
470/// trait to associate the integer types of various sizes with their
471/// corresponding `fwnode_property_read_*_array` functions.
472///
473/// It must be public, because it appears in the signatures of other public
474/// functions, but its methods shouldn't be used outside the kernel crate.
475pub trait PropertyInt: Copy + Sealed {
476 /// Reads a property array.
477 fn read_array_from_fwnode_property<'a>(
478 fwnode: &FwNode,
479 name: &CStr,
480 out: &'a mut [MaybeUninit<Self>],
481 ) -> Result<&'a mut [Self]>;
482
483 /// Reads the length of a property array.
484 fn read_array_len_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<usize>;
485}
486// This macro generates implementations of the traits `Property` and
487// `PropertyInt` for integers of various sizes. Its input is a list
488// of pairs separated by commas. The first element of the pair is the
489// type of the integer, the second one is the name of its corresponding
490// `fwnode_property_read_*_array` function.
491macro_rules! impl_property_for_int {
492 ($($int:ty: $f:ident),* $(,)?) => { $(
493 impl Sealed for $int {}
494 impl<const N: usize> Sealed for [$int; N] {}
495
496 impl PropertyInt for $int {
497 fn read_array_from_fwnode_property<'a>(
498 fwnode: &FwNode,
499 name: &CStr,
500 out: &'a mut [MaybeUninit<Self>],
501 ) -> Result<&'a mut [Self]> {
502 // SAFETY:
503 // - `fwnode`, `name` and `out` are all valid by their type
504 // invariants.
505 // - `out.len()` is a valid bound for the memory pointed to by
506 // `out.as_mut_ptr()`.
507 // CAST: It's ok to cast from `*mut MaybeUninit<$int>` to a
508 // `*mut $int` because they have the same memory layout.
509 let ret = unsafe {
510 bindings::$f(
511 fwnode.as_raw(),
512 name.as_char_ptr(),
513 out.as_mut_ptr().cast(),
514 out.len(),
515 )
516 };
517 to_result(ret)?;
518 // SAFETY: Transmuting from `&'a mut [MaybeUninit<Self>]` to
519 // `&'a mut [Self]` is sound, because the previous call to a
520 // `fwnode_property_read_*_array` function (which didn't fail)
521 // fully initialized the slice.
522 Ok(unsafe { core::mem::transmute::<&mut [MaybeUninit<Self>], &mut [Self]>(out) })
523 }
524
525 fn read_array_len_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<usize> {
526 // SAFETY:
527 // - `fwnode` and `name` are valid by their type invariants.
528 // - It's ok to pass a null pointer to the
529 // `fwnode_property_read_*_array` functions if `nval` is zero.
530 // This will return the length of the array.
531 let ret = unsafe {
532 bindings::$f(
533 fwnode.as_raw(),
534 name.as_char_ptr(),
535 ptr::null_mut(),
536 0,
537 )
538 };
539 to_result(ret)?;
540 Ok(ret as usize)
541 }
542 }
543
544 impl Property for $int {
545 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self> {
546 let val: [_; 1] = <[$int; 1]>::read_from_fwnode_property(fwnode, name)?;
547 Ok(val[0])
548 }
549 }
550
551 impl<const N: usize> Property for [$int; N] {
552 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self> {
553 let mut val: [MaybeUninit<$int>; N] = [const { MaybeUninit::uninit() }; N];
554
555 <$int>::read_array_from_fwnode_property(fwnode, name, &mut val)?;
556
557 // SAFETY: `val` is always initialized when
558 // `fwnode_property_read_*_array` is successful.
559 Ok(val.map(|v| unsafe { v.assume_init() }))
560 }
561 }
562 )* };
563}
564impl_property_for_int! {
565 u8: fwnode_property_read_u8_array,
566 u16: fwnode_property_read_u16_array,
567 u32: fwnode_property_read_u32_array,
568 u64: fwnode_property_read_u64_array,
569 i8: fwnode_property_read_u8_array,
570 i16: fwnode_property_read_u16_array,
571 i32: fwnode_property_read_u32_array,
572 i64: fwnode_property_read_u64_array,
573}
574
575/// A helper for reading device properties.
576///
577/// Use [`Self::required_by`] if a missing property is considered a bug and
578/// [`Self::optional`] otherwise.
579///
580/// For convenience, [`Self::or`] and [`Self::or_default`] are provided.
581pub struct PropertyGuard<'fwnode, 'name, T> {
582 /// The result of reading the property.
583 inner: Result<T>,
584 /// The fwnode of the property, used for logging in the "required" case.
585 fwnode: &'fwnode FwNode,
586 /// The name of the property, used for logging in the "required" case.
587 name: &'name CStr,
588}
589
590impl<T> PropertyGuard<'_, '_, T> {
591 /// Access the property, indicating it is required.
592 ///
593 /// If the property is not present, the error is automatically logged. If a
594 /// missing property is not an error, use [`Self::optional`] instead. The
595 /// device is required to associate the log with it.
596 pub fn required_by(self, dev: &super::Device) -> Result<T> {
597 if self.inner.is_err() {
598 dev_err!(
599 dev,
600 "{}: property '{}' is missing\n",
601 self.fwnode,
602 self.name
603 );
604 }
605 self.inner
606 }
607
608 /// Access the property, indicating it is optional.
609 ///
610 /// In contrast to [`Self::required_by`], no error message is logged if
611 /// the property is not present.
612 pub fn optional(self) -> Option<T> {
613 self.inner.ok()
614 }
615
616 /// Access the property or the specified default value.
617 ///
618 /// Do not pass a sentinel value as default to detect a missing property.
619 /// Use [`Self::required_by`] or [`Self::optional`] instead.
620 pub fn or(self, default: T) -> T {
621 self.inner.unwrap_or(default)
622 }
623}
624
625impl<T: Default> PropertyGuard<'_, '_, T> {
626 /// Access the property or a default value.
627 ///
628 /// Use [`Self::or`] to specify a custom default value.
629 pub fn or_default(self) -> T {
630 self.inner.unwrap_or_default()
631 }
632}