diff options
author | Linus Torvalds | 2023-06-29 15:11:17 -0700 |
---|---|---|
committer | Linus Torvalds | 2023-06-29 15:11:17 -0700 |
commit | a9025a5f16ed610ea28a188cb0946cb71fafff17 (patch) | |
tree | f6a489910ecd949b2aa0a0b4fb6c5829fb6e5cd9 /Documentation | |
parent | 6c1561fb900524c5bceb924071b3e9b8a67ff3da (diff) | |
parent | f50a000b42195a0e0d22c34c16b7c488b22063a2 (diff) |
Merge tag 'soc-newsoc-6.5' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
Pull new ARM SoC support from Arnd Bergmann:
"There are two new SoC families this time, and both appear fairly
similar: The Nuvoton MA35D1 and the STMicroelectronics STM32MP2 are
both dual-core Cortex-A35 based chips for the low-power industrial
embedded market, and they mark the first 64-bit product in a widely
used family of 32-bit Arm MCUs and SoCs.
The way into the kernel is completely different here: The team at ST
has a long history of working upstream with their STM32MP1 and other
SoCs, and they produced a complete port to arm64 together with the
initial announcement. Nuvoton also has multiple SoC product lines with
current or previous upstream support, but those are maintained by
third parties and are unrelated. The patch series from Nuvoton's Jacky
Huang had to go through many revisisions to get to this point and is
still missing a few drivers including the serial port for the moment.
The branch contains the devicetree files as well as all the code
changes, in order to have something that can be tested standalone"
* tag 'soc-newsoc-6.5' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc: (25 commits)
clk: nuvoton: Use clk_parent_data instead of string for parent clock
clk: nuvoton: Update all constant hex values to lowercase
clk: nuvoton: Add clk-ma35d1.h for driver extern functions
remoteproc: stm32: use correct format strings on 64-bit
MAINTAINERS: add entry for ARM/STM32 ARCHITECTURE
arm64: defconfig: enable ARCH_STM32 and STM32 serial driver
arm64: dts: st: add stm32mp257f-ev1 board support
dt-bindings: stm32: document stm32mp257f-ev1 board
arm64: dts: st: introduce stm32mp25 pinctrl files
arm64: dts: st: introduce stm32mp25 SoCs family
arm64: introduce STM32 family on Armv8 architecture
dt-bindings: stm32: add st,stm32mp25-syscfg compatible for syscon
pinctrl: stm32: add stm32mp257 pinctrl support
dt-bindings: pinctrl: stm32: support for stm32mp257 and additional packages
Documentation/process: add soc maintainer handbook
reset: RESET_NUVOTON_MA35D1 should depend on ARCH_MA35
reset: Add Nuvoton ma35d1 reset driver support
clk: nuvoton: Add clock driver for ma35d1 clock controller
arm64: dts: nuvoton: Add initial ma35d1 device tree
dt-bindings: serial: Document ma35d1 uart controller
...
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/devicetree/bindings/arm/nuvoton/nuvoton,ma35d1.yaml | 30 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/arm/nuvoton/nuvoton,npcm.yaml (renamed from Documentation/devicetree/bindings/arm/npcm/npcm.yaml) | 2 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml | 7 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/arm/stm32/stm32.yaml | 6 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml | 63 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml | 4 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/reset/nuvoton,ma35d1-reset.yaml | 45 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/serial/nuvoton,ma35d1-serial.yaml | 48 | ||||
-rw-r--r-- | Documentation/devicetree/bindings/soc/nuvoton/nuvoton,npcm-gcr.yaml (renamed from Documentation/devicetree/bindings/arm/npcm/nuvoton,gcr.yaml) | 2 | ||||
-rw-r--r-- | Documentation/process/maintainer-handbooks.rst | 3 | ||||
-rw-r--r-- | Documentation/process/maintainer-soc.rst | 177 |
11 files changed, 380 insertions, 7 deletions
diff --git a/Documentation/devicetree/bindings/arm/nuvoton/nuvoton,ma35d1.yaml b/Documentation/devicetree/bindings/arm/nuvoton/nuvoton,ma35d1.yaml new file mode 100644 index 000000000000..fb190db61525 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/nuvoton/nuvoton,ma35d1.yaml @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/nuvoton/nuvoton,ma35d1.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton MA35 series SoC based platforms + +maintainers: + - Jacky Huang <ychuang3@nuvoton.com> + +description: | + Boards with an ARMv8 based Nuvoton MA35 series SoC shall have + the following properties. + +properties: + $nodename: + const: '/' + compatible: + oneOf: + + - description: MA35D1 based boards + items: + - enum: + - nuvoton,ma35d1-iot + - nuvoton,ma35d1-som + - const: nuvoton,ma35d1 + +additionalProperties: true +... diff --git a/Documentation/devicetree/bindings/arm/npcm/npcm.yaml b/Documentation/devicetree/bindings/arm/nuvoton/nuvoton,npcm.yaml index 6871483947c5..d386744c8815 100644 --- a/Documentation/devicetree/bindings/arm/npcm/npcm.yaml +++ b/Documentation/devicetree/bindings/arm/nuvoton/nuvoton,npcm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/npcm/npcm.yaml# +$id: http://devicetree.org/schemas/arm/nuvoton/nuvoton,npcm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: NPCM Platforms diff --git a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml index ad8e51aa01b0..b63ff591ef8f 100644 --- a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml @@ -15,12 +15,13 @@ properties: oneOf: - items: - enum: - - st,stm32mp157-syscfg - - st,stm32mp151-pwr-mcu - - st,stm32-syscfg - st,stm32-power-config + - st,stm32-syscfg - st,stm32-tamp - st,stm32f4-gcan + - st,stm32mp151-pwr-mcu + - st,stm32mp157-syscfg + - st,stm32mp25-syscfg - const: syscon - items: - const: st,stm32-tamp diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index 4af5b8f4f803..4466b455bffa 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -161,6 +161,12 @@ properties: - const: phytec,phycore-stm32mp157c-som - const: st,stm32mp157 + - description: ST STM32MP257 based Boards + items: + - enum: + - st,stm32mp257f-ev1 + - const: st,stm32mp257 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml new file mode 100644 index 000000000000..8f0c43683729 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/nuvoton,ma35d1-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton MA35D1 Clock Controller Module + +maintainers: + - Chi-Fang Li <cfli0@nuvoton.com> + - Jacky Huang <ychuang3@nuvoton.com> + +description: | + The MA35D1 clock controller generates clocks for the whole chip, + including system clocks and all peripheral clocks. + + See also: + include/dt-bindings/clock/ma35d1-clk.h + +properties: + compatible: + items: + - const: nuvoton,ma35d1-clk + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + + clocks: + maxItems: 1 + + nuvoton,pll-mode: + description: + A list of PLL operation mode corresponding to CAPLL, DDRPLL, APLL, + EPLL, and VPLL in sequential. + maxItems: 5 + items: + enum: + - integer + - fractional + - spread-spectrum + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + +required: + - compatible + - reg + - "#clock-cells" + - clocks + +additionalProperties: false + +examples: + - | + + clock-controller@40460200 { + compatible = "nuvoton,ma35d1-clk"; + reg = <0x40460200 0x100>; + #clock-cells = <1>; + clocks = <&clk_hxt>; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml index 1ab0f8dde477..2120ef71a78d 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml @@ -27,6 +27,8 @@ properties: - st,stm32mp135-pinctrl - st,stm32mp157-pinctrl - st,stm32mp157-z-pinctrl + - st,stm32mp257-pinctrl + - st,stm32mp257-z-pinctrl '#address-cells': const: 1 @@ -56,7 +58,7 @@ properties: Indicates the SOC package used. More details in include/dt-bindings/pinctrl/stm32-pinfunc.h $ref: /schemas/types.yaml#/definitions/uint32 - enum: [1, 2, 4, 8] + enum: [0x1, 0x2, 0x4, 0x8, 0x100, 0x400, 0x800] patternProperties: '^gpio@[0-9a-f]*$': diff --git a/Documentation/devicetree/bindings/reset/nuvoton,ma35d1-reset.yaml b/Documentation/devicetree/bindings/reset/nuvoton,ma35d1-reset.yaml new file mode 100644 index 000000000000..34c5c1c08ec1 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/nuvoton,ma35d1-reset.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/nuvoton,ma35d1-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton MA35D1 Reset Controller + +maintainers: + - Chi-Fang Li <cfli0@nuvoton.com> + - Jacky Huang <ychuang3@nuvoton.com> + +description: + The system reset controller can be used to reset various peripheral + controllers in MA35D1 SoC. + +properties: + compatible: + items: + - const: nuvoton,ma35d1-reset + + reg: + maxItems: 1 + + '#reset-cells': + const: 1 + +required: + - compatible + - reg + - '#reset-cells' + +additionalProperties: false + +examples: + # system reset controller node: + - | + + system-management@40460000 { + compatible = "nuvoton,ma35d1-reset"; + reg = <0x40460000 0x200>; + #reset-cells = <1>; + }; +... + diff --git a/Documentation/devicetree/bindings/serial/nuvoton,ma35d1-serial.yaml b/Documentation/devicetree/bindings/serial/nuvoton,ma35d1-serial.yaml new file mode 100644 index 000000000000..a76af0f6009b --- /dev/null +++ b/Documentation/devicetree/bindings/serial/nuvoton,ma35d1-serial.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/nuvoton,ma35d1-serial.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton MA35D1 Universal Asynchronous Receiver/Transmitter (UART) + +maintainers: + - Min-Jen Chen <mjchen@nuvoton.com> + - Jacky Huang <ychuang3@nuvoton.com> + +allOf: + - $ref: serial.yaml + +properties: + compatible: + const: nuvoton,ma35d1-uart + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/nuvoton,ma35d1-clk.h> + + serial@40700000 { + compatible = "nuvoton,ma35d1-uart"; + reg = <0x40700000 0x100>; + interrupts = <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk UART0_GATE>; + }; +... diff --git a/Documentation/devicetree/bindings/arm/npcm/nuvoton,gcr.yaml b/Documentation/devicetree/bindings/soc/nuvoton/nuvoton,npcm-gcr.yaml index 94e72f25b331..23e7e4ea01ff 100644 --- a/Documentation/devicetree/bindings/arm/npcm/nuvoton,gcr.yaml +++ b/Documentation/devicetree/bindings/soc/nuvoton/nuvoton,npcm-gcr.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/npcm/nuvoton,gcr.yaml# +$id: http://devicetree.org/schemas/soc/nuvoton/nuvoton,npcm-gcr.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Global Control Registers block in Nuvoton SoCs diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst index d783060b4cc6..fe24cb665fb7 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -15,5 +15,6 @@ Contents: :numbered: :maxdepth: 2 - maintainer-tip maintainer-netdev + maintainer-soc + maintainer-tip diff --git a/Documentation/process/maintainer-soc.rst b/Documentation/process/maintainer-soc.rst new file mode 100644 index 000000000000..49f08289d62c --- /dev/null +++ b/Documentation/process/maintainer-soc.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +SoC Subsystem +============= + +Overview +-------- + +The SoC subsystem is a place of aggregation for SoC-specific code. +The main components of the subsystem are: + +* devicetrees for 32- & 64-bit ARM and RISC-V +* 32-bit ARM board files (arch/arm/mach*) +* 32- & 64-bit ARM defconfigs +* SoC-specific drivers across architectures, in particular for 32- & 64-bit + ARM, RISC-V and Loongarch + +These "SoC-specific drivers" do not include clock, GPIO etc drivers that have +other top-level maintainers. The drivers/soc/ directory is generally meant +for kernel-internal drivers that are used by other drivers to provide SoC- +specific functionality like identifying an SoC revision or interfacing with +power domains. + +The SoC subsystem also serves as an intermediate location for changes to +drivers/bus, drivers/firmware, drivers/reset and drivers/memory. The addition +of new platforms, or the removal of existing ones, often go through the SoC +tree as a dedicated branch covering multiple subsystems. + +The main SoC tree is housed on git.kernel.org: + https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/ + +Clearly this is quite a wide range of topics, which no one person, or even +small group of people are capable of maintaining. Instead, the SoC subsystem +is comprised of many submaintainers, each taking care of individual platforms +and driver subdirectories. +In this regard, "platform" usually refers to a series of SoCs from a given +vendor, for example, Nvidia's series of Tegra SoCs. Many submaintainers operate +on a vendor level, responsible for multiple product lines. For several reasons, +including acquisitions/different business units in a company, things vary +significantly here. The various submaintainers are documented in the +MAINTAINERS file. + +Most of these submaintainers have their own trees where they stage patches, +sending pull requests to the main SoC tree. These trees are usually, but not +always, listed in MAINTAINERS. The main SoC maintainers can be reached via the +alias soc@kernel.org if there is no platform-specific maintainer, or if they +are unresponsive. + +What the SoC tree is not, however, is a location for architecture-specific code +changes. Each architecture has its own maintainers that are responsible for +architectural details, CPU errata and the like. + +Information for (new) Submaintainers +------------------------------------ + +As new platforms spring up, they often bring with them new submaintainers, +many of whom work for the silicon vendor, and may not be familiar with the +process. + +Devicetree ABI Stability +~~~~~~~~~~~~~~~~~~~~~~~~ + +Perhaps one of the most important things to highlight is that dt-bindings +document the ABI between the devicetree and the kernel. +Please read Documentation/devicetree/bindings/ABI.rst. + +If changes are being made to a devicetree that are incompatible with old +kernels, the devicetree patch should not be applied until the driver is, or an +appropriate time later. Most importantly, any incompatible changes should be +clearly pointed out in the patch description and pull request, along with the +expected impact on existing users, such as bootloaders or other operating +systems. + +Driver Branch Dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A common problem is synchronizing changes between device drivers and devicetree +files. Even if a change is compatible in both directions, this may require +coordinating how the changes get merged through different maintainer trees. + +Usually the branch that includes a driver change will also include the +corresponding change to the devicetree binding description, to ensure they are +in fact compatible. This means that the devicetree branch can end up causing +warnings in the "make dtbs_check" step. If a devicetree change depends on +missing additions to a header file in include/dt-bindings/, it will fail the +"make dtbs" step and not get merged. + +There are multiple ways to deal with this: + +* Avoid defining custom macros in include/dt-bindings/ for hardware constants + that can be derived from a datasheet -- binding macros in header files should + only be used as a last resort if there is no natural way to define a binding + +* Use literal values in the devicetree file in place of macros even when a + header is required, and change them to the named representation in a + following release + +* Defer the devicetree changes to a release after the binding and driver have + already been merged + +* Change the bindings in a shared immutable branch that is used as the base for + both the driver change and the devicetree changes + +* Add duplicate defines in the devicetree file guarded by an #ifndef section, + removing them in a later release + +Devicetree Naming Convention +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The general naming scheme for devicetree files is as follows. The aspects of a +platform that are set at the SoC level, like CPU cores, are contained in a file +named $soc.dtsi, for example, jh7100.dtsi. Integration details, that will vary +from board to board, are described in $soc-$board.dts. An example of this is +jh7100-beaglev-starlight.dts. Often many boards are variations on a theme, and +frequently there are intermediate files, such as jh7100-common.dtsi, which sit +between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of +common hardware. + +Some platforms also have System on Modules, containing an SoC, which are then +integrated into several different boards. For these platforms, $soc-$som.dtsi +and $soc-$som-$board.dts are typical. + +Directories are usually named after the vendor of the SoC at the time of its +inclusion, leading to some historical directory names in the tree. + +Validating Devicetree Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``make dtbs_check`` can be used to validate that devicetree files are compliant +with the dt-bindings that describe the ABI. Please read the section +"Running checks" of Documentation/devicetree/bindings/writing-schema.rst for +more information on the validation of devicetrees. + +For new platforms, or additions to existing ones, ``make dtbs_check`` should not +add any new warnings. For RISC-V, as it has the advantage of being a newer +architecture, ``make dtbs_check W=1`` is required to not add any new warnings. +If in any doubt about a devicetree change, reach out to the devicetree +maintainers. + +Branches and Pull Requests +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Just as the main SoC tree has several branches, it is expected that +submaintainers will do the same. Driver, defconfig and devicetree changes should +all be split into separate branches and appear in separate pull requests to the +SoC maintainers. Each branch should be usable by itself and avoid +regressions that originate from dependencies on other branches. + +Small sets of patches can also be sent as separate emails to soc@kernel.org, +grouped into the same categories. + +If changes do not fit into the normal patterns, there can be additional +top-level branches, e.g. for a treewide rework, or the addition of new SoC +platforms including dts files and drivers. + +Branches with a lot of changes can benefit from getting split up into separate +topics branches, even if they end up getting merged into the same branch of the +SoC tree. An example here would be one branch for devicetree warning fixes, one +for a rework and one for newly added boards. + +Another common way to split up changes is to send an early pull request with the +majority of the changes at some point between rc1 and rc4, following up with one +or more smaller pull requests towards the end of the cycle that can add late +changes or address problems identified while testing the first set. + +While there is no cut-off time for late pull requests, it helps to only send +small branches as time gets closer to the merge window. + +Pull requests for bugfixes for the current release can be sent at any time, but +again having multiple smaller branches is better than trying to combine too many +patches into one pull request. + +The subject line of a pull request should begin with "[GIT PULL]" and made using +a signed tag, rather than a branch. This tag should contain a short description +summarising the changes in the pull request. For more detail on sending pull +requests, please see Documentation/maintainer/pull-requests.rst. |