coreboot-gerrit April 2025

coreboot-gerrit@coreboot.org

1 participants
3140 discussions

[L] Change in coreboot[main]: Documentation: Add Ramstage Bootstates
by Martin L Roth (Code Review) 06 Apr '25

06 Apr '25

Attention is currently required from: Martin L Roth. Hello build bot (Jenkins), I'd like you to reexamine a change. Please visit https://review.coreboot.org/c/coreboot/+/87189?usp=email to look at the new patch set (#3). The following approvals got outdated and were removed: Verified+1 by build bot (Jenkins) Change subject: Documentation: Add Ramstage Bootstates ...................................................................... Documentation: Add Ramstage Bootstates Change-Id: I18801967be50e2f318b4404d08c171ffa7e92bbc Signed-off-by: Martin Roth <gaumless(a)gmail.com> --- M Documentation/lib/index.md A Documentation/lib/ramstage_bootstates.md 2 files changed, 515 insertions(+), 0 deletions(-) git pull ssh://review.coreboot.org:29418/coreboot refs/changes/89/87189/3 -- To view, visit https://review.coreboot.org/c/coreboot/+/87189?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: newpatchset Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: I18801967be50e2f318b4404d08c171ffa7e92bbc Gerrit-Change-Number: 87189 Gerrit-PatchSet: 3 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Martin L Roth <gaumless(a)gmail.com>

1 0

[L] Change in coreboot[main]: Documentation: Add Timers, Stopwatch, and Delays
by Martin L Roth (Code Review) 06 Apr '25

06 Apr '25

Attention is currently required from: Martin L Roth. Hello build bot (Jenkins), I'd like you to reexamine a change. Please visit https://review.coreboot.org/c/coreboot/+/87187?usp=email to look at the new patch set (#4). The following approvals got outdated and were removed: Verified+1 by build bot (Jenkins) Change subject: Documentation: Add Timers, Stopwatch, and Delays ...................................................................... Documentation: Add Timers, Stopwatch, and Delays Change-Id: I3b58817c1ed06e6d7d5d5668b0e38ec8cfedf122 Signed-off-by: Martin Roth <gaumless(a)gmail.com> --- M Documentation/lib/index.md A Documentation/lib/stopwatch.md 2 files changed, 879 insertions(+), 0 deletions(-) git pull ssh://review.coreboot.org:29418/coreboot refs/changes/87/87187/4 -- To view, visit https://review.coreboot.org/c/coreboot/+/87187?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: newpatchset Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: I3b58817c1ed06e6d7d5d5668b0e38ec8cfedf122 Gerrit-Change-Number: 87187 Gerrit-PatchSet: 4 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Martin L Roth <gaumless(a)gmail.com>

1 0

[L] Change in coreboot[main]: Documentation/lib: Update Timestamp documentation
by Martin L Roth (Code Review) 06 Apr '25

06 Apr '25

