Tim Wawrzynczak has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/35080 )
Change subject: Documentation/acpi: Add new document on adding ACPI devices to devicetree ......................................................................
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**