Peter Marheine has uploaded this change for review.
documentation: add a section on devicetree refs
There is no existing documentation on how `device ref` and aliases work
in the devicetree, and the behavior around devices not being in the same
location is difficult to discern as well as somewhat unexpected.
Change-Id: I4b30f7d531cfc3453d6523a76084f1969125b4bf
Signed-off-by: Peter Marheine <pmarheine@chromium.org>
---
M Documentation/acpi/devicetree.md
1 file changed, 56 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/54/57354/1
diff --git a/Documentation/acpi/devicetree.md b/Documentation/acpi/devicetree.md
index c184fa0..738de26 100644
--- a/Documentation/acpi/devicetree.md
+++ b/Documentation/acpi/devicetree.md
@@ -20,6 +20,62 @@
distinction, and may only have a devicetree.cb file. Or you can always just
write the ASL (ACPI Source Language) code yourself.
+### Naming & referencing devices
+
+When declaring a device, it can optionally be given an alias that can be
+referred to elsewhere. This is particularly useful to declare a device in one
+device tree while allowing its configuration to be more easily changed in an
+overlay. For instance, the AMD Picasso SoC definition
+(`soc/amd/picasso/chipset.cb`) declares an IOMMU on a PCI bus that is disabled
+by default:
+
+```
+chip soc/amd/picasso
+ device domain 0 on
+ ...
+ device pci 00.2 alias iommu off end
+ ...
+ end
+end
+```
+
+A device based on this SoC can override the configuration for the IOMMU without
+duplicating addresses, as in
+`mainboard/google/zork/variants/baseboard/devicetree_trembyle.cb`:
+
+```
+chip soc/amd/picasso
+ device domain 0
+ ...
+ device ref iommu on end
+ ...
+ end
+end
+```
+
+In this example the override simply enables the IOMMU, but it could also
+set additional properties (or even add child devices) inside the IOMMU `device`
+block.
+
+---
+
+It is important to note that devices that use `device ref` syntax to override
+previous definitions of a device by alias must be placed at **exactly the same
+location in the device tree** as the original declaration. If not, this will
+actually create another device rather than overriding the properties of the
+existing one. For instance, if the above snippet from `devicetree_trembyle.cb`
+were written as follows:
+
+```
+chip soc/amd/picasso
+ # NOTE: not inside domain 0!
+ device ref iommu on end
+end
+```
+
+Then this would leave the SoC's IOMMU disabled, and instead create a new device
+with no properties as a direct child of the SoC.
+
## Device drivers
Let's take a look at an example entry from
To view, visit change 57354. To unsubscribe, or for help writing mail filters, visit settings.