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

🚧	This page is a work-in-progress. Some information contained within may be inaccurate or incomplete. In particular: 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 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 this random Qualcomm support forums post), other times it's different (SM7435 uses "parrot" in the kernel but is actually called "netrani", 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.
• 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 qcom_proprietary_devicetree or similar repo with the DTSI source files (because they're not in the kernel repo for whatever reason...). Search for (downstream codename).dtsi 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 driver/clk/qcom/Kconfig and add the relevant Kconfig option for your SoC (remember to keep it ordered alphabetically):

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.

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

obj-$(CONFIG_SM_GCC_xxxx) += gcc-smXXXX.o

Open driver/clk/qcom/gcc-smXXXX.c.

Paste the initialization code from another GCC driver (static struct platform_driver gcc_smXXXX_driver 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.