Lines Matching +full:bool +full:- +full:property
1 // SPDX-License-Identifier: GPL-2.0
3 //! Unified device property interface.
5 //! C header: [`include/linux/property.h`](srctree/include/linux/property.h)
20 /// A reference-counted fwnode_handle.
32 /// Instances of this type are always reference-counted, that is, a call to
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
46 unsafe fn from_raw(raw: *mut bindings::fwnode_handle) -> ARef<Self> {
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
61 pub(crate) fn as_raw(&self) -> *mut bindings::fwnode_handle {
66 pub fn is_of_node(&self) -> bool {
77 pub fn display_name(&self) -> impl fmt::Display + '_ {
81 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
88 // - `fwnode_get_name` returns null or a valid C string.
89 // - `name` was checked to be non-null.
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.
104 /// Returns firmware property `name` boolean value.
105 pub fn property_read_bool(&self, name: &CStr) -> bool {
107 // - `name` is non-null and null-terminated.
108 // - `self.as_raw()` is valid because `self` is valid.
113 /// property `name`.
114 pub fn property_match_string(&self, name: &CStr, match_str: &CStr) -> Result<usize> {
116 // - `name` and `match_str` are non-null and null-terminated.
117 // - `self.as_raw` is valid because `self` is valid.
129 /// Returns firmware property `name` integer array values in a [`KVec`].
134 ) -> Result<PropertyGuard<'fwnode, 'name, KVec<T>>> {
141 // - `len` is equal to `val.capacity - val.len`, because
143 // - All elements within the interval [`0`, `len`) were initialized
157 /// Returns integer array length for firmware property `name`.
158 pub fn property_count_elem<T: PropertyInt>(&self, name: &CStr) -> Result<usize> {
162 /// Returns the value of firmware property `name`.
175 /// the [implementors of Property][Property#implementors] and [its
176 /// implementations on foreign types][Property#foreign-impls].
181 /// # use kernel::{c_str, device::{Device, property::FwNode}, str::CString};
182 /// fn examples(dev: &Device) -> Result {
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() {
191 pub fn property_read<'fwnode, 'name, T: Property>(
194 ) -> PropertyGuard<'fwnode, 'name, T> {
203 pub fn get_child_by_name(&self, name: &CStr) -> Option<ARef<Self>> {
211 // - `fwnode_get_named_child_node` returns a pointer with its refcount
213 // - That increment is relinquished, i.e. the underlying object is not
219 pub fn children<'a>(&'a self) -> impl Iterator<Item = ARef<FwNode>> + 'a {
235 // - `self.as_raw()` is valid by its type invariant.
236 // - `prev_ptr` may be null, which is allowed and corresponds to
239 // - `prev_ptr` has its refount incremented.
240 // - The increment of `prev_ptr` is relinquished, i.e. the
247 // - `next` is valid because `fwnode_get_next_child_node` returns a
249 // - That increment is relinquished, i.e. the underlying object
264 ) -> Result<FwNodeReferenceArgs> {
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`,
279 // - It may fill the field `fwnode` with a valid pointer,
281 // - It may modify the field `nargs`, in which case it
301 /// The name of the property of the reference indicating the number of
327 // - By the type invariants of `FwNodeReferenceArgs`, its field
329 // - That increment is relinquished. The underlying object won't be
338 pub fn as_slice(&self) -> &[u64] {
345 pub fn len(&self) -> usize {
350 pub fn is_empty(&self) -> bool {
356 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
361 // SAFETY: Instances of `FwNode` are always reference-counted.
365 // refcount is non-zero.
371 // non-zero.
382 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
396 // - The depth passed to `fwnode_get_nth_parent` is
399 // - The reference count was incremented by
401 // - That increment is relinquished to
429 /// to make [`FwNode::property_read`] generic over the type of property being
432 /// - [`property_read_bool`](FwNode::property_read_bool)
433 /// - [`property_read_array_vec`](FwNode::property_read_array_vec)
437 pub trait Property: Sized + Sealed {
439 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self>;
444 impl Property for CString {
445 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self> {
450 // - `name` is non-null and null-terminated.
451 // - `fwnode.as_raw` is valid because `fwnode` is valid.
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
461 // - The memory it points to is not mutated during that time.
469 /// This helper trait is needed on top of the existing [`Property`]
476 /// Reads a property array.
481 ) -> Result<&'a mut [Self]>;
483 /// Reads the length of a property array.
484 fn read_array_len_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<usize>;
486 // This macro generates implementations of the traits `Property` and
501 ) -> Result<&'a mut [Self]> {
503 // - `fwnode`, `name` and `out` are all valid by their type
505 // - `out.len()` is a valid bound for the memory pointed to by
525 fn read_array_len_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<usize> {
527 // - `fwnode` and `name` are valid by their type invariants.
528 // - It's ok to pass a null pointer to the
544 impl Property for $int {
545 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self> {
551 impl<const N: usize> Property for [$int; N] {
552 fn read_from_fwnode_property(fwnode: &FwNode, name: &CStr) -> Result<Self> {
577 /// Use [`Self::required_by`] if a missing property is considered a bug and
582 /// The result of reading the property.
584 /// The fwnode of the property, used for logging in the "required" case.
586 /// The name of the property, used for logging in the "required" case.
591 /// Access the property, indicating it is required.
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
596 pub fn required_by(self, dev: &super::Device) -> Result<T> {
600 "{}: property '{}' is missing\n",
608 /// Access the property, indicating it is optional.
611 /// the property is not present.
612 pub fn optional(self) -> Option<T> {
616 /// Access the property or the specified default value.
618 /// Do not pass a sentinel value as default to detect a missing property.
620 pub fn or(self, default: T) -> T {
626 /// Access the property or a default value.
629 pub fn or_default(self) -> T {