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
11 allows any type of device configuration data t
12 namespace. In principle, the format of the da
13 be identified by a UUID which must be recogniz
14 _DSD output. However, there are generic UUIDs
15 the ACPI subsystem in the Linux kernel which a
16 packages associated with them and makes those
17 as "device properties".
18
19 A device property is a data item consisting of
20 specific type) associated with it.
21
22 In the ACPI _DSD context it is an element of t
23 generic Device Properties UUID in the _DSD ret
24 section titled "Well-Known _DSD UUIDs and Data
25 "Device Properties UUID" in _DSD (Device Speci
26 document [1]_.
27
28 It also may be regarded as the definition of a
29 that can be returned by _DSD in the Device Pro
30 given device.
31
32 A property set is a collection of properties a
33 like a device. In the ACPI _DSD context it is
34 can be returned in the Device Properties UUID
35 question.
36
37 Property subsets are nested collections of pro
38 associated with an additional key (name) allow
39 to as a whole (and to be treated as a separate
40 representation of property subsets is via the
41 section titled "Well-Known _DSD UUIDs and Data
42 "Hierarchical Data Extension UUID" in _DSD (De
43 Implementation Guide document [1]_.
44
45 Property sets may be hierarchical. That is, a
46 multiple property subsets that each may contai
47 own and so on.
48
49 General Validity Rule for Property Sets
50 =======================================
51
52 Valid property sets must follow the guidance g
53 definition document [1].
54
55 _DSD properties are intended to be used in add
56 existing mechanisms defined by the ACPI specif
57 they should only be used if the ACPI specifica
58 provisions for handling the underlying use cas
59 return property sets which do not follow that
60 associated with the Device Properties UUID.
61
62 Additional Considerations
63 -------------------------
64
65 There are cases in which, even if the general
66 principle, the property set may still not be r
67
68 For example, that applies to device properties
69 (either a device driver or a library/subsystem
70 possibly leading to a conflict with AML method
71 particular, that may happen if the kernel code
72 manipulate hardware normally controlled by ACP
73 management, like _PSx and _DSW (for device obj
74 resource objects), or by ACPI device disabling
75 _SRS.
76
77 In all cases in which kernel code may do somet
78 result of using device properties, the device
79 suitable for the ACPI environment and conseque
80 property set.
81
82 Property Sets and Device Tree Bindings
83 ======================================
84
85 It often is useful to make _DSD return propert
86 bindings.
87
88 In those cases, however, the above validity co
89 account in the first place and returning inval
90 avoided. For this reason, it may not be possi
91 set following the given DT binding literally a
92 sake of code re-use, it may make sense to prov
93 data as possible in the form of device propert
94 ACPI-specific mechanism suitable for the use c
95
96 In any case, property sets following DT bindin
97 expected to automatically work in the ACPI env
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.