Hi all,
I'm somewhat unhappy with the current state of affairs in ACPI and how the
graphs as well as references have been implemented. In particular,
whenever dealing with references to non-device nodes, the implementation
for ACPI is quite different than on DT, requiring extra properties and
knowledge of reference types in more generic frameworks that handle these
references.
The issue stems from the fact that currently ACPI does not allow
referencing data extension nodes in the node hierarchy in a generic way.
Both ACPI data extension nodes and device nodes are represented by the
same fwnode_handle objects at runtime.
Parsing a reference requires knowing what kind of reference it is, for
instance whether it's a port, an endpoint or a LED. We currently use
integer properties in the data nodes to tell this ("port" or "endpoint").
This is problematic as each new type of a reference will add new
properties to the same DT binding namespace that are not documented in DT
binding documentation, increasing the likelihood of a clash. This headache
will continue to increase with each new type of a reference.
What I propose to address these issues is the following:
- Instead of defining ways to refer to data nodes by following integer
properties, use the names of the data nodes (first package entry of the
data extension) themselves to do that. This is easier to understand and
entirely agnostic to the type of the reference (see patch 2).
- Add "@" character (as in DT) to separate the node name and its number.
The name defines the purpose of the node, such as "port" for graph ports
and "endpoint" for graph endpoints. This makes parsing easier as the "@"
character separates the name from the number as well as brings ACPI to
feature parity with DT in this respect --- the name could theoretically
include numerals as well.
- Use "reg" property to tell the number, instead of a purpose-defined
property.
These changes will also bring ACPI to feature parity with DT in two
respects:
- DT bindings will be sufficient in the vast majority of cases for making
references.
- References are generic and there is no need to know the type of the
reference when parsing it.
The benefits of these changes will include
- Avoid incrementally increasing headache in managing properties in the
DT property binding namespace that are (and likely won't) be part of the
DT bindings.
- Driver (e.g. LED) changes to support ACPI will be more or less limited
to switching from OF to fwnode property API.
- Firmware type can be hidded most of the time, and we could get rid of
(or at not least add more functions like)
v4l2_fwnode_reference_get_int_prop in
drivers/media/v4l2-core/v4l2-fwnode.c.
The following changes have been made since v1. I hope they address the
review comments.
- Add copyright and improve the hierarchical data node reference
documentation in Documentation/acpi/dsd/data-node-references.txt . The
use of the "reg" property is now documented and an example has been
added.
- The node numbering documentation has been split off to a separate patch
("ACPI / DSD: Document key numbering for hierarchical data extension
refs") as the node references and the numbering of the nodes are
separate matters.
- References to _DSD property as well as _DSD hierarchical data extension
specs have been added.
- Use terms "key" and "target" are used in conjunction with hierarhical
data extension rather than first and second package list entries. While
both are technically correct, the new terms are more meaningful and
aligned with the hierarchical data extension spec itself.
- Improve documentation for acpi_graph_get_next_endpoint() so that it
discussed the preferred referencing style first. Also include the "@"
character to the keys which was missing in v1.
- Document that in absence of multiple port nodes in a graph under a
device object, the number of the sole port node shall be zero.
- Document that for generic references, the node numbering in the
hierarchical data extension keys is in hexadecimal notation.
- Improve subjects of the documentation patches so they can be easily told
apart from non-documentation patches.
As a summary, all the changes are changes to the documentation only.
Sakari Ailus (11):
ACPI: Convert ACPI reference args to generic fwnode reference args
ACPI: property: Allow making references to non-device nodes
ACPI / DSD: Document hierarchical data extension references
ACPI: property: Make the ACPI graph API private
ACPI: property: Allow direct graph endpoint references
ACPI: property: Use data node name and reg property for graphs
ACPI / DSD: Document key numbering for hierarchical data extension
refs
ACPI / DSD: Update documentation for hierarchical data extension 1.1
ACPI / DSD: graph: Fix graph documentation
ACPI / DSD: graph: Improve graph documentation for port/ep numbering
ACPI / DSD: graph: Update graph documentation to use generic
references
Documentation/acpi/dsd/data-node-references.txt | 89 +++++++++
Documentation/acpi/dsd/graph.txt | 72 ++++----
drivers/acpi/property.c | 209 ++++++++++------------
drivers/gpio/gpiolib-acpi.c | 11 +-
drivers/infiniband/hw/hns/hns_roce_hw_v1.c | 10 +-
drivers/media/v4l2-core/v4l2-fwnode.c | 2 +-
drivers/net/ethernet/apm/xgene/xgene_enet_hw.c | 6 +-
drivers/net/ethernet/hisilicon/hns/hns_dsaf_mac.c | 6 +-
drivers/net/ethernet/hisilicon/hns/hns_enet.c | 8 +-
include/linux/acpi.h | 25 +--
include/linux/fwnode.h | 2 +-
11 files changed, 259 insertions(+), 181 deletions(-)
create mode 100644 Documentation/acpi/dsd/data-node-references.txt
--
2.11.0
--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
