[bootlin/training-materials updates] master: Kernel slides: update explanations about DT bindings (de5d5687)
Michael Opdenacker
michael.opdenacker at bootlin.com
Mon Apr 19 07:55:44 CEST 2021
Repository : https://github.com/bootlin/training-materials
On branch : master
Link : https://github.com/bootlin/training-materials/commit/de5d5687880f0eda2b4e1d743ebe76f25ca04d5a
>---------------------------------------------------------------
commit de5d5687880f0eda2b4e1d743ebe76f25ca04d5a
Author: Michael Opdenacker <michael.opdenacker at bootlin.com>
Date: Mon Apr 19 07:55:44 2021 +0200
Kernel slides: update explanations about DT bindings
- Used the DT 101 slides from Thomas Petazzoni
Signed-off-by: Michael Opdenacker <michael.opdenacker at bootlin.com>
>---------------------------------------------------------------
de5d5687880f0eda2b4e1d743ebe76f25ca04d5a
slides/kernel-device-model/dt-spec.png | Bin 0 -> 38250 bytes
slides/kernel-device-model/kernel-device-model.tex | 234 +++++++++++++++++++--
2 files changed, 213 insertions(+), 21 deletions(-)
diff --git a/slides/kernel-device-model/dt-spec.png b/slides/kernel-device-model/dt-spec.png
new file mode 100644
index 00000000..d35fa90d
Binary files /dev/null and b/slides/kernel-device-model/dt-spec.png differ
diff --git a/slides/kernel-device-model/kernel-device-model.tex b/slides/kernel-device-model/kernel-device-model.tex
index 56879748..1563b0a8 100644
--- a/slides/kernel-device-model/kernel-device-model.tex
+++ b/slides/kernel-device-model/kernel-device-model.tex
@@ -733,34 +733,226 @@ static struct platform_driver serial_omap_driver = {
boot time from the device tree, so that you don't need to make any
unnecessary lookups to the DT when loading your driver.
\item Any additional information will be specific to a driver or
- the class it belongs to, defining the {\em bindings}
+ the class it belongs to, defining the {\em bindings}.
\end{itemize}
\end{frame}
-\begin{frame}{Device Tree bindings}
+\begin{frame}{Device Tree design principles}
\begin{itemize}
- \item The compatible string and the associated properties define
- what is called a {\em device tree binding}.
- \item {\em Device tree bindings} are all defined in
- \kdir{devicetree/bindings}.
- \item Since the Device Tree is normally part of the kernel ABI, the
- {\em bindings} must remain compatible over time.
+ \item {\bf Describe hardware} (how the hardware is), not
+ configuration (how I choose to use the hardware)
+ \item {\bf OS-agnostic}
\begin{itemize}
- \item A new kernel must be capable of using an old Device Tree.
- \item This requires a very careful design of the bindings. They
- are all reviewed on the \code{devicetree at vger.kernel.org}
- mailing list.
- \item See Thomas Petazzoni's presentation on this topic:
- {\em Device Tree as a stable ABI: a fairy tale?}
- (\url{https://bit.ly/1U1tYkT}).
+ \item For a given piece of HW, Device Tree should be the same for
+ U-Boot, FreeBSD or Linux
+ \item There should be no need to change the Device Tree when updating the OS
\end{itemize}
- \item A Device Tree binding should contain only a {\em description
- of the hardware} and not {\em configuration}.
+ \item Describe {\bf integration of hardware components}, not the internals
+ of hardware components
\begin{itemize}
- \item An interrupt number can be part of the Device Tree as it
- describes the hardware.
- \item But not whether DMA should be used for a device or not,
- as it is a configuration choice.
+ \item The details of how a specific device/IP block is working is
+ handled by code in device drivers
+ \item The Device Tree describes how the device/IP block is
+ connected/integrated with the rest of the system: IRQ lines, DMA
+ channels, clocks, reset lines, etc.
+ \end{itemize}
+ \item Like all beautiful design principles, these principles are
+ sometimes violated.
+ \end{itemize}
+\end{frame}
+
+\begin{frame}{Device Tree specifications}
+ \begin{columns}
+ \column{0.7\textwidth}
+ \begin{itemize}
+ \item How to write the correct nodes/properties to describe a
+ given hardware platform~?
+ \item {\bf DeviceTree Specifications} $\rightarrow$ base Device
+ Tree syntax + number of standard properties.
+ \begin{itemize}
+ \item \url{https://www.devicetree.org/specifications/}
+ \item Not sufficient to describe the wide variety of hardware.
+ \end{itemize}
+ \item {\bf Device Tree Bindings} $\rightarrow$ documents that each
+ specify how a piece of HW should be described
+ \begin{itemize}
+ \item \code{Documentation/devicetree/bindings/} in Linux kernel sources
+ \item Reviewed by DT bindings maintainer team
+ \item Legacy: human readable documents
+ \item New norm: YAML-written specifications
+ \end{itemize}
+ \end{itemize}
+ \column{0.3\textwidth}
+ \includegraphics[width=\textwidth]{slides/kernel-device-model/dt-spec.png}
+ \end{columns}
+\end{frame}
+
+\begin{frame}[fragile]{Device Tree binding: old style}
+ \begin{center}
+ \kfile{Documentation/devicetree/bindings/mtd/spear_smi.txt}\\
+ \end{center}
+ \begin{columns}[t]
+ \column{0.5\textwidth}
+ \begin{block}{}
+ {\fontsize{5}{6}\selectfont
+\begin{verbatim}
+* SPEAr SMI
+
+Required properties:
+- compatible : "st,spear600-smi"
+- reg : Address range of the mtd chip
+- #address-cells, #size-cells : Must be present if the device has sub-nodes
+ representing partitions.
+- interrupts: Should contain the STMMAC interrupts
+- clock-rate : Functional clock rate of SMI in Hz
+
+Optional properties:
+- st,smi-fast-mode : Flash supports read in fast mode
+
+\end{verbatim}
+ }
+ \end{block}
+ \column{0.5\textwidth}
+ \begin{block}{}
+ {\fontsize{4}{5}\selectfont
+\begin{verbatim}
+Example:
+
+ smi: flash at fc000000 {
+ compatible = "st,spear600-smi";
+ #address-cells = <1>;
+ #size-cells = <1>;
+ reg = <0xfc000000 0x1000>;
+ interrupt-parent = <&vic1>;
+ interrupts = <12>;
+ clock-rate = <50000000>; /* 50MHz */
+
+ flash at f8000000 {
+ st,smi-fast-mode;
+ ...
+ };
+ };
+\end{verbatim}
+ }
+ \end{block}
+ \end{columns}
+\end{frame}
+
+\begin{frame}[fragile]{Device Tree binding: YAML style}
+ \kfile{Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml}
+ \begin{columns}[t]
+ \column{0.5\textwidth}
+ \begin{block}{}
+ {\fontsize{5}{6}\selectfont
+\begin{minted}{yaml}
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/st,stm32-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: I2C controller embedded in STMicroelectronics STM32 I2C platform
+
+maintainers:
+ - Pierre-Yves MORDRET <pierre-yves.mordret at st.com>
+
+properties:
+ compatible:
+ enum:
+ - st,stm32f4-i2c
+ - st,stm32f7-i2c
+ - st,stm32mp15-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: interrupt ID for I2C event
+ - description: interrupt ID for I2C error
+
+ resets:
+ maxItems: 1
+
+\end{minted}
+ }
+ \end{block}
+ \column{0.5\textwidth}
+ \begin{block}{}
+ {\fontsize{5}{6}\selectfont
+\begin{minted}{yaml}
+ clocks:
+ maxItems: 1
+
+ dmas:
+ items:
+ - description: RX DMA Channel phandle
+ - description: TX DMA Channel phandle
+
+ ...
+
+ clock-frequency:
+ description: Desired I2C bus clock frequency in Hz. If not specified,
+ the default 100 kHz frequency will be used.
+ For STM32F7, STM32H7 and STM32MP1 SoCs, if timing
+ parameters match, the bus clock frequency can be from
+ 1Hz to 1MHz.
+ default: 100000
+ minimum: 1
+ maximum: 1000000
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - resets
+ - clocks
+\end{minted}
+ }
+ \end{block}
+ \end{columns}
+\end{frame}
+
+\begin{frame}[fragile]{Device Tree binding: YAML style example}
+ \begin{block}{}
+ {\fontsize{5}{6}\selectfont
+\begin{minted}{yaml}
+examples:
+ - |
+ //Example 3 (with st,stm32mp15-i2c compatible on stm32mp)
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/stm32mp1-clks.h>
+ #include <dt-bindings/reset/stm32mp1-resets.h>
+ i2c at 40013000 {
+ compatible = "st,stm32mp15-i2c";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x40013000 0x400>;
+ interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&rcc I2C2_K>;
+ resets = <&rcc I2C2_R>;
+ i2c-scl-rising-time-ns = <185>;
+ i2c-scl-falling-time-ns = <20>;
+ st,syscfg-fmp = <&syscfg 0x4 0x2>;
+ };
+\end{minted}
+ }
+ \end{block}
+\end{frame}
+
+\begin{frame}{Validating Device Tree in Linux}
+ \begin{itemize}
+ \item \code{dtc} only does syntaxic validation
+ \item YAML bindings allow to do semantic validation
+ \item Linux kernel \code{make} rules:
+ \begin{itemize}
+ \item \code{make dt_binding_check}\\
+ verify that YAML bindings are valid
+ \item \code{make dtbs_check}\\
+ validate DTs currently enabled against YAML bindings
+ \item \code{make DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml dtbs_check}\\
+ validate DTs against a specific YAML binding
\end{itemize}
\end{itemize}
\end{frame}
More information about the training-materials-updates
mailing list