Tim Wawrzynczak has uploaded this change for review.
Documentation/acpi: Add new document on adding ACPI devices to devicetree
Change-Id: I9636e65f7d2499b06b1d71e5f8d09c528b850027
Signed-off-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
---
A Documentation/acpi/devicetree.md
1 file changed, 191 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/80/35080/1
diff --git a/Documentation/acpi/devicetree.md b/Documentation/acpi/devicetree.md
new file mode 100644
index 0000000..fdc36f1
--- /dev/null
+++ b/Documentation/acpi/devicetree.md
@@ -0,0 +1,191 @@
+# 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 busses (in contrast to
+PCI). This document discusses the way that coreboot uses the concept
+of a "device tree" to expose devices to the OS.
+
+## 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 that not all mainboards will have the devicetree/overridetree distinction,
+and may only have a devicetree.cb file. Or you can always just write the AML code
+yourself.
+
+## Device drivers
+
+Let's take a look at an example entry from _src/mainboard/google/hatch/variant/hatch/overridetree.cb_:
+
+```
+device pci 15.0 on
+ chip drivers/i2c/generic
+ register "hid" = ""ELAN0000""
+ register "desc" = ""ELAN Touchpad""
+ register "irq" = "ACPI_IRQ_WAKE_EDGE_LOW(GPP_A21_IRQ)"
+ register "wake" = "GPE0_DW0_21"
+ device i2c 15 on end
+ end
+end # I2C #0
+```
+
+When this entry is processed during ramstage, it will create a device in the
+ACPI SSDT table (all devices in devicetrees end up in the SSDT table). The
+ACPI generation routines in coreboot actually generate the raw bytecode that
+represents the device's structure, but looking at AML code is easier to
+understand; see below for what the disassembled bytecode looks like:
+
+```
+Scope (\_SB.PCI0.I2C0)
+{
+ Device (D015)
+ {
+ Name (_HID, "ELAN0000") // _HID: Hardware ID
+ Name (_UID, Zero) // _UID: Unique ID
+ Name (_DDN, "ELAN Touchpad") // _DDN: DOS Device Name
+ Method (_STA, 0, NotSerialized) // _STA: Status
+ {
+ Return (0x0F)
+ }
+ Name (_CRS, ResourceTemplate () // _CRS: Current Resource Settings
+ {
+ I2cSerialBusV2 (0x0015, ControllerInitiated, 0x00061A80,
+ AddressingMode7Bit, "\\_SB.PCI0.I2C0",
+ 0x00, ResourceConsumer, , Exclusive, )
+ Interrupt (ResourceConsumer, Edge, ActiveLow, ExclusiveAndWake, ,, )
+ {
+ 0x0000002D,
+ }
+ })
+ Name (_S0W, 0x04) // _S0W: S0 Device Wake State
+ Name (_PRW, Package (0x02) // _PRW: Power Resources for Wake
+ {
+ 0x15,
+ 0x03
+ })
+ }
+}
+```
+
+You can see it generates _HID, _UID, _DDN, _STA, _CRS, _S0W, and _PRW
+names/methods in the Device's scope. Let's take a look at how the devicetree
+language corresponds to the "generated AML".
+
+First, note this:
+
+```
+ chip drivers/i2c/generic
+```
+
+This means that the device driver we're using has a corresponding structure,
+located at _src/drivers/i2c/generic/chip.h_, named **struct drivers_i2c_generic_config**
+and it contains many properties you can specify to be included in the ACPI
+table.
+
+## Diving into the above example:
+
+### hid
+
+```
+ register "hid" = ""ELAN0000""
+```
+
+This corresponds to **const char *hid** in the struct.
+In the ACPI AML, it translates to:
+
+```
+ Name (_HID, "ELAN0000") // _HID: Hardware ID
+```
+
+under the Device.
+
+### desc
+
+```
+ register "desc" = ""ELAN Touchpad""
+```
+
+corresponds to **const char *desc** and in AML:
+
+```
+ Name (_DDN, "ELAN Touchpad") // _DDN: DOS Device Name
+```
+
+### irq
+
+It also adds the interrupt, which comes from:
+
+```
+ register "irq" = "ACPI_IRQ_WAKE_EDGE_LOW(GPP_A21_IRQ)"
+```
+
+(Note that the ACPI_IRQ_WAKE_EDGE_LOW macro informs the platform that the GPIO
+will be routed through SCI (ACPI's System Control Interrupt) for use as a wake
+source).
+
+### wake
+
+The last register is:
+
+```
+ register "wake" = "GPE0_DW0_21"
+```
+
+which indicates that the method of waking the system using the touchpad will
+be through a GPE, #21 associated with DW0 (which is setup in devicetree.cb
+from this example).
+
+The last bit of the definition of that device includes:
+
+```
+ device i2c 15 on end
+```
+
+which means it's an I2C device, with 7-bit address 0x15, and the device
+is "on", meaning it will be exposed in the ACPI table.
+
+### Other auto-generated names
+
+### _S0W
+ _S0W indicates the deepest S0 sleep state that this device can wake itself
+from, which in this case is 4, representing _D3cold_.
+
+### _PRW
+ _PRW indicates the power resources and events required for wake. There are no
+dependent power resources, but the GPE (GPE0_DW0_21) is mentioned here (0x15),
+as well as the deepest sleep state that supports waking the system (3), which
+is S3.
+
+### _STA
+The _STA method is generated automatically, and its values, 0xF, indicates the
+following:
+
+ Bit [0] – Set if the device is present.
+ Bit [1] – Set if the device is enabled and decoding its resources.
+ Bit [2] – Set if the device should be shown in the UI.
+ Bit [3] – Set if the device is functioning properly (cleared if device failed its diagnostics).
+
+### _CRS
+The _CRS (current resources) method is generated automatically, as the driver
+knows it is an I2C controller, and so specifies how to configure the controller
+for proper operation with the touchpad.
+
+```
+Name (_CRS, ResourceTemplate () // _CRS: Current Resource Settings
+{
+ I2cSerialBusV2 (0x0015, ControllerInitiated, 0x00061A80,
+ AddressingMode7Bit, "\\_SB.PCI0.I2C0",
+ 0x00, ResourceConsumer, , Exclusive, )
+```
+
+## Notes
+
+ - **All fields that are left unspecified in the devicetree are initialized to zero.**
+ - **All devices in devicetrees end up in the SSDT table, and are generated in coreboot's ramstage**
To view, visit change 35080. To unsubscribe, or for help writing mail filters, visit settings.