[PATCH 00/15] ACPI graph support

[PATCH 00/15] ACPI graph support

[Sakari Ailus]

Hello everyone, 

I posted a previous RFC labelled set of ACPI graph support a while ago:

<URL:http://www.spinics.net/lists/linux-acpi/msg69547.html>

Since then, the matter of how the properties should be used as in ACPI
_DSD was discussed in Ksummit and LPC, and a document detailing the rules
was written [1].

This set contains patches written by Mika Westerberg and by myself. The
patchset brings support for graphs to ACPI. The functionality achieved by
these patches is very similar to what the Device tree provides: the port
and the endpoint concept are being employed. The patches make use of the
_DSD property and data extensions to achieve this. The fwnode interface is
extended by graph functionality; this way graph information originating
from both OF and ACPI may be accessed using the same interface, without
being aware of the underlying firmware interface.

The last patch of the set contains ASL documentation including an example.

The entire set may also be found here (on mediatree.git master, but it
also applies cleanly on linux-next):

<URL:https://git.linuxtv.org/sailus/media_tree.git/log/?h=acpi-graph>

The resulting fwnode graph interface has been tested using V4L2 async with
fwnode matching and smiapp and omap3isp drivers, with appropriate changes 
to make use of the fwnode interface in drivers.

The V4L2 patches can be found here. The fwnode graph interface is used by
the newly added V4L2 fwnode framework which replaces the V4L2 OF
framework, with equivalent functionality.

<URL:https://git.linuxtv.org/sailus/media_tree.git/log/?h=v4l2-acpi>


changes since RFC v1:

- Rebased the set --- there were a few conflicts.

- Fixed a bug in ACPI graph parsing. (Thanks to Mika!)

- Remove one layer (the "ports" node) of the _DSD hierarchical data
  structure. Change the documentation accordingly. Instead, rely on the
  presence of "port" and "endpoint" properties to identify port and
  endpoint nodes.

- Add a reference the DSD property rule document [1].


Feedback is welcome.


[1] Documentation/acpi/DSD-properties-rules.txt

-- 
Kind regards,
Sakari

[PATCH 01/15] ACPI / property: Add possiblity to retrieve parent firmware node

[Sakari Ailus]

From: Mika Westerberg <mika.westerberg@linux.intel.com>

Sometimes it is useful to be able to navigate firmware node hierarchy
upwards toward parent nodes. ACPI device nodes are pretty much already
supported because ACPICA provides acpi_get_parent(). ACPI data nodes,
however, are all below the same parent ACPI device. Their hierarchy is
created by "linking" each other using references in the value field.

Add parent pointer to the parent data node while we create them so it is
easy to navigate the hierarchy backwards. We use this parent pointer in a
new function acpi_node_get_parent() that is able to extract parent of both
ACPI firmware node types.

Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/acpi/property.c | 71 ++++++++++++++++++++++++++++++++++++++-----------
 include/acpi/acpi_bus.h |  1 +
 include/linux/acpi.h    |  7 +++++
 3 files changed, 64 insertions(+), 15 deletions(-)

