^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) _DSD Device Properties Usage Rules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Properties, Property Sets and Property Subsets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ==============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) allows any type of device configuration data to be provided via the ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) namespace. In principle, the format of the data may be arbitrary, but it has to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) be identified by a UUID which must be recognized by the driver processing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) _DSD output. However, there are generic UUIDs defined for _DSD recognized by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) the ACPI subsystem in the Linux kernel which automatically processes the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) packages associated with them and makes those data available to device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) as "device properties".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) A device property is a data item consisting of a string key and a value (of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) specific type) associated with it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) In the ACPI _DSD context it is an element of the sub-package following the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) generic Device Properties UUID in the _DSD return package as specified in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) Device Properties UUID definition document [1]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) It also may be regarded as the definition of a key and the associated data type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) that can be returned by _DSD in the Device Properties UUID sub-package for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) given device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) A property set is a collection of properties applicable to a hardware entity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) like a device. In the ACPI _DSD context it is the set of all properties that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) can be returned in the Device Properties UUID sub-package for the device in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) question.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Property subsets are nested collections of properties. Each of them is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) associated with an additional key (name) allowing the subset to be referred
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) to as a whole (and to be treated as a separate entity). The canonical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) representation of property subsets is via the mechanism specified in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Hierarchical Properties Extension UUID definition document [2]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) Property sets may be hierarchical. That is, a property set may contain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) multiple property subsets that each may contain property subsets of its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) own and so on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) General Validity Rule for Property Sets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Valid property sets must follow the guidance given by the Device Properties UUID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) definition document [1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) _DSD properties are intended to be used in addition to, and not instead of, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) existing mechanisms defined by the ACPI specification. Therefore, as a rule,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) they should only be used if the ACPI specification does not make direct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) provisions for handling the underlying use case. It generally is invalid to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) return property sets which do not follow that rule from _DSD in data packages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) associated with the Device Properties UUID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Additional Considerations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) There are cases in which, even if the general rule given above is followed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) principle, the property set may still not be regarded as a valid one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) For example, that applies to device properties which may cause kernel code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) (either a device driver or a library/subsystem) to access hardware in a way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) possibly leading to a conflict with AML methods in the ACPI namespace. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) particular, that may happen if the kernel code uses device properties to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) manipulate hardware normally controlled by ACPI methods related to power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) resource objects), or by ACPI device disabling/enabling methods, like _DIS and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) _SRS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) In all cases in which kernel code may do something that will confuse AML as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) result of using device properties, the device properties in question are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) suitable for the ACPI environment and consequently they cannot belong to a valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) property set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) Property Sets and Device Tree Bindings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) It often is useful to make _DSD return property sets that follow Device Tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) bindings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) In those cases, however, the above validity considerations must be taken into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) account in the first place and returning invalid property sets from _DSD must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) avoided. For this reason, it may not be possible to make _DSD return a property
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) set following the given DT binding literally and completely. Still, for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) sake of code re-use, it may make sense to provide as much of the configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) data as possible in the form of device properties and complement that with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) ACPI-specific mechanism suitable for the use case at hand.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) In any case, property sets following DT bindings literally should not be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) expected to automatically work in the ACPI environment regardless of their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) contents.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) References
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) .. [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) .. [2] https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags