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