Skip to content

Commit

Permalink
Merge tag 'devprop-5.17-rc1' of git://git.kernel.org/pub/scm/linux/ke…
Browse files Browse the repository at this point in the history
…rnel/git/rafael/linux-pm

Pull device properties framework updates from Rafael Wysocki:
 "These update the handling of software nodes and graph properties, and
  the MAINTAINERS entry for the former.

  Specifics:

   - Remove device_add_properties() which does not work correctly if
     software nodes holding additional device properties are shared or
     reused (Heikki Krogerus).

   - Fix nargs_prop property handling for software nodes (Clément
     Léger).

   - Update documentation of ACPI device properties (Sakari Ailus).

   - Update the handling of graph properties in the generic framework to
     match the DT case (Sakari Ailus).

   - Update software nodes entry in MAINTAINERS (Andy Shevchenko)"

* tag 'devprop-5.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm:
  software node: Update MAINTAINERS data base
  software node: fix wrong node passed to find nargs_prop
  device property: Drop fwnode_graph_get_remote_node()
  device property: Use fwnode_graph_for_each_endpoint() macro
  device property: Implement fwnode_graph_get_endpoint_count()
  Documentation: ACPI: Update references
  Documentation: ACPI: Fix data node reference documentation
  device property: Fix documentation for FWNODE_GRAPH_DEVICE_DISABLED
  device property: Fix fwnode_graph_devcon_match() fwnode leak
  device property: Remove device_add_properties() API
  driver core: Don't call device_remove_properties() from device_del()
  PCI: Convert to device_create_managed_software_node()
  • Loading branch information
torvalds committed Jan 11, 2022
2 parents fe2437c + 3a571fc commit fe8152b
Show file tree
Hide file tree
Showing 11 changed files with 127 additions and 182 deletions.
28 changes: 15 additions & 13 deletions Documentation/firmware-guide/acpi/dsd/data-node-references.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,17 @@
Referencing hierarchical data nodes
===================================

:Copyright: |copy| 2018 Intel Corporation
:Copyright: |copy| 2018, 2021 Intel Corporation
:Author: Sakari Ailus <[email protected]>

ACPI in general allows referring to device objects in the tree only.
Hierarchical data extension nodes may not be referred to directly, hence this
document defines a scheme to implement such references.

A reference consist of the device object name followed by one or more
hierarchical data extension [1] keys. Specifically, the hierarchical data
extension node which is referred to by the key shall lie directly under the
parent object i.e. either the device object or another hierarchical data
hierarchical data extension [dsd-guide] keys. Specifically, the hierarchical
data extension node which is referred to by the key shall lie directly under
the parent object i.e. either the device object or another hierarchical data
extension node.

The keys in the hierarchical data nodes shall consist of the name of the node,
Expand All @@ -33,7 +33,7 @@ extension key.
Example
=======

In the ASL snippet below, the "reference" _DSD property [2] contains a
In the ASL snippet below, the "reference" _DSD property contains a
device object reference to DEV0 and under that device object, a
hierarchical data extension key "node@1" referring to the NOD1 object
and lastly, a hierarchical data extension key "anothernode" referring to
Expand All @@ -52,12 +52,14 @@ the ANOD object which is also the final target node of the reference.
Name (NOD0, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 0 },
Package () { "random-property", 3 },
}
})
Name (NOD1, Package() {
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "reg", 1 },
Package () { "anothernode", "ANOD" },
}
})
Expand All @@ -74,7 +76,11 @@ the ANOD object which is also the final target node of the reference.
Name (_DSD, Package () {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reference", ^DEV0, "node@1", "anothernode" },
Package () {
"reference", Package () {
^DEV0, "node@1", "anothernode"
}
},
}
})
}
Expand All @@ -85,10 +91,6 @@ Documentation/firmware-guide/acpi/dsd/graph.rst.
References
==========

[1] Hierarchical Data Extension UUID For _DSD.
<https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
referenced 2018-07-17.