diff --git a/drivers/acpi/property.c b/drivers/acpi/property.c
index 3afddcd..65a0606 100644
--- a/drivers/acpi/property.c
+++ b/drivers/acpi/property.c
@@ -37,14 +37,16 @@ static const u8 ads_uuid[16] = {
 
 static bool acpi_enumerate_nondev_subnodes(acpi_handle scope,
 					   const union acpi_object *desc,
-					   struct acpi_device_data *data);
+					   struct acpi_device_data *data,
+					   struct fwnode_handle *parent);
 static bool acpi_extract_properties(const union acpi_object *desc,
 				    struct acpi_device_data *data);
 
 static bool acpi_nondev_subnode_extract(const union acpi_object *desc,
 					acpi_handle handle,
 					const union acpi_object *link,
-					struct list_head *list)
+					struct list_head *list,
+					struct fwnode_handle *parent)
 {
 	struct acpi_data_node *dn;
 	bool result;
@@ -55,6 +57,7 @@ static bool acpi_nondev_subnode_extract(const union acpi_object *desc,
 
 	dn->name = link->package.elements[0].string.pointer;
 	dn->fwnode.type = FWNODE_ACPI_DATA;
+	dn->parent = parent;
 	INIT_LIST_HEAD(&dn->data.subnodes);
 
 	result = acpi_extract_properties(desc, &dn->data);
@@ -71,9 +74,11 @@ static bool acpi_nondev_subnode_extract(const union acpi_object *desc,
 		 */
 		status = acpi_get_parent(handle, &scope);
 		if (ACPI_SUCCESS(status)
-		    && acpi_enumerate_nondev_subnodes(scope, desc, &dn->data))
+		    && acpi_enumerate_nondev_subnodes(scope, desc, &dn->data,
+						      &dn->fwnode))
 			result = true;
-	} else if (acpi_enumerate_nondev_subnodes(NULL, desc, &dn->data)) {
+	} else if (acpi_enumerate_nondev_subnodes(NULL, desc, &dn->data,
+						  &dn->fwnode)) {
 		result = true;
 	}
 
@@ -91,7 +96,8 @@ static bool acpi_nondev_subnode_extract(const union acpi_object *desc,
 
 static bool acpi_nondev_subnode_data_ok(acpi_handle handle,
 					const union acpi_object *link,
-					struct list_head *list)
+					struct list_head *list,
+					struct fwnode_handle *parent)
 {
 	struct acpi_buffer buf = { ACPI_ALLOCATE_BUFFER };
 	acpi_status status;
@@ -101,7 +107,7 @@ static bool acpi_nondev_subnode_data_ok(acpi_handle handle,
 	if (ACPI_FAILURE(status))
 		return false;
 
-	if (acpi_nondev_subnode_extract(buf.pointer, handle, link, list))
+	if (acpi_nondev_subnode_extract(buf.pointer, handle, link, list, parent))
 		return true;
 
 	ACPI_FREE(buf.pointer);
@@ -110,7 +116,8 @@ static bool acpi_nondev_subnode_data_ok(acpi_handle handle,
 
 static bool acpi_nondev_subnode_ok(acpi_handle scope,
 				   const union acpi_object *link,
-				   struct list_head *list)
+				   struct list_head *list,
+				   struct fwnode_handle *parent)
 {
 	acpi_handle handle;
 	acpi_status status;
@@ -123,12 +130,13 @@ static bool acpi_nondev_subnode_ok(acpi_handle scope,
 	if (ACPI_FAILURE(status))
 		return false;
 
-	return acpi_nondev_subnode_data_ok(handle, link, list);
+	return acpi_nondev_subnode_data_ok(handle, link, list, parent);
 }
 
 static int acpi_add_nondev_subnodes(acpi_handle scope,
 				    const union acpi_object *links,
-				    struct list_head *list)
+				    struct list_head *list,
+				    struct fwnode_handle *parent)
 {
 	bool ret = false;
 	int i;
@@ -150,15 +158,18 @@ static int acpi_add_nondev_subnodes(acpi_handle scope,
 		/* The second one may be a string, a reference or a package. */
 		switch (link->package.elements[1].type) {
 		case ACPI_TYPE_STRING:
-			result = acpi_nondev_subnode_ok(scope, link, list);
+			result = acpi_nondev_subnode_ok(scope, link, list,
+							 parent);
 			break;
 		case ACPI_TYPE_LOCAL_REFERENCE:
 			handle = link->package.elements[1].reference.handle;
-			result = acpi_nondev_subnode_data_ok(handle, link, list);
+			result = acpi_nondev_subnode_data_ok(handle, link, list,
+							     parent);
 			break;
 		case ACPI_TYPE_PACKAGE:
 			desc = &link->package.elements[1];
-			result = acpi_nondev_subnode_extract(desc, NULL, link, list);
+			result = acpi_nondev_subnode_extract(desc, NULL, link, list,
+							     parent);
 			break;
 		default:
 			result = false;
@@ -172,7 +183,8 @@ static int acpi_add_nondev_subnodes(acpi_handle scope,
 
 static bool acpi_enumerate_nondev_subnodes(acpi_handle scope,
 					   const union acpi_object *desc,
-					   struct acpi_device_data *data)
+					   struct acpi_device_data *data,
+					   struct fwnode_handle *parent)
 {
 	int i;
 
@@ -194,7 +206,8 @@ static bool acpi_enumerate_nondev_subnodes(acpi_handle scope,
 		if (memcmp(uuid->buffer.pointer, ads_uuid, sizeof(ads_uuid)))
 			continue;
 
-		return acpi_add_nondev_subnodes(scope, links, &data->subnodes);
+		return acpi_add_nondev_subnodes(scope, links, &data->subnodes,
+						parent);
 	}
 
 	return false;
@@ -345,7 +358,8 @@ void acpi_init_properties(struct acpi_device *adev)
 		if (acpi_of)
 			acpi_init_of_compatible(adev);
 	}
-	if (acpi_enumerate_nondev_subnodes(adev->handle, buf.pointer, &adev->data))
+	if (acpi_enumerate_nondev_subnodes(adev->handle, buf.pointer,
+					&adev->data, acpi_fwnode_handle(adev)))
 		adev->data.pointer = buf.pointer;
 
 	if (!adev->data.pointer) {
@@ -920,3 +934,30 @@ struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
 	}
 	return NULL;
 }
+
+/**
+ * acpi_node_get_parent - Return parent fwnode of this fwnode
+ * @fwnode: Firmware node whose parent to get
+ *
+ * Returns parent node of an ACPI device or data firmware node or %NULL if
+ * not available.
+ */
+struct fwnode_handle *acpi_node_get_parent(struct fwnode_handle *fwnode)
+{
+	if (is_acpi_data_node(fwnode)) {
+		/* All data nodes have parent pointer so just return that */
+		return to_acpi_data_node(fwnode)->parent;
+	} else if (is_acpi_device_node(fwnode)) {
+		acpi_handle handle, parent_handle;
+
+		handle = to_acpi_device_node(fwnode)->handle;
+		if (ACPI_SUCCESS(acpi_get_parent(handle, &parent_handle))) {
+			struct acpi_device *adev;
+
+			if (!acpi_bus_get_device(parent_handle, &adev))
+				return acpi_fwnode_handle(adev);
+		}
+	}
+
+	return NULL;
+}
diff --git a/include/acpi/acpi_bus.h b/include/acpi/acpi_bus.h
index 4242c31..81129e2 100644
--- a/include/acpi/acpi_bus.h
+++ b/include/acpi/acpi_bus.h
@@ -386,6 +386,7 @@ struct acpi_data_node {
 	const char *name;
 	acpi_handle handle;
 	struct fwnode_handle fwnode;
+	struct fwnode_handle *parent;
 	struct acpi_device_data data;
 	struct list_head sibling;
 	struct kobject kobj;
diff --git a/include/linux/acpi.h b/include/linux/acpi.h
index 5b36974..868f923 100644
--- a/include/linux/acpi.h
+++ b/include/linux/acpi.h
@@ -1001,6 +1001,7 @@ int acpi_dev_prop_read(struct acpi_device *adev, const char *propname,
 
 struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
 					    struct fwnode_handle *subnode);
+struct fwnode_handle *acpi_node_get_parent(struct fwnode_handle *fwnode);
 
 struct acpi_probe_entry;
 typedef bool (*acpi_probe_entry_validate_subtbl)(struct acpi_subtable_header *,
@@ -1123,6 +1124,12 @@ static inline struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
 	return NULL;
 }
 
+static inline struct fwnode_handle *
+acpi_node_get_parent(struct fwnode_handle *fwnode)
+{
+	return NULL;
+}
+
 #define ACPI_DECLARE_PROBE_ENTRY(table, name, table_id, subtable, valid, data, fn) \
 	static const void * __acpi_table_##name[]			\
 		__attribute__((unused))					\
-- 
2.7.4

[PATCH 02/15] device property: Add fwnode_get_parent()

[Sakari Ailus]

From: Mika Westerberg <mika.westerberg@linux.intel.com>

Now that ACPI has support for returning parent firmware node for both types
of nodes we can expose this to others as well. This adds a new function
fwnode_get_parent() that can be used for DT and ACPI nodes to retrieve the
parent firmware node.

Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/base/property.c  | 25 +++++++++++++++++++++++++
 include/linux/property.h |  2 ++
 2 files changed, 27 insertions(+)

diff --git a/drivers/base/property.c b/drivers/base/property.c
index 43a36d6..384998a 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -867,6 +867,31 @@ int device_add_properties(struct device *dev, struct property_entry *properties)
 EXPORT_SYMBOL_GPL(device_add_properties);
 
 /**
+ * fwnode_get_parent - Return parent firwmare node
+ * @fwnode: Firmware whose parent is retrieved
+ *
+ * Return parent firmware node of the given node if possible or %NULL if no
+ * parent was available.
+ */
+struct fwnode_handle *fwnode_get_parent(struct fwnode_handle *fwnode)
+{
+	struct fwnode_handle *parent = NULL;
+
+	if (is_of_node(fwnode)) {
+		struct device_node *node;
+
+		node = of_get_parent(to_of_node(fwnode));
+		if (node)
+			parent = &node->fwnode;
+	} else if (is_acpi_node(fwnode)) {
+		parent = acpi_node_get_parent(fwnode);
+	}
+
+	return parent;
+}
+EXPORT_SYMBOL_GPL(fwnode_get_parent);
+
+/**
  * device_get_next_child_node - Return the next child node handle for a device
  * @dev: Device to find the next child node for.
  * @child: Handle to one of the device's child nodes or a null handle.
diff --git a/include/linux/property.h b/include/linux/property.h
index 856e50b..85060bf 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -70,6 +70,8 @@ int fwnode_property_read_string(struct fwnode_handle *fwnode,
 int fwnode_property_match_string(struct fwnode_handle *fwnode,
 				 const char *propname, const char *string);
 
+struct fwnode_handle *fwnode_get_parent(struct fwnode_handle *fwnode);
+
 struct fwnode_handle *device_get_next_child_node(struct device *dev,
 						 struct fwnode_handle *child);
 
-- 
2.7.4

[PATCH 03/15] ACPI / property: Add fwnode_get_next_child_node()

[Sakari Ailus]

From: Mika Westerberg <mika.westerberg@linux.intel.com>

The ACPI _DSD hierarchical data extension [1] makes it possible to have
hierarchies deeper than one level in similar way than DT allows. These
"subsubnodes" have not been accessible because device property
implementation only provides device_get_next_child_node() that is limited
to direct descendants of a device.

We need this ability in order support things like remote endpoints
currently supported in DT with of_graph_* APIs.

Modify acpi_get_next_subnode() to accept fwnode handle instead and update
callers accordingly. Also add a new function fwnode_get_next_child_node()
that works directly with fwnodes and modify device_get_next_child_node() to
call it directly. While there add a macro fwnode_for_each_child_node()
analogous to the current device_for_each_child_node() but it works with
fwnodes instead of devices.

[1] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf

Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/acpi/property.c  | 27 +++++++++++++++++----------
 drivers/base/property.c  | 38 ++++++++++++++++++++++++++++++--------
 include/linux/acpi.h     |  8 ++++----
 include/linux/property.h |  6 ++++++
 4 files changed, 57 insertions(+), 22 deletions(-)

diff --git a/drivers/acpi/property.c b/drivers/acpi/property.c
index 65a0606..09424ef 100644
--- a/drivers/acpi/property.c
+++ b/drivers/acpi/property.c
@@ -879,21 +879,22 @@ int acpi_node_prop_read(struct fwnode_handle *fwnode,  const char *propname,
 }
 
 /**
- * acpi_get_next_subnode - Return the next child node handle for a device.
- * @dev: Device to find the next child node for.
+ * acpi_get_next_subnode - Return the next child node handle for a fwnode
+ * @fwnode: Firmware node to find the next child node for.
  * @child: Handle to one of the device's child nodes or a null handle.
  */
-struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
+struct fwnode_handle *acpi_get_next_subnode(struct fwnode_handle *fwnode,
 					    struct fwnode_handle *child)
 {
-	struct acpi_device *adev = ACPI_COMPANION(dev);
+	struct acpi_device *adev = to_acpi_device_node(fwnode);
 	struct list_head *head, *next;
 
-	if (!adev)
-		return NULL;
-
 	if (!child || child->type == FWNODE_ACPI) {
-		head = &adev->children;
+		if (adev)
+			head = &adev->children;
+		else
+			goto nondev;
+
 		if (list_empty(head))
 			goto nondev;
 
@@ -902,7 +903,6 @@ struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
 			next = adev->node.next;
 			if (next == head) {
 				child = NULL;
-				adev = ACPI_COMPANION(dev);
 				goto nondev;
 			}
 			adev = list_entry(next, struct acpi_device, node);
@@ -914,9 +914,16 @@ struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
 
  nondev:
 	if (!child || child->type == FWNODE_ACPI_DATA) {
+		struct acpi_data_node *data = to_acpi_data_node(fwnode);
 		struct acpi_data_node *dn;
 
-		head = &adev->data.subnodes;
+		if (adev)
+			head = &adev->data.subnodes;
+		else if (data)
+			head = &data->data.subnodes;
+		else
+			return NULL;
+
 		if (list_empty(head))
 			return NULL;
 
diff --git a/drivers/base/property.c b/drivers/base/property.c
index 384998a..15403f7 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -892,24 +892,46 @@ struct fwnode_handle *fwnode_get_parent(struct fwnode_handle *fwnode)
 EXPORT_SYMBOL_GPL(fwnode_get_parent);
 
 /**
- * device_get_next_child_node - Return the next child node handle for a device
- * @dev: Device to find the next child node for.
- * @child: Handle to one of the device's child nodes or a null handle.
+ * fwnode_get_next_child_node - Return the next child node handle for a node
+ * @fwnode: Firmware node to find the next child node for.
+ * @child: Handle to one of the node's child nodes or a %NULL handle.
  */
-struct fwnode_handle *device_get_next_child_node(struct device *dev,
+struct fwnode_handle *fwnode_get_next_child_node(struct fwnode_handle *fwnode,
 						 struct fwnode_handle *child)
 {
-	if (IS_ENABLED(CONFIG_OF) && dev->of_node) {
+	if (is_of_node(fwnode)) {
 		struct device_node *node;
 
-		node = of_get_next_available_child(dev->of_node, to_of_node(child));
+		node = of_get_next_available_child(to_of_node(fwnode),
+						   to_of_node(child));
 		if (node)
 			return &node->fwnode;
-	} else if (IS_ENABLED(CONFIG_ACPI)) {
-		return acpi_get_next_subnode(dev, child);
+	} else if (is_acpi_node(fwnode)) {
+		return acpi_get_next_subnode(fwnode, child);
 	}
+
 	return NULL;
 }
+EXPORT_SYMBOL_GPL(fwnode_get_next_child_node);
+
+/**
+ * device_get_next_child_node - Return the next child node handle for a device
+ * @dev: Device to find the next child node for.
+ * @child: Handle to one of the device's child nodes or a null handle.
+ */
+struct fwnode_handle *device_get_next_child_node(struct device *dev,
+						 struct fwnode_handle *child)
+{
+	struct acpi_device *adev = ACPI_COMPANION(dev);
+	struct fwnode_handle *fwnode = NULL;
+
+	if (dev->of_node)
+		fwnode = &dev->of_node->fwnode;
+	else if (adev)
+		fwnode = acpi_fwnode_handle(adev);
+
+	return fwnode_get_next_child_node(fwnode, child);
+}
 EXPORT_SYMBOL_GPL(device_get_next_child_node);
 
 /**
diff --git a/include/linux/acpi.h b/include/linux/acpi.h
index 868f923..f6f8655 100644
--- a/include/linux/acpi.h
+++ b/include/linux/acpi.h
@@ -999,8 +999,8 @@ int acpi_node_prop_read(struct fwnode_handle *fwnode, const char *propname,
 int acpi_dev_prop_read(struct acpi_device *adev, const char *propname,
 		       enum dev_prop_type proptype, void *val, size_t nval);
 
-struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
-					    struct fwnode_handle *subnode);
+struct fwnode_handle *acpi_get_next_subnode(struct fwnode_handle *fwnode,
+					    struct fwnode_handle *child);
 struct fwnode_handle *acpi_node_get_parent(struct fwnode_handle *fwnode);
 
 struct acpi_probe_entry;
@@ -1118,8 +1118,8 @@ static inline int acpi_dev_prop_read(struct acpi_device *adev,
 	return -ENXIO;
 }
 
-static inline struct fwnode_handle *acpi_get_next_subnode(struct device *dev,
-						struct fwnode_handle *subnode)
+static inline struct fwnode_handle *
+acpi_get_next_subnode(struct fwnode_handle *fwnode, struct fwnode_handle *child)
 {
 	return NULL;
 }
diff --git a/include/linux/property.h b/include/linux/property.h
index 85060bf..a3d4f52 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -71,6 +71,12 @@ int fwnode_property_match_string(struct fwnode_handle *fwnode,
 				 const char *propname, const char *string);
 
 struct fwnode_handle *fwnode_get_parent(struct fwnode_handle *fwnode);
+struct fwnode_handle *fwnode_get_next_child_node(struct fwnode_handle *fwnode,
+						 struct fwnode_handle *child);
+
+#define fwnode_for_each_child_node(fwnode, child)			\
+	for (child = fwnode_get_next_child_node(fwnode, NULL); child;	\
+	     child = fwnode_get_next_child_node(fwnode, child))
 
 struct fwnode_handle *device_get_next_child_node(struct device *dev,
 						 struct fwnode_handle *child);
-- 
2.7.4

[PATCH 04/15] device property: Add fwnode_get_named_child_node()

[Sakari Ailus]

From: Mika Westerberg <mika.westerberg@linux.intel.com>

Since now we have means to enumerate all children of any fwnode even in
ACPI we can implement fwnode_get_named_child_node(). This is similar than
device_get_named_child_node() with the exception that it can be called to
any fwnode handle. Make device_get_named_child_node() call directly this
new function.

This is useful in cases where we need to be able to find child nodes which
are not direct descendants of the parent device.

Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/base/property.c  | 22 +++++++++++++++++-----
 include/linux/property.h |  2 ++
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/drivers/base/property.c b/drivers/base/property.c
index 15403f7..c0011cf 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -935,20 +935,20 @@ struct fwnode_handle *device_get_next_child_node(struct device *dev,
 EXPORT_SYMBOL_GPL(device_get_next_child_node);
 
 /**
- * device_get_named_child_node - Return first matching named child node handle
- * @dev: Device to find the named child node for.
+ * fwnode_get_named_child_node - Return first matching named child node handle
+ * @fwnode: Firmware node to find the named child node for.
  * @childname: String to match child node name against.
  */
-struct fwnode_handle *device_get_named_child_node(struct device *dev,
+struct fwnode_handle *fwnode_get_named_child_node(struct fwnode_handle *fwnode,
 						  const char *childname)
 {
 	struct fwnode_handle *child;
 
 	/*
-	 * Find first matching named child node of this device.
+	 * Find first matching named child node of this fwnode.
 	 * For ACPI this will be a data only sub-node.
 	 */
-	device_for_each_child_node(dev, child) {
+	fwnode_for_each_child_node(fwnode, child) {
 		if (is_of_node(child)) {
 			if (!of_node_cmp(to_of_node(child)->name, childname))
 				return child;
@@ -960,6 +960,18 @@ struct fwnode_handle *device_get_named_child_node(struct device *dev,
 
 	return NULL;
 }
+EXPORT_SYMBOL_GPL(fwnode_get_named_child_node);
+
+/**
+ * device_get_named_child_node - Return first matching named child node handle
+ * @dev: Device to find the named child node for.
+ * @childname: String to match child node name against.
+ */
+struct fwnode_handle *device_get_named_child_node(struct device *dev,
+						  const char *childname)
+{
+	return fwnode_get_named_child_node(dev_fwnode(dev), childname);
+}
 EXPORT_SYMBOL_GPL(device_get_named_child_node);
 
 /**
diff --git a/include/linux/property.h b/include/linux/property.h
index a3d4f52..66530c3 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -85,6 +85,8 @@ struct fwnode_handle *device_get_next_child_node(struct device *dev,
 	for (child = device_get_next_child_node(dev, NULL); child;	\
 	     child = device_get_next_child_node(dev, child))
 
+struct fwnode_handle *fwnode_get_named_child_node(struct fwnode_handle *fwnode,
+						  const char *childname);
 struct fwnode_handle *device_get_named_child_node(struct device *dev,
 						  const char *childname);
 
-- 
2.7.4

[PATCH 07/15] device property: Add fwnode_handle_get()

[Sakari Ailus]

fwnode_handle_get() is used to obtain a reference to a fwnode_handle
container. In this case this is OF specific struct device_node.

This complements fwnode_handle_put() which is already implemented.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 drivers/base/property.c  | 11 +++++++++++
 include/linux/property.h |  1 +
 2 files changed, 12 insertions(+)

diff --git a/drivers/base/property.c b/drivers/base/property.c
index cf602c3..51c0881 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -976,6 +976,17 @@ struct fwnode_handle *device_get_named_child_node(struct device *dev,
 EXPORT_SYMBOL_GPL(device_get_named_child_node);
 
 /**
+ * fwnode_handle_get - Obtain a reference to a device node
+ * @fwnode: Pointer to the device node to obtain the reference to.
+ */
+void fwnode_handle_get(struct fwnode_handle *fwnode)
+{
+	if (is_of_node(fwnode))
+		of_node_get(to_of_node(fwnode));
+}
+EXPORT_SYMBOL_GPL(fwnode_handle_get);
+
+/**
  * fwnode_handle_put - Drop reference to a device node
  * @fwnode: Pointer to the device node to drop the reference to.
  *
diff --git a/include/linux/property.h b/include/linux/property.h
index 86c47ad..b4b1545 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -90,6 +90,7 @@ struct fwnode_handle *fwnode_get_named_child_node(struct fwnode_handle *fwnode,
 struct fwnode_handle *device_get_named_child_node(struct device *dev,
 						  const char *childname);
 
+void fwnode_handle_get(struct fwnode_handle *fwnode);
 void fwnode_handle_put(struct fwnode_handle *fwnode);
 
 unsigned int device_get_child_node_count(struct device *dev);
-- 
2.7.4

[PATCH 08/15] of: Add of_fwnode_handle() to convert device nodes to fwnode_handle

[Sakari Ailus]

of_fwnode_handle() returns a struct fwnode_handle of the struct
device_node. This may be used on the fwnode property API.

Use a macro instead of a function in order to support const and non-const
arguments.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 include/linux/of.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/include/linux/of.h b/include/linux/of.h
index d72f010..55eee5d 100644
--- a/include/linux/of.h
+++ b/include/linux/of.h
@@ -159,6 +159,8 @@ static inline struct device_node *to_of_node(struct fwnode_handle *fwnode)
 		container_of(fwnode, struct device_node, fwnode) : NULL;
 }
 
+#define of_fwnode_handle(node) (&(node)->fwnode)
+
 static inline bool of_have_populated_dt(void)
 {
 	return of_root != NULL;
@@ -601,6 +603,8 @@ static inline struct device_node *of_find_node_with_property(
 	return NULL;
 }
 
+#define of_fwnode_handle(node) NULL
+
 static inline bool of_have_populated_dt(void)
 {
 	return false;
-- 
2.7.4

[PATCH 10/15] of: No need to include linux/property.h, linux/fwnode.h is sufficient

[Sakari Ailus]

of.h requires a definition of struct fwnode_handle, and for that it
includes linux/property.h. struct fwnode_handle, however, is defined in
linux/fwnode.h. Include linux/fwnode.h directly.

A number of users were however depending on linux/property.h, thus fix
them by including that header directly as well.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 drivers/base/core.c                       | 1 +
 drivers/input/keyboard/gpio_keys.c        | 1 +
 drivers/input/misc/drv260x.c              | 1 +
 drivers/input/misc/gpio_decoder.c         | 1 +
 drivers/input/touchscreen/ad7879.c        | 1 +
 drivers/input/touchscreen/edt-ft5x06.c    | 1 +
 drivers/net/ethernet/faraday/ftgmac100.c  | 1 +
 drivers/net/ethernet/smsc/smc91x.c        | 1 +
 drivers/phy/phy-tusb1210.c                | 1 +
 drivers/power/supply/bq24735-charger.c    | 1 +
 drivers/usb/common/common.c               | 1 +
 drivers/usb/dwc2/params.c                 | 1 +
 drivers/usb/dwc2/pci.c                    | 3 ++-
 drivers/usb/dwc3/host.c                   | 1 +
 include/linux/of.h                        | 2 +-
 sound/soc/codecs/rt5514.c                 | 1 +
 sound/soc/codecs/ts3a227e.c               | 1 +
 sound/soc/mediatek/mt8173/mt8173-rt5650.c | 1 +
 sound/soc/rockchip/rk3399_gru_sound.c     | 1 +
 19 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/drivers/base/core.c b/drivers/base/core.c
index bd87807..ad5a4f7 100644
--- a/drivers/base/core.c
+++ b/drivers/base/core.c
@@ -24,6 +24,7 @@
 #include <linux/of.h>
 #include <linux/of_device.h>
 #include <linux/pm_runtime.h>
+#include <linux/property.h>
 #include <linux/slab.h>
 #include <linux/string.h>
 #include <linux/sysfs.h>
diff --git a/drivers/input/keyboard/gpio_keys.c b/drivers/input/keyboard/gpio_keys.c
index 582462d..a560fad 100644
--- a/drivers/input/keyboard/gpio_keys.c
+++ b/drivers/input/keyboard/gpio_keys.c
@@ -20,6 +20,7 @@
 #include <linux/slab.h>
 #include <linux/sysctl.h>
 #include <linux/proc_fs.h>
+#include <linux/property.h>
 #include <linux/delay.h>
 #include <linux/platform_device.h>
 #include <linux/input.h>
diff --git a/drivers/input/misc/drv260x.c b/drivers/input/misc/drv260x.c
index 0a2b865..1642219 100644
--- a/drivers/input/misc/drv260x.c
+++ b/drivers/input/misc/drv260x.c
@@ -22,6 +22,7 @@
 #include <linux/slab.h>
 #include <linux/delay.h>
 #include <linux/gpio/consumer.h>
+#include <linux/property.h>
 #include <linux/regulator/consumer.h>
 
 #include <dt-bindings/input/ti-drv260x.h>
diff --git a/drivers/input/misc/gpio_decoder.c b/drivers/input/misc/gpio_decoder.c
index ca7e0ba..a498848 100644
--- a/drivers/input/misc/gpio_decoder.c
+++ b/drivers/input/misc/gpio_decoder.c
@@ -22,6 +22,7 @@
 #include <linux/module.h>
 #include <linux/of.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 
 struct gpio_decoder {
 	struct input_polled_dev *poll_dev;
diff --git a/drivers/input/touchscreen/ad7879.c b/drivers/input/touchscreen/ad7879.c
index e16a446..38ad365 100644
--- a/drivers/input/touchscreen/ad7879.c
+++ b/drivers/input/touchscreen/ad7879.c
@@ -34,6 +34,7 @@
 #include <linux/input/touchscreen.h>
 #include <linux/platform_data/ad7879.h>
 #include <linux/module.h>
+#include <linux/property.h>
 #include "ad7879.h"
 
 #define AD7879_REG_ZEROS		0
diff --git a/drivers/input/touchscreen/edt-ft5x06.c b/drivers/input/touchscreen/edt-ft5x06.c
index 28466e3..1978f8b 100644
--- a/drivers/input/touchscreen/edt-ft5x06.c
+++ b/drivers/input/touchscreen/edt-ft5x06.c
@@ -39,6 +39,7 @@
 #include <linux/input/mt.h>
 #include <linux/input/touchscreen.h>
 #include <linux/of_device.h>
+#include <linux/property.h>
 
 #define WORK_REGISTER_THRESHOLD		0x00
 #define WORK_REGISTER_REPORT_RATE	0x08
diff --git a/drivers/net/ethernet/faraday/ftgmac100.c b/drivers/net/ethernet/faraday/ftgmac100.c
index 2625872..69f2693 100644
--- a/drivers/net/ethernet/faraday/ftgmac100.c
+++ b/drivers/net/ethernet/faraday/ftgmac100.c
@@ -30,6 +30,7 @@
 #include <linux/netdevice.h>
 #include <linux/phy.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <net/ip.h>
 #include <net/ncsi.h>
 
diff --git a/drivers/net/ethernet/smsc/smc91x.c b/drivers/net/ethernet/smsc/smc91x.c
index 65077c7..5352a08 100644
--- a/drivers/net/ethernet/smsc/smc91x.c
+++ b/drivers/net/ethernet/smsc/smc91x.c
@@ -75,6 +75,7 @@ static const char version[] =
 #include <linux/ioport.h>
 #include <linux/crc32.h>
 #include <linux/platform_device.h>
+#include <linux/property.h>
 #include <linux/spinlock.h>
 #include <linux/ethtool.h>
 #include <linux/mii.h>
diff --git a/drivers/phy/phy-tusb1210.c b/drivers/phy/phy-tusb1210.c
index 4f6d5e7..f7dd21aa 100644
--- a/drivers/phy/phy-tusb1210.c
+++ b/drivers/phy/phy-tusb1210.c
@@ -12,6 +12,7 @@
 #include <linux/module.h>
 #include <linux/ulpi/driver.h>
 #include <linux/gpio/consumer.h>
+#include <linux/property.h>
 
 #include "ulpi_phy.h"
 
diff --git a/drivers/power/supply/bq24735-charger.c b/drivers/power/supply/bq24735-charger.c
index eb7783b..038f806 100644
--- a/drivers/power/supply/bq24735-charger.c
+++ b/drivers/power/supply/bq24735-charger.c
@@ -27,6 +27,7 @@
 #include <linux/of.h>
 #include <linux/gpio/consumer.h>
 #include <linux/power_supply.h>
+#include <linux/property.h>
 #include <linux/slab.h>
 
 #include <linux/power/bq24735-charger.h>
diff --git a/drivers/usb/common/common.c b/drivers/usb/common/common.c
index 5ef8da6..534a498 100644
--- a/drivers/usb/common/common.c
+++ b/drivers/usb/common/common.c
@@ -14,6 +14,7 @@
 #include <linux/kernel.h>
 #include <linux/module.h>
 #include <linux/of.h>
+#include <linux/property.h>
 #include <linux/usb/ch9.h>
 #include <linux/usb/of.h>
 #include <linux/usb/otg.h>
diff --git a/drivers/usb/dwc2/params.c b/drivers/usb/dwc2/params.c
index a786256..7e6da29 100644
--- a/drivers/usb/dwc2/params.c
+++ b/drivers/usb/dwc2/params.c
@@ -35,6 +35,7 @@
 #include <linux/kernel.h>
 #include <linux/module.h>
 #include <linux/of_device.h>
+#include <linux/property.h>
 
 #include "core.h"
 
diff --git a/drivers/usb/dwc2/pci.c b/drivers/usb/dwc2/pci.c
index a23329e..abf6140 100644
--- a/drivers/usb/dwc2/pci.c
+++ b/drivers/usb/dwc2/pci.c
@@ -44,8 +44,9 @@
 #include <linux/spinlock.h>
 #include <linux/interrupt.h>
 #include <linux/io.h>
-#include <linux/slab.h>
 #include <linux/pci.h>
+#include <linux/property.h>
+#include <linux/slab.h>
 #include <linux/usb.h>
 
 #include <linux/usb/hcd.h>
diff --git a/drivers/usb/dwc3/host.c b/drivers/usb/dwc3/host.c
index 487f0ff..562cbde 100644
--- a/drivers/usb/dwc3/host.c
+++ b/drivers/usb/dwc3/host.c
@@ -16,6 +16,7 @@
  */
 
 #include <linux/platform_device.h>
+#include <linux/property.h>
 
 #include "core.h"
 
diff --git a/include/linux/of.h b/include/linux/of.h
index 55eee5d..16b2054 100644
--- a/include/linux/of.h
+++ b/include/linux/of.h
@@ -23,7 +23,7 @@
 #include <linux/spinlock.h>
 #include <linux/topology.h>
 #include <linux/notifier.h>
-#include <linux/property.h>
+#include <linux/fwnode.h>
 #include <linux/list.h>
 
 #include <asm/byteorder.h>
diff --git a/sound/soc/codecs/rt5514.c b/sound/soc/codecs/rt5514.c
index b281a46..0749219 100644
--- a/sound/soc/codecs/rt5514.c
+++ b/sound/soc/codecs/rt5514.c
@@ -15,6 +15,7 @@
 #include <linux/init.h>
 #include <linux/delay.h>
 #include <linux/pm.h>
+#include <linux/property.h>
 #include <linux/regmap.h>
 #include <linux/i2c.h>
 #include <linux/platform_device.h>
diff --git a/sound/soc/codecs/ts3a227e.c b/sound/soc/codecs/ts3a227e.c
index 4356843..e80b28b 100644
--- a/sound/soc/codecs/ts3a227e.c
+++ b/sound/soc/codecs/ts3a227e.c
@@ -14,6 +14,7 @@
 #include <linux/input.h>
 #include <linux/module.h>
 #include <linux/of_gpio.h>
+#include <linux/property.h>
 #include <linux/regmap.h>
 
 #include <sound/core.h>
diff --git a/sound/soc/mediatek/mt8173/mt8173-rt5650.c b/sound/soc/mediatek/mt8173/mt8173-rt5650.c
index ba65f41..433ae4f 100644
--- a/sound/soc/mediatek/mt8173/mt8173-rt5650.c
+++ b/sound/soc/mediatek/mt8173/mt8173-rt5650.c
@@ -17,6 +17,7 @@
 #include <linux/module.h>
 #include <linux/gpio.h>
 #include <linux/of_gpio.h>
+#include <linux/property.h>
 #include <sound/soc.h>
 #include <sound/jack.h>
 #include "../../codecs/rt5645.h"
diff --git a/sound/soc/rockchip/rk3399_gru_sound.c b/sound/soc/rockchip/rk3399_gru_sound.c
index 3475c61..9134b46 100644
--- a/sound/soc/rockchip/rk3399_gru_sound.c
+++ b/sound/soc/rockchip/rk3399_gru_sound.c
@@ -22,6 +22,7 @@
 #include <linux/gpio.h>
 #include <linux/of_gpio.h>
 #include <linux/delay.h>
+#include <linux/property.h>
 #include <linux/spi/spi.h>
 #include <linux/input.h>
 #include <sound/core.h>
-- 
2.7.4

Re: [PATCH 10/15] of: No need to include linux/property.h, linux/fwnode.h is sufficient

[kbuild test robot]

[-- Attachment #1: Type: text/plain, Size: 4361 bytes --]

Hi Sakari,

[auto build test WARNING on driver-core/driver-core-testing]
[also build test WARNING on v4.10-rc5 next-20170125]
[if your patch is applied to the wrong git tree, please drop us a note to help improve the system]

url:    https://github.com/0day-ci/linux/commits/Sakari-Ailus/ACPI-graph-support/20170128-032753
config: arm64-defconfig (attached as .config)
compiler: aarch64-linux-gnu-gcc (Debian 6.1.1-9) 6.1.1 20160705
reproduce:
        wget https://git.kernel.org/cgit/linux/kernel/git/wfg/lkp-tests.git/plain/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        # save the attached .config to linux build tree
        make.cross ARCH=arm64 

All warnings (new ones prefixed by >>):

   In file included from arch/arm64/kvm/../../../virt/kvm/arm/vgic/vgic-v2.c:17:0:
>> include/linux/irqchip/arm-gic.h:123:30: warning: 'struct device' declared inside parameter list will not be visible outside of this definition or declaration
    int gic_of_init_child(struct device *dev, struct gic_chip_data **gic, int irq);
                                 ^~~~~~

vim +123 include/linux/irqchip/arm-gic.h

4c2880b3 include/linux/irqchip/arm-gic.h     Jon Hunter     2015-07-31  107  int gic_cpu_if_down(unsigned int gic_nr);
cdbb813d include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  108  void gic_cpu_save(struct gic_chip_data *gic);
cdbb813d include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  109  void gic_cpu_restore(struct gic_chip_data *gic);
cdbb813d include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  110  void gic_dist_save(struct gic_chip_data *gic);
cdbb813d include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  111  void gic_dist_restore(struct gic_chip_data *gic);
e807acbc arch/arm/include/asm/hardware/gic.h Changhwan Youn 2011-07-16  112  
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  113  /*
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  114   * Subdrivers that need some preparatory work can initialize their
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  115   * chips and call this to register their GICs.
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  116   */
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  117  int gic_of_init(struct device_node *node, struct device_node *parent);
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  118  
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  119  /*
9c8edddf include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  120   * Initialises and registers a non-root or child GIC chip. Memory for
9c8edddf include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  121   * the gic_chip_data structure is dynamically allocated.
9c8edddf include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  122   */
9c8edddf include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07 @123  int gic_of_init_child(struct device *dev, struct gic_chip_data **gic, int irq);
9c8edddf include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  124  
9c8edddf include/linux/irqchip/arm-gic.h     Jon Hunter     2016-06-07  125  /*
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  126   * Legacy platforms not converted to DT yet must use this to init
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  127   * their GIC
8673c1d7 include/linux/irqchip/arm-gic.h     Linus Walleij  2015-10-24  128   */
e81a7cd9 include/linux/irqchip/arm-gic.h     Marc Zyngier   2015-10-13  129  void gic_init(unsigned int nr, int start,
e81a7cd9 include/linux/irqchip/arm-gic.h     Marc Zyngier   2015-10-13  130  	      void __iomem *dist , void __iomem *cpu);
db0d4db2 arch/arm/include/asm/hardware/gic.h Marc Zyngier   2011-11-12  131  

:::::: The code at line 123 was first introduced by commit
:::::: 9c8edddfc9924cb473a7570c37ca466db70728f8 irqchip/gic: Add platform driver for non-root GICs that require RPM

:::::: TO: Jon Hunter <jonathanh-DDmLM1+adcrQT0dZR+AlfA@public.gmane.org>
:::::: CC: Marc Zyngier <marc.zyngier-5wv7dgnIgG8@public.gmane.org>

---
0-DAY kernel test infrastructure                Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all                   Intel Corporation

[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 33724 bytes --]

[PATCH v1.1 10/16] irqchip/gic: Add missing forward declaration for struct device

[Sakari Ailus]

A pointer to struct device is used in the header as a function argument
but there's no declaration for it. Add one.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
This patch goes before "[PATCH 10/15] of: No need to include
linux/property.h, linux/fwnode.h is sufficient".

 include/linux/irqchip/arm-gic.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/linux/irqchip/arm-gic.h b/include/linux/irqchip/arm-gic.h
index eafc965..b16afa1 100644
--- a/include/linux/irqchip/arm-gic.h
+++ b/include/linux/irqchip/arm-gic.h
@@ -100,6 +100,7 @@
 
 #include <linux/irqdomain.h>
 
+struct device;
 struct device_node;
 struct gic_chip_data;
 
-- 
2.7.4

[PATCH 11/15] device property: Obtain device's fwnode independently of FW type

[Sakari Ailus]

OF uses struct device's of_node field (of type struct device_node) to
refer to the device's OF properties. ACPI employs the fwnode field
instead. The latter is of type fwnode_handle, which is also embedded in
struct device_node.

The struct fwnode_handle pointer in both cases can be used as an argument
for the device property API which is firmware agnostic. Also make
obtaining the firmware node independent of the type of the firmware.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 include/linux/property.h | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/include/linux/property.h b/include/linux/property.h
index b4b1545..294418d 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -13,7 +13,9 @@
 #ifndef _LINUX_PROPERTY_H_
 #define _LINUX_PROPERTY_H_
 
+#include <linux/device.h>
 #include <linux/fwnode.h>
+#include <linux/of.h>
 #include <linux/types.h>
 
 struct device;
@@ -273,4 +275,12 @@ struct fwnode_handle *fwnode_graph_get_remote_port(
 struct fwnode_handle *fwnode_graph_get_remote_endpoint(
 	struct fwnode_handle *fwnode);
 
+static inline struct fwnode_handle *device_fwnode_handle(struct device *dev)
+{
+	if (dev->of_node)
+		return of_fwnode_handle(dev->of_node);
+	else
+		return dev->fwnode;
+}
+
 #endif /* _LINUX_PROPERTY_H_ */
-- 
2.7.4

[PATCH 13/15] of: Add nop implementation of of_get_next_parent()

[Sakari Ailus]

To avoid #ifdefs where the function is used.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 include/linux/of.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/include/linux/of.h b/include/linux/of.h
index 16b2054..e0ddb22 100644
--- a/include/linux/of.h
+++ b/include/linux/of.h
@@ -585,6 +585,12 @@ static inline struct device_node *of_get_parent(const struct device_node *node)
 	return NULL;
 }
 
+static inline struct device_node *of_get_next_parent(
+	const struct device_node *node)
+{
+	return NULL;
+}
+
 static inline struct device_node *of_get_next_child(
 	const struct device_node *node, struct device_node *prev)
 {
-- 
2.7.4

[PATCH 05/15] ACPI / property: Add support for remote endpoints

[Sakari Ailus]

From: Mika Westerberg <mika.westerberg-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

DT has had concept of remote endpoints for some time already. It makes
possible to reference another firmware node through a property called
remote-endpoint. This is already used by some subsystems like v4l2 for
parsing hardware properties related to camera.

This patch adds ACPI support for remote endpoints utilizing _DSD
hierarchical data extensions.

Signed-off-by: Mika Westerberg <mika.westerberg-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
---
 drivers/acpi/property.c | 139 ++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/acpi.h    |  23 ++++++++
 2 files changed, 162 insertions(+)

diff --git a/drivers/acpi/property.c b/drivers/acpi/property.c
index 09424ef..39e2033 100644
--- a/drivers/acpi/property.c
+++ b/drivers/acpi/property.c
@@ -968,3 +968,142 @@ struct fwnode_handle *acpi_node_get_parent(struct fwnode_handle *fwnode)
 
 	return NULL;
 }
+
+/**
+ * acpi_graph_get_next_endpoint - Get next endpoint ACPI firmware node
+ * @fwnode: Pointer to the parent firmware node
+ * @prev: Previous endpoint node or %NULL to get the first
+ *
+ * Looks up next endpoint ACPI firmware node below a given @fwnode. Returns
+ * %NULL if there is no next endpoint, ERR_PTR() in case of error. In case
+ * of success the next endpoint is returned.
+ */
+struct fwnode_handle *acpi_graph_get_next_endpoint(struct fwnode_handle *fwnode,
+						   struct fwnode_handle *prev)
+{
+	struct fwnode_handle *port = NULL;
+	struct fwnode_handle *endpoint;
+
+	if (!prev) {
+		do {
+			port = fwnode_get_next_child_node(fwnode, port);
+			/* Ports must have port property */
+			if (fwnode_property_present(port, "port"))
+				break;
+		} while (port);
+	} else {
+		port = fwnode_get_parent(prev);
+	}
+
+	if (!port)
+		return NULL;
+
+	endpoint = fwnode_get_next_child_node(port, prev);
+	while (!endpoint) {
+		port = fwnode_get_next_child_node(fwnode, port);
+		if (!port)
+			break;
+		if (fwnode_property_present(port, "port"))
+			endpoint = fwnode_get_next_child_node(port, NULL);
+	}
+
+	if (endpoint) {
+		/* Endpoints must have "endpoint" property */
+		if (!fwnode_property_present(endpoint, "endpoint"))
+			return ERR_PTR(-EPROTO);
+	}
+
+	return endpoint;
+}
+
+/**
+ * acpi_graph_get_child_at - Return a data extension child at given index
+ * @fwnode: parent node
+ * @at: index of the child node in the data extension package
+ *
+ * Find the child node at index of a data extension. Returns the child
+ * node on success, NULL otherwise.
+ */
+static struct fwnode_handle *acpi_graph_get_child_at(
+	struct fwnode_handle *fwnode, unsigned int at)
+{
+	struct fwnode_handle *child;
+	unsigned int i = 0;
+
+	fwnode_for_each_child_node(fwnode, child) {
+		if (i++ < at)
+			continue;
+
+		return child;
+	}
+
+	return NULL;
+}
+
+/**
+ * acpi_graph_get_remote_enpoint - Parses and returns remote end of an endpoint
+ * @fwnode: Endpoint firmware node pointing to a remote device
+ * @parent: Firmware node of remote port parent is filled here if not %NULL
+ * @port: Firmware node of remote port is filled here if not %NULL
+ * @endpoint: Firmware node of remote endpoint is filled here if not %NULL
+ *
+ * Function parses remote end of ACPI firmware remote endpoint and fills in
+ * fields requested by the caller. Returns %0 in case of success and
+ * negative errno otherwise.
+ */
+int acpi_graph_get_remote_endpoint(struct fwnode_handle *fwnode,
+				   struct fwnode_handle **parent,
+				   struct fwnode_handle **port,
+				   struct fwnode_handle **endpoint)
+{
+	unsigned int port_idx, endpoint_idx;
+	struct acpi_reference_args args;
+	int ret;
+
+	memset(&args, 0, sizeof(args));
+	ret = acpi_node_get_property_reference(fwnode, "remote-endpoint", 0,
+					       &args);
+	if (ret)
+		return ret;
+
+	/*
+	 * Always require two arguments with the reference: port and
+	 * endpoint indices.
+	 */
+	if (args.nargs != 2)
+		return -EPROTO;
+
+	fwnode = acpi_fwnode_handle(args.adev);
+	port_idx = args.args[0];
+	endpoint_idx = args.args[1];
+
+	if (parent)
+		*parent = fwnode;
+
+	if (!port && !endpoint)
+		return 0;
+
+	fwnode = acpi_graph_get_child_at(fwnode, port_idx);
+	if (!fwnode)
+		return -EPROTO;
+
+	if (!fwnode_property_present(fwnode, "port"))
+		return -EPROTO;
+
+	if (port)
+		*port = fwnode;
+
+	if (!endpoint)
+		return 0;
+
+	fwnode = acpi_graph_get_child_at(fwnode, endpoint_idx);
+	if (!fwnode)
+		return -EPROTO;
+
+	if (!fwnode_property_present(fwnode, "endpoint"))
+		return -EPROTO;
+
+	*endpoint = fwnode;
+
+	return 0;
+}
diff --git a/include/linux/acpi.h b/include/linux/acpi.h
index f6f8655..05ff957 100644
--- a/include/linux/acpi.h
+++ b/include/linux/acpi.h
@@ -1003,6 +1003,13 @@ struct fwnode_handle *acpi_get_next_subnode(struct fwnode_handle *fwnode,
 					    struct fwnode_handle *child);
 struct fwnode_handle *acpi_node_get_parent(struct fwnode_handle *fwnode);
 
+struct fwnode_handle *acpi_graph_get_next_endpoint(struct fwnode_handle *fwnode,
+						   struct fwnode_handle *prev);
+int acpi_graph_get_remote_endpoint(struct fwnode_handle *fwnode,
+				   struct fwnode_handle **remote,
+				   struct fwnode_handle **port,
+				   struct fwnode_handle **endpoint);
+
 struct acpi_probe_entry;
 typedef bool (*acpi_probe_entry_validate_subtbl)(struct acpi_subtable_header *,
 						 struct acpi_probe_entry *);
@@ -1130,6 +1137,22 @@ acpi_node_get_parent(struct fwnode_handle *fwnode)
 	return NULL;
 }
 
+static inline struct fwnode_handle *
+acpi_graph_get_next_endpoint(struct fwnode_handle *fwnode,
+			     struct fwnode_handle *prev)
+{
+	return ERR_PTR(-ENXIO);
+}
+
+static inline int
+acpi_graph_get_remote_endpoint(struct fwnode_handle *fwnode,
+			       struct fwnode_handle **remote,
+			       struct fwnode_handle **port,
+			       struct fwnode_handle **endpoint)
+{
+	return -ENXIO;
+}
+
 #define ACPI_DECLARE_PROBE_ENTRY(table, name, table_id, subtable, valid, data, fn) \
 	static const void * __acpi_table_##name[]			\
 		__attribute__((unused))					\
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 06/15] device property: Add support for remote endpoints

[Sakari Ailus]

From: Mika Westerberg <mika.westerberg-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

This follows DT implementation of of_graph_* APIs but we call them
fwnode_graph_* instead. For DT nodes the existing of_graph_* implementation
will be used. For ACPI we use the new ACPI graph implementation instead.

This commit includes code from Sakari Ailus.

Signed-off-by: Mika Westerberg <mika.westerberg-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
---
 drivers/base/property.c  | 122 +++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/property.h |   9 ++++
 2 files changed, 131 insertions(+)

diff --git a/drivers/base/property.c b/drivers/base/property.c
index c0011cf..cf602c3 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -15,6 +15,7 @@
 #include <linux/kernel.h>
 #include <linux/of.h>
 #include <linux/of_address.h>
+#include <linux/of_graph.h>
 #include <linux/property.h>
 #include <linux/etherdevice.h>
 #include <linux/phy.h>
@@ -1111,3 +1112,124 @@ void *device_get_mac_address(struct device *dev, char *addr, int alen)
 	return device_get_mac_addr(dev, "address", addr, alen);
 }
 EXPORT_SYMBOL(device_get_mac_address);
+
+/**
+ * device_graph_get_next_endpoint - Get next endpoint firmware node
+ * @fwnode: Pointer to the parent firmware node
+ * @prev: Previous endpoint node or %NULL to get the first
+ *
+ * Returns an endpoint firmware node pointer or %NULL if no more endpoints
+ * are available.
+ */
+struct fwnode_handle *
+fwnode_graph_get_next_endpoint(struct fwnode_handle *fwnode,
+			       struct fwnode_handle *prev)
+{
+	struct fwnode_handle *endpoint = NULL;
+
+	if (is_of_node(fwnode)) {
+		struct device_node *node;
+
+		node = of_graph_get_next_endpoint(to_of_node(fwnode),
+						  to_of_node(prev));
+
+		if (node)
+			endpoint = &node->fwnode;
+	} else if (is_acpi_node(fwnode)) {
+		endpoint = acpi_graph_get_next_endpoint(fwnode, prev);
+		if (IS_ERR(endpoint))
+			endpoint = NULL;
+	}
+
+	return endpoint;
+
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_next_endpoint);
+
+/**
+ * fwnode_graph_get_remote_port_parent - Return fwnode of a remote device
+ * @fwnode: Endpoint firmware node pointing to the remote endpoint
+ *
+ * Extracts firmware node of a remote device the @fwnode points to.
+ */
+struct fwnode_handle *
+fwnode_graph_get_remote_port_parent(struct fwnode_handle *fwnode)
+{
+	struct fwnode_handle *parent = NULL;
+
+	if (is_of_node(fwnode)) {
+		struct device_node *node;
+
+		node = of_graph_get_remote_port_parent(to_of_node(fwnode));
+		if (node)
+			parent = &node->fwnode;
+	} else if (is_acpi_node(fwnode)) {
+		int ret;
+
+		ret = acpi_graph_get_remote_endpoint(fwnode, &parent, NULL,
+						     NULL);
+		if (ret)
+			return NULL;
+	}
+
+	return parent;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_port_parent);
+
+/**
+ * fwnode_graph_get_remote_port - Return fwnode of a remote port
+ * @fwnode: Endpoint firmware node pointing to the remote endpoint
+ *
+ * Extracts firmware node of a remote port the @fwnode points to.
+ */
+struct fwnode_handle *fwnode_graph_get_remote_port(struct fwnode_handle *fwnode)
+{
+	struct fwnode_handle *port = NULL;
+
+	if (is_of_node(fwnode)) {
+		struct device_node *node;
+
+		node = of_graph_get_remote_port(to_of_node(fwnode));
+		if (node)
+			port = &node->fwnode;
+	} else if (is_acpi_node(fwnode)) {
+		int ret;
+
+		ret = acpi_graph_get_remote_endpoint(fwnode, NULL, &port, NULL);
+		if (ret)
+			return NULL;
+	}
+
+	return port;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_port);
+
+/**
+ * fwnode_graph_get_remote_endpoint - Return fwnode of a remote endpoint
+ * @fwnode: Endpoint firmware node pointing to the remote endpoint
+ *
+ * Extracts firmware node of a remote endpoint the @fwnode points to.
+ */
+struct fwnode_handle *
+fwnode_graph_get_remote_endpoint(struct fwnode_handle *fwnode)
+{
+	struct fwnode_handle *endpoint = NULL;
+
+	if (is_of_node(fwnode)) {
+		struct device_node *node;
+
+		node = of_parse_phandle(to_of_node(fwnode), "remote-endpoint", 0);
+		if (node)
+			endpoint = &node->fwnode;
+	} else if (is_acpi_node(fwnode)) {
+		int ret;
+
+		ret = acpi_graph_get_remote_endpoint(fwnode, NULL, NULL,
+						     &endpoint);
+		if (ret)
+			return NULL;
+	}
+
+	return endpoint;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_endpoint);
diff --git a/include/linux/property.h b/include/linux/property.h
index 66530c3..86c47ad 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -263,4 +263,13 @@ int device_get_phy_mode(struct device *dev);
 
 void *device_get_mac_address(struct device *dev, char *addr, int alen);
 
+struct fwnode_handle *fwnode_graph_get_next_endpoint(
+	struct fwnode_handle *fwnode, struct fwnode_handle *prev);
+struct fwnode_handle *fwnode_graph_get_remote_port_parent(
+	struct fwnode_handle *fwnode);
+struct fwnode_handle *fwnode_graph_get_remote_port(
+	struct fwnode_handle *fwnode);
+struct fwnode_handle *fwnode_graph_get_remote_endpoint(
+	struct fwnode_handle *fwnode);
+
 #endif /* _LINUX_PROPERTY_H_ */
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/15] device property: Add support for remote endpoints

[Rob Herring]

On Fri, Jan 27, 2017 at 10:03 AM, Sakari Ailus
<sakari.ailus@linux.intel.com> wrote:
> From: Mika Westerberg <mika.westerberg@linux.intel.com>
>
> This follows DT implementation of of_graph_* APIs but we call them
> fwnode_graph_* instead. For DT nodes the existing of_graph_* implementation
> will be used. For ACPI we use the new ACPI graph implementation instead.
>
> This commit includes code from Sakari Ailus.

Then it should have your S-o-b. Actually, either way it should have it.

Whether or not copying DT graphs is a good idea or not, I'll let
someone else chime in on that...

> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>  drivers/base/property.c  | 122 +++++++++++++++++++++++++++++++++++++++++++++++
>  include/linux/property.h |   9 ++++
>  2 files changed, 131 insertions(+)
>
> diff --git a/drivers/base/property.c b/drivers/base/property.c
> index c0011cf..cf602c3 100644
> --- a/drivers/base/property.c
> +++ b/drivers/base/property.c
> @@ -15,6 +15,7 @@
>  #include <linux/kernel.h>
>  #include <linux/of.h>
>  #include <linux/of_address.h>
> +#include <linux/of_graph.h>
>  #include <linux/property.h>
>  #include <linux/etherdevice.h>
>  #include <linux/phy.h>
> @@ -1111,3 +1112,124 @@ void *device_get_mac_address(struct device *dev, char *addr, int alen)
>         return device_get_mac_addr(dev, "address", addr, alen);
>  }
>  EXPORT_SYMBOL(device_get_mac_address);
> +
> +/**
> + * device_graph_get_next_endpoint - Get next endpoint firmware node
> + * @fwnode: Pointer to the parent firmware node
> + * @prev: Previous endpoint node or %NULL to get the first
> + *
> + * Returns an endpoint firmware node pointer or %NULL if no more endpoints
> + * are available.
> + */
> +struct fwnode_handle *
> +fwnode_graph_get_next_endpoint(struct fwnode_handle *fwnode,
> +                              struct fwnode_handle *prev)
> +{
> +       struct fwnode_handle *endpoint = NULL;
> +
> +       if (is_of_node(fwnode)) {
> +               struct device_node *node;
> +
> +               node = of_graph_get_next_endpoint(to_of_node(fwnode),
> +                                                 to_of_node(prev));
> +
> +               if (node)
> +                       endpoint = &node->fwnode;
> +       } else if (is_acpi_node(fwnode)) {
> +               endpoint = acpi_graph_get_next_endpoint(fwnode, prev);
> +               if (IS_ERR(endpoint))
> +                       endpoint = NULL;
> +       }

This is an ugly pattern IMO. Why not define an ops struct and set it
to OF or ACPI rather than check on every function call with
is_{of,acpi}_node()?

The of_graph_* functions need some better helpers too, so duplicating
them 2 more times is not ideal. Basically, drivers are left to do too
much of the walking of nodes themselves.

Rob

Re: [PATCH 06/15] device property: Add support for remote endpoints

[Sakari Ailus]

Hi Rob,

Thank you for the review.

On Fri, Jan 27, 2017 at 03:45:04PM -0600, Rob Herring wrote:
> On Fri, Jan 27, 2017 at 10:03 AM, Sakari Ailus
> <sakari.ailus@linux.intel.com> wrote:
> > From: Mika Westerberg <mika.westerberg@linux.intel.com>
> >
> > This follows DT implementation of of_graph_* APIs but we call them
> > fwnode_graph_* instead. For DT nodes the existing of_graph_* implementation
> > will be used. For ACPI we use the new ACPI graph implementation instead.
> >
> > This commit includes code from Sakari Ailus.
> 
> Then it should have your S-o-b. Actually, either way it should have it.

I'll add that.

> 
> Whether or not copying DT graphs is a good idea or not, I'll let
> someone else chime in on that...
> 
> > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > ---
> >  drivers/base/property.c  | 122 +++++++++++++++++++++++++++++++++++++++++++++++
> >  include/linux/property.h |   9 ++++
> >  2 files changed, 131 insertions(+)
> >
> > diff --git a/drivers/base/property.c b/drivers/base/property.c
> > index c0011cf..cf602c3 100644
> > --- a/drivers/base/property.c
> > +++ b/drivers/base/property.c
> > @@ -15,6 +15,7 @@
> >  #include <linux/kernel.h>
> >  #include <linux/of.h>
> >  #include <linux/of_address.h>
> > +#include <linux/of_graph.h>
> >  #include <linux/property.h>
> >  #include <linux/etherdevice.h>
> >  #include <linux/phy.h>
> > @@ -1111,3 +1112,124 @@ void *device_get_mac_address(struct device *dev, char *addr, int alen)
> >         return device_get_mac_addr(dev, "address", addr, alen);
> >  }
> >  EXPORT_SYMBOL(device_get_mac_address);
> > +
> > +/**
> > + * device_graph_get_next_endpoint - Get next endpoint firmware node
> > + * @fwnode: Pointer to the parent firmware node
> > + * @prev: Previous endpoint node or %NULL to get the first
> > + *
> > + * Returns an endpoint firmware node pointer or %NULL if no more endpoints
> > + * are available.
> > + */
> > +struct fwnode_handle *
> > +fwnode_graph_get_next_endpoint(struct fwnode_handle *fwnode,
> > +                              struct fwnode_handle *prev)
> > +{
> > +       struct fwnode_handle *endpoint = NULL;
> > +
> > +       if (is_of_node(fwnode)) {
> > +               struct device_node *node;
> > +
> > +               node = of_graph_get_next_endpoint(to_of_node(fwnode),
> > +                                                 to_of_node(prev));
> > +
> > +               if (node)
> > +                       endpoint = &node->fwnode;
> > +       } else if (is_acpi_node(fwnode)) {
> > +               endpoint = acpi_graph_get_next_endpoint(fwnode, prev);
> > +               if (IS_ERR(endpoint))
> > +                       endpoint = NULL;
> > +       }
> 
> This is an ugly pattern IMO. Why not define an ops struct and set it
> to OF or ACPI rather than check on every function call with
> is_{of,acpi}_node()?

That appears to be an established practice in the implementation of the
device / fwnode property API.

One option could be to choose the relevant ops struct based on fwnode type
in each function operating on the fwnode.

Alternatively it could be set at the time when the fwnode field is set. A
large number of drivers are manipulating their OF nodes, some do that for
fwnodes as well. Manually setting the ops struct pointer in those cases
might not be robust enough: sometimes one could simply forget. Also, adding
a pointer to struct fwnode_handle would increase the size of the struct
significantly without much gain.

The number of functions operating on fwnode_handle is rather limited. I
wonder if it'd be simply better to keep it as-is.

> 
> The of_graph_* functions need some better helpers too, so duplicating
> them 2 more times is not ideal. Basically, drivers are left to do too
> much of the walking of nodes themselves.

I have to admit my experience in using them is limited to V4L2, but I have
to say they've been working pretty well for what they're used for. Actually
the graph functionality was originally specific for V4L2, that could be the
reason why the current API is a good fit for V4L2. :-)

The current use ACPI use case is related to V4L2 as well (I'll post a new
version in the near future):

<URL:http://www.spinics.net/lists/linux-media/msg106160.html>

Are there any particular pain points that should be addressed?

I noticed Kunimori Morimoto's patchset adding of_graph_get_remote_endpoint()
which is just a new convenience function to the current API.

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi	XMPP: sailus@retiisi.org.uk

Re: [PATCH 06/15] device property: Add support for remote endpoints

[Rob Herring]

On Tue, Jan 31, 2017 at 3:58 AM, Sakari Ailus <sakari.ailus-X3B1VOXEql0@public.gmane.org> wrote:
> Hi Rob,
>
> Thank you for the review.
>
> On Fri, Jan 27, 2017 at 03:45:04PM -0600, Rob Herring wrote:
>> On Fri, Jan 27, 2017 at 10:03 AM, Sakari Ailus
>> <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org> wrote:
>> > From: Mika Westerberg <mika.westerberg-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>> >
>> > This follows DT implementation of of_graph_* APIs but we call them
>> > fwnode_graph_* instead. For DT nodes the existing of_graph_* implementation
>> > will be used. For ACPI we use the new ACPI graph implementation instead.
>> >
>> > This commit includes code from Sakari Ailus.
>>
>> Then it should have your S-o-b. Actually, either way it should have it.
>
> I'll add that.
>
>>
>> Whether or not copying DT graphs is a good idea or not, I'll let
>> someone else chime in on that...
>>
>> > Signed-off-by: Mika Westerberg <mika.westerberg-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>> > ---
>> >  drivers/base/property.c  | 122 +++++++++++++++++++++++++++++++++++++++++++++++
>> >  include/linux/property.h |   9 ++++
>> >  2 files changed, 131 insertions(+)
>> >
>> > diff --git a/drivers/base/property.c b/drivers/base/property.c
>> > index c0011cf..cf602c3 100644
>> > --- a/drivers/base/property.c
>> > +++ b/drivers/base/property.c
>> > @@ -15,6 +15,7 @@
>> >  #include <linux/kernel.h>
>> >  #include <linux/of.h>
>> >  #include <linux/of_address.h>
>> > +#include <linux/of_graph.h>
>> >  #include <linux/property.h>
>> >  #include <linux/etherdevice.h>
>> >  #include <linux/phy.h>
>> > @@ -1111,3 +1112,124 @@ void *device_get_mac_address(struct device *dev, char *addr, int alen)
>> >         return device_get_mac_addr(dev, "address", addr, alen);
>> >  }
>> >  EXPORT_SYMBOL(device_get_mac_address);
>> > +
>> > +/**
>> > + * device_graph_get_next_endpoint - Get next endpoint firmware node
>> > + * @fwnode: Pointer to the parent firmware node
>> > + * @prev: Previous endpoint node or %NULL to get the first
>> > + *
>> > + * Returns an endpoint firmware node pointer or %NULL if no more endpoints
>> > + * are available.
>> > + */
>> > +struct fwnode_handle *
>> > +fwnode_graph_get_next_endpoint(struct fwnode_handle *fwnode,
>> > +                              struct fwnode_handle *prev)
>> > +{
>> > +       struct fwnode_handle *endpoint = NULL;
>> > +
>> > +       if (is_of_node(fwnode)) {
>> > +               struct device_node *node;
>> > +
>> > +               node = of_graph_get_next_endpoint(to_of_node(fwnode),
>> > +                                                 to_of_node(prev));
>> > +
>> > +               if (node)
>> > +                       endpoint = &node->fwnode;
>> > +       } else if (is_acpi_node(fwnode)) {
>> > +               endpoint = acpi_graph_get_next_endpoint(fwnode, prev);
>> > +               if (IS_ERR(endpoint))
>> > +                       endpoint = NULL;
>> > +       }
>>
>> This is an ugly pattern IMO. Why not define an ops struct and set it
>> to OF or ACPI rather than check on every function call with
>> is_{of,acpi}_node()?
>
> That appears to be an established practice in the implementation of the
> device / fwnode property API.

I know. That doesn't mean it is good practice or not in need of
refactoring as fwnode API expands.

> One option could be to choose the relevant ops struct based on fwnode type
> in each function operating on the fwnode.

That helps absolutely nothing.

> Alternatively it could be set at the time when the fwnode field is set. A
> large number of drivers are manipulating their OF nodes, some do that for
> fwnodes as well.

What do you mean by manipulating? A fwnode should be statically
pointing to a DT node and the DT node is static.

> Manually setting the ops struct pointer in those cases
> might not be robust enough: sometimes one could simply forget. Also, adding
> a pointer to struct fwnode_handle would increase the size of the struct
> significantly without much gain.

4 or 8 bytes, really?

>
> The number of functions operating on fwnode_handle is rather limited. I
> wonder if it'd be simply better to keep it as-is.

It was, but you're adding a lot.

>> The of_graph_* functions need some better helpers too, so duplicating
>> them 2 more times is not ideal. Basically, drivers are left to do too
>> much of the walking of nodes themselves.
>
> I have to admit my experience in using them is limited to V4L2, but I have
> to say they've been working pretty well for what they're used for. Actually
> the graph functionality was originally specific for V4L2, that could be the
> reason why the current API is a good fit for V4L2. :-)

I'd guess the problem is V4L2 has common graph code and DRM does not.
I'd also guess we can find common patterns in both that could be
abstracted. And as you noticed, ALSA folks are working on using OF
graph.

> The current use ACPI use case is related to V4L2 as well (I'll post a new
> version in the near future):
>
> <URL:http://www.spinics.net/lists/linux-media/msg106160.html>
>
> Are there any particular pain points that should be addressed?

I think generally we want drivers to avoid walking the port and
endpoint nodes themselves. Rather, have functions like "For my device
node, give me the device node connected via port N, endpoint M."
Essentially, that is of_graph_get_endpoint_by_regs and
of_graph_get_remote_port_parent. The only time drivers really should
have port or endpoint node ptrs is to read properties, so maybe we add
property retrieval functions that take the device node and port and
endpoint numbers.

Really it may be an exercise in just removing some of the functions
which are too low level.

Take of_cal_create_instance() as an example. Here's what it does:

- Find port with reg == inst
- Get port's first endpoint
- Get remote port parent and save sensor_node
- Get the remote endpoint node
- Parse the remote endpoint properties (v4l2_of_parse_endpoint)

The first 3 steps are 40 lines of code and could be just 1 function
call returning node ptr for sensor_node.

v4l2_of_parse_link also open codes stuff that should be in the core.

> I noticed Kunimori Morimoto's patchset adding of_graph_get_remote_endpoint()
> which is just a new convenience function to the current API.

Right, I had similar comments there.

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/15] device property: Add support for remote endpoints

[Sakari Ailus]

Hi Rob,

On Thu, Feb 02, 2017 at 11:19:08AM -0600, Rob Herring wrote:
> On Tue, Jan 31, 2017 at 3:58 AM, Sakari Ailus <sakari.ailus@iki.fi> wrote:
> > Hi Rob,
> >
> > Thank you for the review.
> >
> > On Fri, Jan 27, 2017 at 03:45:04PM -0600, Rob Herring wrote:
> >> On Fri, Jan 27, 2017 at 10:03 AM, Sakari Ailus
> >> <sakari.ailus@linux.intel.com> wrote:
> >> > From: Mika Westerberg <mika.westerberg@linux.intel.com>
> >> >
> >> > This follows DT implementation of of_graph_* APIs but we call them
> >> > fwnode_graph_* instead. For DT nodes the existing of_graph_* implementation
> >> > will be used. For ACPI we use the new ACPI graph implementation instead.
> >> >
> >> > This commit includes code from Sakari Ailus.
> >>
> >> Then it should have your S-o-b. Actually, either way it should have it.
> >
> > I'll add that.
> >
> >>
> >> Whether or not copying DT graphs is a good idea or not, I'll let
> >> someone else chime in on that...
> >>
> >> > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> >> > ---
> >> >  drivers/base/property.c  | 122 +++++++++++++++++++++++++++++++++++++++++++++++
> >> >  include/linux/property.h |   9 ++++
> >> >  2 files changed, 131 insertions(+)
> >> >
> >> > diff --git a/drivers/base/property.c b/drivers/base/property.c
> >> > index c0011cf..cf602c3 100644
> >> > --- a/drivers/base/property.c
> >> > +++ b/drivers/base/property.c
> >> > @@ -15,6 +15,7 @@
> >> >  #include <linux/kernel.h>
> >> >  #include <linux/of.h>
> >> >  #include <linux/of_address.h>
> >> > +#include <linux/of_graph.h>
> >> >  #include <linux/property.h>
> >> >  #include <linux/etherdevice.h>
> >> >  #include <linux/phy.h>
> >> > @@ -1111,3 +1112,124 @@ void *device_get_mac_address(struct device *dev, char *addr, int alen)
> >> >         return device_get_mac_addr(dev, "address", addr, alen);
> >> >  }
> >> >  EXPORT_SYMBOL(device_get_mac_address);
> >> > +
> >> > +/**
> >> > + * device_graph_get_next_endpoint - Get next endpoint firmware node
> >> > + * @fwnode: Pointer to the parent firmware node
> >> > + * @prev: Previous endpoint node or %NULL to get the first
> >> > + *
> >> > + * Returns an endpoint firmware node pointer or %NULL if no more endpoints
> >> > + * are available.
> >> > + */
> >> > +struct fwnode_handle *
> >> > +fwnode_graph_get_next_endpoint(struct fwnode_handle *fwnode,
> >> > +                              struct fwnode_handle *prev)
> >> > +{
> >> > +       struct fwnode_handle *endpoint = NULL;
> >> > +
> >> > +       if (is_of_node(fwnode)) {
> >> > +               struct device_node *node;
> >> > +
> >> > +               node = of_graph_get_next_endpoint(to_of_node(fwnode),
> >> > +                                                 to_of_node(prev));
> >> > +
> >> > +               if (node)
> >> > +                       endpoint = &node->fwnode;
> >> > +       } else if (is_acpi_node(fwnode)) {
> >> > +               endpoint = acpi_graph_get_next_endpoint(fwnode, prev);
> >> > +               if (IS_ERR(endpoint))
> >> > +                       endpoint = NULL;
> >> > +       }
> >>
> >> This is an ugly pattern IMO. Why not define an ops struct and set it
> >> to OF or ACPI rather than check on every function call with
> >> is_{of,acpi}_node()?
> >
> > That appears to be an established practice in the implementation of the
> > device / fwnode property API.
> 
> I know. That doesn't mean it is good practice or not in need of
> refactoring as fwnode API expands.
> 
> > One option could be to choose the relevant ops struct based on fwnode type
> > in each function operating on the fwnode.
> 
> That helps absolutely nothing.

You could add a bunch of macros to help with that, and wrap the actual
functions so that you'd find the ops using the macro. It'd be less pretty
than having an ops pointer in the struct, I agree.

> 
> > Alternatively it could be set at the time when the fwnode field is set. A
> > large number of drivers are manipulating their OF nodes, some do that for
> > fwnodes as well.
> 
> What do you mean by manipulating? A fwnode should be statically
> pointing to a DT node and the DT node is static.

I should have phrased that differently. The OF node (or fwnode_handle)
pointers are stored locally in driver specific structs. Now that I look at
that more closely, the only problems appears to be that most forget
of_node_get() but that's unrelated to this.

> 
> > Manually setting the ops struct pointer in those cases
> > might not be robust enough: sometimes one could simply forget. Also, adding
> > a pointer to struct fwnode_handle would increase the size of the struct
> > significantly without much gain.
> 
> 4 or 8 bytes, really?

Per node. Going forward, 8 is getting more and more common.

> 
> >
> > The number of functions operating on fwnode_handle is rather limited. I
> > wonder if it'd be simply better to keep it as-is.
> 
> It was, but you're adding a lot.

With the patchset, there are 14 occurrences of is_of_node() and 12
occurrences of is_acpi_node(). Before the numbers were 6 and 4,
respectively.

I think it'd be good to have a third opinion on that.

I presume you'd prefer these changes done before this set?

> 
> >> The of_graph_* functions need some better helpers too, so duplicating
> >> them 2 more times is not ideal. Basically, drivers are left to do too
> >> much of the walking of nodes themselves.
> >
> > I have to admit my experience in using them is limited to V4L2, but I have
> > to say they've been working pretty well for what they're used for. Actually
> > the graph functionality was originally specific for V4L2, that could be the
> > reason why the current API is a good fit for V4L2. :-)
> 
> I'd guess the problem is V4L2 has common graph code and DRM does not.

The graph code is generic, what V4L2 has concerning OF is common parsing of
the properties. That's the current state at least.

> I'd also guess we can find common patterns in both that could be
> abstracted. And as you noticed, ALSA folks are working on using OF
> graph.

Please see drivers/media/platform/omap3isp/isp.c, and isp_of_parse_nodes()
there. This is where the omap3isp driver parses information originating from
DT. That's a pretty good example, most other V4L2 drivers that work with OF
nodes do something similar.

isp_of_parse_nodes() function could certainly be improved, but the
improvement would be related to the interface of V4L2 async framework.
That's not really related to DT or graphs.

The V4L2 async framework is already aware of DT but it just makes it
possible to match devices using OF nodes. It could well facilitate the
process a lot more than it does now.

I wonder if something similar could be done for DRM.

Cc Guennadi and Laurent.

> 
> > The current use ACPI use case is related to V4L2 as well (I'll post a new
> > version in the near future):
> >
> > <URL:http://www.spinics.net/lists/linux-media/msg106160.html>
> >
> > Are there any particular pain points that should be addressed?
> 
> I think generally we want drivers to avoid walking the port and
> endpoint nodes themselves. Rather, have functions like "For my device
> node, give me the device node connected via port N, endpoint M."

I'd like to question whether that really helps: you need to iterate over all
the ports and all the endpoints in them, instead of being simply given all
the endpoints that have connected devices, one by one. At least when it
comes to V4L2, I prefer the latter. As noted, I believe the enumerating
work could (and should) be moved to the V4L2 async framework.

It does show the firmware concepts to the driver but is there any harm from
doing so?

> Essentially, that is of_graph_get_endpoint_by_regs and
> of_graph_get_remote_port_parent. The only time drivers really should
> have port or endpoint node ptrs is to read properties, so maybe we add
> property retrieval functions that take the device node and port and
> endpoint numbers.
> 
> Really it may be an exercise in just removing some of the functions
> which are too low level.
> 
> Take of_cal_create_instance() as an example. Here's what it does:
> 
> - Find port with reg == inst
> - Get port's first endpoint
> - Get remote port parent and save sensor_node
> - Get the remote endpoint node
> - Parse the remote endpoint properties (v4l2_of_parse_endpoint)
> 
> The first 3 steps are 40 lines of code and could be just 1 function
> call returning node ptr for sensor_node.
> 
> v4l2_of_parse_link also open codes stuff that should be in the core.
> 
> > I noticed Kunimori Morimoto's patchset adding of_graph_get_remote_endpoint()
> > which is just a new convenience function to the current API.
> 
> Right, I had similar comments there.

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi	XMPP: sailus@retiisi.org.uk

[PATCH 09/15] driver core: Arrange headers alphabetically

[Sakari Ailus]

Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
---
 drivers/base/core.c | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/drivers/base/core.c b/drivers/base/core.c
index 020ea7f..bd87807 100644
--- a/drivers/base/core.c
+++ b/drivers/base/core.c
@@ -13,19 +13,19 @@
 #include <linux/device.h>
 #include <linux/err.h>
 #include <linux/fwnode.h>
+#include <linux/genhd.h>
 #include <linux/init.h>
-#include <linux/module.h>
-#include <linux/slab.h>
-#include <linux/string.h>
+#include <linux/kallsyms.h>
 #include <linux/kdev_t.h>
+#include <linux/module.h>
+#include <linux/mutex.h>
+#include <linux/netdevice.h>
 #include <linux/notifier.h>
 #include <linux/of.h>
 #include <linux/of_device.h>
-#include <linux/genhd.h>
-#include <linux/kallsyms.h>
-#include <linux/mutex.h>
 #include <linux/pm_runtime.h>
-#include <linux/netdevice.h>
+#include <linux/slab.h>
+#include <linux/string.h>
 #include <linux/sysfs.h>
 
 #include "base.h"
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 12/15] device property: Add support for fwnode endpoints

[Sakari Ailus]

Similar to OF endpoints, endpoint type nodes can be also supported on
ACPI. In order to make it possible for drivers to ignore the matter,
add a type for fwnode_endpoint and a function to parse them.

Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
---
 drivers/base/property.c  | 33 +++++++++++++++++++++++++++++++++
 include/linux/fwnode.h   |  6 ++++++
 include/linux/property.h |  3 +++
 3 files changed, 42 insertions(+)

diff --git a/drivers/base/property.c b/drivers/base/property.c
index 51c0881..21b103f 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -1244,3 +1244,36 @@ fwnode_graph_get_remote_endpoint(struct fwnode_handle *fwnode)
 	return endpoint;
 }
 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_endpoint);
+
+/*
+ * fwnode_graph_parse_endpoint() - parse common endpoint node properties
+ * @node: pointer to endpoint device_node
+ * @endpoint: pointer to the fwnode endpoint data structure
+ *
+ * The caller should hold a reference to @node.
+ */
+int fwnode_graph_parse_endpoint(struct fwnode_handle *fwnode,
+				struct fwnode_endpoint *endpoint)
+{
+	struct fwnode_handle *port_fwnode = fwnode_get_parent(fwnode);
+
+	memset(endpoint, 0, sizeof(*endpoint));
+
+	endpoint->local_fwnode = fwnode;
+	/*
+	 * It doesn't matter whether the two calls below succeed.
+	 * If they don't then the default value 0 is used.
+	 */
+	if (is_acpi_node(port_fwnode)) {
+		fwnode_property_read_u32(port_fwnode, "port", &endpoint->port);
+		fwnode_property_read_u32(fwnode, "endpoint", &endpoint->id);
+	} else {
+		fwnode_property_read_u32(port_fwnode, "reg", &endpoint->port);
+		fwnode_property_read_u32(fwnode, "reg", &endpoint->id);
+	}
+
+	fwnode_handle_put(port_fwnode);
+
+	return 0;
+}
+EXPORT_SYMBOL(fwnode_graph_parse_endpoint);
diff --git a/include/linux/fwnode.h b/include/linux/fwnode.h
index 8bd28ce..cb60f29 100644
--- a/include/linux/fwnode.h
+++ b/include/linux/fwnode.h
@@ -27,4 +27,10 @@ struct fwnode_handle {
 	struct fwnode_handle *secondary;
 };
 
+struct fwnode_endpoint {
+	unsigned int port;
+	unsigned int id;
+	const struct fwnode_handle *local_fwnode;
+};
+
 #endif
diff --git a/include/linux/property.h b/include/linux/property.h
index 294418d..eb7ba73 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -283,4 +283,7 @@ static inline struct fwnode_handle *device_fwnode_handle(struct device *dev)
 		return dev->fwnode;
 }
 
+int fwnode_graph_parse_endpoint(struct fwnode_handle *fwnode,
+				struct fwnode_endpoint *endpoint);
+
 #endif /* _LINUX_PROPERTY_H_ */
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 14/15] device property: Add fwnode_get_next_parent()

[Sakari Ailus]

In order to differentiate the functionality between dropping a reference
to the node (or not) for the benefit of OF, introduce
fwnode_get_next_parent().

Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
---
 drivers/base/property.c  | 29 +++++++++++++++++++++++++++++
 include/linux/property.h |  1 +
 2 files changed, 30 insertions(+)

diff --git a/drivers/base/property.c b/drivers/base/property.c
index 21b103f..d31a31f 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -868,6 +868,35 @@ int device_add_properties(struct device *dev, struct property_entry *properties)
 EXPORT_SYMBOL_GPL(device_add_properties);
 
 /**
+ * fwnode_get_next_parent - Iterate to the node's parent
+ * @fwnode: Firmware whose parent is retrieved
+ *
+ * This is like fwnode_get_parent() except that it drops the refcount
+ * on the passed node, making it suitable for iterating through a
+ * node's parents.
+ *
+ * Returns a node pointer with refcount incremented, use
+ * fwnode_handle_node() on it when done.
+ */
+struct fwnode_handle *fwnode_get_next_parent(struct fwnode_handle *fwnode)
+{
+	struct fwnode_handle *parent = NULL;
+
+	if (is_of_node(fwnode)) {
+		struct device_node *node;
+
+		node = of_get_next_parent(to_of_node(fwnode));
+		if (node)
+			parent = &node->fwnode;
+	} else if (is_acpi_node(fwnode)) {
+		parent = acpi_node_get_parent(fwnode);
+	}
+
+	return parent;
+}
+EXPORT_SYMBOL_GPL(fwnode_get_next_parent);
+
+/**
  * fwnode_get_parent - Return parent firwmare node
  * @fwnode: Firmware whose parent is retrieved
  *
diff --git a/include/linux/property.h b/include/linux/property.h
index eb7ba73..760df98 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -73,6 +73,7 @@ int fwnode_property_match_string(struct fwnode_handle *fwnode,
 				 const char *propname, const char *string);
 
 struct fwnode_handle *fwnode_get_parent(struct fwnode_handle *fwnode);
+struct fwnode_handle *fwnode_get_next_parent(struct fwnode_handle *fwnode);
 struct fwnode_handle *fwnode_get_next_child_node(struct fwnode_handle *fwnode,
 						 struct fwnode_handle *child);
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 15/15] ACPI / DSD: Document references, ports and endpoints

[Sakari Ailus]

Document the use of references into the hierarchical data extension
structure, as well as the use of port and endpoint concepts that are very
similar to those in Devicetree.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 Documentation/acpi/dsd/graph.txt | 166 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 Documentation/acpi/dsd/graph.txt

diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt
new file mode 100644
index 0000000..928cc07
--- /dev/null
+++ b/Documentation/acpi/dsd/graph.txt
@@ -0,0 +1,166 @@
+Graphs
+
+
+_DSD
+----
+
+_DSD (Device Specific Data) [7] 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
+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
+defined by the property extension. The two extensions together provide
+a tree-like structure with zero or more properties (key-value pairs)
+in each node of the tree.
+
+The data structure may be accessed at runtime by using the device_*
+and fwnode_* functions defined in include/linux/fwnode.h .
+
+Fwnode represents a generic firmware node object. It is independent on
+the firmware type. In ACPI, fwnodes are _DSD hierarchical data
+extensions objects. A device's _DSD object is represented by an
+fwnode.
+
+The data structure may be referenced to elsewhere in the ACPI tables
+by using a hard reference to the device itself and an index to the
+hierarchical data extension array on each depth.
+
+
+Ports and endpoints
+-------------------
+
+The port and endpoint concepts are very similar to those in Devicetree
+[3]. The port represent represent interface in a device, and an
+endpoint represents a connection to that interface.
+
+All port nodes are located under the device's "_DSD" node in
+hierarchical data extension tree. The first package list entry of the
+hierarchical data extension related to each port node must begin with
+"port" string and must be followed by the number of the port.
+
+Further on, endpoints are located under the individual port nodes. The
+first hierarchical data extension package list entry of the endpoint
+nodes must begin with "endpoint" and must be followed by the number
+of the endpoint.
+
+Each port node contains a property extension key "port", the value of
+which is the number of the port node. Similarly, each endpoint node
+must contain "endpoint" property which is the number of the endpoint
+node.
+
+The endpoint reference uses property extension with "remote-endpoint"
+property name followed by a reference in the same package. Such
+references consist of the name of the device, index of the port node
+and finally the index of the endpoint node. These indices are indeed
+indices to the referred port and endpoint arrays, not the numbers of
+the ports or the endpoints that are related to numbering of actual
+hardware interfaces in the respective hardware. Individual references
+thus appear as:
+
+    Package() { device, port_node_index, endpoint_node_index }
+
+The references to endpoints must be always done both ways, to the
+remote endpoint and back from the referred remote endpoint node.
+
+A simple example of this is show below:
+
+    Scope (\_SB.PCI0.I2C2)
+    {
+	Device (CAM0)
+	{
+	    Name (_DSD, Package () {
+		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+		Package () {
+		    Package () { "compatible", Package () { "nokia,smia" } },
+		},
+		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+		Package () {
+		    Package () { "port0", "PRT0" },
+		}
+	    })
+	    Name (PRT0, Package() {
+		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+		Package () {
+		    Package () { "port", 0 },
+		},
+		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+		Package () {
+		    Package () { "endpoint0", "EP0" },
+		}
+	    })
+	    Name (EP0, Package() {
+		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+		Package () {
+		    Package () { "endpoint", 0 },
+		    Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, 0, 0 } },
+		}
+	    })
+	}
+    }
+
+    Scope (\_SB.PCI0)
+    {
+	Device (ISP)
+	{
+	    Name (_DSD, Package () {
+		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+		Package () {
+		    Package () { "port4", "PRT4" },
+		}
+	    })
+
+	    Name (PRT4, Package() {
+		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+		Package () {
+		    Package () { "port", 4 }, /* CSI-2 port number */
+		},
+		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+		Package () {
+		    Package () { "endpoint0", "EP0" },
+		}
+	    })
+
+	    Name (EP0, Package() {
+		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+		Package () {
+		    Package () { "endpoint", 0 },
+		    Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, 0, 0 } },
+		}
+	    })
+	}
+    }
+
+Here, the port 0 of the "CAM0" device is connected to the port 4 of
+the "ISP" device. Note that the port index in the reference is still
+0, as it refers to an entry in the table and not the port node number
+itself.
+
+
+References
+----------
+
+[1] _DSD (Device Specific Data) Implementation Guide.
+    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
+    referenced 2016-10-03.
+
+[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
+
+[3] Documentation/devicetree/bindings/graph.txt
+
+[4] Device Properties UUID For _DSD.
+    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+    referenced 2016-10-04.
+
+[5] Hierarchical Data Extension UUID For _DSD.
+    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf>,
+    referenced 2016-10-04.
+
+[6] Advanced Configuration and Power Interface Specification.
+    <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
+    referenced 2016-10-04.
+
+[7] _DSD Device Properties Usage Rules.
+    Documentation/acpi/DSD-properties-rules.txt
-- 
2.7.4