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