0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==================================
0004 _DSD Device Properties Usage Rules
0005 ==================================
0006
0007 Properties, Property Sets and Property Subsets
0008 ==============================================
0009
0010 The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
0011 allows any type of device configuration data to be provided via the ACPI
0012 namespace. In principle, the format of the data may be arbitrary, but it has to
0013 be identified by a UUID which must be recognized by the driver processing the
0014 _DSD output. However, there are generic UUIDs defined for _DSD recognized by
0015 the ACPI subsystem in the Linux kernel which automatically processes the data
0016 packages associated with them and makes those data available to device drivers
0017 as "device properties".
0018
0019 A device property is a data item consisting of a string key and a value (of a
0020 specific type) associated with it.
0021
0022 In the ACPI _DSD context it is an element of the sub-package following the
0023 generic Device Properties UUID in the _DSD return package as specified in the
0024 section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section
0025 "Device Properties UUID" in _DSD (Device Specific Data) Implementation Guide
0026 document [1]_.
0027
0028 It also may be regarded as the definition of a key and the associated data type
0029 that can be returned by _DSD in the Device Properties UUID sub-package for a
0030 given device.
0031
0032 A property set is a collection of properties applicable to a hardware entity
0033 like a device. In the ACPI _DSD context it is the set of all properties that
0034 can be returned in the Device Properties UUID sub-package for the device in
0035 question.
0036
0037 Property subsets are nested collections of properties. Each of them is
0038 associated with an additional key (name) allowing the subset to be referred
0039 to as a whole (and to be treated as a separate entity). The canonical
0040 representation of property subsets is via the mechanism specified in the
0041 section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section
0042 "Hierarchical Data Extension UUID" in _DSD (Device Specific Data)
0043 Implementation Guide document [1]_.
0044
0045 Property sets may be hierarchical. That is, a property set may contain
0046 multiple property subsets that each may contain property subsets of its
0047 own and so on.
0048
0049 General Validity Rule for Property Sets
0050 =======================================
0051
0052 Valid property sets must follow the guidance given by the Device Properties UUID
0053 definition document [1].
0054
0055 _DSD properties are intended to be used in addition to, and not instead of, the
0056 existing mechanisms defined by the ACPI specification. Therefore, as a rule,
0057 they should only be used if the ACPI specification does not make direct
0058 provisions for handling the underlying use case. It generally is invalid to
0059 return property sets which do not follow that rule from _DSD in data packages
0060 associated with the Device Properties UUID.
0061
0062 Additional Considerations
0063 -------------------------
0064
0065 There are cases in which, even if the general rule given above is followed in
0066 principle, the property set may still not be regarded as a valid one.
0067
0068 For example, that applies to device properties which may cause kernel code
0069 (either a device driver or a library/subsystem) to access hardware in a way
0070 possibly leading to a conflict with AML methods in the ACPI namespace. In
0071 particular, that may happen if the kernel code uses device properties to
0072 manipulate hardware normally controlled by ACPI methods related to power
0073 management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power
0074 resource objects), or by ACPI device disabling/enabling methods, like _DIS and
0075 _SRS.
0076
0077 In all cases in which kernel code may do something that will confuse AML as a
0078 result of using device properties, the device properties in question are not
0079 suitable for the ACPI environment and consequently they cannot belong to a valid
0080 property set.
0081
0082 Property Sets and Device Tree Bindings
0083 ======================================
0084
0085 It often is useful to make _DSD return property sets that follow Device Tree
0086 bindings.
0087
0088 In those cases, however, the above validity considerations must be taken into
0089 account in the first place and returning invalid property sets from _DSD must be
0090 avoided. For this reason, it may not be possible to make _DSD return a property
0091 set following the given DT binding literally and completely. Still, for the
0092 sake of code re-use, it may make sense to provide as much of the configuration
0093 data as possible in the form of device properties and complement that with an
0094 ACPI-specific mechanism suitable for the use case at hand.
0095
0096 In any case, property sets following DT bindings literally should not be
0097 expected to automatically work in the ACPI environment regardless of their
0098 contents.
0099
0100 References
0101 ==========
0102
0103 .. [1] https://github.com/UEFI/DSD-Guide
