1# Adding new devices to a device tree 2 3## Introduction 4 5ACPI exposes a platform-independent interface for operating systems to perform 6power management and other platform-level functions. Some operating systems 7also use ACPI to enumerate devices that are not immediately discoverable, such 8as those behind I2C or SPI buses (in contrast to PCI). This document discusses 9the way that coreboot uses the concept of a "device tree" to generate ACPI 10tables for usage by the operating system. 11 12## Devicetree and overridetree (if applicable) 13 14For mainboards that are organized around a "reference board" or "baseboard" 15model (see ``src/mainboard/google/octopus`` or ``hatch`` for examples), there is 16typically a devicetree.cb file that all boards share, and any differences for a 17specific board ("variant") are captured in the overridetree.cb file. Any 18settings changed in the overridetree take precedence over those in the main 19devicetree. Note, not all mainboards will have the devicetree/overridetree 20distinction, and may only have a devicetree.cb file. Or you can always just 21write the ASL (ACPI Source Language) code yourself. 22 23### Naming and referencing devices 24 25When declaring a device, it can optionally be given an alias that can be 26referred to elsewhere. This is particularly useful to declare a device in one 27device tree while allowing its configuration to be more easily changed in an 28overlay. For instance, the AMD Picasso SoC definition 29(`soc/amd/picasso/chipset.cb`) declares an IOMMU on a PCI bus that is disabled 30by default: 31 32``` 33chip soc/amd/picasso 34 device domain 0 on 35 ... 36 device pci 00.2 alias iommu off end 37 ... 38 end 39end 40``` 41 42A device based on this SoC can override the configuration for the IOMMU without 43duplicating addresses, as in 44`mainboard/google/zork/variants/baseboard/devicetree_trembyle.cb`: 45 46``` 47chip soc/amd/picasso 48 device domain 0 49 ... 50 device ref iommu on end 51 ... 52 end 53end 54``` 55 56In this example the override simply enables the IOMMU, but it could also 57set additional properties (or even add child devices) inside the IOMMU `device` 58block. 59 60--- 61 62It is important to note that devices that use `device ref` syntax to override 63previous definitions of a device by alias must be placed at **exactly the same 64location in the device tree** as the original declaration. If not, this will 65actually create another device rather than overriding the properties of the 66existing one. For instance, if the above snippet from `devicetree_trembyle.cb` 67were written as follows: 68 69``` 70chip soc/amd/picasso 71 # NOTE: not inside domain 0! 72 device ref iommu on end 73end 74``` 75 76Then this would leave the SoC's IOMMU disabled, and instead create a new device 77with no properties as a direct child of the SoC. 78 79## Device drivers 80 81Platform independent device drivers are hooked up via entries in a devicetree. 82See [Driver Devicetree Entries](../drivers/dt_entries.md) for more info. 83 84## Notes 85 86 - **All fields that are left unspecified in the devicetree are initialized to 87 zero.** 88