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