Adding new devices to a device tree¶
ACPI exposes a platform-independent interface for operating systems to perform power management and other platform-level functions. Some operating systems also use ACPI to enumerate devices that are not immediately discoverable, such as those behind I2C or SPI buses (in contrast to PCI). This document discusses the way that coreboot uses the concept of a “device tree” to generate ACPI tables for usage by the operating system.
Devicetree and overridetree (if applicable)¶
For mainboards that are organized around a “reference board” or “baseboard”
hatch for examples), there is
typically a devicetree.cb file that all boards share, and any differences for a
specific board (“variant”) are captured in the overridetree.cb file. Any
settings changed in the overridetree take precedence over those in the main
devicetree. Note, not all mainboards will have the devicetree/overridetree
distinction, and may only have a devicetree.cb file. Or you can always just
write the ASL (ACPI Source Language) code yourself.
Naming and 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
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
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
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
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.
Platform independent device drivers are hooked up via entries in a devicetree. See Driver Devicetree Entries for more info.
- All fields that are left unspecified in the devicetree are initialized to zero.