1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun================================== 4*4882a593Smuzhiyun_DSD Device Properties Usage Rules 5*4882a593Smuzhiyun================================== 6*4882a593Smuzhiyun 7*4882a593SmuzhiyunProperties, Property Sets and Property Subsets 8*4882a593Smuzhiyun============================================== 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunThe _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1, 11*4882a593Smuzhiyunallows any type of device configuration data to be provided via the ACPI 12*4882a593Smuzhiyunnamespace. In principle, the format of the data may be arbitrary, but it has to 13*4882a593Smuzhiyunbe identified by a UUID which must be recognized by the driver processing the 14*4882a593Smuzhiyun_DSD output. However, there are generic UUIDs defined for _DSD recognized by 15*4882a593Smuzhiyunthe ACPI subsystem in the Linux kernel which automatically processes the data 16*4882a593Smuzhiyunpackages associated with them and makes those data available to device drivers 17*4882a593Smuzhiyunas "device properties". 18*4882a593Smuzhiyun 19*4882a593SmuzhiyunA device property is a data item consisting of a string key and a value (of a 20*4882a593Smuzhiyunspecific type) associated with it. 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunIn the ACPI _DSD context it is an element of the sub-package following the 23*4882a593Smuzhiyungeneric Device Properties UUID in the _DSD return package as specified in the 24*4882a593SmuzhiyunDevice Properties UUID definition document [1]_. 25*4882a593Smuzhiyun 26*4882a593SmuzhiyunIt also may be regarded as the definition of a key and the associated data type 27*4882a593Smuzhiyunthat can be returned by _DSD in the Device Properties UUID sub-package for a 28*4882a593Smuzhiyungiven device. 29*4882a593Smuzhiyun 30*4882a593SmuzhiyunA property set is a collection of properties applicable to a hardware entity 31*4882a593Smuzhiyunlike a device. In the ACPI _DSD context it is the set of all properties that 32*4882a593Smuzhiyuncan be returned in the Device Properties UUID sub-package for the device in 33*4882a593Smuzhiyunquestion. 34*4882a593Smuzhiyun 35*4882a593SmuzhiyunProperty subsets are nested collections of properties. Each of them is 36*4882a593Smuzhiyunassociated with an additional key (name) allowing the subset to be referred 37*4882a593Smuzhiyunto as a whole (and to be treated as a separate entity). The canonical 38*4882a593Smuzhiyunrepresentation of property subsets is via the mechanism specified in the 39*4882a593SmuzhiyunHierarchical Properties Extension UUID definition document [2]_. 40*4882a593Smuzhiyun 41*4882a593SmuzhiyunProperty sets may be hierarchical. That is, a property set may contain 42*4882a593Smuzhiyunmultiple property subsets that each may contain property subsets of its 43*4882a593Smuzhiyunown and so on. 44*4882a593Smuzhiyun 45*4882a593SmuzhiyunGeneral Validity Rule for Property Sets 46*4882a593Smuzhiyun======================================= 47*4882a593Smuzhiyun 48*4882a593SmuzhiyunValid property sets must follow the guidance given by the Device Properties UUID 49*4882a593Smuzhiyundefinition document [1]. 50*4882a593Smuzhiyun 51*4882a593Smuzhiyun_DSD properties are intended to be used in addition to, and not instead of, the 52*4882a593Smuzhiyunexisting mechanisms defined by the ACPI specification. Therefore, as a rule, 53*4882a593Smuzhiyunthey should only be used if the ACPI specification does not make direct 54*4882a593Smuzhiyunprovisions for handling the underlying use case. It generally is invalid to 55*4882a593Smuzhiyunreturn property sets which do not follow that rule from _DSD in data packages 56*4882a593Smuzhiyunassociated with the Device Properties UUID. 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunAdditional Considerations 59*4882a593Smuzhiyun------------------------- 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunThere are cases in which, even if the general rule given above is followed in 62*4882a593Smuzhiyunprinciple, the property set may still not be regarded as a valid one. 63*4882a593Smuzhiyun 64*4882a593SmuzhiyunFor example, that applies to device properties which may cause kernel code 65*4882a593Smuzhiyun(either a device driver or a library/subsystem) to access hardware in a way 66*4882a593Smuzhiyunpossibly leading to a conflict with AML methods in the ACPI namespace. In 67*4882a593Smuzhiyunparticular, that may happen if the kernel code uses device properties to 68*4882a593Smuzhiyunmanipulate hardware normally controlled by ACPI methods related to power 69*4882a593Smuzhiyunmanagement, like _PSx and _DSW (for device objects) or _ON and _OFF (for power 70*4882a593Smuzhiyunresource objects), or by ACPI device disabling/enabling methods, like _DIS and 71*4882a593Smuzhiyun_SRS. 72*4882a593Smuzhiyun 73*4882a593SmuzhiyunIn all cases in which kernel code may do something that will confuse AML as a 74*4882a593Smuzhiyunresult of using device properties, the device properties in question are not 75*4882a593Smuzhiyunsuitable for the ACPI environment and consequently they cannot belong to a valid 76*4882a593Smuzhiyunproperty set. 77*4882a593Smuzhiyun 78*4882a593SmuzhiyunProperty Sets and Device Tree Bindings 79*4882a593Smuzhiyun====================================== 80*4882a593Smuzhiyun 81*4882a593SmuzhiyunIt often is useful to make _DSD return property sets that follow Device Tree 82*4882a593Smuzhiyunbindings. 83*4882a593Smuzhiyun 84*4882a593SmuzhiyunIn those cases, however, the above validity considerations must be taken into 85*4882a593Smuzhiyunaccount in the first place and returning invalid property sets from _DSD must be 86*4882a593Smuzhiyunavoided. For this reason, it may not be possible to make _DSD return a property 87*4882a593Smuzhiyunset following the given DT binding literally and completely. Still, for the 88*4882a593Smuzhiyunsake of code re-use, it may make sense to provide as much of the configuration 89*4882a593Smuzhiyundata as possible in the form of device properties and complement that with an 90*4882a593SmuzhiyunACPI-specific mechanism suitable for the use case at hand. 91*4882a593Smuzhiyun 92*4882a593SmuzhiyunIn any case, property sets following DT bindings literally should not be 93*4882a593Smuzhiyunexpected to automatically work in the ACPI environment regardless of their 94*4882a593Smuzhiyuncontents. 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunReferences 97*4882a593Smuzhiyun========== 98*4882a593Smuzhiyun 99*4882a593Smuzhiyun.. [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf 100*4882a593Smuzhiyun.. [2] https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf 101