dts: bindings: add title property

kartben · kartben · commit a58e65908c1c · 2025-05-17T14:11:35.000+02:00
This adds a proper, concise, title property to a bunch of bindings for
which the first sentence of their description (which used to be a
makeshift title) was really long

Signed-off-by: Benjamin Cabé &lt;benjamin@zephyrproject.org&gt;
diff --git a/dts/bindings/clock/gd,gd32-cctl.yaml b/dts/bindings/clock/gd,gd32-cctl.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2022, Teslabs Engineering S.L.
 # SPDX-License-Identifier: Apache-2.0
 
+title: Gigadevice RCU (Reset and Clock Unit) - Clock Controller
+
 description: |
   Gigadevice Reset and Clock Unit (RCU) if a multi-function peripheral in
   charge of reset control (RCTL) and clock control (CCTL) for all SoC
diff --git a/dts/bindings/ethernet/st,stm32-ethernet-controller.yaml b/dts/bindings/ethernet/st,stm32-ethernet-controller.yaml
@@ -1,9 +1,10 @@
 # Copyright The Zephyr Project Contributors
 # SPDX-License-Identifier: Apache-2.0
 
+title: STM32 Ethernet Controller
+
 description: |
-  ST STM32 Ethernet controller, contains the Ethernet MAC
-  and the MDIO as a child nodes.
+  Contains the Ethernet MAC and the MDIO as child nodes.
 
 compatible: "st,stm32-ethernet-controller"
 
diff --git a/dts/bindings/memory-controllers/nxp,flexram.yaml b/dts/bindings/memory-controllers/nxp,flexram.yaml
@@ -1,8 +1,9 @@
 # Copyright 2023 NXP
 # SPDX-License-Identifier: Apache-2.0
 
+title: NXP FlexRAM on-chip RAM controller
+
 description: |
-  NXP FlexRAM on-chip ram controller
   If the flexram,bank-spec property is specified, then the flexram will be
   dynamically reconfigured to the configuration specified at runtime. An
   example to configure the flexram dynamically using the
diff --git a/dts/bindings/mfd/gd,gd32-rcu.yaml b/dts/bindings/mfd/gd,gd32-rcu.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2022, Teslabs Engineering S.L.
 # SPDX-License-Identifier: Apache-2.0
 
+title: Gigadevice RCU (Reset and Clock Unit)
+
 description: |
   Gigadevice Reset and Clock Unit (RCU) if a multi-function peripheral in
   charge of reset control (RCTL) and clock control (CCTL) for all SoC
diff --git a/dts/bindings/pinctrl/ambiq,apollo3-pinctrl.yaml b/dts/bindings/pinctrl/ambiq,apollo3-pinctrl.yaml
@@ -1,10 +1,12 @@
 # Copyright (c) 2023 Ambiq Micro Inc. <www.ambiq.com>
 # SPDX-License-Identifier: Apache-2.0
 
+title: Ambiq Apollo3 Pin Controller
+
 description: |
-  The Ambiq Apollo3 pin controller is a node responsible for controlling
-  pin function selection and pin properties, such as routing a UART0 TX
-  to pin 60 and enabling the pullup resistor on that pin.
+  Singleton node responsible for controlling pin function selection and pin
+  properties, such as routing a UART0 TX to pin 60 and enabling the pullup
+  resistor on that pin.
 
   The node has the 'pinctrl' node label set in your SoC's devicetree,
   so you can modify it like this:
diff --git a/dts/bindings/pinctrl/ambiq,apollo4-pinctrl.yaml b/dts/bindings/pinctrl/ambiq,apollo4-pinctrl.yaml
@@ -1,10 +1,12 @@
 # Copyright (c) 2023 Antmicro <www.antmicro.com>
 # SPDX-License-Identifier: Apache-2.0
 
+title: Ambiq Apollo4 Pin Controller
+
 description: |
-    The Ambiq Apollo4 pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing a UART0 TX
-    to pin 60 and enabling the pullup resistor on that pin.
+    Singleton node responsible for controlling pin function selection and pin
+    properties, such as routing a UART0 TX to pin 60 and enabling the pullup
+    resistor on that pin.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/ambiq,apollo5-pinctrl.yaml b/dts/bindings/pinctrl/ambiq,apollo5-pinctrl.yaml
@@ -1,10 +1,12 @@
 # Copyright (c) 2025 Ambiq Micro Inc.
 # SPDX-License-Identifier: Apache-2.0
 
+title: Ambiq Apollo5 Pin Controller
+
 description: |
