Mainlining Wiki - User contributions [en]

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T19:14:19Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''codenames''' of the SoC. Qualcomm SoCs appear to have two codenames<ref>The names of these codenames have been sourced from [https://wiki.postmarketos.org/wiki/Qualcomm_Snapdragon_8_Gen_1/8%2B_Gen_1/7%2B_Gen_2_(SM8450/SM8475/SM7475) the postmarketOS wiki page for the Snapdragon 8 Gen 1], not sure where that is sourced from.</ref>:
** '''Board codename''' ("DTS nickname"?) - you'll find it in the driver names on the device, as well as in the main compatible string of the devicetree. This is what's used across most of the downstream kernel.
** '''Platform codename''' - presumably shared between multiple SoCs from the same family.
** Since SM7635 ("Volcano"/"Milos") getting upstreamed, Qualcomm appears to have changed their policy around driver/compatible naming in mainline and now expects developers to use the platform codename instead of the model number<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>. If you're unsure of the platform codename for your device, you can send the Qualcomm folks an email and ask them directly<ref>I ended up getting [https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/ a public reply to my query for SM7435].</ref>, or just use the model name for now and let them correct you (as was done in the Milos case).
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T19:12:36Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''codenames''' of the SoC. Qualcomm SoCs appear to have two codenames<ref>The names of these codenames have been sourced from [https://wiki.postmarketos.org/wiki/Qualcomm_Snapdragon_8_Gen_1/8%2B_Gen_1/7%2B_Gen_2_(SM8450/SM8475/SM7475) the postmarketOS wiki page for the Snapdragon 8 Gen 1], not sure where that is sourced from.</ref>:
** '''Board codename''' ("DTS nickname"?) - you'll find it in the driver names on the device, as well as in the main compatible string of the devicetree. This is what's used across most of the downstream kernel.
** '''Platform codename''' - presumably shared between multiple SoCs from the same family.
** Since SM7635 ("Volcano"/"Milos"), Qualcomm has changed their policy around driver/compatible naming in mainline and now expects developers to use the platform codename instead<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>. If you're unsure of the platform codename for your device, you can send the Qualcomm folks an email and ask them directly<ref>I ended up getting [https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/ a public reply to my query for SM7435].</ref>, or just use the model name for now and let them correct you (as was done in the Milos case).
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T19:11:54Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''codenames''' of the SoC. Qualcomm SoCs appear to have two codenames<ref>The names of these codenames have been sourced from [https://wiki.postmarketos.org/wiki/Qualcomm_Snapdragon_8_Gen_1/8%2B_Gen_1/7%2B_Gen_2_(SM8450/SM8475/SM7475) the postmarketOS wiki page for the Snapdragon 8 Gen 1, not sure where that is sourced from.</ref>:
** '''Board codename''' ("DTS nickname"?) - you'll find it in the driver names on the device, as well as in the main compatible string of the devicetree. This is what's used across most of the downstream kernel.
** '''Platform codename''' - presumably shared between multiple SoCs from the same family.
** Since SM7635 ("Volcano"/"Milos"), Qualcomm has changed their policy around driver/compatible naming in mainline and now expects developers to use the platform codename instead<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>. If you're unsure of the platform codename for your device, you can send the Qualcomm folks an email and ask them directly<ref>I ended up getting [https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/ a public reply to my query for SM7435].</ref>, or just use the model name for now and let them correct you (as was done in the Milos case).
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T19:11:22Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''codenames''' of the SoC. Qualcomm SoCs appear to have two codenames<ref>The names of these codenames have been sourced from [https://wiki.postmarketos.org/wiki/Qualcomm_Snapdragon_8_Gen_1/8%2B_Gen_1/7%2B_Gen_2_(SM8450/SM8475/SM7475) the postmarketOS wiki page for the Snapdragon 8 Gen 1, not sure where that is sourced from.</ref>:
** ''Board codename'' ("DTS nickname"?) - you'll find it in the driver names on the device, as well as in the main compatible string of the devicetree. This is what's used across most of the downstream kernel.
** ''Platform codename''. Presumably shared between multiple SoCs from the same family.
** Since SM7635 ("Volcano"/"Milos"), Qualcomm has changed their policy around driver/compatible naming in mainline and now expects developers to use the platform codename instead<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>. If you're unsure of the platform codename for your device, you can send the Qualcomm folks an email and ask them directly<ref>I ended up getting [https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/ a public reply to my query for SM7435].</ref>, or just use the model name for now and let them correct you (as was done in the Milos case).
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T19:06:38Z

Knuxify:

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''codenames''' of the SoC. Qualcomm SoCs appear to have two codenames:
** ''"DTS nickname"'' (board name?). You'll find it in the driver names on the device, as well as in the main compatible string of the devicetree. This is what's used across most of the downstream kernel.
** ''Platform codename(?)''. Presumably shared between multiple SoCs from the same family.
** Since SM7635 ("Volcano"/"Milos"), Qualcomm has changed their policy around driver/compatible naming in mainline and now expects developers to use the platform codename instead<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>. If you're unsure of the platform codename for your device, you can send the Qualcomm folks an email and ask them directly<ref>I ended up getting [https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/ a public reply to my query for SM7435].</ref>, or just use the model name for now and let them correct you (as was done in the Milos case).
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T19:05:49Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''codenames''' of the SoC. Qualcomm SoCs appear to have two codenames:
** ''"DTS nickname"'' (board name?). You'll find it in the driver names on the device, as well as in the main compatible string of the devicetree. This is what's used across most of the downstream kernel.
** ''Platform codename(?)''. Presumably shared between multiple SoCs from the same family.
** Since SM7635 ("Volcano"/"Milos"), Qualcomm has changed their policy around driver/compatible naming in mainline and now expects developers to use the platform codename instead<ref>https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/</ref>. If you're unsure of the platform codename for your device, you can send the Qualcomm folks an email and ask them directly<ref>I ended up getting [https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/ a public reply to my query for SM7435].</ref>, or just use the model name for now and let them correct you (as was done in the Milos case).
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T18:57:37Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''downstream codename''' ("DTS nickname"?) of your SoC. If you're lucky, it's probably already somewhere out there online. You'll find it in the driver names on the device, as well as in the main compatible string of the devicetree. This will be useful when looking things up in the downstream kernel, as it primarily uses the codename.
* The '''internal codename''' of your SoC. Around mid-2025, Qualcomm's mainline Linux engineers decided that instead of using the model name for SoC drivers, they should use the codename instead... except the codename in the downstream code isn't always the same as the ''actual'' SoC codename.
** Sometimes the downstream codename matches with the internal name (as might be the case for "waipio" given it's mentioned alongside the others in [https://mysupport.qualcomm.com/supportforums/s/question/0D54V00007gUfXASA0/whats-the-difference-of-v69-and-v73 this random Qualcomm support forums post]), other times it's different (SM7435 uses "parrot" in the kernel but is actually called "netrani"<ref>https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/</ref>, SM7635 uses "volcano" in downstream but is actually called "milos").
** ''Mere mortals'' shall not know these codenames... but you can probably ask your friendly neighborhood sympathizer of the mainline cause<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>.
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T18:48:35Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''downstream codename''' ("DTS nickname"?) of your SoC. If you're lucky, it's probably already somewhere out there online. You'll find it in the driver names on the device. This will be useful when looking things up in the downstream kernel, as it primarily uses the codename, whereas mainline uses the model number.
* The '''internal codename''' of your SoC. Around mid-2025, Qualcomm's mainline Linux engineers decided that instead of using the model name for SoC drivers, they should use the codename instead... except the codename in downstream isn't always the same as the ''actual'' codename.
** ''Mere mortals'' shall not know these codenames... but you can probably ask your friendly neighborhood sympathizer of the mainline cause<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>.
** Sometimes the downstream codename matches with the internal name (as might be the case for "waipio" given it's mentioned alongside the others in [https://mysupport.qualcomm.com/supportforums/s/question/0D54V00007gUfXASA0/whats-the-difference-of-v69-and-v73 this random Qualcomm support forums post]), othertimes it's different (SM7435 uses "parrot" in the kernel but is actually called "netrani"<ref>https://lore.kernel.org/lkml/c379aad4-96f6-4134-8b90-0f1eec8001a3@oss.qualcomm.com/</ref>).
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2026-02-02T18:38:30Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The '''downstream codename''' ("DTS nickname"?) of your SoC. If you're lucky, it's probably already somewhere out there online. You'll find it in the driver names on the device. This will be useful when looking things up in the downstream kernel, as it primarily uses the codename, whereas mainline uses the model number.
* The '''internal codename''' of your SoC. Around mid-2025, Qualcomm's mainline Linux engineers decided that instead of using the model name for SoC drivers, they should use the codename instead... except the codename they ''want'' you to use is different from the one that's plastered all over the downstream kernel.
** ''Mere mortals'' shall not know these codenames... but you can probably ask your friendly neighborhood sympathizer of the mainline cause<ref>https://lore.kernel.org/lkml/888a7598-38d9-4640-9823-2b073da006f4@kernel.org/</ref>.
* A copy of the '''downstream kernel'''; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by downstream codename).
* A copy of the '''<code>qcom_proprietary_devicetree</code>''' or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(downstream codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An '''extracted DTB from your device'''. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]])?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

== References ==

User:Knuxify/Draft:Getting started

2026-01-27T05:57:51Z

Knuxify:

This page serves as an introduction to the basics of mainlining.

== What is mainlining? ==

'''Mainlining''' is the act of adding support for a device, or porting its drivers from an older, non-upstream tree, to the mainline Linux kernel.

The name comes from the term "''mainline Linux kernel''", which is used to refer to the upstream Linux kernel repository maintained by Linus Torvalds<ref>https://en.wikipedia.org/wiki/Linux_kernel#Mainline_Linux</ref>, and which itself comes from the term "''mainline branch''" used to refer to the main development trunk of a project<ref>https://en.wikipedia.org/wiki/Branching_(version_control)#Trunk</ref>.

=== Why is mainlining necessary? ===

Users of the Linux kernel on x86-64 PCs may be accustomed to the fact that most components work out of the box on these devices. This can be partly attributed to the fact that both AMD and Intel - the largest players in the x86-64 market - contribute support for their CPUs and chipsets directly to the mainline Linux kernel.

With most embedded SoCs, however, the typical lifecycle of Linux support looks like this:

* The SoC vendor forks the Linux kernel and applies patches for device support on top of this fork
* The SoC fork is sent to device manufacturers, who apply their own patches on top of it to add support for their devices

The code from these forks usually never makes it back upstream; it's maintained internally by the SoC vendor's team. Yet worse, device vendors often neglect rebasing their forks on the vendor's updated kernels. As kernel APIs change over time, updating these kernels to the latest version becomes more difficult.

Since upstreaming is not a priority, and the main goal of a vendor is to provide a viable product to developers as fast as possible, the drivers in an SoC fork don't necessarily conform to the standards and practices of the mainline Linux kernel.

This is where '''mainlining''' comes in. Mainlining comprises of:

* Analyzing the drivers from original source code, or experimenting with the hardware itself to determine how it works (reverse engineering), to then write new, upstream-ready drivers for it;
* Submitting those drivers upstream, responding to review comments, maintaining them in the mainline Linux kernel tree.

== Prerequisites ==

* A computer running Linux, which will handle building the kernel.
** If you're on Windows, you can use WSL (though flashing the kernel to your device might be a bit challenging, TODO).
** (Note about recommended specs goes here; faster hardware is better, but only necessary bits are rebuilt on subsequent builds; also mention ccache?)
* Some familiarity with the Linux shell and [[User:Knuxify/Draft:C crash course|C programming language syntax]] is recommended.

== Getting to know your device and SoC ==

{{todo|These are both topics worthy of their own page. Some things to mention here:

* Finding out whether the SoC is supported to mainline and, if so, how well.
* Finding out what components your device has (it's nice to keep a table!)}}

== Preparing the build environment ==

In order to mainline a device, we need to be able to cross-compile the Linux kernel for it.

=== Downloading the Linux kernel source code ===

Depending on your SoC's support status:

* There may be an up-to-date maintained [[close-to mainline]] fork of the Linux kernel for your device's SoC; if there is one, start from it.
* If there is no dedicated fork for your device's SoC, or the fork is out of date, start with either:
** '''The latest stable tag''' directly from Torvalds' tree (see [https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/] or <code>github.com/torvalds/linux</code>).
** For very new SoCs with ongoing work, you may want to use the '''linux-next tree''' instead.

If you're on GitHub, you can fork [https://github.com/torvalds/linux the torvalds/linux repository] and start from there.

Once you have your kernel cloned, switch to the latest tag, then create a new feature branch from it:

<syntaxhighlight lang="shell-session">
$ git checkout v6.14 # replace 6.14 with latest kernel version
$ git checkout -b codename-mainline # git checkout -b creates a new branch based on current HEAD and checks out into it
</syntaxhighlight>

{{todo|Link to some nice guide on git here (and probably elsewhere in the page)}}

=== Cross-compiler setup ===

{{todo|Explain cross-compiler setup; where to get toolchains (AUR for Arch users? Linaro?), postmarketOS envkernel.sh}}

=== Selecting/creating a defconfig ===

The '''kernel config''' dictates which drivers and platform-specific support bits (including DTBs) get built. There are a handful of pre-made configs, called '''defconfigs''', in <code>arch/{arm,arm64,...}/configs</code> - use <code>make name_defconfig</code> to build them.

{{todo|Common ARM(64) config? Which options to select/unselect? pmbootstrap kconfig check might be useful here}}

=== Adding a device tree for your device ===

Devices using ARM chipsets use [[devicetree]]s to describe the hardware. See [[Devicetree/Writing a Linux device tree]] for a guide.

=== Building the kernel ===

{{todo|<code>make -j$(nproc)</code>}}

=== Packaging the kernel into a boot image ===

{{todo|See how I do it in [https://github.com/refractionware/linux/blob/meta/tools/mainline-tools mainline-tools], mention pmbootstrap build --envkernel?}}

Then, flash the resulting kernel to the device.

== Getting the kernel to boot ==

{{todo|UART, DTBO trickery}}

== See also ==

{{todo|pmOS wiki has links to talks and resources}}

== References ==

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2025-07-14T16:18:47Z

Knuxify: /* Finding information about your SoC */

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The codename of your SoC. If you're lucky, it's probably already somewhere out there online. This will be useful when looking things up in the downstream kernel, as it primarily uses the codename, whereas mainline uses the model number. (TODO - we should have a table of SoC codenames somewhere!)
* A copy of the downstream kernel; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by codename).
* A copy of the <code>qcom_proprietary_devicetree</code> or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An extracted DTB from your device. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]]?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC. You'll also be able to check the other SoC's drivers and use them as a base for your own drivers.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2025-07-14T16:17:35Z

Knuxify:

{{Subpage of|Qualcomm}}
{{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}}

This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run. 

This guide was tested with the SM7435. Some details might be different for other SoCs. If you have any hints, please contribute!

== High-level overview ==

{{todo|Some of this will have to be moved out to the top-level Qualcomm page}}

The basic components of a Qualcomm SoC are:

* The '''GCC''', or ''Global Clock Controller''; as the name suggests, it is the primary clock controller for most components.
* The other clock controllers: '''CAMCC''', '''DISPCC''', '''GPUCC''' and '''VIDEOCC'''.
* The '''RPM''', or ''Resource and Power Manager'' ('''RPMH''' or RPM ''Hardened'' in SDM845 and later); todo explanation from [https://wiki.postmarketos.org/wiki/Qualcomm_Glossary qcom glossary].
** Under the RPM is the '''RPM(H)CC''' (''RPM clock controller'') and '''RPM(H)PD''' (''RPM power domains'').
* '''QUP''', or ''Qualcomm Universal Peripheral''; the part of the SoC that provides I2C or SPI busses, as well as UART.
* '''TLMM''' (''Top Level Mode Multiplexer''); provides pinmux and GPIO pins.
* Many '''NOC''' interconnects (''Network on Chip'').
* A timer and an interrupt controller, both standard ARM parts.

These are just the most low-level components; from there, we can move on to the higher-level ones:

* Thermal monitoring sensor
* USB host controller and PHY
* Display controller and DSI PHY
* GPU
* etc.

This page will touch on mainline porting of most of these parts.

== Finding information about your SoC ==

In order to begin mainlining your SoC, you need to have the following bits of information:

* The codename of your SoC. If you're lucky, it's probably already somewhere out there online. This will be useful when looking things up in the downstream kernel, as it primarily uses the codename, whereas mainline uses the model number. (TODO - we should have a table of SoC codenames somewhere!)
* A copy of the downstream kernel; preferably the one for your device, but you can also use the kernel from another device with the same SoC, or - as a last resort - any kernel with the relevant SoC drivers (hint: search by codename).
* A copy of the <code>qcom_proprietary_devicetree</code> or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for <code>(codename).dtsi</code> on GitHub and you'll find the right repository eventually.
* An extracted DTB from your device. Dump this from a running device using FDT (todo: instructions, would probably be good on a generic page, maybe subpage of [[Devicetree]]?
* Find a similar SoC that is already supported. Usually flagship SoCs are available in mainline; try to find a flagship from around the same time as the SoC you're mainlining. Find its DTSIs as well; then you can compare the differences between downstream and mainline for the upstreamed SoC, and correlate them with differences in your SoC.

== Adding the DTSI ==

todo

== Porting individual parts ==

=== Clock controllers ===

On recent Qualcomm SoCs, the downstream kernel uses the mainline Qualcomm clock driver with only ''some'' vendor-specific quirks. This means that the clock drivers and their relevant headers can pretty much be copied verbatim from downstream, with some slight modifications.

First, create the '''GCC''' driver. Open <code>driver/clk/qcom/Kconfig</code> and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

<syntaxhighlight lang="kconfig">
config SM_GCC_xxxx
tristate "SMxxxx Global Clock Controller"
depends on ARM64 || COMPILE_TEST
select QCOM_GDSC
help
Support for the global clock controller on SMxxxx devices.
Say Y if you want to use peripheral devices such as UART,
SPI, I2C, USB, SD/UFS, PCIe etc.
</syntaxhighlight>

Open <code>driver/clk/qcom/Makefile</code> and add the relevant entry:

<syntaxhighlight lang="makefile">
obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o
</syntaxhighlight>

Open <code>driver/clk/qcom/gcc-smXXXX.c</code>.

Paste the initialization code from another GCC driver (<syntaxhighlight inline lang="c">static struct platform_driver gcc_smXXXX_driver</syntaxhighlight> and onwards.)

== Porting the PMIC(s) ==

Qualcomm devices use ''multiple'' PMICs for different purposes. Often, the PMIC is paired with an SoC or series of SoCs.

User:Knuxify/Draft:Qualcomm/Adding a new SoC to mainline Linux

2025-07-13T16:24:44Z

Knuxify: Created page with "{{Subpage of|Qualcomm}} {{Work-in-progress page|note=Currently in the middle of finding this out in real time :)}} This guide will cover the process of adding support for a recent (~2020 or newer, todo?) Qualcomm SoC into mainline Linux. Most of the information contained within is also applicable to older chips, though more manual effort may be needed to get these to run.  == High-level overview == {{todo|Some of this will have to..."

Template:Subpage of

2025-07-13T07:45:54Z

Knuxify: Created page with "<noinclude><templatedata> { "params": { "1": { "label": "First-level page", "type": "string", "required": true }, "2": { "label": "Second level page", "description": "The page title after the first slash (/).", "type": "string" }, "3": { "label": "Third-level page", "description": "The page title after the second slash (/).", "type": "string" } }, "description": "Displays a link back to the parent page of a subpage. Include this..."

<noinclude><templatedata>
{
"params": {
"1": {
"label": "First-level page",
"type": "string",
"required": true
},
"2": {
"label": "Second level page",
"description": "The page title after the first slash (/).",
"type": "string"
},
"3": {
"label": "Third-level page",
"description": "The page title after the second slash (/).",
"type": "string"
}
},
"description": "Displays a link back to the parent page of a subpage. Include this template at the beginning of a page."
}
</templatedata>
This is intended to replace MediaWiki's default subpage link display feature, which is not enabled on the pmOS wiki (as it would interfere with the names of any wiki page that uses the / character).

This template supports up to 3 subpages.

== Example ==

<nowiki>{{Subpage of|Qualcomm}}</nowiki>

{{Subpage of|Qualcomm}}

<nowiki>{{Subpage of|Qualcomm|Adding a new SoC to mainline Linux}}</nowiki>

{{Subpage of|Qualcomm|Adding a new SoC to mainline Linux}}
</noinclude><includeonly><div id="contentSub" style="margin-top: -8px; margin-bottom: 18px;"><span class="subpages">< [[{{{1}}}]]{{#if: {{{2|}}}| | [[{{{1}}}/{{{2}}}|{{{2}}}]]|}}{{#if: {{{3|}}}| |[[{{{1}}}/{{{2}}}/{{{3}}}|{{{3}}}]]|}}</span>‎</div></includeonly>

Category:Work-in-progress pages

2025-07-13T07:40:58Z

Knuxify: Created page with "Pages which are marked as work-in-progress using the <code><nowiki>{{Work-in-progress page}}</nowiki></code> template."

Pages which are marked as work-in-progress using the [[Template:Work-in-progress page|<code><nowiki>{{Work-in-progress page}}</nowiki></code>]] template.

Template:Work-in-progress page

2025-07-13T07:40:07Z

Knuxify:

<noinclude>
<templatedata>
{
"params": {
"note": {
"label": "Note",
"description": "A note to display in the box.",
"type": "content"
},
"nocategory": {
"label": "Do not add to \"Stub pages\" category",
"description": "If set, the page will not be added to the \"Stub pages\" category.",
"type": "boolean",
"autovalue": "no"
}
},
"format": "inline",
"description": "Template to include on WIP pages to warn the user and give additional details as to what's currently in progress."
}
</templatedata>

== Usage ==

<pre><nowiki>{{Work-in-progress_page|note=Add some notes about foo, clean up section about bar}}
</nowiki></pre>
{{Work-in-progress_page|note=Add some notes about foo, clean up section about bar|nocategory=yes}}

Pages are added to [[:Category:Work-in-progress pages]] by default. To prevent that add the <code>nocategory=yes</code> argument:

<pre><nowiki>{{Work-in-progress_page|note=Add some notes about foo, clean up section about bar|nocategory=yes}}
</nowiki></pre>
</noinclude><includeonly>{{Icon box
| box-icons = 🚧
| box-text = '''This page is a work-in-progress.''' Some information contained within may be inaccurate or incomplete.
{{#if: {{{note|{{{1|}}}}}}|<br>In particular: ''{{{note|{{{1|}}}}}}''|}}
| border-color = #C1B598
| border-width = 2px
| border-style = dotted
| background = #E8E0CC
| background-dark = #221e16
| class = box-wip
}}{{#ifeq: {{boolean|{{{nocategory|no}}}|default=false}}|false|[[Category:Work-in-progress pages]]|}}</includeonly>

Template:Work-in-progress page

2025-07-13T07:40:00Z

Knuxify: Created page with "<noinclude> {{Template}} <templatedata> { "params": { "note": { "label": "Note", "description": "A note to display in the box.", "type": "content" }, "nocategory": { "label": "Do not add to \"Stub pages\" category", "description": "If set, the page will not be added to the \"Stub pages\" category.", "type": "boolean", "autovalue": "no" } }, "format": "inline", "description": "Template to include on WIP pages to warn the user and give addi..."

<noinclude>
{{Template}}
<templatedata>
{
"params": {
"note": {
"label": "Note",
"description": "A note to display in the box.",
"type": "content"
},
"nocategory": {
"label": "Do not add to \"Stub pages\" category",
"description": "If set, the page will not be added to the \"Stub pages\" category.",
"type": "boolean",
"autovalue": "no"
}
},
"format": "inline",
"description": "Template to include on WIP pages to warn the user and give additional details as to what's currently in progress."
}
</templatedata>

== Usage ==

<pre><nowiki>{{Work-in-progress_page|note=Add some notes about foo, clean up section about bar}}
</nowiki></pre>
{{Work-in-progress_page|note=Add some notes about foo, clean up section about bar|nocategory=yes}}

Pages are added to [[:Category:Work-in-progress pages]] by default. To prevent that add the <code>nocategory=yes</code> argument:

<pre><nowiki>{{Work-in-progress_page|note=Add some notes about foo, clean up section about bar|nocategory=yes}}
</nowiki></pre>
</noinclude><includeonly>{{Icon box
| box-icons = 🚧
| box-text = '''This page is a work-in-progress.''' Some information contained within may be inaccurate or incomplete.
{{#if: {{{note|{{{1|}}}}}}|<br>In particular: ''{{{note|{{{1|}}}}}}''|}}
| border-color = #C1B598
| border-width = 2px
| border-style = dotted
| background = #E8E0CC
| background-dark = #221e16
| class = box-wip
}}{{#ifeq: {{boolean|{{{nocategory|no}}}|default=false}}|false|[[Category:Work-in-progress pages]]|}}</includeonly>

Template:Boolean

2025-03-02T07:45:18Z

Knuxify:

<includeonly>{{#switch: {{lc: {{#if: {{{value|}}}|{{{value}}}|{{#if: {{{1|}}}|{{{1}}}|{{{default|false}}}}}}}}}
|1|y|yes|t|true=true
|0|n|no|f|false=false
|{{#if: {{{default-invalid|false}}}|{{{boolean|{{{default-invalid|false}}}}}}||}}
}}</includeonly><noinclude>
<templatedata>
{
"params": {
"1": {
"aliases": [
"value"
],
"label": "Value",
"description": "Value to turn into a boolean. \"1\", \"y\", \"yes\", \"t\" or \"true\" will turn into \"true\"; \"0\", \"n\", \"no\", \"f\" or \"false\" will turn into \"false\". Case insensitive.",
"type": "boolean",
"suggested": true
},
"default": {
"label": "Default",
"description": "Default value to fall back to if the passed value is empty. Accepts the same values as the value parameter.",
"type": "boolean",
"autovalue": "false"
},
"default-invalid": {
"label": "Default for invalid values",
"description": "Default value for invalid values. Accepts the same values as the \"values\" parameter, or an empty string.",
"type": "boolean",
"autovalue": "false"
}
},
"description": "Parse a boolean argument (\"y\", \"yes\", \"1\", \"true\", \"t\"; \"n\", \"no\", \"0\", \"false\", \"f\") and turn it into either \"true\" or \"false\".",
"paramOrder": [
"1",
"default",
"default-invalid"
]
}
</templatedata>
== Examples ==

<syntaxhighlight inline lang="wikitext">{{boolean|yes}}</syntaxhighlight> -> {{boolean|yes}}

<syntaxhighlight inline lang="wikitext">{{boolean|Yes}}</syntaxhighlight> -> {{boolean|Yes}}

<syntaxhighlight inline lang="wikitext">{{boolean|N}}</syntaxhighlight> -> {{boolean|N}}

<syntaxhighlight inline lang="wikitext">{{boolean||default=false}}</syntaxhighlight> -> {{boolean||default=false}}

<syntaxhighlight inline lang="wikitext">{{boolean||default=yes}}</syntaxhighlight> -> {{boolean||default=yes}}

<syntaxhighlight inline lang="wikitext">{{boolean|asdf|default-invalid=invalid}}</syntaxhighlight> -> {{boolean|asdf|default-invalid=invalid}}

</noinclude>

Template:Boolean

2025-03-02T07:42:53Z

Knuxify: Created page with "<includeonly>{{#switch: {{lc: {{#if: {{{value|}}}|{{{value}}}|{{#if: {{{1|}}}|{{{1}}}|{{{default|false}}}}}}}}} |y|yes|true=true |n|no|false=false |{{#if: {{{default-invalid|false}}}|{{{boolean|{{{default-invalid|false}}}}}}||}} }}</includeonly><noinclude> <templatedata> { "params": { "1": { "aliases": [ "value" ], "label": "Value", "description": "Value to turn into a boolean. \"y\", \"yes\" or \"true\" will turn into \"true\"; \"n\", \"no\"..."

<includeonly>{{#switch: {{lc: {{#if: {{{value|}}}|{{{value}}}|{{#if: {{{1|}}}|{{{1}}}|{{{default|false}}}}}}}}}
|y|yes|true=true
|n|no|false=false
|{{#if: {{{default-invalid|false}}}|{{{boolean|{{{default-invalid|false}}}}}}||}}
}}</includeonly><noinclude>
<templatedata>
{
"params": {
"1": {
"aliases": [
"value"
],
"label": "Value",
"description": "Value to turn into a boolean. \"y\", \"yes\" or \"true\" will turn into \"true\"; \"n\", \"no\" or \"false\" will turn into \"false\". Case insensitive.",
"type": "boolean",
"suggested": true
},
"default": {
"label": "Default",
"description": "Default value to fall back to if the passed value is empty. Accepts the same values as the value parameter.",
"type": "boolean",
"autovalue": "false"
},
"default-invalid": {
"label": "Default for invalid values",
"description": "Default value for invalid values. Accepts the same values as the \"values\" parameter, or an empty string.",
"type": "boolean",
"autovalue": "false"
}
},
"description": "Parse a boolean argument (\"y\", \"yes\", \"n\", \"no\", ...) and turn it into either \"true\" or \"false\".",
"paramOrder": [
"1",
"default",
"default-invalid"
]
}
</templatedata>
== Examples ==

<syntaxhighlight inline lang="wikitext">{{boolean|yes}}</syntaxhighlight> -> {{boolean|yes}}

<syntaxhighlight inline lang="wikitext">{{boolean|Yes}}</syntaxhighlight> -> {{boolean|Yes}}

<syntaxhighlight inline lang="wikitext">{{boolean|N}}</syntaxhighlight> -> {{boolean|N}}

<syntaxhighlight inline lang="wikitext">{{boolean||default=false}}</syntaxhighlight> -> {{boolean||default=false}}

<syntaxhighlight inline lang="wikitext">{{boolean||default=yes}}</syntaxhighlight> -> {{boolean||default=yes}}

<syntaxhighlight inline lang="wikitext">{{boolean|asdf|default-invalid=invalid}}</syntaxhighlight> -> {{boolean|asdf|default-invalid=invalid}}

</noinclude>

User:Knuxify/Draft:Getting started

2025-02-27T21:31:55Z

Knuxify: Created page with "This page serves as an introduction to the basics of mainlining. == Prerequisites == * A computer running Linux, which will handle building the kernel. ** If you're on Windows, you can use WSL (though flashing the kernel to your device might be a bit challenging, TODO). ** (Note about recommended specs goes here; faster hardware is better, but only necessary bits are rebuilt on subsequent builds; also mention ccache?) * Some familiarity with the Linux shell and User:..."

This page serves as an introduction to the basics of mainlining.

== Prerequisites ==

* A computer running Linux, which will handle building the kernel.
** If you're on Windows, you can use WSL (though flashing the kernel to your device might be a bit challenging, TODO).
** (Note about recommended specs goes here; faster hardware is better, but only necessary bits are rebuilt on subsequent builds; also mention ccache?)
* Some familiarity with the Linux shell and [[User:Knuxify/Draft:C crash course|C programming language syntax]] is recommended.

== Getting to know your device and SoC ==

{{todo|These are both topics worthy of their own page. Some things to mention here:

* Finding out whether the SoC is supported to mainline and, if so, how well.
* Finding out what components your device has (it's nice to keep a table!)}}

== Preparing the build environment ==

In order to mainline a device, we need to be able to cross-compile the Linux kernel for it.

=== Downloading the Linux kernel source code ===

Depending on your SoC's support status:

* There may be an up-to-date maintained [[close-to mainline]] fork of the Linux kernel for your device's SoC; if there is one, start from it.
* If there is no dedicated fork for your device's SoC, or the fork is out of date, start with either:
** '''The latest stable tag''' directly from Torvalds' tree (see [https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/] or <code>github.com/torvalds/linux</code>).
** For very new SoCs with ongoing work, you may want to use the '''linux-next tree''' instead.

If you're on GitHub, you can fork [https://github.com/torvalds/linux the torvalds/linux repository] and start from there.

Once you have your kernel cloned, switch to the latest tag, then create a new feature branch from it:

<syntaxhighlight lang="shell-session">
$ git checkout v6.14 # replace 6.14 with latest kernel version
$ git checkout -b codename-mainline # git checkout -b creates a new branch based on current HEAD and checks out into it
</syntaxhighlight>

{{todo|Link to some nice guide on git here (and probably elsewhere in the page)}}

=== Cross-compiler setup ===

{{todo|Explain cross-compiler setup; where to get toolchains (AUR for Arch users? Linaro?), postmarketOS envkernel.sh}}

=== Selecting/creating a defconfig ===

The '''kernel config''' dictates which drivers and platform-specific support bits (including DTBs) get built. There are a handful of pre-made configs, called '''defconfigs''', in <code>arch/{arm,arm64,...}/configs</code> - use <code>make name_defconfig</code> to build them.

{{todo|Common ARM(64) config? Which options to select/unselect? pmbootstrap kconfig check might be useful here}}

=== Adding a device tree for your device ===

Devices using ARM chipsets use [[devicetree]]s to describe the hardware. See [[Devicetree/Writing a Linux device tree]] for a guide.

=== Building the kernel ===

{{todo|<code>make -j$(nproc)</code>}}

=== Packaging the kernel into a boot image ===

{{todo|See how I do it in [https://github.com/refractionware/linux/blob/meta/tools/mainline-tools mainline-tools], mention pmbootstrap build --envkernel?}}

Then, flash the resulting kernel to the device.

== Getting the kernel to boot ==

{{todo|UART, DTBO trickery}}

== See also ==

{{todo|pmOS wiki has links to talks and resources}}

Category:To-do items

2025-02-27T21:00:13Z

Knuxify: Created page with "Pages containing to-do items. All pages using the <code>todo</code> template are automatically added here."

Pages containing to-do items. All pages using the [[Template:Todo|<code>todo</code> template]] are automatically added here.

Template:Todo

2025-02-27T20:58:59Z

Knuxify:

<templatestyles src="Todo/style.css"/><includeonly>{{Icon box
| box-icons = [[File:Red warning icon.svg|20px|link=|TODO]]
| box-text = <b>TODO:</b> {{{1}}}
| border-color = #b60000
| border-width = 1px
| background = #fdd1d1
| class = box-todo
}}{{#if: {{{nocategory|}}}||[[Category:To-do items]]}}</includeonly><noinclude>
<templatedata>
{
"params": {
"1": {
"label": "Text",
"description": "Text to place in the box",
"type": "unbalanced-wikitext",
"required": true
},
"nocategory": {
"label": "No category",
"description": "If true/yes, do not add this page to the \"To-do items\" category.",
"type": "boolean"
}
},
"description": "TODO box containing a to-do item. Also adds the page to the \"To-do items\" category; this behavior can be disabled with the \"nocategory\" parameter.",
"format": "inline"
}
</templatedata>

== Example ==

<nowiki>{{todo|This is '''yet to be done'''.}}</nowiki>

{{todo|This is '''yet to be done'''.|nocategory=yes}}
</noinclude>

File:Red warning icon.svg

2025-02-27T20:57:11Z

Knuxify: == Licensing == {{MIT|1=2011-2019 [https://phabricator.wikimedia.org/diffusion/GOJU/browse/master/AUTHORS.txt OOjs UI Team and other contributors]}}

== Summary ==
== Licensing ==
{{MIT|1=2011-2019 [https://phabricator.wikimedia.org/diffusion/GOJU/browse/master/AUTHORS.txt OOjs UI Team and other contributors]}}

Template:Todo/style.css

2025-02-27T20:55:17Z

Knuxify: Created page with "html.skin-theme-clientpref-night .box-todo { color: #fff !important; background-color: #5c1e1e !important; border-color: #c64242 !important; } @media (prefers-color-scheme: dark) { html.skin-theme-clientpref-os .box-todo { color: #fff !important; background-color: #5c1e1e !important; border-color: #c64242 !important; } }"

html.skin-theme-clientpref-night .box-todo {
color: #fff !important;
background-color: #5c1e1e !important;
border-color: #c64242 !important;
}

@media (prefers-color-scheme: dark) {
html.skin-theme-clientpref-os .box-todo {
color: #fff !important;
background-color: #5c1e1e !important;
border-color: #c64242 !important;
}
}

Template:Todo

2025-02-27T20:54:12Z

Knuxify: Created page with "<templatestyles src="Todo/style.css"/><includeonly>{{Icon box | box-icons = TODO | box-text = <b>TODO:</b> {{{1}}} | border-color = #b60000 | border-width = 1px | background = #fdd1d1 | class = box-todo }}{{#if: {{{nocategory|}}}||Category:Todo Items}}</includeonly><noinclude> <templatedata> { "params": { "1": { "label": "Text",..."

<templatestyles src="Todo/style.css"/><includeonly>{{Icon box
| box-icons = [[File:Red warning icon.svg|20px|link=|TODO]]
| box-text = <b>TODO:</b> {{{1}}}
| border-color = #b60000
| border-width = 1px
| background = #fdd1d1
| class = box-todo
}}{{#if: {{{nocategory|}}}||[[Category:Todo Items]]}}</includeonly><noinclude>
<templatedata>
{
"params": {
"1": {
"label": "Text",
"description": "Text to place in the box",
"type": "unbalanced-wikitext",
"required": true
},
"nocategory": {
"label": "No category",
"description": "If true/yes, do not add this page to the \"To-do items\" category.",
"type": "boolean"
}
},
"description": "TODO box containing a to-do item. Also adds the page to the \"To-do items\" category; this behavior can be disabled with the \"nocategory\" parameter.",
"format": "inline"
}
</templatedata>

== Example ==

<nowiki>{{todo|This is '''yet to be done'''.}}</nowiki>

{{todo|This is '''yet to be done'''.|nocategory=yes}}
</noinclude>

User:Knuxify/Draft:Devicetree take 2

2025-02-27T20:42:15Z

Knuxify: Blanked the page

Devicetree/Bindings

2025-02-22T07:38:11Z

Knuxify:

{{Navbox devicetree}}
Devicetrees are validated using '''devicetree schema'''; this schema specifies allowed properties for nodes based on their <code>compatible</code> string. Devicetree schema is defined through '''bindings''', YAML files containing schema information (older bindings use TXT format, but this is deprecated).

Bindings for most Linux components can be found in <code>Documentation/devicetree/bindings</code>; there is also a [https://github.com/devicetree-org/dt-schema core DT schema] defining the most basic components and syntax.

== Validating DT bindings ==

The Linux kernel has tools for validating devicetree schema bindings. Getting the DT binding check to pass is required for upstreaming the binding.

To verify all DT bindings, run:

<syntaxhighlight lang="shell-session">
$ make dt_binding_check
</syntaxhighlight>

You can also verify only a specific binding by providing its filename in the <code>DT_SCHEMA_FILES</code> option. This option takes either a filename or a directory name:

<syntaxhighlight lang="shell-session">
$ make dt_binding_check DT_SCHEMA_FILES=brcm,bcm590xx.yaml # Checks all bindings named brcm,bcm590xx.yaml
$ make dt_binding_check DT_SCHEMA_FILES=qcom # Checks all bindings in any (sub)folder named "qcom"
$ make dt_binding_check DT_SCHEMA_FILES=/gpio/ # Checks all bindings in /gpio folder
</syntaxhighlight>

To verify a DTS file against a DT schema, build the DTB target directly and provide the <code>CHECK_DTBS=y</code> option alongside <code>DT_SCHEMA_FILES</code>:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb
</syntaxhighlight>

== See also ==

* From Linux kernel documentation:
** [https://docs.kernel.org/devicetree/bindings/writing-schema.html Writing Devicetree Bindings in json-schema]
** [https://docs.kernel.org/devicetree/bindings/writing-bindings.html DOs and DON’Ts for designing and writing Devicetree bindings]
** [https://docs.kernel.org/devicetree/bindings/submitting-patches.html Submitting Devicetree (DT) binding patches]

Devicetree/DTS syntax

2025-02-20T18:20:34Z

Knuxify: /* TODOs */

{{Navbox devicetree}}

This page serves as a guide to the device tree source (DTS) file syntax.

== TODOs ==

* Quick intro to explain how things are typically laid out in ARM chips, buses like I2C, etc. - how <code>reg</code> addresses work, how DTS syntax describes this layout
* Split up into more granular subsections

== Basic DTS syntax ==

Here is a very simple DTS file to explain the basics of what you might see in a device tree source file:

{{SyntaxHighlight header|foo.dts}}
<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};

node2@2000 {
compatible = "vendor,bar";
reg = <0x2000 0xa4>;
vendor,baz-companion = <&my_node>;
};

i2c-controller@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;

#address-cells = <1>;
#size-cells = <0>;

sensor@10 {
compatible = "vendor,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

In this example, we define an empty DTS; in its root node (<code>/</code>), we place three nodes: a node named "node1" with a label "my_node" at address 0x1000, a node named "node2" at address 0x2000, and a node named "i2c-controller" at address 0x3000.

A node contains:
* A <code>compatible</code> value (here <code>"vendor,foo"</code>). This specifies what kind of component it is; Linux uses this information to load the correct driver.
* A <code>reg</code> value. In this case, the first parameter is the base address in memory (<code>0x1000</code>), and the second is the size it occupies (<code>0x54</code>). The amount of cells for the address and size are specified by the <code>#address-cells</code> and <code>#size-cells</code> properties of the root node, respectively.
** You might notice that the i2c-controller node defines another set of these <code>#address-cells</code> and <code>#size-cells</code> properties - this is because I2C devices contain their own subdevices with addresses ranging from 0x08 to 0x7f (todo verify), and they do not use a size.
* A custom vendor-specific property, <code>vendor,bar-factor</code>, which takes a number.

On node 2 there is also a property, <code>vendor,baz-companion</code>, which takes a pointer to another node - here the one we labeled "my_node".

== Working with included DTSIs ==

Very often you'll see <code>#include</code> directives; these can either include header files (which usually contain constants defined with <code>#define</code>, similarly to C) or other DTSes. DTS files meant for inclusion are called '''DTS includes''' and use the '''.dtsi''' file extension.

Usually, an SoC will have a common DTS include with all of the relevant nodes for that SoC. A board's DTS will then include the SoC DTSI.

As an example, here's a very bare-bones DTSI for a fictional "FOO1234" SoC:

{{SyntaxHighlight header|foo1234.dtsi}}
<syntaxhighlight lang="dts" line>
/*
* Common DTSI for Foobar FOO1234 System-on-a-Chip.
*/
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

cpus {
#address-cells = <1>;
#size-cells = <0>;

cpu0: cpu@0 {
device_type = "cpu";
compatible = "arm,cortex-a7";
reg = <0>;
clock-frequency = <1000000000>;
};
};

soc {
/* ... */

i2c1: i2c@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;
status = "disabled";
};

i2c2: i2c@4000 {
compatible = "vendor,foobar-i2c";
reg = <0x4000 0x800>;
status = "disabled";
};

i2c3: i2c@5000 {
compatible = "vendor,foobar-i2c";
reg = <0x5000 0x800>;
status = "disabled";
};

/* ... */
};
};
</syntaxhighlight>

Here is a DTS for a fictional device named "Quox Haystack" that uses the FOO1234 SoC:

{{SyntaxHighlight header|foo1234-quox-haystack.dts}}
<syntaxhighlight lang="dts" line>
/*
* Device tree source for Quox Haystack based on FOO1234 SoC
*/
/dts-v1/;

#include "foo1234.dtsi"

/ {
compatible = "quox,haystack", "foobar,foo1234";

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x40000000>;
};
};

&i2c1 {
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};
</syntaxhighlight>

Some interesting things to look out for:

* The board DTS includes the SoC DTSI with a <code>#include "foo1234.dtsi"</code> directive.
* We re-define the root <code>/</code> node, and inside of it we place a <code>memory</code> node. This node, as well as the <code>compatible</code>, will be merged into the root node of the included DTSI.
* Outside of the root node, there is a node with a name starting with an ampersand (<code>&i2c1</code>); this signifies a pointer to a labeled node (see node labels in the previous example). Like with the root node above, the contents of this node will be merged with the contents of the node with this label in the SoC DTSI.
** A similar effect could be achieved by overriding the <code>i2c1</code> node under the root node, where it's located in the SoC DTSI (though the preferred way is to do it with a label - we do it here for demonstration purposes):
*: {{SyntaxHighlight header|foo1234-quox-haystack.dts}}<syntaxhighlight lang="dts" line start="3">
/ {
compatible = "quox,haystack", "foobar,foo1234";

/* ... */

i2c1: i2c@3000 {
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

For a more visual example - the merged version of these two files would look something like this:

<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

compatible = "quox,haystack", "foobar,foo1234";

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x40000000>;
};

cpus {
#address-cells = <1>;
#size-cells = <0>;

cpu0: cpu@0 {
device_type = "cpu";
compatible = "arm,cortex-a7";
reg = <0>;
clock-frequency = <1000000000>;
};
};

soc {
/* ... */

i2c1: i2c@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};

i2c2: i2c@4000 {
compatible = "vendor,foobar-i2c";
reg = <0x4000 0x800>;
status = "disabled";
};

i2c3: i2c@5000 {
compatible = "vendor,foobar-i2c";
reg = <0x5000 0x800>;
status = "disabled";
};

/* ... */
};
};
</syntaxhighlight>

Template:Note/style.css

2025-02-20T18:18:48Z

Knuxify:

html.skin-theme-clientpref-night .box-note {
color: #fff !important;
background-color: #261c09 !important;
border-color: #6a481c !important;
}

@media (prefers-color-scheme: dark) {
html.skin-theme-clientpref-os .box-note {
color: #fff !important;
background-color: #261c09 !important;
border-color: #6a481c !important;
}
}

Template:Icon box

2025-02-20T18:16:47Z

Knuxify: add class property

<includeonly><table role="{{{role|text container}}}" {{#if: {{{class|}}}|class="{{{class}}}" }} style="color: {{{color|inherit}}}; background-color: {{{background|inherit}}}; border: {{{border-width|1px}}} {{{border-style|solid}}} {{{border-color|#eaecf0}}}; margin: 4px {{#if: {{{margin|}}}|10%|0}}; border-collapse: collapse;"><tr>
<td style="padding: 2px 0 2px 0.9em; text-align: center; line-height: 1;"><span style="white-space: nowrap;">{{{box-icons}}}</span></td>
<td style="padding: {{{padding|0.35em}}} 0.9em; width: 100%;">{{{box-text}}}</td>
</tr></table></includeonly><noinclude>
<templatedata>
{
"params": {
"role": {
"label": "HTML role",
"description": "HTML accessible role parameter to add to the box.",
"type": "string",
"autovalue": "text container"
},
"color": {
"label": "Text color",
"type": "string",
"description": "Text color in any format supported by CSS (hex, rgb(...), ...)",
"autovalue": "inherit"
},
"background": {
"label": "Background color",
"type": "string",
"description": "Background color in any format supported by CSS (hex, rgb(...), ...)",
"autovalue": "inherit"
},
"border-width": {
"label": "Border width",
"type": "string",
"description": "Border width with unit",
"example": "1px",
"autovalue": "1px"
},
"border-style": {
"label": "Border style",
"description": "CSS border-style value",
"example": "solid",
"type": "string",
"autovalue": "solid"
},
"border-color": {
"label": "Border color",
"description": "Text color in any format supported by CSS (hex, rgb(...), ...)",
"type": "string",
"autovalue": "#eaecf0"
},
"box-icons": {
"label": "Box icons",
"description": "Standard wikitext containing the icons to place inside of the box, see example syntax.",
"type": "content",
"suggested": true
},
"padding": {
"label": "Padding",
"description": "Padding to add to the box, with the unit",
"type": "string",
"autovalue": "0.35em"
},
"box-text": {
"label": "Box text",
"description": "Text inside of the box.",
"type": "content",
"required": true
},
"margin": {
"label": "Enable margin",
"description": "If set, adds a margin from the sides of the box.",
"type": "boolean",
"autovalue": "false",
"suggested": true
},
"class": {
"label": "HTML class",
"description": "HTML class/classes to add to the box, space-separated.",
"type": "string"
}
},
"description": "Floating box with an icon and background. Used for licensing templates, Template:Note and similar boxes.",
"format": "block",
"paramOrder": [
"box-text",
"box-icons",
"margin",
"color",
"background",
"border-color",
"border-style",
"border-width",
"padding",
"role",
"class"
]
}
</templatedata>
</noinclude>

Devicetree

2025-02-20T18:10:40Z

Knuxify: /* Introduction */

{{Navbox devicetree}}
The '''devicetree''' (device tree, DT) is a tree structure that describes the hardware register layout and configuration of a device. In the Linux kernel, as well as in other DT-using projects like U-Boot, it is the primary method of discovering peripherals on embedded platforms such as ARM.

Devicetrees are written in a plaintext format known as the '''Device Tree Source (DTS)''' format. The DTS is later compiled into a '''Device Tree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

Devicetrees are validated using '''devicetree schema''', which is described in '''DT bindings'''; see [[/Bindings]] for more information.

== Introduction ==

An SoC (System-on-Chip) comprises of many subcomponents: timer, clock controller, I2C/SPI controller, GPIO, interrupt controller, SDHCI storage, USB, and so on. Each needs its own driver, and for most parts the exact implementation differs between chip manufacturers. Most of them expose a static range of addresses in MMIO (memory-mapped IO) space that the system can use to communicate with them.

Additionally, there may be other peripherals connected to the system - often through a bus like I2C or SPI, or as a simple device controlled by a GPIO.

On a standard x86 system, peripherals are usually autodetected, either through ACPI, or by being on a bus like PCI or USB. On most embedded platforms like ARM, however, there is no such autodetection method, and the hardware needs to be described manually.

The solution for this, used by both the Linux kernel, as well as a variety of other projects like U-Boot, is the '''devicetree'''.

The following is a very simple example DTS (device tree source):

<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};

i2c-controller@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;

#address-cells = <1>;
#size-cells = <0>;

sensor@10 {
compatible = "vendor,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

{{note|For a full guide to DTS syntax, see [[/DTS syntax]].}}

The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).

Devicetrees are written in the '''DTS''' (Device Tree Source) format; the source file can then be compiled into a '''DTB''' (Device Tree Blob), which software can parse to get all the necessary information about a given platform.

On modern systems, the bootloader loads the DTB into a set place in memory; the Linux kernel then decodes the information from the DTB and initializes all the components based on it. (On 32-bit ARM, which predates widespread adoption of DTBs and DTB-capable bootloaders, an alternative mechanism exists in Linux to load a DTB appended to the kernel image).

== History ==

The initial version of the devicetree standard was developed as part of the OpenFirmware initiative; from this standard, the Flattened Device Tree (FDT) emerged and was adopted by the Linux kernel for PowerPC platforms. Around 2009, discussions began to include FDT support for ARM[1]. It was eventually added and first device trees began to appear in 2011[2], although the format didn't see wider usage (especially in vendor kernels) until around 2013/2014.

Nowadays, the devicetree standard is managed by [https://www.devicetree.org/ devicetree.org]; they maintain the latest version of the [https://www.devicetree.org/specifications Devicetree Specification] and the related set of [https://github.com/devicetree-org/dt-schema core DT schema].

Before the introduction of devicetrees, ARM kernels used '''board files'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.

== Devicetree sources in the Linux kernel ==

TODO

== Verifying DTS files ==

The Linux kernel has tools for making sure that device tree sources (DTS) use the bindings correctly. These are useful when writing device sources; getting
the DT checks to pass is also mandatory for upstream inclusion of a DTS.

To verify all DTS files built with the selected defconfig options, run:

<syntaxhighlight lang="shell-session">
$ make dtbs_check
</syntaxhighlight>

To verify a specific DTS, build the DTB target directly and provide the <code>CHECK_DTBS=y</code> option:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y qcom/sm8450-hdk.dtb
</syntaxhighlight>

You can also test a DTS against a specific subset of bindings by providing the <code>DT_SCHEMA_FILES</code> variable as mentioned in the previous section:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb
</syntaxhighlight>

== Working with DTC ==

The <code>dtc</code> tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS. (TODO: add instructions)

== See also ==

* From Linux kernel documentation:
** [https://docs.kernel.org/devicetree/bindings/dts-coding-style.html Devicetree Sources (DTS) Coding Style]
* On elinux.org:
** [https://elinux.org/Device_Tree_Reference Device Tree Reference]
** [https://elinux.org/Device_Tree_Reference Device Tree Usage]

== References ==

todo enable refs extension

[1] https://www.mail-archive.com/linux-embedded@vger.kernel.org/msg01721.html
[2] https://github.com/torvalds/linux/commit/b85a3ef4ac65169b65fd2fe9bec7912bbf475ba4

Devicetree

2025-02-20T18:10:14Z

Knuxify: /* Introduction */

{{Navbox devicetree}}
The '''devicetree''' (device tree, DT) is a tree structure that describes the hardware register layout and configuration of a device. In the Linux kernel, as well as in other DT-using projects like U-Boot, it is the primary method of discovering peripherals on embedded platforms such as ARM.

Devicetrees are written in a plaintext format known as the '''Device Tree Source (DTS)''' format. The DTS is later compiled into a '''Device Tree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

Devicetrees are validated using '''devicetree schema''', which is described in '''DT bindings'''; see [[/Bindings]] for more information.

== Introduction ==

An SoC (System-on-Chip) comprises of many subcomponents: timer, clock controller, I2C/SPI controller, GPIO, interrupt controller, SDHCI storage, USB, and so on. Each needs its own driver, and for most parts the exact implementation differs between chip manufacturers. Most of them expose a static range of addresses in MMIO (memory-mapped IO) space that the system can use to communicate with them.

Additionally, there may be other peripherals connected to the system - often through a bus like I2C or SPI, or as a simple device controlled by a GPIO.

On a standard x86 system, peripherals are usually autodetected, either through ACPI, or by being on a bus like PCI or USB. On most embedded platforms like ARM, however, there is no such autodetection method, and the hardware needs to be described manually.

The solution for this, used by both the Linux kernel, as well as a variety of other projects like U-Boot, is the '''devicetree'''.

The following is a very simple example DTS (device tree source):

{{note|For a full guide to DTS syntax, see [[/DTS syntax]].}}

<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};

i2c-controller@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;

#address-cells = <1>;
#size-cells = <0>;

sensor@10 {
compatible = "vendor,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).

Devicetrees are written in the '''DTS''' (Device Tree Source) format; the source file can then be compiled into a '''DTB''' (Device Tree Blob), which software can parse to get all the necessary information about a given platform.

On modern systems, the bootloader loads the DTB into a set place in memory; the Linux kernel then decodes the information from the DTB and initializes all the components based on it. (On 32-bit ARM, which predates widespread adoption of DTBs and DTB-capable bootloaders, an alternative mechanism exists in Linux to load a DTB appended to the kernel image).

== History ==

The initial version of the devicetree standard was developed as part of the OpenFirmware initiative; from this standard, the Flattened Device Tree (FDT) emerged and was adopted by the Linux kernel for PowerPC platforms. Around 2009, discussions began to include FDT support for ARM[1]. It was eventually added and first device trees began to appear in 2011[2], although the format didn't see wider usage (especially in vendor kernels) until around 2013/2014.

Nowadays, the devicetree standard is managed by [https://www.devicetree.org/ devicetree.org]; they maintain the latest version of the [https://www.devicetree.org/specifications Devicetree Specification] and the related set of [https://github.com/devicetree-org/dt-schema core DT schema].

Before the introduction of devicetrees, ARM kernels used '''board files'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.

== Devicetree sources in the Linux kernel ==

TODO

== Verifying DTS files ==

The Linux kernel has tools for making sure that device tree sources (DTS) use the bindings correctly. These are useful when writing device sources; getting
the DT checks to pass is also mandatory for upstream inclusion of a DTS.

To verify all DTS files built with the selected defconfig options, run:

<syntaxhighlight lang="shell-session">
$ make dtbs_check
</syntaxhighlight>

To verify a specific DTS, build the DTB target directly and provide the <code>CHECK_DTBS=y</code> option:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y qcom/sm8450-hdk.dtb
</syntaxhighlight>

You can also test a DTS against a specific subset of bindings by providing the <code>DT_SCHEMA_FILES</code> variable as mentioned in the previous section:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb
</syntaxhighlight>

== Working with DTC ==

The <code>dtc</code> tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS. (TODO: add instructions)

== See also ==

* From Linux kernel documentation:
** [https://docs.kernel.org/devicetree/bindings/dts-coding-style.html Devicetree Sources (DTS) Coding Style]
* On elinux.org:
** [https://elinux.org/Device_Tree_Reference Device Tree Reference]
** [https://elinux.org/Device_Tree_Reference Device Tree Usage]

== References ==

todo enable refs extension

[1] https://www.mail-archive.com/linux-embedded@vger.kernel.org/msg01721.html
[2] https://github.com/torvalds/linux/commit/b85a3ef4ac65169b65fd2fe9bec7912bbf475ba4

Template:Note

2025-02-20T18:09:35Z

Knuxify:

<templatestyles src="Note/style.css"/><includeonly>{{Icon box
| box-icons = [[File:Reference icon.svg|20px|link=|Note]]
| box-text = {{{1}}}
| border-color = #ac6600
| border-width = 1px
| background = #f6efe5
| class = box-note
}}</includeonly><noinclude>
<templatedata>
{
"params": {
"1": {
"label": "Text",
"description": "Text to place in the box",
"type": "unbalanced-wikitext",
"required": true
}
},
"description": "Note box containing a note.",
"format": "inline"
}
</templatedata>

== Example ==

<nowiki>{{note|This is quite '''note-worthy'''.}}</nowiki>

{{note|This is quite '''note-worthy'''.}}
</noinclude>

File:Reference icon.svg

2025-02-20T18:08:37Z

Knuxify:

Template:Icon box

2025-02-20T18:07:37Z

Knuxify:

<includeonly><table role="{{{role|text container}}}" style="color: {{{color|inherit}}}; background-color: {{{background|inherit}}}; border: {{{border-width|1px}}} {{{border-style|solid}}} {{{border-color|#eaecf0}}}; margin: 4px {{#if: {{{margin|}}}|10%|0}}; border-collapse: collapse;"><tr>
<td style="padding: 2px 0 2px 0.9em; text-align: center; line-height: 1;"><span style="white-space: nowrap;">{{{box-icons}}}</span></td>
<td style="padding: {{{padding|0.35em}}} 0.9em; width: 100%;">{{{box-text}}}</td>
</tr></table></includeonly><noinclude>
<templatedata>
{
"params": {
"role": {
"label": "HTML role",
"description": "HTML accessible role parameter to add to the box.",
"type": "string",
"autovalue": "text container"
},
"color": {
"label": "Text color",
"type": "string",
"description": "Text color in any format supported by CSS (hex, rgb(...), ...)",
"autovalue": "inherit"
},
"background": {
"label": "Background color",
"type": "string",
"description": "Background color in any format supported by CSS (hex, rgb(...), ...)",
"autovalue": "inherit"
},
"border-width": {
"label": "Border width",
"type": "string",
"description": "Border width with unit",
"example": "1px",
"autovalue": "1px"
},
"border-style": {
"label": "Border style",
"description": "CSS border-style value",
"example": "solid",
"type": "string",
"autovalue": "solid"
},
"border-color": {
"label": "Border color",
"description": "Text color in any format supported by CSS (hex, rgb(...), ...)",
"type": "string",
"autovalue": "#eaecf0"
},
"box-icons": {
"label": "Box icons",
"description": "Standard wikitext containing the icons to place inside of the box, see example syntax.",
"type": "content",
"suggested": true
},
"padding": {
"label": "Padding",
"description": "Padding to add to the box, with the unit",
"type": "string",
"autovalue": "0.35em"
},
"box-text": {
"label": "Box text",
"description": "Text inside of the box.",
"type": "content",
"required": true
},
"margin": {
"label": "Enable margin",
"description": "If set, adds a margin from the sides of the box.",
"type": "boolean",
"autovalue": "false",
"suggested": true
}
},
"description": "Floating box with an icon and background. Used for licensing templates, Template:Note and similar boxes.",
"format": "block",
"paramOrder": [
"box-text",
"box-icons",
"margin",
"color",
"background",
"border-color",
"border-style",
"border-width",
"padding",
"role"
]
}
</templatedata>
</noinclude>

Devicetree

2025-02-20T18:07:10Z

Knuxify:

{{Navbox devicetree}}
The '''devicetree''' (device tree, DT) is a tree structure that describes the hardware register layout and configuration of a device. In the Linux kernel, as well as in other DT-using projects like U-Boot, it is the primary method of discovering peripherals on embedded platforms such as ARM.

Devicetrees are written in a plaintext format known as the '''Device Tree Source (DTS)''' format. The DTS is later compiled into a '''Device Tree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

Devicetrees are validated using '''devicetree schema''', which is described in '''DT bindings'''; see [[/Bindings]] for more information.

== Introduction ==

An SoC (System-on-Chip) comprises of many subcomponents: timer, clock controller, I2C/SPI controller, GPIO, interrupt controller, SDHCI storage, USB, and so on. Each needs its own driver, and for most parts the exact implementation differs between chip manufacturers. Most of them expose a static range of addresses in MMIO (memory-mapped IO) space that the system can use to communicate with them.

Additionally, there may be other peripherals connected to the system - often through a bus like I2C or SPI, or as a simple device controlled by a GPIO.

On a standard x86 system, peripherals are usually autodetected, either through ACPI, or by being on a bus like PCI or USB. On most embedded platforms like ARM, however, there is no such autodetection method, and the hardware needs to be described manually.

The solution for this, used by both the Linux kernel, as well as a variety of other projects like U-Boot, is the '''devicetree'''.

The following is a very simple example DTS (device tree source):

{{note|For a full guide to DTS syntax, see [[/DTS syntax guide]].}}

<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};

i2c-controller@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;

#address-cells = <1>;
#size-cells = <0>;

sensor@10 {
compatible = "vendor,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).

Devicetrees are written in the '''DTS''' (Device Tree Source) format; the source file can then be compiled into a '''DTB''' (Device Tree Blob), which software can parse to get all the necessary information about a given platform.

On modern systems, the bootloader loads the DTB into a set place in memory; the Linux kernel then decodes the information from the DTB and initializes all the components based on it. (On 32-bit ARM, which predates widespread adoption of DTBs and DTB-capable bootloaders, an alternative mechanism exists in Linux to load a DTB appended to the kernel image).

== History ==

The initial version of the devicetree standard was developed as part of the OpenFirmware initiative; from this standard, the Flattened Device Tree (FDT) emerged and was adopted by the Linux kernel for PowerPC platforms. Around 2009, discussions began to include FDT support for ARM[1]. It was eventually added and first device trees began to appear in 2011[2], although the format didn't see wider usage (especially in vendor kernels) until around 2013/2014.

Nowadays, the devicetree standard is managed by [https://www.devicetree.org/ devicetree.org]; they maintain the latest version of the [https://www.devicetree.org/specifications Devicetree Specification] and the related set of [https://github.com/devicetree-org/dt-schema core DT schema].

Before the introduction of devicetrees, ARM kernels used '''board files'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.

== Devicetree sources in the Linux kernel ==

TODO

== Verifying DTS files ==

The Linux kernel has tools for making sure that device tree sources (DTS) use the bindings correctly. These are useful when writing device sources; getting
the DT checks to pass is also mandatory for upstream inclusion of a DTS.

To verify all DTS files built with the selected defconfig options, run:

<syntaxhighlight lang="shell-session">
$ make dtbs_check
</syntaxhighlight>

To verify a specific DTS, build the DTB target directly and provide the <code>CHECK_DTBS=y</code> option:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y qcom/sm8450-hdk.dtb
</syntaxhighlight>

You can also test a DTS against a specific subset of bindings by providing the <code>DT_SCHEMA_FILES</code> variable as mentioned in the previous section:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb
</syntaxhighlight>

== Working with DTC ==

The <code>dtc</code> tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS. (TODO: add instructions)

== See also ==

* From Linux kernel documentation:
** [https://docs.kernel.org/devicetree/bindings/dts-coding-style.html Devicetree Sources (DTS) Coding Style]
* On elinux.org:
** [https://elinux.org/Device_Tree_Reference Device Tree Reference]
** [https://elinux.org/Device_Tree_Reference Device Tree Usage]

== References ==

todo enable refs extension

[1] https://www.mail-archive.com/linux-embedded@vger.kernel.org/msg01721.html
[2] https://github.com/torvalds/linux/commit/b85a3ef4ac65169b65fd2fe9bec7912bbf475ba4

Template:Note

2025-02-20T18:06:58Z

Knuxify: Created page with "<templatestyles src="Note/style.css"/><includeonly>{{Icon box | box-icons = Note | box-text = {{{1}}} | border-color = #ac6600 | border-width = 1px | background = #f6efe5 | class = box-note }}</includeonly><noinclude> <templatedata> { "params": { "1": { "label": "Text", "description": "Text to place in the box", "type": "unbalanced-wikitext",..."

Template:Note/style.css

2025-02-20T18:06:55Z

Knuxify: Created page with ".skin-theme-clientpref-night .box-note { color: #fff !important; background-color: #261c09 !important; border-color: #6a481c !important; } @media (prefers-color-scheme: dark) { .skin-theme-clientpref-os .box-note { color: #fff !important; background-color: #261c09 !important; border-color: #6a481c !important; } }"

.skin-theme-clientpref-night .box-note {
color: #fff !important;
background-color: #261c09 !important;
border-color: #6a481c !important;
}

@media (prefers-color-scheme: dark) {
.skin-theme-clientpref-os .box-note {
color: #fff !important;
background-color: #261c09 !important;
border-color: #6a481c !important;
}
}

Template:Icon box

2025-02-20T18:03:11Z

Knuxify: make no margin the default, replace nomargin option with margin option

<includeonly><table role="{{{role|text container}}}" style="color: {{{color|inherit}}}; background-color: {{{background|inherit}}}; border: {{{border-width|1px}}} {{{border-style|solid}}} {{{border-color|#eaecf0}}}; margin: 4px {{#if: {{{margin|}}}|0|10%}}; border-collapse: collapse;"><tr>
<td style="padding: 2px 0 2px 0.9em; text-align: center; line-height: 1;"><span style="white-space: nowrap;">{{{box-icons}}}</span></td>
<td style="padding: {{{padding|0.35em}}} 0.9em; width: 100%;">{{{box-text}}}</td>
</tr></table></includeonly><noinclude>
<templatedata>
{
"params": {
"role": {
"label": "HTML role",
"description": "HTML accessible role parameter to add to the box.",
"type": "string",
"autovalue": "text container"
},
"color": {
"label": "Text color",
"type": "string",
"description": "Text color in any format supported by CSS (hex, rgb(...), ...)",
"autovalue": "inherit"
},
"background": {
"label": "Background color",
"type": "string",
"description": "Background color in any format supported by CSS (hex, rgb(...), ...)",
"autovalue": "inherit"
},
"border-width": {
"label": "Border width",
"type": "string",
"description": "Border width with unit",
"example": "1px",
"autovalue": "1px"
},
"border-style": {
"label": "Border style",
"description": "CSS border-style value",
"example": "solid",
"type": "string",
"autovalue": "solid"
},
"border-color": {
"label": "Border color",
"description": "Text color in any format supported by CSS (hex, rgb(...), ...)",
"type": "string",
"autovalue": "#eaecf0"
},
"box-icons": {
"label": "Box icons",
"description": "Standard wikitext containing the icons to place inside of the box, see example syntax.",
"type": "content",
"suggested": true
},
"padding": {
"label": "Padding",
"description": "Padding to add to the box, with the unit",
"type": "string",
"autovalue": "0.35em"
},
"box-text": {
"label": "Box text",
"description": "Text inside of the box.",
"type": "content",
"required": true
},
"margin": {
"label": "Enable margin",
"description": "If set, adds a margin from the sides of the box.",
"type": "boolean",
"autovalue": "false",
"suggested": true
}
},
"description": "Floating box with an icon and background. Used for licensing templates, Template:Note and similar boxes.",
"format": "block",
"paramOrder": [
"box-text",
"box-icons",
"margin",
"color",
"background",
"border-color",
"border-style",
"border-width",
"padding",
"role"
]
}
</templatedata>
</noinclude>

Template:SyntaxHighlight header

2025-02-20T18:01:51Z

Knuxify: move template source above template data

<includeonly><div class="mw-highlight mainline-syntaxhighlight-header" style="background: var(--background-color-neutral,#eaecf0); color: var(--color-base,#202122); margin-bottom: -1em; padding: 0.35em 1.05em; border: 1px solid var(--border-color-muted,#dadde3); border-bottom: none; font-family: monospace; font-weight: bold;">{{{text|{{{1|}}}}}}</div></includeonly><noinclude>
<templatedata>
{
"params": {
"text": {
"aliases": [
"1"
],
"label": "Text",
"description": "Text to place in the header.",
"type": "unbalanced-wikitext",
"required": true
}
},
"description": "Header that can be placed before a <syntaxhighlight> tag to e.g. show a filename or block title.",
"format": "inline"
}
</templatedata>

== Example ==

<pre><nowiki>
{{SyntaxHighlight header|foo.dts}}
<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};
};
</syntaxhighlight>
</nowiki></pre>

{{SyntaxHighlight header|foo.dts}}
<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};
};
</syntaxhighlight>
</noinclude>

User:Knuxify/Draft:Devicetree take 2

2025-02-20T17:47:23Z

Knuxify:

{{Navbox devicetree}}
The '''devicetree''' (device tree, DT) is a tree structure that describes the hardware register layout and configuration of a device.

Devicetrees are written in a plaintext format known as the '''Devicetree Source (DTS)''' format. The DTS is later compiled into a '''Devicetree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

Devicetrees are validated using '''devicetree schema''', which is described in '''DT bindings'''; see [[/Bindings]] for more information.

In the Linux kernel, as well as in other DT-using projects like U-Boot, it is the primary method of discovering peripherals on embedded platforms such as ARM.

== Introduction ==

An SoC (System-on-Chip) comprises of many subcomponents: timer, clock controller, I2C/SPI controller, GPIO, interrupt controller, SDHCI storage, USB, and so on. Each needs its own driver, and for most parts the exact implementation differs between chip manufacturers. Most of them expose a static range of addresses in MMIO (memory-mapped IO) space that the system can use to communicate with them.

Additionally, there may be other peripherals connected to the system - often through a bus like I2C or SPI, or as a simple device controlled by a GPIO.

On a standard x86 system, peripherals are usually autodetected, either through ACPI, or by being on a bus like PCI or USB. On most embedded platforms like ARM, however, there is no such autodetection method, and the hardware needs to be described manually.

The solution for this, used by both the Linux kernel, as well as a variety of other projects like U-Boot, is the '''devicetree'''.

The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).

Devicetrees are written in the '''DTS''' (Device Tree Source) format; the source file can then be compiled into a '''DTB''' (Device Tree Blob), which software can parse to get all the necessary information about a given platform.

On modern systems, the bootloader loads the DTB into a set place in memory; the Linux kernel then decodes the information from the DTB and initializes all the components based on it. (On 32-bit ARM, which predates widespread adoption of DTBs and DTB-capable bootloaders, an alternative mechanism exists in Linux to load a DTB appended to the kernel image).

User:Knuxify/Draft:Devicetree take 2

2025-02-20T09:20:17Z

Knuxify: Created page with "{{Navbox devicetree}} The '''devicetree''' (device tree, DT) is a tree structure that describes the hardware register layout and configuration of a device. Devicetrees are written in a plaintext format known as the '''Devicetree Source (DTS)''' format. The DTS is later compiled into a '''Devicetree Blob (DTB)'''; in this form, it can be loaded by software/firmware. Devicetrees are validated using '''devicetree schema''', which is described in '''DT bindings'''; see /..."

Devicetree/DTS syntax

2025-02-19T20:03:39Z

Knuxify:

{{Navbox devicetree}}

This page serves as a guide to the device tree source (DTS) file syntax.

== TODOs ==

* Quick intro to explain how things are typically laid out in ARM chips, buses like I2C, etc. - how <code>reg</code> addresses work, how DTS syntax describes this layout

== Basic DTS syntax ==

Here is a very simple DTS file to explain the basics of what you might see in a device tree source file:

{{SyntaxHighlight header|foo.dts}}
<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};

node2@2000 {
compatible = "vendor,bar";
reg = <0x2000 0xa4>;
vendor,baz-companion = <&my_node>;
};

i2c-controller@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;

#address-cells = <1>;
#size-cells = <0>;

sensor@10 {
compatible = "vendor,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

In this example, we define an empty DTS; in its root node (<code>/</code>), we place three nodes: a node named "node1" with a label "my_node" at address 0x1000, a node named "node2" at address 0x2000, and a node named "i2c-controller" at address 0x3000.

A node contains:
* A <code>compatible</code> value (here <code>"vendor,foo"</code>). This specifies what kind of component it is; Linux uses this information to load the correct driver.
* A <code>reg</code> value. In this case, the first parameter is the base address in memory (<code>0x1000</code>), and the second is the size it occupies (<code>0x54</code>). The amount of cells for the address and size are specified by the <code>#address-cells</code> and <code>#size-cells</code> properties of the root node, respectively.
** You might notice that the i2c-controller node defines another set of these <code>#address-cells</code> and <code>#size-cells</code> properties - this is because I2C devices contain their own subdevices with addresses ranging from 0x08 to 0x7f (todo verify), and they do not use a size.
* A custom vendor-specific property, <code>vendor,bar-factor</code>, which takes a number.

On node 2 there is also a property, <code>vendor,baz-companion</code>, which takes a pointer to another node - here the one we labeled "my_node".

== Working with included DTSIs ==

Very often you'll see <code>#include</code> directives; these can either include header files (which usually contain constants defined with <code>#define</code>, similarly to C) or other DTSes. DTS files meant for inclusion are called '''DTS includes''' and use the '''.dtsi''' file extension.

Usually, an SoC will have a common DTS include with all of the relevant nodes for that SoC. A board's DTS will then include the SoC DTSI.

As an example, here's a very bare-bones DTSI for a fictional "FOO1234" SoC:

{{SyntaxHighlight header|foo1234.dtsi}}
<syntaxhighlight lang="dts" line>
/*
* Common DTSI for Foobar FOO1234 System-on-a-Chip.
*/
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

cpus {
#address-cells = <1>;
#size-cells = <0>;

cpu0: cpu@0 {
device_type = "cpu";
compatible = "arm,cortex-a7";
reg = <0>;
clock-frequency = <1000000000>;
};
};

soc {
/* ... */

i2c1: i2c@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;
status = "disabled";
};

i2c2: i2c@4000 {
compatible = "vendor,foobar-i2c";
reg = <0x4000 0x800>;
status = "disabled";
};

i2c3: i2c@5000 {
compatible = "vendor,foobar-i2c";
reg = <0x5000 0x800>;
status = "disabled";
};

/* ... */
};
};
</syntaxhighlight>

Here is a DTS for a fictional device named "Quox Haystack" that uses the FOO1234 SoC:

{{SyntaxHighlight header|foo1234-quox-haystack.dts}}
<syntaxhighlight lang="dts" line>
/*
* Device tree source for Quox Haystack based on FOO1234 SoC
*/
/dts-v1/;

#include "foo1234.dtsi"

/ {
compatible = "quox,haystack", "foobar,foo1234";

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x40000000>;
};
};

&i2c1 {
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};
</syntaxhighlight>

Some interesting things to look out for:

* The board DTS includes the SoC DTSI with a <code>#include "foo1234.dtsi"</code> directive.
* We re-define the root <code>/</code> node, and inside of it we place a <code>memory</code> node. This node, as well as the <code>compatible</code>, will be merged into the root node of the included DTSI.
* Outside of the root node, there is a node with a name starting with an ampersand (<code>&i2c1</code>); this signifies a pointer to a labeled node (see node labels in the previous example). Like with the root node above, the contents of this node will be merged with the contents of the node with this label in the SoC DTSI.
** A similar effect could be achieved by overriding the <code>i2c1</code> node under the root node, where it's located in the SoC DTSI (though the preferred way is to do it with a label - we do it here for demonstration purposes):
*: {{SyntaxHighlight header|foo1234-quox-haystack.dts}}<syntaxhighlight lang="dts" line start="3">
/ {
compatible = "quox,haystack", "foobar,foo1234";

/* ... */

i2c1: i2c@3000 {
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

For a more visual example - the merged version of these two files would look something like this:

<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

compatible = "quox,haystack", "foobar,foo1234";

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x40000000>;
};

cpus {
#address-cells = <1>;
#size-cells = <0>;

cpu0: cpu@0 {
device_type = "cpu";
compatible = "arm,cortex-a7";
reg = <0>;
clock-frequency = <1000000000>;
};
};

soc {
/* ... */

i2c1: i2c@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};

i2c2: i2c@4000 {
compatible = "vendor,foobar-i2c";
reg = <0x4000 0x800>;
status = "disabled";
};

i2c3: i2c@5000 {
compatible = "vendor,foobar-i2c";
reg = <0x5000 0x800>;
status = "disabled";
};

/* ... */
};
};
</syntaxhighlight>

Devicetree/DTS syntax

2025-02-19T20:03:06Z

Knuxify:

{{Navbox devicetree}}

This page serves as a guide to the device tree source (DTS) file syntax.

== TODOs ==

* Look through the whole thing again and rewrite. The writing is rather awkward...
* Quick intro to explain how things are typically laid out in ARM chips, buses like I2C, etc. - how <code>reg</code> addresses work, how DTS syntax describes this layout

== Basic DTS syntax ==

Here is a very simple DTS file to explain the basics of what you might see in a device tree source file:

{{SyntaxHighlight header|foo.dts}}
<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};

node2@2000 {
compatible = "vendor,bar";
reg = <0x2000 0xa4>;
vendor,baz-companion = <&my_node>;
};

i2c-controller@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;

#address-cells = <1>;
#size-cells = <0>;

sensor@10 {
compatible = "vendor,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

In this example, we define an empty DTS; in its root node (<code>/</code>), we place three nodes: a node named "node1" with a label "my_node" at address 0x1000, a node named "node2" at address 0x2000, and a node named "i2c-controller" at address 0x3000.

A node contains:
* A <code>compatible</code> value (here <code>"vendor,foo"</code>). This specifies what kind of component it is; Linux uses this information to load the correct driver.
* A <code>reg</code> value. In this case, the first parameter is the base address in memory (<code>0x1000</code>), and the second is the size it occupies (<code>0x54</code>). The amount of cells for the address and size are specified by the <code>#address-cells</code> and <code>#size-cells</code> properties of the root node, respectively.
** You might notice that the i2c-controller node defines another set of these <code>#address-cells</code> and <code>#size-cells</code> properties - this is because I2C devices contain their own subdevices with addresses ranging from 0x08 to 0x7f (todo verify), and they do not use a size.
* A custom vendor-specific property, <code>vendor,bar-factor</code>, which takes a number.

On node 2 there is also a property, <code>vendor,baz-companion</code>, which takes a pointer to another node - here the one we labeled "my_node".

== Working with included DTSIs ==

Very often you'll see <code>#include</code> directives; these can either include header files (which usually contain constants defined with <code>#define</code>, similarly to C) or other DTSes. DTS files meant for inclusion are called '''DTS includes''' and use the '''.dtsi''' file extension.

Usually, an SoC will have a common DTS include with all of the relevant nodes for that SoC. A board's DTS will then include the SoC DTSI.

As an example, here's a very bare-bones DTSI for a fictional "FOO1234" SoC:

{{SyntaxHighlight header|foo1234.dtsi}}
<syntaxhighlight lang="dts" line>
/*
* Common DTSI for Foobar FOO1234 System-on-a-Chip.
*/
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

cpus {
#address-cells = <1>;
#size-cells = <0>;

cpu0: cpu@0 {
device_type = "cpu";
compatible = "arm,cortex-a7";
reg = <0>;
clock-frequency = <1000000000>;
};
};

soc {
/* ... */

i2c1: i2c@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;
status = "disabled";
};

i2c2: i2c@4000 {
compatible = "vendor,foobar-i2c";
reg = <0x4000 0x800>;
status = "disabled";
};

i2c3: i2c@5000 {
compatible = "vendor,foobar-i2c";
reg = <0x5000 0x800>;
status = "disabled";
};

/* ... */
};
};
</syntaxhighlight>

Here is a DTS for a fictional device named "Quox Haystack" that uses the FOO1234 SoC:

{{SyntaxHighlight header|foo1234-quox-haystack.dts}}
<syntaxhighlight lang="dts" line>
/*
* Device tree source for Quox Haystack based on FOO1234 SoC
*/
/dts-v1/;

#include "foo1234.dtsi"

/ {
compatible = "quox,haystack", "foobar,foo1234";

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x40000000>;
};
};

&i2c1 {
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};
</syntaxhighlight>

Some interesting things to look out for:

* The board DTS includes the SoC DTSI with a <code>#include "foo1234.dtsi"</code> directive.
* We re-define the root <code>/</code> node, and inside of it we place a <code>memory</code> node. This node, as well as the <code>compatible</code>, will be merged into the root node of the included DTSI.
* Outside of the root node, there is a node with a name starting with an ampersand (<code>&i2c1</code>); this signifies a pointer to a labeled node (see node labels in the previous example). Like with the root node above, the contents of this node will be merged with the contents of the node with this label in the SoC DTSI.
** A similar effect could be achieved by overriding the <code>i2c1</code> node under the root node, where it's located in the SoC DTSI (though the preferred way is to do it with a label - we do it here for demonstration purposes):
*: {{SyntaxHighlight header|foo1234-quox-haystack.dts}}<syntaxhighlight lang="dts" line start="3">
/ {
compatible = "quox,haystack", "foobar,foo1234";

/* ... */

i2c1: i2c@3000 {
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

For a more visual example - the merged version of these two files would look something like this:

<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

compatible = "quox,haystack", "foobar,foo1234";

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x40000000>;
};

cpus {
#address-cells = <1>;
#size-cells = <0>;

cpu0: cpu@0 {
device_type = "cpu";
compatible = "arm,cortex-a7";
reg = <0>;
clock-frequency = <1000000000>;
};
};

soc {
/* ... */

i2c1: i2c@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;
clock-frequency = <400000>;
status = "okay";

sensor@10 {
compatible = "foobar,baz-sensor";
reg = <0x10>;
};
};

i2c2: i2c@4000 {
compatible = "vendor,foobar-i2c";
reg = <0x4000 0x800>;
status = "disabled";
};

i2c3: i2c@5000 {
compatible = "vendor,foobar-i2c";
reg = <0x5000 0x800>;
status = "disabled";
};

/* ... */
};
};
</syntaxhighlight>

Template:Sidebar/styles.css

2025-02-19T19:48:21Z

Knuxify: Undo revision 63 by Knuxify (talk)

.sidebar {
width: 22em;
float: right;
clear: right;
margin: 0.5em 0 1em 1em;
font-size: 88%;
}

@media (max-width: 640px) {
.sidebar {
width: 100% !important;
clear: both;
float: none !important;
margin-left: 0 !important;
margin-right: 0 !important;
}

.sidebar.nomobile {
display: none;
}
}

Template:Sidebar/styles.css

2025-02-19T19:47:49Z

Knuxify:

.sidebar {
width: 22em;
float: right;
clear: right;
margin: 0 0 1em 1em;
font-size: 88%;
}

@media (max-width: 640px) {
.sidebar {
width: 100% !important;
clear: both;
float: none !important;
margin-left: 0 !important;
margin-right: 0 !important;
}

.sidebar.nomobile {
display: none;
}
}

Devicetree

2025-02-19T19:46:27Z

Knuxify:

{{Navbox devicetree}}
The '''devicetree''' (device tree, DT) is a data structure which holds information about all components present on a device. This data is structured in nested nodes with key/value property pairs for configuration.

In simpler terms - a devicetree tells the kernel (or another DT-compatible piece of software/firmware like a bootloader) where each component is in register space/on an I2C or similar bus, and what settings to use to set it up. It is the basic mechanism for discovering components on embedded platforms, including ARM.

Devicetrees are written in a plaintext format known as the '''Device Tree Source (DTS)''' format. The DTS is later compiled into a '''Device Tree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

Devicetrees are validated using '''devicetree schema''', which is described by bindings; see [[/Bindings]] for more information.

== History ==

The initial version of the devicetree standard was developed as part of the OpenFirmware initiative; from this standard, the Flattened Device Tree (FDT) emerged and was adopted by the Linux kernel for PowerPC platforms. Around 2009, discussions began to include FDT support for ARM[1]. It was eventually added and first device trees began to appear in 2011[2], although the format didn't see wider usage (especially in vendor kernels) until around 2013/2014.

Nowadays, the devicetree standard is managed by [https://www.devicetree.org/ devicetree.org]; they maintain the latest version of the [https://www.devicetree.org/specifications Devicetree Specification] and the related set of [https://github.com/devicetree-org/dt-schema core DT schema].

Before the introduction of devicetrees, ARM kernels used '''board files'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.

== Device Tree Source (DTS) basics ==

The following is a simple DTS file to demonstrate the DTS syntax. For a more in-depth syntax guide, see [[Devicetree/DTS syntax]].

{{SyntaxHighlight header|foo.dts}}
<syntaxhighlight lang="dts" line>
/dts-v1/;

/ {
#address-cells = <1>;
#size-cells = <1>;

my_node: node1@1000 {
compatible = "vendor,foo";
reg = <0x1000 0x54>;
vendor,bar-factor = <0x2a>;
};

node2@2000 {
compatible = "vendor,bar";
reg = <0x2000 0xa4>;
vendor,baz-companion = <&my_node>;
};

i2c-controller@3000 {
compatible = "vendor,foobar-i2c";
reg = <0x3000 0x800>;

#address-cells = <1>;
#size-cells = <0>;

sensor@10 {
compatible = "vendor,baz-sensor";
reg = <0x10>;
};
};
};
</syntaxhighlight>

== Verifying DTS files ==

The Linux kernel has tools for making sure that device tree sources (DTS) use the bindings correctly. These are useful when writing device sources; getting
the DT checks to pass is also mandatory for upstream inclusion of a DTS.

To verify all DTS files built with the selected defconfig options, run:

<syntaxhighlight lang="shell-session">
$ make dtbs_check
</syntaxhighlight>

To verify a specific DTS, build the DTB target directly and provide the <code>CHECK_DTBS=y</code> option:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y qcom/sm8450-hdk.dtb
</syntaxhighlight>

You can also test a DTS against a specific subset of bindings by providing the <code>DT_SCHEMA_FILES</code> variable as mentioned in the previous section:

<syntaxhighlight lang="shell-session">
$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb
</syntaxhighlight>

== Working with DTC ==

The <code>dtc</code> tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS. (TODO: add instructions)

== See also ==

* From Linux kernel documentation:
** [https://docs.kernel.org/devicetree/bindings/dts-coding-style.html Devicetree Sources (DTS) Coding Style]
* On elinux.org:
** [https://elinux.org/Device_Tree_Reference Device Tree Reference]
** [https://elinux.org/Device_Tree_Reference Device Tree Usage]

== References ==

todo enable refs extension

[1] https://www.mail-archive.com/linux-embedded@vger.kernel.org/msg01721.html
[2] https://github.com/torvalds/linux/commit/b85a3ef4ac65169b65fd2fe9bec7912bbf475ba4

Template:Navbox devicetree

2025-02-19T19:42:40Z

Knuxify:

<includeonly>{{navbox
|header=[[File:Devicetree logo.png|48px]]<br><span style="display: block; margin-top: 6px;">Devicetree</span>
|links=
* [[Devicetree|Introduction]]
* [[Devicetree/DTS syntax|DTS syntax guide]]
* [[Devicetree/Bindings|DT bindings]]}}</includeonly><noinclude>
<templatedata>
{
"params": {},
"description": "Navbox template for Devicetree-related pages.",
"format": "inline"
}
</templatedata>

== Example ==

{{Navbox devicetree}}

</noinclude>

Template:Navbox/styles.css

2025-02-19T19:42:22Z

Knuxify:

.navbox {
background-color: var(--background-color-neutral-subtle, #f8f9fa);
border: 1px solid var(--border-color-base, #a2a9b1);
line-height: 1.4em;
text-align: center;
max-width: 14em;
}

.navbox .navbox-header {
padding: 2px;
font-size: 1.35em;
font-weight: bold;
}

.navbox:not(.no-header-bg) .navbox-header {
background-color: var(--background-color-neutral, #eaecf0);
border-bottom: 1px solid var(--border-color-base, #a2a9b1);
padding: 4px;
}

.navbox .navbox-content .subheading {
padding: 2px;
font-size: 1.2em;
font-weight: bold;
line-height: 1.5em;
}

.navbox .navbox-content {
padding: 2px;
}

.navbox .navbox-content ul,
.navbox .navbox-content ol {
margin: 0.25em 0;
list-style-type: none;
}
.navbox .navbox-content li {
padding: 0.05em 0;
}
.navbox .navbox-content li:before {
content: "•";
margin-right: 0.35em;
}
.navbox .navbox-content li:after {
content: "•";
margin-left: 0.35em;
}

@media (max-width: 640px) {
.navbox { max-width: 100%; }
}

File:Devicetree logo.png

2025-02-19T19:38:27Z

Knuxify: Source: https://github.com/devicetree-org/devicetree-website/blob/main/public/favicon.png

== Summary ==
Source: https://github.com/devicetree-org/devicetree-website/blob/main/public/favicon.png