[2] Device Properties UUID For _DSD.
<https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
referenced 2016-10-04.
[dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
2021-11-30.
40 changes: 18 additions & 22 deletions Documentation/firmware-guide/acpi/dsd/graph.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ Graphs
_DSD
====

_DSD (Device Specific Data) [7] is a predefined ACPI device
_DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device
configuration object that can be used to convey information on
hardware features which are not specifically covered by the ACPI
specification [1][6]. There are two _DSD extensions that are relevant
for graphs: property [4] and hierarchical data extensions [5]. The
specification [acpi]. There are two _DSD extensions that are relevant
for graphs: property [dsd-guide] and hierarchical data extensions. The
property extension provides generic key-value pairs whereas the
hierarchical data extension supports nodes with references to other
nodes, forming a tree. The nodes in the tree may contain properties as
Expand All @@ -36,8 +36,9 @@ Ports and endpoints
===================

The port and endpoint concepts are very similar to those in Devicetree
[3]. A port represents an interface in a device, and an endpoint
represents a connection to that interface.
[devicetree, graph-bindings]. A port represents an interface in a device, and
an endpoint represents a connection to that interface. Also see [data-node-ref]
for generic data node references.

All port nodes are located under the device's "_DSD" node in the hierarchical
data extension tree. The data extension related to each port node must begin
Expand Down Expand Up @@ -153,25 +154,20 @@ the "ISP" device and vice versa.
References
==========

[1] _DSD (Device Specific Data) Implementation Guide.
https://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
referenced 2016-10-03.
[acpi] Advanced Configuration and Power Interface Specification.
https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.

[2] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst

[3] Documentation/devicetree/bindings/graph.txt
[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.

[4] Device Properties UUID For _DSD.
https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2016-10-04.
[dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
2021-11-30.

[5] Hierarchical Data Extension UUID For _DSD.
https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2016-10-04.

[6] Advanced Configuration and Power Interface Specification.
https://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
referenced 2016-10-04.

[7] _DSD Device Properties Usage Rules.
[dsd-rules] _DSD Device Properties Usage Rules.
Documentation/firmware-guide/acpi/DSD-properties-rules.rst

[graph-bindings] Common bindings for device graphs (Devicetree).
https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml,
referenced 2021-11-30.
40 changes: 18 additions & 22 deletions Documentation/firmware-guide/acpi/dsd/leds.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,20 @@
Describing and referring to LEDs in ACPI
========================================

Individual LEDs are described by hierarchical data extension [6] nodes under the
Individual LEDs are described by hierarchical data extension [5] nodes under the
device node, the LED driver chip. The "reg" property in the LED specific nodes
tells the numerical ID of each individual LED output to which the LEDs are
connected. [3] The hierarchical data nodes are named "led@X", where X is the
connected. [leds] The hierarchical data nodes are named "led@X", where X is the
number of the LED output.

Referring to LEDs in Device tree is documented in [4], in "flash-leds" property
documentation. In short, LEDs are directly referred to by using phandles.
Referring to LEDs in Device tree is documented in [video-interfaces], in
"flash-leds" property documentation. In short, LEDs are directly referred to by
using phandles.

While Device tree allows referring to any node in the tree[1], in ACPI
references are limited to device nodes only [2]. For this reason using the same
mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes
is documented in [7].
While Device tree allows referring to any node in the tree [devicetree], in
ACPI references are limited to device nodes only [acpi]. For this reason using
the same mechanism on ACPI is not possible. A mechanism to refer to non-device
ACPI nodes is documented in [data-node-ref].

ACPI allows (as does DT) using integer arguments after the reference. A
combination of the LED driver device reference and an integer argument,
Expand Down Expand Up @@ -90,22 +91,17 @@ where
References
==========

[1] Device tree. https://www.devicetree.org, referenced 2019-02-21.
[acpi] Advanced Configuration and Power Interface Specification.
https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.

[2] Advanced Configuration and Power Interface Specification.
https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf,
referenced 2019-02-21.
[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst

[3] Documentation/devicetree/bindings/leds/common.txt
[devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21.

[4] Documentation/devicetree/bindings/media/video-interfaces.txt
[dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
2021-11-30.

[5] Device Properties UUID For _DSD.
https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2019-02-21.
[leds] Documentation/devicetree/bindings/leds/common.yaml

[6] Hierarchical Data Extension UUID For _DSD.
https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2019-02-21.

[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
[video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml
28 changes: 15 additions & 13 deletions Documentation/firmware-guide/acpi/dsd/phy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@
MDIO bus and PHYs in ACPI
=========================

The PHYs on an MDIO bus [1] are probed and registered using
The PHYs on an MDIO bus [phy] are probed and registered using
fwnode_mdiobus_register_phy().

Later, for connecting these PHYs to their respective MACs, the PHYs registered
on the MDIO bus have to be referenced.

This document introduces two _DSD properties that are to be used
for connecting PHYs on the MDIO bus [3] to the MAC layer.
for connecting PHYs on the MDIO bus [dsd-properties-rules] to the MAC layer.

These properties are defined in accordance with the "Device
Properties UUID For _DSD" [2] document and the
Properties UUID For _DSD" [dsd-guide] document and the
daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
Data Descriptors containing them.

Expand Down Expand Up @@ -48,22 +48,22 @@ as device object references (e.g. \_SB.MDI0.PHY1).
phy-mode
--------
The "phy-mode" _DSD property is used to describe the connection to
the PHY. The valid values for "phy-mode" are defined in [4].
the PHY. The valid values for "phy-mode" are defined in [ethernet-controller].

managed
-------
Optional property, which specifies the PHY management type.
The valid values for "managed" are defined in [4].
The valid values for "managed" are defined in [ethernet-controller].

fixed-link
----------
The "fixed-link" is described by a data-only subnode of the
MAC port, which is linked in the _DSD package via
hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b
in accordance with [5] "_DSD Implementation Guide" document).
in accordance with [dsd-guide] "_DSD Implementation Guide" document).
The subnode should comprise a required property ("speed") and
possibly the optional ones - complete list of parameters and
their values are specified in [4].
their values are specified in [ethernet-controller].

The following ASL example illustrates the usage of these properties.

Expand Down Expand Up @@ -188,12 +188,14 @@ MAC node example with a "fixed-link" subnode.
References
==========

[1] Documentation/networking/phy.rst
[phy] Documentation/networking/phy.rst

[2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
[dsd-properties-rules]
Documentation/firmware-guide/acpi/DSD-properties-rules.rst

[3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst
[ethernet-controller]
Documentation/devicetree/bindings/net/ethernet-controller.yaml

[4] Documentation/devicetree/bindings/net/ethernet-controller.yaml

[5] https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf
[dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
2021-11-30.
7 changes: 6 additions & 1 deletion MAINTAINERS
Original file line number Diff line number Diff line change
Expand Up @@ -17734,12 +17734,17 @@ F: drivers/firmware/arm_sdei.c
F: include/linux/arm_sdei.h
F: include/uapi/linux/arm_sdei.h

SOFTWARE NODES
SOFTWARE NODES AND DEVICE PROPERTIES
R: Andy Shevchenko <[email protected]>
R: Daniel Scally <[email protected]>
R: Heikki Krogerus <[email protected]>
R: Sakari Ailus <[email protected]>
L: [email protected]
S: Maintained
F: drivers/base/property.c
F: drivers/base/swnode.c
F: include/linux/fwnode.h
F: include/linux/property.h

SOFTWARE RAID (Multiple Disks) SUPPORT
M: Song Liu <[email protected]>
Expand Down
1 change: 0 additions & 1 deletion drivers/base/core.c
Original file line number Diff line number Diff line change
Expand Up @@ -3581,7 +3581,6 @@ void device_del(struct device *dev)
device_pm_remove(dev);
driver_deferred_probe_del(dev);
device_platform_notify_remove(dev);
device_remove_properties(dev);
device_links_purge(dev);

if (dev->bus)
Expand Down
Loading

0 comments on commit fe8152b

Please sign in to comment.