Documentation/getting_started/devicetree.md

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