\documentclass[aspectratio=169,obeyspaces,spaces,hyphens,dvipsnames]{beamer}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}% http://ctan.org/pkg/lm
\usepackage{minted}
\usepackage{hyperref}
\usepackage{xcolor}
\usepackage{pgfplots}
\usepackage{tikz}
\usepackage{tabularx}
\usepackage[normalem]{ulem}

\mode<presentation>
\usetheme{Bootlin}

\def\signed #1{{\leavevmode\unskip\nobreak\hfil\penalty50\hskip2em
  \hbox{}\nobreak\hfil(#1)
  \parfillskip=0pt \finalhyphendemerits=0 \endgraf}}

\graphicspath{ {./images/} }

\newsavebox\mybox
\newenvironment{aquote}[1]
  {\savebox\mybox{#1}\begin{quotation}}
  {\signed{\usebox\mybox}\end{quotation}}

\title{Device Tree overlays and U-boot extension board management}
\authors{Köry Maincent}
\email{kory.maincent@bootlin.com}
\slidesurl{https://bootlin.com/pub/conferences/2021/lee/maincent-devicetree-overlay-and-uboot-extension-board-management/}
\institute{Bootlin}
\conference{Live Embedded Event, June 3rd 2021}

\begin{document}

\addtocontents{toc}{\protect\setcounter{tocdepth}{-1}}
\section{Device Tree overlays and U-boot extension board management}
\addtocontents{toc}{\protect\setcounter{tocdepth}{2}}

\begin{frame}{Köry Maincent}
    \begin{itemize}
    \item Embedded Linux engineer at Bootlin
      \begin{itemize}
      \item Embedded Linux, U-Boot, Linux kernel, Yocto, Buildroot {\bf
          expertise}
      \item {\bf Development}, consulting and training
      \item Strong open-source focus
      \end{itemize}
    \item Open-source contributor
      \begin{itemize}
      \item Contributed {\bf extension board management support to U-Boot}
      \item Contributed Ubuntu support to ELBE
      \end{itemize}
    \item Living in {\bf Toulouse}, France
    \end{itemize}
\end{frame}

\begin{frame}{Agenda}
  \begin{itemize}
  \item Introduction to Device Tree overlays
    \begin{itemize}
    \item Principle
    \item Syntax
    \item Support in Linux / U-Boot
    \end{itemize}
  \item Beagleboard.org use of overlays for CAPE extensions
  \item The extension board manager in U-Boot
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Device Tree}
  \begin{itemize}
    \item Data structure that describes the hardware components and topology of the embedded platforms
    \item Used on a majority of CPU architectures
    \item See {\em Device Tree 101}, {\small \url{https://bootlin.com/pub/conferences/2021/webinar/petazzoni-device-tree-101/petazzoni-device-tree-101.pdf}}
  \end{itemize}
  \begin{onlyenv}<2>
  \begin{block}{}
  \fontsize{7}{7}\selectfont
    \begin{minted}{C}
/dts-v1/;
/ {
        compatible = "corp,foo";

        /* shared resources */
        res: res {
        };

        /* On chip peripherals */
        ocp: ocp {
                /* peripherals that are always instantiated */
                peripheral1 {
                        compatible = "foo,periph";
                };
        };
};
    \end{minted}
  \end{block}
  \end{onlyenv}
\end{frame}

\begin{frame}{Device Tree Overlay}
  \begin{columns}
  \column{0.6\textwidth}
  \begin{itemize}
    \item Goal:
    \begin{itemize}
      \item Modify a loaded Device Tree
      \item Add, remove, disable or adjust a node of the existing Device Tree
    \end{itemize}
    \bigskip
    \item In practice:
    \begin{itemize}
      \item Load the overlays corresponding to each extension boards plugged
      \item Load the overlay corresponding to the API programed in a FPGA region
      \end{itemize}
  \end{itemize}
    \column{0.4\textwidth}
    \includegraphics[width=0.8\textwidth]{dip.jpeg}
    \includegraphics[width=0.8\textwidth]{rasp-hat.jpeg}
  \end{columns}
\end{frame}

\begin{frame}[fragile]{Device Tree Overlay syntax}
\begin{itemize}
  \item Old syntax
  \begin{onlyenv}<2>
    \begin{block}{}
      \fontsize{8}{8}\selectfont
    \begin{minted}{C}
/dts-v1/;
/plugin/;       /* allow undefined label references and record them */
/ {
        /* various properties for loader use; i.e. part id etc. */
        fragment@0 {
                target = <&ocp>;
                __overlay__ {
                        /* bar peripheral */
                        bar {
                                compatible = "bar,periph";
                                /* various properties and child nodes */
                        };
                };
        };
};
    \end{minted}
  \end{block}
  \end{onlyenv}
  \item New syntax (since devicetree-compiler version 1.5)
  \begin{onlyenv}<3>
    \begin{block}{}
    \fontsize{8}{8}\selectfont
    \begin{minted}{C}
/dts-v1/;
/plugin/;

&ocp {
        /* bar peripheral */
        bar {
                compatible = "bar,periph";
                /* various properties and child nodes */
        };
};
    \end{minted}
    \end{block}
  \small You can use the syntax \code{&{/ocp}} to specify the targeted node path
  \end{onlyenv}
  \begin{onlyenv}<4>
  \item Compilation
  \begin{itemize}
    \item Build like normal devicetree
    \item Use \code{.dtbo} naming (DeviceTree Blob Overlay)
  \end{itemize}
  \begin{minted}{bash}
$ dtc -O dtb -o bar-overlay.dtbo bar-overlay.dts
  \end{minted}
  \end{onlyenv}
  \begin{onlyenv}<5>
    \item Result: \code{$ fdtdump bar.dtbo}
    \begin{block}{}
    \fontsize{6}{6}\selectfont
    \begin{minted}{C}
/dts-v1/;
// magic:               0xd00dfeed
// totalsize:           0xf2 (242)
// off_dt_struct:       0x38
// off_dt_strings:      0xdc
// off_mem_rsvmap:      0x28
// version:             17
// last_comp_version:   16
// boot_cpuid_phys:     0x0
// size_dt_strings:     0x16
// size_dt_struct:      0xa4

/ {
    fragment@0 {
        target = <0xffffffff>;
        __overlay__ {
            bar {
                compatible = "bar,periph";
            };
        };
    };
    __fixups__ {
        ocp = "/fragment@0:target:0";
    };
};
    \end{minted}
    \end{block}
  \end{onlyenv}
\end{itemize}
\end{frame}

\begin{frame}{Linux kernel support for DT overlays}
  \begin{itemize}
  \item Internal kernel API to apply/remove overlays in
    \code{<linux/of.h>}
    \begin{itemize}
    \item \code{of_overlay_fdt_apply}
    \item \code{of_overlay_remove}
    \item \code{of_overlay_remove_all}
    \item + notifiers
    \end{itemize}
  \item No user-space API provided in the upstream Linux kernel
    $\rightarrow$ no way to apply DT overlays from Linux.
  \item Various user-space APIs proposed over time, but never merged.
  \item Some downstream platform-specific kernels do have some custom
    user-space API
  \item Some subsystems are also not really ready to get extra DT
    description contributed at runtime
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{U-Boot support for DT overlays}

  \begin{itemize}

  \item Easier to handle overlays in U-Boot $\rightarrow$ they are
    applied before the DT is passed to the kernel

  \item \code{fdt} command has a \code{apply} subcommand to apply a DT
    overlay

    \begin{block}{}
      \begin{minted}{console}
=> fdt
fdt - flattened device tree utility commands

Usage:
....
fdt apply <addr>                    - Apply overlay to the DT
\end{minted}
    \end{block}

  \item Contributed by Bootlin to upstream U-Boot in 2016!

  \end{itemize}
\end{frame}

\begin{frame}[fragile]{The case of BeagleBoard.org and the CAPEs}
  \begin{columns}
  \column{0.6\textwidth}
  \begin{itemize}
    \item Several possibles CAPEs plugged into one board
    \begin{onlyenv}<2>
    \begin{itemize}
      \item Manage the different CAPEs easily by selecting the right overlay
      \item Each CAPE has a EEPROM filled with identification data, accessible over I2C
      \item BeagleBoard.org made a U-Boot patch to read the EEPROM and load the overlays that matches
    \end{itemize}
    \end{onlyenv}
    \bigskip
    \item CAPEs compatible with different base boards (BBB, BB-AI)
    \begin{onlyenv}<3>
    \begin{itemize}
      \item Different hardware between the different base boards
      \item Have to deal with the node naming
    \end{itemize}
    \end{onlyenv}
  \end{itemize}
  \column{0.4\textwidth}
  \begin{onlyenv}<1,2>
    \includegraphics[width=\textwidth]{bbb.jpeg}
  \end{onlyenv}
  \begin{onlyenv}<3>
    \begin{block}{BeagleBone\_Black\_buses.dtsi}
    \fontsize{6}{6}\selectfont
    \begin{minted}{C}
// I2Cs 
bone_i2c_1: &i2c1 {
};

bone_i2c_2: &i2c2 {
    // Already in use for cape EEPROM reading
};
    \end{minted}
    \end{block}
    \begin{block}{BeagleBone\_AI\_buses.dtsi}
    \fontsize{6}{6}\selectfont
    \begin{minted}{C}
// I2Cs
bone_i2c_1: &i2c5 {
};

bone_i2c_2: &i2c4 {
    // Already in use for cape EEPROM reading
};
    \end{minted}
    \end{block}
  \end{onlyenv}
  \end{columns}
\end{frame}

\begin{frame}{The extension board management in U-Boot}
  \begin{itemize}
    \item Implement a {\bf generic extension board manager}
    \item Replacement for the ad-hoc and platform-specific U-Boot
      scripts used in BeagleBoard.org forks of U-Boot
    \item Contributed by Bootlin, merged upstream, available at the v2021.07 release
    \item List of the commands implemented:
    \begin{itemize}
      \item \code{extension scan} to detect available extension boards
      \item \code{extension list} to list the detected extension boards
      \item \code{extension apply} to apply the Device Tree overlay(s) corresponding to one extension board or to all expansion boards
    \end{itemize}
    \item The \code{extension scan} command calls a board-specific function to enumerate the detected extension boards and fill-in information used by the generic extension board manager.
  \end{itemize}
\end{frame}

\begin{frame}{Demo}
  \begin{columns}
  \column{0.5\textwidth}
    \huge Show time !!
  \column{0.5\textwidth}
    \includegraphics[width=0.9\textwidth]{demo.jpeg}
  \end{columns}
\end{frame}

\begin{frame}{References}
  \begin{itemize}
  \item References:
  \begin{itemize}
    \item \url{https://www.kernel.org/doc/html/latest/devicetree/overlay-notes.html}
    \item \url{https://elinux.org/Beagleboard:BeagleBone_cape_interface_spec}
    \item \url{https://lists.denx.de/pipermail/u-boot/2021-May/448794.html}
  \end{itemize}
  \end{itemize}
\end{frame}

\questionslide

\end{document}
