[bootlin/training-materials updates] master: device-model: Remove redundant DT chapter (3b33db48)
Miquel Raynal
miquel.raynal at bootlin.com
Sat Jan 14 00:07:03 CET 2023
Repository : https://github.com/bootlin/training-materials
On branch : master
Link : https://github.com/bootlin/training-materials/commit/3b33db48be3511f79667b5727588e9b9cd1ad608
>---------------------------------------------------------------
commit 3b33db48be3511f79667b5727588e9b9cd1ad608
Author: Miquel Raynal <miquel.raynal at bootlin.com>
Date: Sat Jan 14 00:05:15 2023 +0100
device-model: Remove redundant DT chapter
Signed-off-by: Miquel Raynal <miquel.raynal at bootlin.com>
>---------------------------------------------------------------
3b33db48be3511f79667b5727588e9b9cd1ad608
slides/kernel-device-model/kernel-device-model.tex | 383 ++-------------------
slides/kernel-hw-devices/kernel-hw-devices.tex | 25 ++
2 files changed, 53 insertions(+), 355 deletions(-)
diff --git a/slides/kernel-device-model/kernel-device-model.tex b/slides/kernel-device-model/kernel-device-model.tex
index 1586bd3a..6117c21d 100644
--- a/slides/kernel-device-model/kernel-device-model.tex
+++ b/slides/kernel-device-model/kernel-device-model.tex
@@ -504,371 +504,44 @@ base = ioremap(res->start, PAGE_SIZE);
sport->rxirq = platform_get_irq(pdev, 0);
\end{minted}
\end{block}
-\begin{frame}
- \frametitle{Device Tree}
- \begin{itemize}
- \item On many embedded architectures, manual instantiation of
- platform devices was considered to be too verbose and not easily
- maintainable.
- \item Such architectures have moved, to use the {\em Device Tree}.
- \item It is a {\bf tree of nodes} that models the hierarchy of
- devices in the system, from the devices inside the processor to
- the devices on the board.
- \item Each node can have a number of {\bf properties} describing
- various properties of the devices: addresses, interrupts, clocks,
- etc.
- \item At boot time, the kernel is given a compiled version, the {\bf
- Device Tree Blob}, which is parsed to instantiate all the
- devices described in the DT.
- \item On ARM, they are located in \kdir{arch/arm/boot/dts}.
- \end{itemize}
-\end{frame}
-
-\begin{frame}[fragile]
- \frametitle{Device Tree example}
- \begin{block}{}
-\begin{minted}[fontsize=\small]{perl}
-uart0: serial at 44e09000 {
- compatible = "ti,omap3-uart";
- ti,hwmods = "uart1";
- clock-frequency = <48000000>;
- reg = <0x44e09000 0x2000>;
- interrupts = <72>;
- status = "disabled";
-};
- \end{minted}
- \end{block}
- \normalsize
- \begin{itemize}
- \item \code{serial at 44e09000} is the {\bf node name}
- \item \code{uart0} is a {\bf label}, that can be referred to in other
- parts of the DT as \code{&uart0}
- \item other lines are {\bf properties}. Their values are usually
- strings, list of integers, or references to other nodes.
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{Device Tree inheritance (1/2)}
- \begin{itemize}
- \item Each particular hardware platform has its own {\em device tree}.
- \item However, several hardware platforms use the same processor,
- and often various processors in the same family share a number of
- similarities.
- \item To allow this, a {\em device tree} file can include another
- one. The trees described by the including file overwrites the tree
- described by the included file. This can be done:
+ \item As well as the various common dependencies through individual
+ APIs:
\begin{itemize}
- \item Either by using the \code{/include/} statement
- provided by the Device Tree language.
- \item Either by using the {\usebeamercolor[fg]{code}\tt
- \#include} statement, which requires calling the C
- preprocessor before parsing the Device Tree.
+ \item \kfunc{clk_get}
+ \item \kfunc{gpio_request}
+ \item \kfunc{dma_request_channel}
\end{itemize}
- Linux currently uses either one technique or the other
- (different from one ARM subarchitecture to another, for example).
\end{itemize}
\end{frame}
-\begin{frame}
- \frametitle{Device Tree inheritance (2/2)}
- \begin{center}
- \includegraphics[height=0.8\textheight]{slides/kernel-device-model/dt-inheritance.pdf}
- \end{center}
-\end{frame}
-
\begin{frame}[fragile]
- \frametitle{Device Tree: {\tt compatible} string}
- \small
+ \frametitle{Driver data}
\begin{itemize}
- \item With the {\em device tree}, a {\em device} is bound to the
- corresponding {\em driver} using the {\bf compatible} string.
- \item The \ksym{of_match_table} field of \kstruct{device_driver}
- lists the compatible strings supported by the driver.
- \kfile{drivers/tty/serial/omap-serial.c} example:
+ \item In addition to the per-device resources and information, drivers
+ may require driver-specific information to behave slighlty
+ differently when different flavors of an IP block are driven by the
+ same driver.
+ \item A \code{void *} \code{data} pointer can be used to store
+ per-compatible specificities:
\begin{block}{}
- \begin{minted}[fontsize=\tiny]{c}
-#if defined(CONFIG_OF)
-static const struct of_device_id omap_serial_of_match[] = {
- { .compatible = "ti,omap2-uart" },
- { .compatible = "ti,omap3-uart" },
- { .compatible = "ti,omap4-uart" },
- {},
-};
-MODULE_DEVICE_TABLE(of, omap_serial_of_match);
-#endif
-static struct platform_driver serial_omap_driver = {
- .probe = serial_omap_probe,
- .remove = serial_omap_remove,
- .driver = {
- .name = DRIVER_NAME,
- .pm = &serial_omap_dev_pm_ops,
- .of_match_table = of_match_ptr(omap_serial_of_match),
+ \begin{minted}[fontsize=\footnotesize]{c}
+static const struct of_device_id marvell_nfc_of_ids[] = {
+ {
+ .compatible = "marvell,armada-8k-nand-controller",
+ .data = &marvell_armada_8k_nfc_caps,
},
};
-\end{minted}
-\end{block}
- \item Note: the \kfunc{of_match_ptr} macro instantiates to \code{NULL}
- when \kconfig{CONFIG_OF} is not set.
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{Device Tree Resources}
- \begin{itemize}
- \item The drivers will use the same mechanism that we saw previously
- to retrieve basic information: interrupts numbers, physical
- addresses, etc.
- \item The available resources list will be built up by the kernel at
- 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}.
- \end{itemize}
-\end{frame}
-
-\begin{frame}{Device Tree design principles}
- \begin{itemize}
- \item {\bf Describe hardware} (how the hardware is), not
- configuration (how I choose to use the hardware)
- \item {\bf OS-agnostic}
- \begin{itemize}
- \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 Describe {\bf integration of hardware components}, not the internals
- of hardware components
- \begin{itemize}
- \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 \kdoctext{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}
- \kdoctext{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}
- \kdoctext{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}
+ \end{minted}
+ \end{block}
+ \item Which can be retrieved in the probe with:
\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 syntactic 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}
+ \begin{minted}[fontsize=\footnotesize]{c}
+ /* Get NAND controller capabilities */
+ if (pdev->id_entry) /* legacy way */
+ nfc->caps = (void *)pdev->id_entry->driver_data;
+ else /* current way */
+ nfc->caps = of_device_get_match_data(&pdev->dev);
+ \end{minted}
+ \end{block}
\end{itemize}
\end{frame}
-
-\begin{frame}
- \frametitle{References}
- \begin{columns}
- \column{0.6\textwidth}
- \begin{itemize}
- \item Device Tree 101 webinar, Thomas Petazzoni (2021):\\
- Slides: \url{https://bootlin.com/blog/device-tree-101-webinar-slides-and-videos/}\\
- Video: \url{https://youtu.be/a9CZ1Uk3OYQ}
- \item Kernel documentation
- \begin{itemize}
- \item \kdochtmldir{driver-api/driver-model}
- \item \kdochtmldir{devicetree}
- \item \kdochtml{filesystems/sysfs}
- \end{itemize}
- \item \url{https://devicetree.org}
- \item The kernel source code
- \begin{itemize}
- \item Full of examples of other drivers!
- \end{itemize}
- \end{itemize}
- \column{0.4\textwidth}
- \includegraphics[width=\textwidth]{common/device-tree-video.jpg}
- \end{columns}
-\end{frame}
-
diff --git a/slides/kernel-hw-devices/kernel-hw-devices.tex b/slides/kernel-hw-devices/kernel-hw-devices.tex
index c93bbe5b..5ce46b58 100644
--- a/slides/kernel-hw-devices/kernel-hw-devices.tex
+++ b/slides/kernel-hw-devices/kernel-hw-devices.tex
@@ -1153,6 +1153,31 @@ spi3: spi at 4000c000 {
% \end{frame}
+\begin{frame}
+ \frametitle{References}
+ \begin{columns}
+ \column{0.6\textwidth}
+ \begin{itemize}
+ \item Device Tree 101 webinar, Thomas Petazzoni (2021):\\
+ Slides: \url{https://bootlin.com/blog/device-tree-101-webinar-slides-and-videos/}\\
+ Video: \url{https://youtu.be/a9CZ1Uk3OYQ}
+ \item Kernel documentation
+ \begin{itemize}
+ \item \kdochtmldir{driver-api/driver-model}
+ \item \kdochtmldir{devicetree}
+ \item \kdochtml{filesystems/sysfs}
+ \end{itemize}
+ \item \url{https://devicetree.org}
+ \item The kernel source code
+ \begin{itemize}
+ \item Full of examples of other drivers!
+ \end{itemize}
+ \end{itemize}
+ \column{0.4\textwidth}
+ \includegraphics[width=\textwidth]{common/device-tree-video.jpg}
+ \end{columns}
+\end{frame}
+
\subsection{Discoverable hardware: USB and PCI}
\begin{frame}{Discoverable hardware}
More information about the training-materials-updates
mailing list