-    The Ambiq Apollo5 pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing a UART0 TX
-    to pin 60 and enabling the pullup resistor on that pin.
+    Singleton node responsible for controlling pin function selection and pin
+    properties, such as routing a UART0 TX to pin 60 and enabling the pullup
+    resistor on that pin.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/arm,mps2-pinctrl.yaml b/dts/bindings/pinctrl/arm,mps2-pinctrl.yaml
@@ -1,10 +1,11 @@
 # Copyright 2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
 # SPDX-License-Identifier: Apache-2.0
 
+title: Arm MPS2 Pin Controller
+
 description: |
-    The Arm Mps2 pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing a UART3 TX
-    to pin 1.
+    Node responsible for controlling pin function selection and pin properties,
+    such as routing a UART3 TX to pin 1.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/arm,mps3-pinctrl.yaml b/dts/bindings/pinctrl/arm,mps3-pinctrl.yaml
@@ -1,10 +1,11 @@
 # Copyright 2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
 # SPDX-License-Identifier: Apache-2.0
 
+title: Arm MPS3 Pin Controller
+
 description: |
-    The Arm Mps3 pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing a UART3 TX
-    to pin 1.
+    Node responsible for controlling pin function selection and pin properties,
+    such as routing a UART3 TX to pin 1.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/gd,gd32-afio.yaml b/dts/bindings/pinctrl/gd,gd32-afio.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2021 Teslabs Engineering S.L.
 # SPDX-License-Identifier: Apache-2.0
 
+title: GD32 AFIO (Alternate Function Input/Output)
+
 description: |
   The AFIO peripheral is used to configure pin remapping, EXTI sources and,
   when available, enable the I/O compensation cell.
diff --git a/dts/bindings/pinctrl/gd,gd32-pinctrl-af.yaml b/dts/bindings/pinctrl/gd,gd32-pinctrl-af.yaml
@@ -1,11 +1,12 @@
 # Copyright (c) 2021 Teslabs Engineering S.L.
 # SPDX-License-Identifier: Apache-2.0
 
+title: GD32 Pin Controller (AF Model)
+
 description: |
-    The GD32 pin controller (AF model) is a singleton node responsible for
-    controlling pin function selection and pin properties. For example, you can
-    use this node to route USART0 RX to pin PA10 and enable the pull-up resistor
-    on the pin.
+    Singleton node responsible for controlling pin function selection and pin
+    properties. For example, you can use this node to route USART0 RX to pin
+    PA10 and enable the pull-up resistor on the pin.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/gd,gd32-pinctrl-afio.yaml b/dts/bindings/pinctrl/gd,gd32-pinctrl-afio.yaml
@@ -1,11 +1,12 @@
 # Copyright (c) 2021 Teslabs Engineering S.L.
 # SPDX-License-Identifier: Apache-2.0
 
+title: GD32 Pin Controller (AFIO Model)
+
 description: |
-    The GD32 pin controller (AFIO model) is a singleton node responsible for
-    controlling pin function selection and pin properties. For example, you can
-    use this node to route USART0 RX to pin PA10 and enable the pull-up resistor
-    on the pin. Remapping is also supported.
+    Singleton node responsible for controlling pin function selection and pin
+    properties. For example, you can use this node to route USART0 RX to pin
+    PA10 and enable the pull-up resistor on the pin. Remapping is also supported.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/infineon,xmc4xxx-pinctrl.yaml b/dts/bindings/pinctrl/infineon,xmc4xxx-pinctrl.yaml
@@ -1,8 +1,10 @@
 # Copyright (c) 2022, Andriy Gelman <andriy.gelman@gmail.com>
 # SPDX-License-Identifier: Apache-2.0
 
+title: Infineon XMC4XXX Pin Controller
+
 description: |
-  The Infineon XMC4XXX pin controller is responsible for connecting peripheral outputs
+  Singleton node responsible for connecting peripheral outputs to specific port/pins
   to specific port/pins (also known as alternate functions) and configures pin properties.
 
   The pinctrl settings are referenced in a device tree peripheral node. For example in a UART
diff --git a/dts/bindings/pinctrl/nordic,nrf-pinctrl.yaml b/dts/bindings/pinctrl/nordic,nrf-pinctrl.yaml
@@ -1,11 +1,12 @@
 # Copyright (c) 2021 Nordic Semiconductor ASA
 # SPDX-License-Identifier: Apache-2.0
 
+title: Nordic nRF family Pin Controller
+
 description: |
-    The nRF pin controller is a singleton node responsible for controlling
-    pin function selection and pin properties. For example, you can use this
-    node to route UART0 RX to pin P0.1 and enable the pull-up resistor on the
-    pin.
+    Singleton node responsible for controlling pin function selection and pin
+    properties. For example, you can use this node to route UART0 RX to pin P0.1
+    and enable the pull-up resistor on the pin.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/raspberrypi,pico-pinctrl.yaml b/dts/bindings/pinctrl/raspberrypi,pico-pinctrl.yaml
@@ -2,10 +2,12 @@
 # Copyright (c) 2021 Yonatan Schachter
 # SPDX-License-Identifier: Apache-2.0
 