Attention is currently required from: Nicholas Chin. Martin L Roth has posted comments on this change by Martin L Roth. ( https://review.coreboot.org/c/coreboot/+/87186?usp=email ) Change subject: Documentation/lib: Update Timestamp documentation ...................................................................... Patch Set 3: (1 comment) Patchset: PS3: > Hrm - it looks like we already had timestamp documentation in the lib directory. […] Done -- To view, visit https://review.coreboot.org/c/coreboot/+/87186?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: comment Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: I6e4cc244edf6cc860cc66165173f134a30a81589 Gerrit-Change-Number: 87186 Gerrit-PatchSet: 3 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Nicholas Chin <nic.c3.14(a)gmail.com> Gerrit-Attention: Nicholas Chin <nic.c3.14(a)gmail.com> Gerrit-Comment-Date: Sun, 06 Apr 2025 21:20:33 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Comment-In-Reply-To: Martin L Roth <gaumless(a)gmail.com>

1 0

[L] Change in coreboot[main]: Documentation/lib: Update Timestamp documentation
by Martin L Roth (Code Review) 06 Apr '25

06 Apr '25

Attention is currently required from: Nicholas Chin. Hello build bot (Jenkins), I'd like you to reexamine a change. Please visit https://review.coreboot.org/c/coreboot/+/87186?usp=email to look at the new patch set (#4). The following approvals got outdated and were removed: Verified+1 by build bot (Jenkins) Change subject: Documentation/lib: Update Timestamp documentation ...................................................................... Documentation/lib: Update Timestamp documentation - Reformat to 72 characters - Rephrase some items - Add additional code examples - Add additional sections Change-Id: I6e4cc244edf6cc860cc66165173f134a30a81589 Signed-off-by: Martin Roth <gaumless(a)gmail.com> --- M Documentation/lib/timestamp.md 1 file changed, 291 insertions(+), 83 deletions(-) git pull ssh://review.coreboot.org:29418/coreboot refs/changes/86/87186/4 -- To view, visit https://review.coreboot.org/c/coreboot/+/87186?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: newpatchset Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: I6e4cc244edf6cc860cc66165173f134a30a81589 Gerrit-Change-Number: 87186 Gerrit-PatchSet: 4 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Nicholas Chin <nic.c3.14(a)gmail.com> Gerrit-Attention: Nicholas Chin <nic.c3.14(a)gmail.com>

1 0

[XL] Change in coreboot[main]: Documentation: Update acronyms list
by Nicholas Chin (Code Review) 06 Apr '25

06 Apr '25

Attention is currently required from: Martin L Roth. Nicholas Chin has posted comments on this change by Martin L Roth. ( https://review.coreboot.org/c/coreboot/+/87184?usp=email ) Change subject: Documentation: Update acronyms list ...................................................................... Patch Set 2: (5 comments) File Documentation/acronyms.md: https://review.coreboot.org/c/coreboot/+/87184/comment/7d24ca4e_313fc3a1?us… : PS2, Line 662: Meitä - **coreboot Configuration** - The name of coreboot's build : configuration system, derived from Kconfig. First time I've ever heard of this :) https://review.coreboot.org/c/coreboot/+/87184/comment/2acf9637_50d5d58e?us… : PS2, Line 928: 'Friendly' I've also seen 'Fine' https://review.coreboot.org/c/coreboot/+/87184/comment/47be3dff_9f2952cd?us… : PS2, Line 1176: VDDQ Memory/Power Is "Memory/Power" supposed to be a category and not part of the Acronym? ```suggestion * VDDQ - Memory/Power: The supply voltage for the DQ/DQS (data and data ``` https://review.coreboot.org/c/coreboot/+/87184/comment/0e4ef8db_97cfe740?us… : PS2, Line 1224: VREF Memory/Power Same here ```suggestion * VREF - Memory/Power: Reference voltage for the input lines of a chip ``` https://review.coreboot.org/c/coreboot/+/87184/comment/55da3f0e_cc36d984?us… : PS2, Line 1236: VTT Memory/Power Same here ```suggestion * VTT - Memory/Power: **Tracking Termination Voltage** - A voltage ``` -- To view, visit https://review.coreboot.org/c/coreboot/+/87184?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: comment Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: I0d5c76f6cf6118635c0fae217d5d37d39c8403a9 Gerrit-Change-Number: 87184 Gerrit-PatchSet: 2 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Nicholas Chin <nic.c3.14(a)gmail.com> Gerrit-Attention: Martin L Roth <gaumless(a)gmail.com> Gerrit-Comment-Date: Sun, 06 Apr 2025 21:14:49 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No

1 0

[L] Change in coreboot[main]: mb/asus/p8x7x-series: Add p8b75-v variant
by Angel Pons (Code Review) 06 Apr '25

06 Apr '25

Attention is currently required from: Felix Held, Keith Hui. Angel Pons has posted comments on this change by Keith Hui. ( https://review.coreboot.org/c/coreboot/+/85792?usp=email ) Change subject: mb/asus/p8x7x-series: Add p8b75-v variant ...................................................................... Patch Set 3: (1 comment) Commit Message: https://review.coreboot.org/c/coreboot/+/85792/comment/a85219ec_8e1849b1?us… : PS3, Line 21: to use both to build a 16MiB flash space but that's to be confirmed. > Looks like the vendor update is the BIOS/upper 8MiB only and does not include the bottom half with I […] Of note: Asrock B85M Pro4 has 5 MB ME firmware and a 8 MiB flash chip -- To view, visit https://review.coreboot.org/c/coreboot/+/85792?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: comment Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: Ibb14c9efd1fb5b8826a646aae5f3fab9d9c08187 Gerrit-Change-Number: 85792 Gerrit-PatchSet: 3 Gerrit-Owner: Keith Hui <buurin(a)gmail.com> Gerrit-Reviewer: Felix Held <felix-coreboot(a)felixheld.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Angel Pons <th3fanbus(a)gmail.com> Gerrit-Attention: Keith Hui <buurin(a)gmail.com> Gerrit-Attention: Felix Held <felix-coreboot(a)felixheld.de> Gerrit-Comment-Date: Sun, 06 Apr 2025 21:04:53 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Comment-In-Reply-To: Angel Pons <th3fanbus(a)gmail.com> Comment-In-Reply-To: Keith Hui <buurin(a)gmail.com>

1 0

[L] Change in coreboot[main]: Documentation: Add information about the site-local directory
by Nicholas Chin (Code Review) 06 Apr '25

06 Apr '25

1 0

[L] Change in coreboot[main]: Documentation: Add information about the site-local directory
by Nicholas Chin (Code Review) 06 Apr '25

06 Apr '25

Attention is currently required from: Martin L Roth. Nicholas Chin has posted comments on this change by Martin L Roth. ( https://review.coreboot.org/c/coreboot/+/87185?usp=email ) Change subject: Documentation: Add information about the site-local directory ...................................................................... Patch Set 1: (1 comment) File Documentation/getting_started/site-local.md: PS1: > Okay,but this isn't a tutorial,and it covers the entirety of using site local, so it's different. […] Looking at the content in `managing_local_additions.md` again, I'd actually say that it doesn't really fit the "tutorial" label, as it doesn't really have a clear step by step approach of a good tutorial (`tutorial/part1.md` is a good example of one). To me, `managing_local_additions.md` actually looks quite similar in style to the content you wrote here, with maybe a bit more discussion/explanation in some spots compared to here. I'd actually say your page is a better guide for site-local compared to what's actually in that tutorial, so I wouldn't be opposed to dropping `managing_local_additions.md` or reworking it to better fit the style of a tutorial (either could be done in a separate patch) I'll mark this as resolved as I'm fine with merging site-local.md as is and then figuring out what to do with `managing_local_additions.md` later. As a side note, I like the way https://diataxis.fr/start-here/ describes tutorials and other styles of documentation. -- To view, visit https://review.coreboot.org/c/coreboot/+/87185?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: comment Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: Ida176aa460be7673bad219f958f741dd68a8aa62 Gerrit-Change-Number: 87185 Gerrit-PatchSet: 1 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Nicholas Chin <nic.c3.14(a)gmail.com> Gerrit-Attention: Martin L Roth <gaumless(a)gmail.com> Gerrit-Comment-Date: Sun, 06 Apr 2025 20:49:56 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Comment-In-Reply-To: Martin L Roth <gaumless(a)gmail.com> Comment-In-Reply-To: Nicholas Chin <nic.c3.14(a)gmail.com>

1 0

[XL] Change in coreboot[main]: Documentation/internals: Add devicetree language documentation
by Martin L Roth (Code Review) 06 Apr '25

06 Apr '25

Martin L Roth has submitted this change. ( https://review.coreboot.org/c/coreboot/+/84710?usp=email ) Change subject: Documentation/internals: Add devicetree language documentation ...................................................................... Documentation/internals: Add devicetree language documentation Signed-off-by: Martin Roth <gaumless(a)gmail.com> Change-Id: If868ad9a87cb2903bf144996fe3b87d29d4fc755 Reviewed-on: https://review.coreboot.org/c/coreboot/+/84710 Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org> Reviewed-by: Nicholas Chin <nic.c3.14(a)gmail.com> --- A Documentation/internals/devicetree_language.md M Documentation/internals/index.md 2 files changed, 1,310 insertions(+), 0 deletions(-) Approvals: build bot (Jenkins): Verified Nicholas Chin: Looks good to me, approved diff --git a/Documentation/internals/devicetree_language.md b/Documentation/internals/devicetree_language.md new file mode 100644 index 0000000..0609559 --- /dev/null +++ b/Documentation/internals/devicetree_language.md @@ -0,0 +1,1309 @@ +# Devicetree Language + +Devicetrees use what's called a Domain Specific Language, so you need to +follow the rules of the language when you're writing a devicetree. +Fortunately, it's a relatively simple language, and because its use is +so limited, it can frequently be learned just by following existing +examples. + + +## Comments + +Comments in the devicetree are all single line style. They use the '#' +character to start the comment, and go to the end of the line. + + +### Comment Style + +* Put a space between the pound sign and the comment. + * \# Good + * \#Bad +* Sentence fragments are fine, but don't end them with a period. + + +### When to use comments + +There are standard locations where comments are typically used and +expected. + + +#### Starting a group of settings + +Similar to commenting a function with the intent of the function, it can +be useful to describe at the top of a block of settings with what's +being configured. + +Below is a good example. + +```text +# VR Settings Configuration for 4 Domains +# +----------------+-----------+-----------+-------------+----------+ +# | Domain/Setting | SA | IA | GT Unsliced | GT | +# +----------------+-----------+-----------+-------------+----------+ +# | Psi1Threshold | 20A | 20A | 20A | 20A | +# | Psi2Threshold | 4A | 5A | 5A | 5A | +# | Psi3Threshold | 1A | 1A | 1A | 1A | +# | Psi3Enable | 1 | 1 | 1 | 1 | +# | Psi4Enable | 1 | 1 | 1 | 1 | +# | ImonSlope | 0 | 0 | 0 | 0 | +# | ImonOffset | 0 | 0 | 0 | 0 | +# | IccMax | 7A | 34A | 35A | 35A | +# | VrVoltageLimit | 1.52V | 1.52V | 1.52V | 1.52V | +# | AC LoadLine | 15 mOhm | 5.7 mOhm | 5.2 mOhm | 5.2 mOhm | +# | DC LoadLine | 14.3 mOhm | 4.83 mOhm | 4.2 mOhm | 4.2 mOhm | +# +----------------+-----------+-----------+-------------+----------+ +``` + + +#### End of keyword blocks + +If there are multiple end statements in a row, and it's not instantly +obvious which end statement closes which keyword block, It's useful to +add a comment to say what's being ended. + +Below, we have three end statements in a row and the start of these +blocks are probably close to the top of the file. Identifying what the +'end' statement is closing can be determined by the spacing, but it's +still useful to note it with a comment. + +```text + end # agesa northbridge + end # domain +end # northbridge/amd/agesa/family14/root_complex +``` + + +#### Identifying the reason for a setting + +Registers which don't have a name that makes it obvious what is being +set, or don't have a macro that identifies what it's being set to should +be commented. + +The register setting and macro below both describe what the setting is, +but don't describe what they're being used for. Adding the comment of +"Camera", gives the reader the extra information to know what's on that +USB port, and understand that you (generally) don't need overcurrent +protection for an internal camera. + +```text +register "usb2_ports[7]" = "USB2_PORT_MID(OC_SKIP)" # Camera +``` + +This below register is well named and tells you that there's going to be +a delay of 12ms, but without the comment, you don't know why. + +```text +register "stop_delay_ms" = "12" # NIC needs time to quiesce +``` + + +#### Devices without aliases + +It's been common in the past to comment device identifiers with what the +device is, but this may be less needed now with aliases, which allow +devices to be named in a meaningful way. + +For older platforms which don't have aliases set in the chipset.cb file, +or for non chipset devices, it's still useful to add a comment after the +device is set. + + +### When not to use comments + +#### Magic numbers + +This overlaps somewhat with the next section, but if you find yourself +having to put in a comment to explain what's being set, evaluate whether +it can be expressed as a macro instead. + +``` +register "PmConfigSlpS3MinAssert" = "2" # 50ms +``` + +Instead of using the magic number 2, use a macro, just as you'd be +expected to do in your code. It's not obvious without the comment what +2 means, so use a macro instead. + +If there's some reason that a macro cannot be used, then sure, add a +comment, but this should be very unusual. + +#### Redundant comments + +With good naming, comments may not be needed. + +Example of redundant comments: + +```text +register "ipc1" = "0x00000000" # IPC1 +``` + +```text +register "link_freq[0]" = "360 * MHz" # 360 MHz +``` + +#### Devices with aliases + +For older chipset or SoC devices, or for non chipset devices that don't +have a chipset.cb file, it's still desirable to use comments on the +'device' line, but if the device has an alias, it should be used. + + +## Registers + +### Register Names + +Any registers which encode a value that has any sort of unit should +include the unit in the name instead of in a comment. + +The name "tFAW" in the register below is taken directly from the name in +the spec, but adding the units makes it a lot easier to understand. + +```text +register "tFAW" = "40000" # picoseconds +``` + +### Use Macros for encoded values + +If the value associated with the register encodes the unit, instead of +entering the value directly, add a macro for the value. + +```text +register "PchPmSlpS3MinAssert" = "3" # 50ms +``` + +This would be easier to understand if it had a macro, not just a magic +number, as seen below. + +```text +register "PchPmSlpS3MinAssert" = "ASSERT_50_MILLISEC" +``` + +## Devicetree Keywords + +alias, as, chip, cpu, cpu_cluster, device, domain, drq, end, field, +fw_config, generic, gpio, hidden, i2c, inherit, io, ioapic, ioapic_irq, +lapic, mandatory, mmio, off, on, option, pci, pnp, probe, ref, register, +smbios_dev_info, smbios_slot_desc, spi, subsystemid, usb, use + + +## Keyword Types + +The keywords are divided into a number of different categories. A few +keywords fall into more than one of these categories. + + +### Alias Types + +The alias type keywords are used to give human readable names to +devices, then later update that name for a specific usage. + +* alias, as, use + + +### Containers + +These keywords act to group information into logical units of different +sorts. + +* chip, device, domain, field, fw_config, end + + +### Device/Bus Types + +These keywords are used to identify the type of device being configured +and select the appropriate structure for configuration. + +* cpu, cpu_cluster, domain, generic, gpio, i2c, ioapic, lapic, mmio, + pci, pnp, ref, spi, usb + + +### Enumeration Status Modifiers + +The status modifiers determine how a device should be treated during +enumeration. + +* on, off, hidden, mandatory + + +### Firmware configuration + +* field, fw_config, option, probe, ref + + +### Resource allocation + +* drq, io, irq + + +### SMBIOS + +* smbios_dev_info, smbios_slot_desc + + +### Subsystem + +* inherit, subsystemid + + +### Register + +* register + + +### MPTABLE + +* ioapic_irq + + +## Keyword Definitions + +### alias + +* Keyword type: Alias +* Introduced in June of 2020, coreboot version 4.12 +* Usage: `device <device type> <device address> **alias** <ALIAS ID> <status modifier> ... end` + +Sometimes, the driver of one device needs to know about another device +that can be anywhere in the device hierarchy. Current applications boil +down to EEPROMs that store information that is consumed by some code +(e.g. MAC address). + +The idea is to give device nodes in the `devicetree.cb` an alias that +can later be used to link it to a device driver's `config` structure. +The driver has to declare a field of type `struct device *`, e.g. + +Override devices can add an alias if it does not exist, but cannot +change the alias for a device that already exists. + +Alias names are checked for conflicts both in the base tree and in the +override tree. + +References are resolved after the tree is parsed so aliases and +references do not need to be in a specific order in the tree. + +Example: +```text +device i2c 0x50 alias my_eeprom on end +``` + +static.c: + +```C +struct some_chip_driver_config { + DEVTREE_CONST struct device *needed_eeprom; +}; +``` + +### as + +* Keyword type: Alias +* Introduced in June of 2020, coreboot version 4.12 +* Usage: `use <Alias ID> as <Alias ID 2>` + +This keyword is used along with the 'use' keyword to give a more +specific name to a generic alias. + +The author of the devicetree is free to choose any alias name that is +unique in the devicetree. Later, when configuring the driver the alias +can be used to link the device with the field of a driver's config as in +the following example. + + +Example: + +```text +chip some/chip/driver + use my_eeprom as needed_eeprom +end +``` + + +### chip + +* Keyword type: Component type +* Introduced in initial sconfig implementation, pre coreboot 4.0 +* Usage: `**chip** <path to chip.h file> ... end` + +The chip keyword defines a section for a device inside a hierarchy of +devices. + +Following the chip keyword is a path to an optional chip.h file. If +this file exists, it should contain a structure of all register settings +available for this device. + +The section started with "chip" is closed with the "end" keyword. + +Note that register commands are chip based, not device based. + +Example: +```text +chip some/chip/driver # comment as desired + # A chip section must have at least one device inside it + ... +end # some/chip/driver +``` + + +### cpu + +* Keyword type: Device type +* Introduced in October of 2014, coreboot version 4.0 +* Usage: `device **cpu** <Identifier> [alias <alias ID>] <status modifier> ... end` + +The cpu device type was introduced In order to enumerate CPU devices +that are non-x86 (read: no lapic). + +This device type is not used very much, as most non-x86 platforms just +handle all the CPU configuration at the cpu_cluster level. + +Example: + +```text +device cpu 0 on end +``` + + +### cpu_cluster + +* Keyword type: Device type +* Introduced in initial sconfig implementation, pre coreboot 4.0 as apic_cluster +* Updated in May of 2010 - renamed from apic_cluster to lapic_cluster +* Updated in February of 2013 - Renamed from from lapic_cluster to cpu_cluster +* Usage: `device cpu_cluster <Identifier> [alias <alias ID>] <status modifier> …. end` + +The CPU Cluster is typically one of the two top-level devices in a +devicetree, with the other being the PCI Domain. Like the domain +keyword, the cpu_cluster acts as a bridge device to contain any CPU and +lapic devices. + +On x86 type devices, the CPU Cluster contains CPU chip entries for each +socket which then contain any lapics on the system. + +On ARM or other non-x86 devices, the CPU Cluster can either contain +multiple CPUs or it can just be marked 'on', leaving all CPU +configuration to be handled at the CPU Cluster level. + +Example: + +```text +device cpu_cluster 0 on + device lapic 0 on end +end +``` + +### device + +* Keyword type: Component type +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `device <device type> <Identifier> [alias <alias ID>] <status modifier>…. end` + +A chip defines a collection of one or more devices, and as such, the +device is the fundamental building block of devicetree. + +The device block tells coreboot that a device is present on the +mainboard, gives some information on how to find, access, and work with +the device based on the device type. + +Examples: + +```text +device cpu_cluster 0 on + device lapic 0 on end +end +``` + +### domain + +* Keyword type: Device type +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Updated in: February of 2013: Renamed pci_domain to domain +* Usage: `device domain <identifier> [alias <alias ID>] <status modifier> ... end` + +The domain type device acts as a container for one or more chips, +defining a logical bus segment. + +As of 2022-04-29, the domain keyword is still used exclusively to define +PCI bus segments. + +Example: + +```text +device domain 0 on + device generic 0 alias dptf_policy on end + device pci 1f.0 on # 8086 229c - LPC bridge + device pnp 2e.209 off end # GPIO 4 + end +end +``` + + +### drq + +* Keyword type: Resource type +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `drq 0x<register #> = <drq line>` + +Drq is used to configure a legacy DMA Request line register for a device +on a legacy bus - ISA/LPC/eSPI. + +The drq configuration is only allowed inside a pnp block. + +Example: + +```text +device pnp 2e.1 on # Parallel port + io 0x60 = 0x378 + irq 0x70 = 7 + drq 0x74 = 3 +end +``` + +### end + +* Keyword type: Component type +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `<device | chip | domain | field | fw_config> ... end` + +End is used to close a chip, device, field, or fw_config block. + +Example: + +```text +chip northbridge/intel/x4x + device domain 0 on + chip southbridge/intel/i82801gx + device pci 1f.0 on # ISA bridge + chip superio/winbond/w83627dhg + device pnp 2e.1 on # LPT + io 0x60 = 0x378 + irq 0x70 = 7 + drq 0x74 = 3 + end # LPT + end # superio/winbond/w83627dhg + end # ISA Bridge + end # Southbridge + end # domain 0 +end # Northbridge +``` + +### field + +* Keyword type: Firmware config +* Introduced in: May of 2020, coreboot version 4.12 +* Usage: `field <Identifier string> <low bit> <high bit> [ | <low bit> <high bit> …] ... end` + +Fields define the bits used in the Firmware config runtime options. +Note that the bits in a field can be discontiguous. + +All field definitions must be inside a fw_config block. + +Example: + +```text +field AUDIO 8 10 | 29 29 + option NONE 0 + option MAX98357_ALC5682I_I2S 1 + option MAX98373_ALC5682I_I2S 2 + option MAX98373_ALC5682_SNDW 3 + option MAX98373_ALC5682I_I2S_UP4 4 + option MAX98360_ALC5682I_I2S 5 + option RT1011_ALC5682I_I2S 6 + option AUDIO_FOO 7 + option AUDIO_BAR 8 + option AUDIO_QUUX 9 + option AUDIO_BLAH1 10 + option AUDIO_BLAH2 15 +end +``` + +static_fw_config.h: + +```C + FW_CONFIG_FIELD_AUDIO_MASK 0x20000700 + FW_CONFIG_FIELD_AUDIO_OPTION_NONE_VALUE 0x0 + FW_CONFIG_FIELD_AUDIO_OPTION_MAX98357_ALC5682I_I2S_VALUE 0x100 + FW_CONFIG_FIELD_AUDIO_OPTION_MAX98373_ALC5682I_I2S_VALUE 0x200 + FW_CONFIG_FIELD_AUDIO_OPTION_MAX98373_ALC5682_SNDW_VALUE 0x300 + FW_CONFIG_FIELD_AUDIO_OPTION_MAX98373_ALC5682I_I2S_UP4_VALUE 0x400 + FW_CONFIG_FIELD_AUDIO_OPTION_MAX98360_ALC5682I_I2S_VALUE 0x500 + FW_CONFIG_FIELD_AUDIO_OPTION_RT1011_ALC5682I_I2S_VALUE 0x600 + FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_FOO_VALUE 0x700 + FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BAR_VALUE 0x20000000 + FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_QUUX_VALUE 0x20000100 + FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BLAH1_VALUE 0x20000200 + FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BLAH2_VALUE 0x20000700 +``` + +### fw_config + +* Keyword type: Firmware config +* Introduced in: May of 2020, coreboot version 4.12 +* Usage: fw_config + +Fw_config is the top level token for defining firmware config fields. +All field and option definitions must be inside the fw_config block. +Note that the table can be defined before any chips are configured. + +Example: +```text +fw_config + field USB_DB 0 1 + option USB_DB_A1_PS8811_C1_PS8818 0 + option USB_DB_A1_ANX7491_C1_ANX7451 1 + end + field FORM_FACTOR 2 + option FORM_FACTOR_CLAMSHELL 0 + option FORM_FACTOR_CONVERTIBLE 1 + end +end +``` + + +### generic + +* Keyword type: Device type +* Introduced in: May of 2016, coreboot version 4.4 +* Usage: `device generic <identifier> [alias <alias ID>] <status modifier> ... end` + +This allows the devicetree to describe a device that does not have a +specific bus, but may need to be described in tables for the operating +system. For instance some chips may have various GPIO connections that +need to be described but do not fall under any other device. + +Example: +```text +device pci 0c.0 on # CNVi + chip drivers/wifi/generic + register "wake" = "GPE0A_CNVI_PME_STS" + device generic 0 on end + end +end +``` + + +### gpio + +* Keyword type: Device type +* Introduced in: December 2020, coreboot version 4.13 +* Usage: `device **gpio** <identifier> [alias <alias ID>] <status modifier> ... end` + +The general idea behind this is that every chip can have gpios that +shall be accessible in a very generic way by any driver through the +devicetree. + +The chip that implements the chip-specific gpio operations has to assign +them to the generic device operations struct, which then gets assigned +to the gpio device during device probing. See CB:48583 for how this gets +done for the SoCs using intel/blocks/gpio. + +The gpio device then can be added to the devicetree with an alias name +like in the following example: + +```text +chip soc/whateverlake + device gpio 0 alias soc_gpio on end + ... +end +``` + +Any driver that requires access to this gpio device needs to have a +device pointer (or multiple) and an option for specifying the gpio to be +used in its chip config like this: + +```C +struct drivers_ipmi_config { + ... + DEVTREE_CONST struct device *gpio_dev; + u16 post_complete_gpio; + ... +}; +``` + +The device `soc_gpio` can then be linked to the chip driver's `gpio_dev` +above by using the syntax `use ... as ...`, which was introduced in +commit 8e1ea52: + +```text +chip drivers/ipmi + use soc_gpio as gpio_dev + register "bmc_jumper_gpio" = "GPP_D22" + ... +end +``` + +The IPMI driver can then use the generic gpio operations without any +knowlege of the chip's specifics: + +```C +unsigned int gpio_val; +const struct gpio_operations *gpio_ops; +gpio_ops = dev_get_gpio_ops(conf->gpio_dev); +gpio_val = gpio_ops->get(conf->bmc_jumper_gpio); +``` + +For a full example have a look at CB:48096 and CB:48095. + + +### hidden + +* Keyword type: Enumeration Status Modifier +* Introduced in: September 2018, coreboot version 4.8 +* Updated in: February of 2020, coreboot version 4.11 +* Usage: `device <device type> <identifier> [alias <alias ID>] hidden ... end` + +The "Hidden" keyword was added to support devices sharing the same +driver to update their ACPI status with different values. If a device +is marked as Hidden, it omits the "SHOW_IN_UI" field, which prevents the +device from showing up in the OSPM user interface. This was added to +prevent ChromeOS specific devices from showing up in Windows, for +example. It does not look like this keyword was ever actually used in +this capacity, but the code for this is still present. + +In 2020, the "Hidden" keyword's use was expanded to fix the problem of +PCI devices which have been hidden by disabling access to the config +space. Because the Device/Vendor IDs read back as 0xffffffff from the +hidden device, it appears that there is no PCI device located at that +Bus/Device/Function. This causes coreboot to remove the device at the +end of PCI enumeration. To fix this, if a device uses 'hidden' instead +of 'on', then it will be assumed during PCI enumeration that the device +indeed does exist, and it will not be removed. This allows coreboot to +manually assign resources to the device even though it doesn't appear to +exist. + +Example: +```text +device pci 1f.2 alias pmc hidden end +``` + +static.c: + +```C +.enabled = 1, +.hidden = 1, +.mandatory = 0, +``` + + +### i2c + +* Keyword type: Device type +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `device I2c <identifier> [alias <alias ID>] <status modifier> ... end` + +Example: + +```text +device i2c 2c on end +chip drivers/i2c/generic + register "hid" = ""ELAN0000"" + register "desc" = ""ELAN Touchpad"" + register "irq_gpio" = "ACPI_GPIO_IRQ_LEVEL_LOW(GPIO_9)" + register "wake" = "GEVENT_22" + register "probed" = "1" + device i2c 15 on end +end +``` + +### inherit + +* Keyword type: subsystem +* Introduced in: March of 2011, coreboot version 4.0 +* Usage: `subsystemid beee c001 inherit` + +Used to modify the subsystemid keyword, inherit makes the ID apply to +all subdevices and functions. + +Example: +```text +device pci 00.0 on + subsystemid 0xdead 0xbeef inherit +end +``` + + +### io + +* Keyword type: Resource +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `io 0x<address> = 0x<value>` + +The io command is used to set an legacy device's io register to a value. + +Example: + +```text +device pnp 4e.06 on # Keyboard + io 0x60 = 0x0060 + io 0x62 = 0x0064 + irq 0x70 = 1 +end +``` + +### ioapic + +* Keyword type: Device type + +* Usage: `device ioapic <identifier> [alias <alias ID>] <status modifier> ... end` + + +### ioapic_irq + +* Keyword type: Mpinit type +* Introduced in: June of 2012, coreboot version 4.0 +* Usage: `ioapic_irq <APICID> <INTA|INTB|INTC|INTD> <INTPIN>` + +This keyword is used to support autogeneration of the MPTABLE from +devicetree.cb. This is done by a write_smp_table() declared weak in +mpspec.c. If the mainboard doesn't provide its own function, this +generic implementation is called. + +The ioapic_irq directive can be used in pci and pci_domain devices. If +there's no directive, the autogen code traverses the tree back to the +pci_domain and stops at the first device which sets such a directive, +and uses that information to generate the entry according to PCI IRQ +routing rules. + +```text +``` + + +### irq + +* Keyword type: Resource type +* Introduced in initial sconfig implementation, pre coreboot 4.0 +* Usage: `irq 0x<address> = 0x<value>` + +Irq is used to configure a legacy interrupt Request line register for a +device on a legacy bus - ISA/LPC/eSPI. + +The irq configuration is only allowed inside a pnp block. + +Example: + +```text +irq 0xc5 = 0x1f +``` + +```text +chip superio/fintek/f71808a + device pnp 4e.4 on # Hardware monitor + io 0x60 = 0x295 + irq 0x70 = 0 + end +end +``` + +### lapic + +* Keyword type: Device type +* Introduced in initial sconfig implementation, pre coreboot 4.0 +* Updated in May of 2010 - Renamed apic to lapic +* Usage: `device lapic <identifier> [alias <alias ID>] <status modifier> ... end` + +Defines an lapic device on an x86 mainboard. + +Example: + +```text +device cpu_cluster 0 on # (L)APIC cluster + chip cpu/intel/slot_1 # CPU socket 0 + device lapic 0 on end # Local APIC of CPU 0 + end + chip cpu/intel/slot_1 # CPU socket 1 + device lapic 1 on end # Local APIC of CPU 1 + end +end +``` + +### mandatory + +* Keyword type: Enumeration Status Modifier +* Introduced in: February of 2020, coreboot version 4.11 +* Usage: `device <device type> <identifier> [alias <alias ID>] mandatory ... end` + +The Mandatory keyword allows for minimal PCI scanning which speeds up the +boot process. Only devices marked "mandatory" get enabled and scanned +during PCI enumeration when the MINIMAL_PCI_SCANNING Kconfig option is +enabled. + +If MINIMAL_PCI_SCANNING is not enabled, this means the same as 'on'. + +static.c: + +```C +.enabled = 1, +.hidden = 0, +.mandatory = 1, +``` + +example: + +```text +device pci 1f.0 mandatory # LPC + chip drivers/pc80/tpm + device pnp 0c31.0 on end + end # tpm +end # LPC +``` + + +### mmio + +* Keyword type: Device type +* Introduced in January of 2018, coreboot version 4.7 +* Usage: `device mmio 0x<address> [alias <alias ID>] <status modifier> ... end` + +The mmio keyword allows fixed memory-mapped IO addressed devices to be +assigned to given values. + +AMD platforms perform a significant amount of configuration through these +MMIO addresses, including I2C bus configuration. + +example: + +```text +device mmio 0xfedc9000 alias uart_0 off end +device mmio 0xfedca000 alias uart_1 off end +device mmio 0xfedc2000 on # I2C 0 + + chip drivers/generic/adau7002 + device generic 0.0 on end + end + + chip drivers/i2c/da7219 + register "irq_gpio" = "ACPI_GPIO_IRQ_EDGE_LOW(GPIO_14)" + end + + chip drivers/generic/max98357a + register "hid" = ""MX98357A"" + register "sdmode_delay" = "5" + device generic 0.1 on end + end + +end # I2C 0 +``` + + +### off + +* Keyword type: Enumeration Status Modifier +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `device <device type> <identifier> [alias <alias ID>] off ... end` + +Indicates that the device should be disabled if possible and should not +be enumerated or configured. To disable a device, the code to disable it +must be present in the chipset/SoC code, though it isn't always possible +to actually disable the device. + +Note that If a device (especially PCI devices) is marked as 'off', but +does not get disabled, the OS or a driver may discover the device during +its enumeration sequence and assign it resources anyway. + +static.c: + +```C +.enabled = 0 +.hidden = 0, +.mandatory = 0, +``` + +example: + +```text +device usb 2.6 off end +device pnp 2e.0 off end # FDC +device pci 15.2 off end +``` + +### on + +* Keyword type: Enumeration Status Modifier +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `device <device type> <identifier> [alias <alias ID>] on ... end` + +Marks a device as present and enabled. This indicates that the device +should be enumerated and configured. + +static.c: + +```C +.enabled = 1 +.hidden = 0, +.mandatory = 0, +``` + +Example: + +```text +device lapic 0 on end +device pci 00.0 on end # Host Bridge +device pnp 0c31.0 on end +``` + +### option + +* Keyword type: Firmware config +* Usage: `option <name> <value>` + +Options define the values which may be used in a firmware config field. +The option keyword may only be used inside a field, which may only be +used inside an fw_config block. + +Example: + +```text +fw_config + field OLED_SCREEN 28 + option OLED_NOT_PRESENT 0 + option OLED_PRESENT 1 + end +end +``` + +### pci + +* Keyword type: Device type +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `device pci <dev.func> [alias <alias ID>] <status modifier> …. end` + +The pci device type defines a PCI or PCIe device on the PCI logical bus. + +Resources for all PCI devices are assigned automatically, or must be +assigned in code if they're non-standard. + +Currently, only a single segment is supported, but there is work to make +multiple different segments supported, each with a bus 0. Because the +bus is not specified, It's assumed that all pci devices that are not +behind a pci bridge device are on bus 0. If there are additional pci +busses in a chip, they can be added behind their bridge device. + +Examples: + +```text +device pci 1a.0 on end # USB2 EHCI #2 +device pci 1b.0 on # High Definition Audio + subsystemid 0x1a86 0x4352 +end +``` + +Example - ISA bus under PCI to ISA bridge: + +```text +device pci 4.0 on # ISA bridge + chip superio/winbond/w83977tf # Super I/O + device pnp 3f0.2 on # COM1 + io 0x60 = 0x3f8 + irq 0x70 = 4 + end + end +end +``` + +Example - PCI Bus under a PCI to PCI bridge: + +```text +device pci 08.0 on end # Dummy Host Bridge, do not disable +device pci 08.1 alias gpp_bridge_a off # Internal GPP Bridge 0 to Bus A + device pci 0.0 alias gfx off end # Internal GPU (GFX) + device pci 0.1 alias gfx_hda off end # Display HDA (GFXAZ) +end +``` + + +### pnp + +* Keyword type: Device type +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `device pnp <Identifier> [alias <alias ID>] <status modifier>…. end` + +pnp is used to define an IO addressed device within a chip on a legacy +bus - ISA, LPC, or eSPI. The identifier is the IO address used to +access the chip, followed by the identifier for the device within the +chip. + +The io, irq, and drq resource identifiers are allowed only inside a pnp +device. + +Example: + +```text +chip superio/ite/it8783ef + device pnp 2e.0 off end # Floppy + device pnp 2e.1 on # COM 1 + io 0x60 = 0x3f8 + irq 0x70 = 4 + end +end +``` + +### probe + +* Keyword type: Firmware config +* Introduced in May of 2020, coreboot version 4.12 +* Usage: `probe <Field Name> <Option Name>` + +The fields and options can be used to probe for a device and have that +device be disabled if it is not found at boot time. + +Example: + +```text +fw_config + field FEATURE 0 0 + option DISABLE 0 + option ENABLE 1 + end +end + +chip drivers/generic/feature + device generic 0 on + probe FEATURE ENABLE + end +end +``` + + +### ref + +* Keyword type: Device type (alias) +* Introduced in July of 2020, coreboot version 4.12 +* Usage: `device REF <Identifier> <status modifier>…. end` + +This allows the chipset to assign alias names to devices as well as set +default register values. This works for both the baseboard devicetree.cb +as well as variant overridetree.cb. + +Example: + +chipset.cb: + +```text +device pci 15.0 alias i2c0 off end +``` + +devicetree.cb: + +```text +device ref i2c0 on end +``` + +### register + +* Keyword type: Register +* Introduced in: Initial sconfig implementation, pre coreboot 4.0 +* Usage: `register "name" = "value"` + +The register keyword was initially intended to supply just that - +information for device register values. Over the years, its use has been +expanded to much more than this, becoming a general configuration +mechanism. + +All values set by the register keyword MUST be defined in the chip.h +file. The register keyword only works at the chip level, not at the +device level. + +Any register defined in the chip.h file that is not set in the +devicetree file gets set to zero. + +To double quote a value, use two sets of quotes: `register "name" = ""string""` + +Examples: + +```text +register "desc" = ""USB2 Type-A Rear Lower"" +register "pcie_power_limits" = "{ { 10, 0 }, { 0, 0 }, { 0, 0 }, + { 0, 0 }, { 10, 0 }, { 0, 0 } }" +register "SataPortsEnable[0]" = "1" +register "generic.irq" = "ACPI_IRQ_LEVEL_LOW(GPP_B3_IRQ)" +register "common_soc_config" = "{ + // Touchpad I2C bus + .i2c[0] = { + .speed = I2C_SPEED_FAST, + .rise_time_ns = 80, + .fall_time_ns = 110, + }, + }" +``` + + +### smbios_dev_info + +* Keyword type: smbios +* Introduced in: May of 2019, coreboot version 4.9 +* Usage: `smbios_dev_info <Identifier>` + +Specify the instance ID and RefDes (Reference Designation) of onboard +devices. + +The `SMBIOS_TYPE41_PROVIDED_BY_DEVTREE` Kconfig option enables using +this syntax to control the generated Type 41 entries (Onboard Devices +Extended Information). When this option is enabled, Type 41 entries are +only autogenerated for devices with a defined instance ID. This avoids +having to keep track of which instance IDs have been used for every +device class. + +Using `smbios_dev_info` when `SMBIOS_TYPE41_PROVIDED_BY_DEVTREE` is not +enabled will result in a build-time error, as the syntax is meaningless +in this case. This is done with preprocessor guards around the Type 41 +members in `struct device` and the code which uses the guarded members. +Although the preprocessor usage isn't particularly elegant, adjusting the +devicetree syntax and/or grammar depending on a Kconfig option is +probably even worse. + +Example: + +```text +device pci 1c.0 on # PCIe Port #1 + device pci 00.0 on + smbios_dev_info 6 + end +end +device pci 1c.1 on # PCIe Port #2 + device pci 00.0 on + smbios_dev_info 42 "PCIe-PCI Time Machine" + end +end +``` + +### smbios_slot_desc + +* Keyword type: smbios +* Introduced in: May of 2019, coreboot version 4.9 +* Usage: `smbios_slot_desc** <type> <length> [designation] [data width]` + +Add the new field 'smbios_slot_desc', which takes 2 to 4 arguments. +The field is only valid for PCI devices and only compiled if SMBIOS +table generation is enabled. + +smbios_slot_desc arguments - described in src/include/smbios.h: + +1. slot type: enum misc_slot_type +2. slot length: enum misc_slot_length +3. slot designation (optional): text string +4. slot data width (optional): enum slot_data_bus_bandwidth + +Example: + +```text +device pci 1c.1 on + smbios_slot_desc "SlotTypePciExpressGen3X16" "SlotLengthOther" "SLOT2" "SlotDataBusWidth8X" +end # PCIe Port #2 Integrated Wireless LAN +``` + +### spi + +* Keyword type: Device type +* Introduced in: February of 2017, coreboot version 4.5 +* Usage: device **SPI** <Identifier> [alias <alias ID>] <status modifier>…. end + +The SPI device takes only one parameter, the chip-select for the device +on the SPI bus. + +Example: + +```text +device spi 0 alias spi_tpm on end +``` + + +### subsystemid + +* Keyword type: Subsystem +* Introduced in: March of 2011, coreboot version 4.0 +* Usage: `subsystemid <vendor> <device> [inherit]` + +Sets a PCI subsystem ID. + +If the user wants to have this ID inherited to all subdevices/functions, +they can add the keyword 'inherit' after the ID. + +If the user doesn't want to inherit the subsystem value for a single +device, they can specify 'subsystemid 0 0' on this particular device. + +Example: + +```text +device pci 00.0 on + subsystemid 0xdead 0xbeef +end +``` + +or + +```text +device pci 00.0 on + subsystemid 0xdead 0xbeef inherit +end +``` + +### usb + +* Keyword type: Device type +* Introduced in: May of 2018, coreboot version 4.7 +* Usage: `device usb <Identifier> [alias <alias ID>] <status modifier> ... end` + +This supports describing USB ports in the devicetree. It allows a USB +port location to be described in the tree with configuration +information, and ACPI code to be generated that provides this +information to the OS. + +The usb symbol works with the scan_usb_bus() operation to scan bridges +for devices so a tree of ports and hubs can be created. + +The device address is computed with a 'port type' and a 'port id' which +is flexible for the SOC to handle depending on their specific USB setup +This also allows USB2 and USB3 ports to be described separately. + +For example a board may have devices on two ports, one with a USB2 +device and one with a USB3 device, both of which are connected to an +xHCI controller with a root hub: + +```text + xHCI + | + RootHub + | | + USB2[0] USB3[2] +``` + +This is described by the following example: + +```text +device pci 14.0 on + chip drivers/usb/acpi + register "name" = ""Root Hub"" + device usb 0.0 on + + chip drivers/usb/acpi + register "name" = ""USB 2.0 Port 0"" + device usb 2.0 on end + end + + chip drivers/usb/acpi + register "name" = ""USB 3.0 Port 2"" + device usb 3.2 on end + end + + end # device usb 0.0 + end # chip drivers/usb/acpi +end # device pci 14.0 +``` + +### use + +* Keyword type: Alias +* Introduced in September of 2020, coreboot version 4.12 +* Usage: `use <Alias ID> as <Alias ID2>` + +The author of the devicetree is free to choose any alias name that is +unique in the devicetree. Later, when configuring the driver for a +board, the alias can be used to link the device with the field of a +driver's config, giving it a specific name. + +Example: + +```text +chip some/chip/driver + use my_eeprom as needed_eeprom +end +``` diff --git a/Documentation/internals/index.md b/Documentation/internals/index.md index 01d5696..17dee55 100644 --- a/Documentation/internals/index.md +++ b/Documentation/internals/index.md @@ -9,5 +9,6 @@ :maxdepth: 1 coreboot devicetree <devicetree.md> +coreboot devicetree language <devicetree_language.md> ``` -- To view, visit https://review.coreboot.org/c/coreboot/+/84710?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: merged Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: If868ad9a87cb2903bf144996fe3b87d29d4fc755 Gerrit-Change-Number: 84710 Gerrit-PatchSet: 5 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: Nicholas Chin <nic.c3.14(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>

1 0

[L] Change in coreboot[main]: Documentation/internals: Add devicetree documentation
by Martin L Roth (Code Review) 06 Apr '25

06 Apr '25

Martin L Roth has submitted this change. ( https://review.coreboot.org/c/coreboot/+/84709?usp=email ) Change subject: Documentation/internals: Add devicetree documentation ...................................................................... Documentation/internals: Add devicetree documentation Signed-off-by: Martin Roth <gaumless(a)gmail.com> Change-Id: I2a43a96911844bd2b682004d5423126ad00a4bf3 Reviewed-on: https://review.coreboot.org/c/coreboot/+/84709 Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org> Reviewed-by: Nicholas Chin <nic.c3.14(a)gmail.com> --- M Documentation/index.md A Documentation/internals/devicetree.md A Documentation/internals/index.md 3 files changed, 698 insertions(+), 0 deletions(-) Approvals: build bot (Jenkins): Verified Nicholas Chin: Looks good to me, approved diff --git a/Documentation/index.md b/Documentation/index.md index 7ba88f3..b564c5c 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -219,6 +219,7 @@ Payloads <payloads.md> Distributions <distributions.md> Technotes <technotes/index.md> +Internal APIs & Configuration <internals/index.md> ACPI <acpi/index.md> Native Graphics Initialization with libgfxinit <gfx/libgfxinit.md> Display panel <gfx/display-panel.md> diff --git a/Documentation/internals/devicetree.md b/Documentation/internals/devicetree.md new file mode 100644 index 0000000..c6f5c4c --- /dev/null +++ b/Documentation/internals/devicetree.md @@ -0,0 +1,684 @@ +# Devicetree + +## Introduction to the coreboot devicetree + +The first thing that may come to mind when one hears "DeviceTree" is a +different sort of description file that is generally passed to the Linux +kernel to describe a system's components. Both that devicetree and +coreboot's devicetree serve fundamentally the same purpose, but are +otherwise unrelated and have completely different syntax. The term +devicetree was used long before either version was created, and was +initially used in coreboot as a generic term. + +coreboot's devicetree's main use is to define and describe the runtime +configuration and settings of the hardware on a board, chip or device +level. It defines which of the functions of the chips on the board are +enabled, and how they're configured. + +The devicetree file is parsed during the build process by a utility +named `sconfig`, which translates the devicetree into a tree of C +structures containing the included devices. This code is placed in the +file `static.c` and a couple of header files, all under the `build` +directory. This file is then built into the binaries for the various +coreboot stages and is referred to during the coreboot boot process. + +For the early stages of the coreboot boot process, the data that is +generated by `sconfig` is a useful resource, but this structure is the +critical architectural glue of ramstage. This structure gets filled in +with pointers to every chip's initialization code, allowing ramstage to +find and initialize those devices through the `chip_operations` +structures. + + +### History of coreboot's devicetree + +The initial devicetree in coreboot was introduced in 2003 by Ron Minnich +as a part of the linuxbios config file, 'config.lb'. At this point both +the devicetree and config options were in the same file. In 2009, +when Kconfig was added into the coreboot build, devicetree was split +out into its own file for each mainboard in a commit with this message: + +```text +devicetree.cb + +The devicetree that formerly resided in src/mainboard/*/*/Config.lb. + +Just without the build system crap +``` + +The devicetree structure was initially mainly used only in ramstage for +PCI device enumeration, configuration and resource allocation. It has +since expanded for use in the pre-ram stages as a read-only structure. + +The language used in the devicetree has been expanded greatly since it +was first introduced as well, adding new features every year or so. + + +### Devicetree Registers + +In coreboot, the devicetree register setting is one of the two main +methods used to configure a board's properties. In this way, devicetree +is similar in function to Kconfig. It's more flexible in many ways as +it can specify not only single values, but also arrays or structures. +It's also even more static than Kconfig because there's no update +mechanism for it other than editing the devicetree files. + +Chip-specific configuration values are often set using `register` +definitions within a `chip` block, corresponding to a `struct` defined +in the chip's `chip.h` file. + +For example, in a `chip drivers/gpio/acpi` block, you might set a GPE: + +```text +register "gpe0_sts" = "0x42" +``` + + +### Adding new static configuration options: Devicetree or Kconfig + +When adding options for a new board or chip, there is frequently a +decision that needs to be made about how the option should be added. +Using the devicetree or Kconfig are the two typical methods of +build-time configuration. Below are some general guidelines on when to +use each. + +Kconfig should be used if the option configures the build in a Makefile, +or if the option is something that should be user selectable. Kconfig +is also preferred if the configuration is a global option and not limited +to a single chip. Another thing Kconfig excels at is handling decisions +based on other configuration options, which devicetree cannot do. + +Devicetree should obviously be used to define the hardware hierarchy. +It's also preferred if the option is only used in C code and is static +for a mainboard, or if the option is chip-specific. As mentioned +earlier, devicetree registers can also define structures or arrays, +which Kconfig cannot. + +Both Kconfig and devicetree can be used in C code for runtime +configuration, but there's a significant difference in how they are +handled. Because Kconfig generates a `#define` for the choice, the +compiler can eliminate code paths not used by the option. Devicetree +options, however, are actual runtime selections, and the code for all +choices remains in the final build. + + +## Basic Devicetree Syntax + +The coreboot devicetree uses a custom language parsed by the `sconfig` +utility. Here's a brief overview of the main keywords and concepts: + +* **`chip <directory>`**: Defines a collection of devices associated + with the code in the specified directory. `sconfig` may also parse a + `chip.h` file within this directory for register definitions. +* **`device <type> <id> [on|off] [alias <name>] ... end`**: Defines a + specific hardware device. + * `<type>`: Specifies the device type (e.g., `pci`, `cpu_cluster`, + `i2c`). + * `<id>`: A unique identifier for the device within its type/bus + (e.g., PCI BDF `17.0`, I2C address `0x50`). + * `on`/`off`: Enables or disables the device definition. + * `alias <name>`: Assigns a human-readable alias for referencing + this device elsewhere (often used in `chipset.cb`). + * `end`: Marks the end of the device definition block. Registers + and other properties are defined between `device` and `end`. +* **`register "<name>" = <value>`**: Sets the value of a configuration + register defined in the corresponding `chip.h` structure. The value + can be a number, string, or complex structure initialization. +* **`probe <field> <option>`**: Used for firmware configuration + (`fw_config`), indicating a setting should be probed at runtime. +* **`ops "<identifier>"`**: Associates a `chip_operations` structure + with the device, used primarily in ramstage for device initialization. +* **`fw_config field <name> size <bits> ... end`**: Defines a firmware + configuration field, often used for passing board-specific data to + payloads. Options within the field are defined using `option`. +* **`ref <alias>`**: Used within `device` definitions in `devicetree.cb` + or `overridetree.cb` to refer to a device defined (usually via an + `alias`) in a lower-level file like `chipset.cb`. +* **`# <comment text>`**: Single-line comments. + +Device definitions can be nested within `chip` blocks. `end` keywords +close the current block (`device` or `chip`). + + +## Three levels of devicetree files + +There are currently three different levels of devicetrees used to build +up the structure of components and register values in coreboot. From +the lowest, most general level to the highest and most specific, they +are `chipset.cb`, `devicetree.cb`, and `overridetree.cb`. + +Unless there's a specific reason to name them something other than these +names, they should be used. + +For newer SoCs and chipsets, there will generally be a `chipset.cb` file. +Every mainboard requires a `devicetree.cb` file, although it can be empty +if everything is inherited from the `chipset.cb`. An `overridetree.cb` +file is only required if variants have differences from the primary +mainboard's `devicetree.cb`. + + +### SoC / chipset level, `chipset.cb` + +The `chipset.cb` file was added in October 2020, allowing a single +chipset or SoC to provide a "base level" devicetree, reducing +duplication between mainboards. + +The `chipset.cb` file also typically defines human-readable "aliases" +for particular devices so that mainboards can use those instead of PCI +device/function numbers or other hardware identifiers. + +The use of the `chipset.cb` file is specified in Kconfig by the +`CHIPSET_DEVICETREE` symbol, which provides the path to the file. + +In a `chipset.cb` file, you might see lines like this: + +```text +# Chip definition for the SoC/chipset itself +chip soc/intel/common/block + + # Define PCI device 17.0, alias it to "sata", and default it off + device pci 17.0 alias sata off end + + # Define PCI device 1e.0, alias it to "uart0", and default it off + device pci 1e.0 alias uart0 off end + +end # chip soc/intel/common/block +``` + +This defines the devices, assigns aliases, and sets their default state. + + +### Primary mainboard level, `devicetree.cb` + +Each mainboard must have a `devicetree.cb` file. The filename and path are +typically set by the `DEVICETREE` Kconfig symbol, defaulting to +`src/mainboard/<VENDOR>/<BOARD>/devicetree.cb`. + +If a mainboard using the above `chipset.cb` wanted both devices enabled, +its `devicetree.cb` might contain: + +```text +# Reference the SATA device by its alias and enable it +device ref sata on end + +# Reference the UART0 device by its alias and enable it +device ref uart0 on end +``` + +The `ref` keyword looks up the device (usually by alias) defined in a +lower-level file (`chipset.cb` in this case) and modifies its properties. + + +### Mainboard variant level, `overridetree.cb` + +Introduced in 2018 to reduce duplication and maintenance for board +variants, the `overridetree.cb` file is the most specific level. + +This allows a base `devicetree.cb` at the top mainboard level shared by +all variants. Each variant then only needs an `overridetree.cb` to +specify its differences. + +The override tree filename is set in Kconfig with the +`OVERRIDE_DEVICETREE` symbol and is typically named `overridetree.cb`. + +Finally, if one variant of the mainboard lacked a SATA connector, it +could disable the SATA device again using the following in its specific +`overridetree.cb`: + +```text +# Reference the SATA device by alias and disable it for this variant +device ref sata off end +``` + + +## Additional files + + +### `chip.h` files + +coreboot looks at a "chip" as a collection of devices. This collection +can be a single logical device or multiple different ones. The `chip` +keyword starts this collection. Following the `chip` keyword is a +directory path (relative to `src/`) containing the code for that chip +or logical block of hardware. + +There may optionally be a `chip.h` file in that directory. If present, +`sconfig` parses this file to define a C structure containing the +"register definitions" for the chip. The values for this structure's +members are set using the `register` keyword in one of the devicetree +files (`chipset.cb`, `devicetree.cb`, `overridetree.cb`). If not +explicitly set, members typically default to 0 or follow standard C +initialization rules. The `chip.h` file frequently also contains C +macros, enums, and sub-structures used for setting the members of the +main register structure. + +The C structure for the chip's register definition is named after the +directory containing the `chip.h` file, with slashes (`/`) changed to +underscores (`_`), and `_config` appended. The leading `src/` is omitted. + +This means that a line in a devicetree file like: +`chip drivers/i2c/hid` +would cause `sconfig` to look for `src/drivers/i2c/hid/chip.h`. If found, +the register definition structure it contains would be named +`drivers_i2c_hid_config`. + +Here is the content of `src/drivers/i2c/hid/chip.h`: + +```c +/* SPDX-License-Identifier: GPL-2.0-only */ + +#ifndef __DRIVERS_I2C_HID_CHIP_H__ +#define __DRIVERS_I2C_HID_CHIP_H__ +#include <drivers/i2c/generic/chip.h> +#define I2C_HID_CID "PNP0C50" + +struct drivers_i2c_hid_config { + struct drivers_i2c_generic_config generic; + uint8_t hid_desc_reg_offset; +}; + +#endif /* __I2C_HID_CHIP_H__ */ +``` + +In a devicetree, you could set `hid_desc_reg_offset` like this: + +```text +chip drivers/i2c/hid + device i2c 0x2c on + # Set the HID descriptor register offset + register "hid_desc_reg_offset" = "0x01" + end +end +``` + + +## The `sconfig` utility and generated files + + +### `util/sconfig` + +`sconfig` is the tool that parses the coreboot devicetrees and turns +them into a collection of C structures. This is a coreboot-specific +tool, built using flex & bison to define and parse the domain-specific +language used by coreboot's devicetree. + +`sconfig` is called by the makefiles during the build process and doesn't +generally need to be run directly. If run manually (e.g., +`build/util/sconfig/sconfig --help`), it shows its command-line options. +The exact options might vary slightly, but typically include: + +```text +usage: sconfig <options> + + -c | --output_c : Path to output static.c file (required) + -r | --output_h : Path to header static.h file (required) + -d | --output_d : Path to header static_devices.h file (required) + -f | --output_f : Path to header static_fw_config.h file (required) + -m | --mainboard_devtree : Path to mainboard devicetree file (required) + -o | --override_devtree : Path to override devicetree file (optional) + -p | --chipset_devtree : Path to chipset/SOC devicetree file (optional) +``` + + +### `sconfig` inputs + +The `sconfig` input files `chip.h`, `chipset.cb`, `devicetree.cb`, and +`overridetree.cb` were discussed previously. As the usage above shows, +the only required input file is the mainboard devicetree (`-m`). The +additional devicetree files, `chipset.cb` (`-p`) and `overridetree.cb` +(`-o`), are optional. The `chip.h` files do not need to be specified on +the command line; their locations are determined by the `chip` directory +paths within the `.cb` files. + +Constructing the devicetree input files will be discussed later. + + +### `sconfig` outputs + +#### `static.c` + +This is the primary C file generated by `sconfig`. It contains the static +definitions of the device tree structures, including device nodes, bus +links, and register configuration data. + +For historic reasons, `static.c` is generated in the +`build/mainboard/<VENDOR>/<BOARD>` directory. + + +#### `static.h` + +The `static.h` file is the main header file included by most coreboot C +files that need access to the devicetree data. It is included by +`src/include/device/device.h`, which provides the primary API +(definitions, structures, function prototypes) for interacting with the +devicetree-generated output. + +`static.h` used to contain all generated declarations directly. As of +October 2020, it simply includes the other two generated header files +(`static_devices.h` and `static_fw_config.h`). This separation allows +the firmware config options (`fw_config`) to be used independently, for +example, by a payload. + + +#### `static_devices.h` + +The file `static_devices.h` contains `extern` declarations for all the +device structures (`struct device`) defined in `static.c`. This allows +other C files to reference the generated device tree nodes. + + +#### `static_fw_config.h` + +`static_fw_config.h` contains only the `FW_CONFIG_FIELD_*` macro results, +derived from `fw_config` entries in the devicetree. This makes it easily +consumable by payloads or other components needing platform `FW_CONFIG` +data without pulling in the full device tree structure. + + +## Devicetree Example + + +### A very simple devicetree + +This is the `devicetree.cb` file from +`src/mainboard/sifive/hifive-unleashed`, with line numbers added for +reference. Non-x86 devicetree files are often simpler than their x86 +counterparts. + +```text + 1 # SPDX-License-Identifier: GPL-2.0-only + 2 chip soc/sifive/fu540 + 3 device cpu_cluster 0 on end + 4 end +``` + +This can be broken down as follows: + +Line 1: Comments start with `#`. This line is the SPDX license +identifier for the file. + +Line 2: `chip soc/sifive/fu540` starts a block for the SiFive FU540 SoC. +`sconfig` will look for code and potentially a `chip.h` in +`src/soc/sifive/fu540/`. + +Line 3: `device cpu_cluster 0 on end` defines a device of type +`cpu_cluster` with ID `0`. It's marked as enabled (`on`). Since there are +no registers or other properties defined between `device` and `end`, this +is a simple enablement entry. + +Line 4: `end` closes the block started by the `chip` keyword on line 2. + + +### Generated files + +Continuing with the simple `sifive/hifive-unleashed` mainboard example, +these are the files generated by `sconfig` from the devicetree above (as +of mid-2022; exact output can change). Because the input devicetree is +minimal, the generated files are also quite sparse. + + +#### `build/static.h` + +```c +#ifndef __STATIC_DEVICE_TREE_H +#define __STATIC_DEVICE_TREE_H + +#include <static_fw_config.h> +#include <static_devices.h> + +#endif /* __STATIC_DEVICE_TREE_H */ +``` +(Includes the other generated headers.) + + +#### `build/static_devices.h` + +```c +#ifndef __STATIC_DEVICES_H +#define __STATIC_DEVICES_H +#include <device/device.h> +/* expose_device_names */ +#endif /* __STATIC_DEVICE_NAMES_H */ +``` +(Includes `device/device.h` but contains no actual device externs beyond +the implicit root device, as the simple example didn't define complex +devices requiring separate structs.) + + +#### `build/static_fw_config.h` + +```c +#ifndef __STATIC_FW_CONFIG_H +#define __STATIC_FW_CONFIG_H +#endif /* __STATIC_FW_CONFIG_H */ +``` +(Empty because the example `devicetree.cb` did not use `fw_config`.) + + +#### `build/mainboard/sifive/hifive-unleashed/static.c` + +##### Includes + +```text +1 #include <boot/coreboot_tables.h> +2 #include <device/device.h> +3 #include <device/pci.h> +4 #include <fw_config.h> +5 #include <static.h> +``` + +Lines 1-5: Includes header files required for the following structure +definitions and macros. + + +##### Declarations for chip-ops + +```text +6 +7 #if !DEVTREE_EARLY +8 __attribute__((weak)) struct chip_operations mainboard_ops = {}; +9 extern struct chip_operations soc_sifive_fu540_ops; +10 #endif +``` + +Lines 7 & 10: The `ops` structures inside this `#if !DEVTREE_EARLY` block +are only relevant and linked in ramstage. + +Lines 8-9: Declarations for `chip_operations` structures. This section +expands as more chips are added to the devicetree. +* Line 8: `mainboard_ops` is always present. It's defined as `weak` + because the mainboard C code may or may not provide this structure. +* Line 9: This `extern` is generated by the `chip soc/sifive/fu540` + declaration in the `devicetree.cb`. There will be a similar line for + every `chip` declared. + +##### `STORAGE` definition + +```text +11 +12 #define STORAGE static __unused DEVTREE_CONST +``` + +Line 12: This macro conditionally adds `const` based on the build stage. +It resolves to `static __unused const` in early stages (pre-RAM) and +`static __unused` in ramstage, where the structures might be modified. + +##### Structure definitions + +```text +13 +14 +15 /* pass 0 */ +16 STORAGE struct bus dev_root_links[]; +17 STORAGE struct device _dev_0; +18 DEVTREE_CONST struct device * DEVTREE_CONST last_dev = &_dev_0; +``` + +Lines 16-18: Forward declarations of the static structures generated by +`sconfig` based on the devicetree input. `_dev_0` corresponds to the +`cpu_cluster 0` device. + +##### Register Structures + +```text +19 +20 /* chip configs */ +``` + +Line 20: This section is empty for this mainboard because the +`soc/sifive/fu540/chip.h` file (if it exists) does not define a register +structure, or the devicetree did not instantiate it using `register`. +Otherwise, this section would contain the static initialization of chip +configuration structures based on `register` entries. + +##### `dev_root` structure + +Lines 21-44: `dev_root`. This structure represents the root of the +coreboot device tree. It is always generated, regardless of the content +of the `devicetree.cb` file. It serves as the entry point for traversing +the tree. + +```text +21 +22 /* pass 1 */ +23 DEVTREE_CONST struct device dev_root = { +24 #if !DEVTREE_EARLY +25 .ops = &default_dev_ops_root, +26 #endif +27 .bus = &dev_root_links[0], +28 .path = { .type = DEVICE_PATH_ROOT }, +29 .enabled = 1, +30 .hidden = 0, +31 .mandatory = 0, +32 .on_mainboard = 1, +33 .link_list = &dev_root_links[0], +34 .sibling = NULL, +35 #if !DEVTREE_EARLY +36 .chip_ops = &mainboard_ops, +37 .name = mainboard_name, +38 #endif +39 .next=&_dev_0, +40 #if !DEVTREE_EARLY +41 #if CONFIG(GENERATE_SMBIOS_TABLES) +42 #endif +43 #endif +44 }; +``` + +* Lines 24-26: Points to a default ramstage `device_operation` + structure (`default_dev_ops_root`) found in + `src/device/root_device.c`. This structure typically does little by + default but can be overridden or utilized by mainboard code via the + `chip_operations->enable_dev()` hook for tasks like ACPI table + generation. +* Line 27: `.bus`: Pointer to the bus structure associated with this + device. For the root device, this points to its own bus structure. +* Line 28: `.path`: The unique path identifier for this device. The type + is `DEVICE_PATH_ROOT`. +* Lines 29-32: Device status flags. + * `enabled`: Set based on `on`/`off` in the devicetree (always on + for `dev_root`). Can be modified later (e.g., during enumeration + in ramstage). + * `hidden`, `mandatory`: Set only by corresponding keywords in the + devicetree (not used here). + * `on_mainboard`: Indicates the device was defined in the static + devicetree, as opposed to being discovered dynamically (e.g., via + PCI enumeration). Always true for `dev_root`. +* Line 33: `.link_list`: Pointer to the list of child buses attached to + this device. +* Line 34: `.sibling`: Pointer to the next device at the same level in + the tree. Should always be `NULL` for `dev_root`. +* Line 36: `.chip_ops`: Pointer to the mainboard's `chip_operations` + structure (the `weak` `mainboard_ops`). Although not a physical + chip, the mainboard gets this to hook into the boot process like + other chips. +* Line 37: `.name`: A string identifier, typically the mainboard name, + set at build time (from `src/device/root_device.c`). +* Line 39: `.next`: Pointer used internally by `sconfig` during tree + construction. Points to the next device structure processed (`_dev_0`). + +##### `dev_root_links` + +Lines 45-52: The `dev_root` bus structure array. + +This array (`struct bus`) holds pointers defining the bus topology. Each +element represents a link on a bus. `dev_root` acts as the bridge for the +top-level bus. + +A new bus structure array is typically created for each distinct bus type +or domain originating from a bridge device in the devicetree (e.g., PCI +domain 0, LPC bus). + +```text +45 STORAGE struct bus dev_root_links[] = { +46 [0] = { +47 .link_num = 0, +48 .dev = &dev_root, +49 .children = &_dev_0, +50 .next = NULL, +51 }, +52 }; +``` + +* Line 47: `.link_num`: Index of this link within the bus array. +* Line 48: `.dev`: Pointer back to the bridge device structure for this + bus (`dev_root`). +* Line 49: `.children`: Pointer to the first child device structure on + this bus (`_dev_0`). +* Line 50: `.next`: Pointer to the next bridge device on the *parent* + bus. Since `dev_root` has no parent bus, this is `NULL`. + +##### `_dev_0` + +Lines 53-72: The `cpu_cluster` device structure (`_dev_0`). + +This structure corresponds directly to the +`device cpu_cluster 0 on end` line in the `devicetree.cb`. + +```text +53 STORAGE struct device _dev_0 = { +54 #if !DEVTREE_EARLY +55 .ops = NULL, +56 #endif +57 .bus = &dev_root_links[0], +58 .path = {.type=DEVICE_PATH_CPU_CLUSTER,{.cpu_cluster={ .cluster = 0x0 }}}, +59 .enabled = 1, +60 .hidden = 0, +61 .mandatory = 0, +62 .on_mainboard = 1, +63 .link_list = NULL, +64 .sibling = NULL, +65 #if !DEVTREE_EARLY +66 .chip_ops = &soc_sifive_fu540_ops, +67 #endif +68 #if !DEVTREE_EARLY +69 #if CONFIG(GENERATE_SMBIOS_TABLES) +70 #endif +71 #endif +72 }; +``` + +* Lines 54-56: `.ops`: Pointer to a `device_operations` structure. This + is `NULL` because this entry represents the `chip` itself, not a + specific functional sub-device requiring device-level operations. The + chip-level operations are handled by `chip_ops`. +* Line 57: `.bus`: Pointer to the bus structure this device resides on. + Since it's directly under `dev_root`, it points to `dev_root_links[0]`. +* Line 58: `.path`: The unique device path structure (defined in + `src/include/device/path.h`). Type is `DEVICE_PATH_CPU_CLUSTER`, + and the cluster ID is `0`, matching the devicetree entry. This path + is used when searching the tree (e.g., with `dev_find_path()`). +* Lines 59-62: Enumeration Status. Similar to `dev_root`. `enabled = 1` + comes from the `on` keyword. +* Line 63: `.link_list`: Pointer to child buses. `NULL` because this + `cpu_cluster` device doesn't bridge to any further buses in this + simple example. +* Line 64: `.sibling`: Pointer to the next device at the same level + (i.e., another device directly under `dev_root`). `NULL` as it's the + only child. +* Lines 65-67: `.chip_ops`: Pointer to the processor's `chip_operations` + structure (`soc_sifive_fu540_ops`), used in ramstage for SoC/CPU + initialization steps. This link comes from the `chip soc/sifive/fu540` + declaration. +* Lines 68-71: Placeholder for SMBIOS information, enabled by Kconfig. + Not used in this example. diff --git a/Documentation/internals/index.md b/Documentation/internals/index.md new file mode 100644 index 0000000..01d5696 --- /dev/null +++ b/Documentation/internals/index.md @@ -0,0 +1,13 @@ +# coreboot internals + +This section contains documentation about the configuration and +programming APIs internal to coreboot + +## Configuration + +```{toctree} +:maxdepth: 1 + +coreboot devicetree <devicetree.md> + +``` -- To view, visit https://review.coreboot.org/c/coreboot/+/84709?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email Gerrit-MessageType: merged Gerrit-Project: coreboot Gerrit-Branch: main Gerrit-Change-Id: I2a43a96911844bd2b682004d5423126ad00a4bf3 Gerrit-Change-Number: 84709 Gerrit-PatchSet: 5 Gerrit-Owner: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: Martin L Roth <gaumless(a)gmail.com> Gerrit-Reviewer: Nicholas Chin <nic.c3.14(a)gmail.com> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>

1 0

Jump to page:

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

coreboot-gerrit April 2025