8e013cd8c8
Move the devicetree driver example into a separate page under the drivers category, and link to it from both the devicetree page and the drivers index page. This makes more sense from a grouping perspective and makes the info easier to find. Change-Id: Ic3ca80b93a0020737c7ccb5313a0877172022e1a Signed-off-by: Matt DeVillier <matt.devillier@amd.corp-partner.google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/67762 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
88 lines
2.9 KiB
Markdown
88 lines
2.9 KiB
Markdown
# Adding new devices to a device tree
|
|
|
|
## Introduction
|
|
|
|
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"
|
|
model (see ``src/mainboard/google/octopus`` or ``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
|
|
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
|
|
|
|
Platform independent device drivers are hooked up via entries in a devicetree.
|
|
See [Driver Devicetree Entries](drivers/dt_entries.md) for more info.
|
|
|
|
## Notes
|
|
|
|
- **All fields that are left unspecified in the devicetree are initialized to
|
|
zero.**
|