104 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==================================4_DSD Device Properties Usage Rules5==================================6 7Properties, Property Sets and Property Subsets8==============================================9 10The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,11allows any type of device configuration data to be provided via the ACPI12namespace. In principle, the format of the data may be arbitrary, but it has to13be identified by a UUID which must be recognized by the driver processing the14_DSD output. However, there are generic UUIDs defined for _DSD recognized by15the ACPI subsystem in the Linux kernel which automatically processes the data16packages associated with them and makes those data available to device drivers17as "device properties".18 19A device property is a data item consisting of a string key and a value (of a20specific type) associated with it.21 22In the ACPI _DSD context it is an element of the sub-package following the23generic Device Properties UUID in the _DSD return package as specified in the24section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section25"Device Properties UUID" in _DSD (Device Specific Data) Implementation Guide26document [1]_.27 28It also may be regarded as the definition of a key and the associated data type29that can be returned by _DSD in the Device Properties UUID sub-package for a30given device.31 32A property set is a collection of properties applicable to a hardware entity33like a device. In the ACPI _DSD context it is the set of all properties that34can be returned in the Device Properties UUID sub-package for the device in35question.36 37Property subsets are nested collections of properties. Each of them is38associated with an additional key (name) allowing the subset to be referred39to as a whole (and to be treated as a separate entity). The canonical40representation of property subsets is via the mechanism specified in the41section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section42"Hierarchical Data Extension UUID" in _DSD (Device Specific Data)43Implementation Guide document [1]_.44 45Property sets may be hierarchical. That is, a property set may contain46multiple property subsets that each may contain property subsets of its47own and so on.48 49General Validity Rule for Property Sets50=======================================51 52Valid property sets must follow the guidance given by the Device Properties UUID53definition document [1].54 55_DSD properties are intended to be used in addition to, and not instead of, the56existing mechanisms defined by the ACPI specification. Therefore, as a rule,57they should only be used if the ACPI specification does not make direct58provisions for handling the underlying use case. It generally is invalid to59return property sets which do not follow that rule from _DSD in data packages60associated with the Device Properties UUID.61 62Additional Considerations63-------------------------64 65There are cases in which, even if the general rule given above is followed in66principle, the property set may still not be regarded as a valid one.67 68For example, that applies to device properties which may cause kernel code69(either a device driver or a library/subsystem) to access hardware in a way70possibly leading to a conflict with AML methods in the ACPI namespace. In71particular, that may happen if the kernel code uses device properties to72manipulate hardware normally controlled by ACPI methods related to power73management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power74resource objects), or by ACPI device disabling/enabling methods, like _DIS and75_SRS.76 77In all cases in which kernel code may do something that will confuse AML as a78result of using device properties, the device properties in question are not79suitable for the ACPI environment and consequently they cannot belong to a valid80property set.81 82Property Sets and Device Tree Bindings83======================================84 85It often is useful to make _DSD return property sets that follow Device Tree86bindings.87 88In those cases, however, the above validity considerations must be taken into89account in the first place and returning invalid property sets from _DSD must be90avoided. For this reason, it may not be possible to make _DSD return a property91set following the given DT binding literally and completely. Still, for the92sake of code re-use, it may make sense to provide as much of the configuration93data as possible in the form of device properties and complement that with an94ACPI-specific mechanism suitable for the use case at hand.95 96In any case, property sets following DT bindings literally should not be97expected to automatically work in the ACPI environment regardless of their98contents.99 100References101==========102 103.. [1] https://github.com/UEFI/DSD-Guide104