+title: Raspberry Pi Pico Pin Controller
+
 description: |
-    The RPi Pico pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing a UART0 Rx
-    to pin 1 and enabling the pullup resistor on that pin.
+    Singleton node responsible for controlling pin function selection and pin
+    properties, such as routing a UART0 Rx to pin 1 and enabling the pullup
+    resistor on that pin.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/renesas,ra-pincrl-pfs.yaml b/dts/bindings/pinctrl/renesas,ra-pincrl-pfs.yaml
@@ -1,10 +1,11 @@
 # Copyright (c) 2024 Renesas Electronics Corporation
 # SPDX-License-Identifier: Apache-2.0
 
+title: Renesas RA Pin Controller
+
 description: |
-    The Renesas RA pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing a SCI0 RXD
-    to P610.
+    Node responsible for controlling pin function selection and pin properties,
+    such as routing a SCI0 RXD to P610.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/renesas,rzn-pinctrl.yaml b/dts/bindings/pinctrl/renesas,rzn-pinctrl.yaml
@@ -1,11 +1,12 @@
 # Copyright (c) 2025 Renesas Electronics Corporation
 # SPDX-License-Identifier: Apache-2.0
 
+title: Renesas RZ/N2L Pin Controller
 
 description: |
-    The Renesas RZ/N2L pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing the TX and RX of UART0
-    to pin 5 and pin 6 of port 16.
+    Singleton node responsible for controlling pin function selection and pin
+    properties, such as routing the TX and RX of UART0 to pin 5 and pin 6 of
+    port 16.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/renesas,rzt2m-pinctrl.yaml b/dts/bindings/pinctrl/renesas,rzt2m-pinctrl.yaml
@@ -1,10 +1,12 @@
 # Copyright (c) 2023 Antmicro <www.antmicro.com>
 # SPDX-License-Identifier: Apache-2.0
 
+title: Renesas RZ/T2M Pin Controller
+
 description: |
-    The Renesas RZ/T2M pin controller is a node responsible for controlling
-    pin function selection and pin properties, such as routing the TX and RX of UART0
-    to pin 5 and pin 6 of port 16.
+    Singleton node responsible for controlling pin function selection and pin
+    properties, such as routing the TX and RX of UART0 to pin 5 and pin 6 of
+    port 16.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/renesas,smartbond-pinctrl.yaml b/dts/bindings/pinctrl/renesas,smartbond-pinctrl.yaml
@@ -1,10 +1,12 @@
 # Copyright (c) 2022 Renesas Electronics Corporation
 # SPDX-License-Identifier: Apache-2.0
 
+title: Renesas SmartBond Pin Controller
+
 description: |
-    The SmartBond pin controller is a singleton node responsible for controlling
-    pin function selection and pin properties, such as routing a UART RX to pin
-    P1.8 and enabling the pullup resistor on that pin.
+    Singleton node responsible for controlling pin function selection and pin
+    properties, such as routing a UART RX to pin P1.8 and enabling the pullup
+    resistor on that pin.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/pinctrl/sensry,sy1xx-pinctrl.yaml b/dts/bindings/pinctrl/sensry,sy1xx-pinctrl.yaml
@@ -1,9 +1,11 @@
 # Copyright (c) 2024 sensry.io
 # SPDX-License-Identifier: Apache-2.0
 
+title: Sensry SY1xx Pin Controller
+
 description: |
-  The sensry SY1xx pin controller is a single node responsible for controlling
-  pin configuration, such as pull-up, pull-down, tri-state, ...
+  Singleton node responsible for controlling pin configuration, such as pull-up,
+  pull-down, tri-state, ...
 
   The node has the 'pinctrl0' node label set in your SoC's devicetree,
   so you can modify it like this:
diff --git a/dts/bindings/pinctrl/silabs,gecko-pinctrl.yaml b/dts/bindings/pinctrl/silabs,gecko-pinctrl.yaml
@@ -1,9 +1,12 @@
 # Copyright (c) 2022 Silicon Labs
 # SPDX-License-Identifier: Apache-2.0
 
+title: Silabs Gecko Pin Controller
+
 description: |
-    The Silabs pin controller is a singleton node responsible for controlling
-    pin function selection and pin properties. For example, you can use this
+    Singleton node responsible for controlling pin function selection and pin
+    properties. For example, you can use this node to route UART0 RX to pin P0.1
+    and enable the pull-up resistor on the pin.
     node to route UART0 RX to pin P0.1 and enable the pull-up resistor on the
     pin.
 
