projects/linux·blob master · refs

633 lines · 23.7 KiB

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