On Tuesday, July 17, 2018 4:19:10 PM CEST Sakari Ailus wrote:
> 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
>
>
All applied, thanks!
--
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