diff --git a/dts/bindings/pinctrl/silabs,siwx91x-pinctrl.yaml b/dts/bindings/pinctrl/silabs,siwx91x-pinctrl.yaml
@@ -2,9 +2,10 @@
 # Copyright (c) 2024 Silicon Laboratories Inc.
 # SPDX-License-Identifier: Apache-2.0
 
+title: Silabs SiWx91x Pin Controller
+
 description: |
-  The Silabs SiWx91x pin controller is a devicetree node tasked with selecting
-  the proper IO function for a given pin.
+  Node tasked with selecting the proper IO function for a given pin.
 
   The pinctrl settings are referenced in a device tree peripheral node. For
   example when configuring a UART:
diff --git a/dts/bindings/pinctrl/ti,cc32xx-pinctrl.yaml b/dts/bindings/pinctrl/ti,cc32xx-pinctrl.yaml
@@ -1,11 +1,12 @@
 # Copyright (c) 2023 Nordic Semiconductor ASA
 # SPDX-License-Identifier: Apache-2.0
 
+title: TI CC32XX Pin Controller
+
 description: |
-    The TI CC32XX pin controller is a singleton node responsible for controlling
-    pin function selection and pin properties. For example, you can
-    use this node to route UART0 RX to pin 55 and enable the pull-up resistor
-    on the pin.
+    Singleton node responsible for controlling pin function selection and pin
+    properties. For example, you can use this node to route UART0 RX to pin 55
+    and enable the pull-up resistor on the pin.
 
     The node has the 'pinctrl' node label set in your SoC's devicetree,
     so you can modify it like this:
diff --git a/dts/bindings/reset/gd,gd32-rctl.yaml b/dts/bindings/reset/gd,gd32-rctl.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2022, Teslabs Engineering S.L.
 # SPDX-License-Identifier: Apache-2.0
 
+title: Gigadevice RCU (Reset and Clock Unit) - Reset Controller
+
 description: |
   Gigadevice Reset and Clock Unit (RCU) if a multi-function peripheral in
   charge of reset control (RCTL) and clock control (CCTL) for all SoC
diff --git a/dts/bindings/sensor/bosch,bme680-i2c.yaml b/dts/bindings/sensor/bosch,bme680-i2c.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2018, Bosch Sensortec GmbH
 # SPDX-License-Identifier: Apache-2.0
 
+title: Bosch BME680 Environmental Sensor (I2C)
+
 description: |
     The BME680 is an integrated environmental sensor that measures
     temperature, pressure, humidity and air quality
diff --git a/dts/bindings/sensor/bosch,bme680-spi.yaml b/dts/bindings/sensor/bosch,bme680-spi.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2022, Leonard Pollak
 # SPDX-License-Identifier: Apache-2.0
 
+title: Bosch BME680 Environmental Sensor (SPI)
+
 description: |
     The BME680 is an integrated environmental sensor that measures
     temperature, pressure, humidity and air quality
diff --git a/dts/bindings/sensor/nxp,s32-qdec.yaml b/dts/bindings/sensor/nxp,s32-qdec.yaml
@@ -1,8 +1,10 @@
 # Copyright 2023 NXP
 # SPDX-License-Identifier: Apache-2.0
 
+title: NXP S32 Quadrature Decoder
+
 description: |
-  Quadrature Decoder driver which processes encoder signals to determine motor revs
+  Quadrature Decoder processes encoder signals to determine motor revs
   with the cooperation of S32 IP blocks- eMIOS, TRGMUX and LCU.
   The sensor qdec application can be used for testing this driver.
   The following example uses TRGMUX IN2 and IN3 to connect to LCU1 LC0 I0 and I1.
diff --git a/dts/bindings/usb/nxp,usbphy.yaml b/dts/bindings/usb/nxp,usbphy.yaml
@@ -1,10 +1,12 @@
 # Copyright  2024 NXP
 # SPDX-License-Identifier: Apache-2.0
 
+title: NXP USB (Universal Serial Bus) High Speed PHY
+
 description: |
-  NXP USB high speed phy that is used on NXP RTxxxx, RTxxx, MCX, LPC and Kinetis
+  NXP USB high speed PHY that is used on NXP RTxxxx, RTxxx, MCX, LPC and Kinetis
   platforms if high speed usb is supported on these platforms.
-  Note: Only some LPC plafforms use it (like: LPC55S69, LPC55S28 and LPC55S16 etc).
+  Note: Only some LPC platforms use it (like: LPC55S69, LPC55S28 and LPC55S16 etc).
 
 compatible: "nxp,usbphy"
 
