\documentclass[aspectratio=169,obeyspaces,spaces,hyphens,dvipsnames]{beamer}
\usepackage[utf8]{inputenc}
\usepackage{minted}
\usepackage{hyperref}
\usepackage[export]{adjustbox}
\usepackage{subfigure}

\mode<presentation>
\usetheme{Bootlin}

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

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

\title{Understanding D-Bus}
\conference{Meetup Toulouse, May 2016}
\authors{Mylène Josserand}
\email{mylene.josserand@bootlin.com}
\institute{Bootlin}
\slidesurl{http://bootlin.com/pub/conferences/2016/meetup/dbus/}

\begin{document}

\addtocontents{toc}{\protect\setcounter{tocdepth}{-1}}
\section{Understanding D-Bus}
\addtocontents{toc}{\protect\setcounter{tocdepth}{2}}

\begin{frame}{What is this talk about?}
  \begin{itemize}
  \item D-Bus generality \& IPC
  \item The D-Bus principles
  \item Differents tools and libraries with demo
  \item Different projects using D-Bus
  \item A short use case with Connman and Ofono
  \end{itemize}
\end{frame}

\subsection{D-Bus generality}

\begin{frame}{D-Bus}
  \begin{columns}[T]
    \begin{column}{.6\textwidth}
      % The text
      \begin{itemize}
      \item Created in 2002
      \item Is part of the {\em freedesktop.org} project
      \item Maintained by RedHat and the community
      \item Is an Inter-process communication mechanism
      \item Initiated to standardize services of Linux desktop environments
      \end{itemize}
    \end{column}
    \begin{column}{.4\textwidth}
      % The image included here
    \begin{figure}[t]
      \subfigure{\includegraphics[width=0.8\textwidth]{drawings/freedesktop_logo.png}}
      \subfigure{\includegraphics[width=0.5\textwidth]{drawings/redhat_logo.png}}
    \end{figure}
  \end{column}
  \end{columns}
\end{frame}

\begin{frame}{Inter-Process Communication (IPC)}
  \begin{columns}[T]
    \begin{column}{.5\textwidth}
       % The text here
       \begin{itemize}
       \item Mechanisms allowing processes to communicate with each other
         \begin{itemize}
         \item \textbf{Shared memory}: read/write into a defined memory location
         \item \textbf{Memory-mapped file}: same as \code{shared memory} but uses a file
         \item \textbf{Pipe}: two-way data stream (standard input / output)
         \item \textbf{Named pipe}: same as \code{pipe} but uses a file (FIFO)
         \item \textbf{Socket}: communication even on distant machines
         \item and others
         \end{itemize}
       \end{itemize}
    \end{column}
    \begin{column}{.5\textwidth}
      % The image included here
      \includegraphics[width=\textwidth,right]{drawings/01-ipc_without_dbus.pdf}
    \end{column}
  \end{columns}
\end{frame}

\begin{frame}{IPC using D-Bus}
  \begin{itemize}
  \item Uses the socket mechanism
  \item Provides software bus abstraction
  \item Way simpler than most alternatives
  \end{itemize}
  \includegraphics[width=0.4\textwidth,center]{drawings/02-ipc_with_dbus.pdf}
\end{frame}

\subsection{How D-Bus is working ?}

\begin{frame}{D-Bus elements}
  \begin{itemize}
  \item D-Bus includes:
    \begin{itemize}
    \item \code{libdbus}: a low-level library
    \item \code{dbus-daemon}: a daemon based on libdbus. Handles and controls data transfers between DBus peers
    \item two types of busses: a \code{system} and a \code{session} one. Each bus instance is managed by a \code{dbus-daemon}
    \item a security mechanism using \code{policy} files
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{System \& Session busses}
  \begin{itemize}
  \item System bus
    \begin{itemize}
    \item On desktop, a single bus for all users
    \item Dedicated to system services
    \item Is about low-level events such as connection to a network, USB devices, etc
    \item On embedded Linux systems, this bus is often the only D-Bus type
    \end{itemize}
    \item Session bus
      \begin{itemize}
      \item One instance per user session
      \item Provides desktop services to user applications
      \item Linked to the X session
      \end{itemize}
    \end{itemize}
\end{frame}

\subsection{The principles}

\begin{frame}{Generality}
  \begin{itemize}
  \item D-Bus is working with different elements:
    \begin{itemize}
    \item Services
    \item Objects
    \item Interfaces
    \item Clients: applications using a D-Bus service
    \end{itemize}
  \item One D-Bus \textit{service} contains \textit{object(s)} which implements \textit{interface(s)}
  \end{itemize}
  \includegraphics[width=0.4\textwidth,center]{drawings/03-construction.pdf}
\end{frame}

\begin{frame}{Service}
  \begin{itemize}
  \item An application can expose its services to all D-Bus users by registering to a bus instance
  \item A \code{service} is a collection of \code{objects} providing a specific set of features
  \item When an application opens a connection to a bus instance, it is assigned a unique name (ie \code{:1.40})
  \item Can request a more human-readable service name: the \textbf{well-known name} (ie \code{org.ofono})
  See the \color{blue}{\href{https://dbus.freedesktop.org/doc/dbus-specification.html\#message-protocol-names-bus}{freedesktop.org specification}}
  \end{itemize}
  \includegraphics[width=0.4\textwidth,center]{drawings/04-service.pdf}
\end{frame}

\begin{frame}{Objects}
  \begin{itemize}
  \item Are attached to one service
  \item Can be dynamically created or removed
  \item Are uniquely identified by an \textbf{object path} (ie \code{/} or \code{/net/connman/technology/cellular})
  \item Implement one or several interfaces
  \end{itemize}
  \includegraphics[width=0.4\textwidth,center]{drawings/05-objects.pdf}
\end{frame}

\begin{frame}{Interfaces}
  \begin{itemize}
  \item Can be compared to a ``namespace'' in Java
  \item Has a unique name ressembling Java interface names, using dots (ie \code{org.ofono.Manager})
  \item Contains \textit{members}: properties, methods and signals
  \end{itemize}
  \includegraphics[width=0.6\textwidth,center]{drawings/06-interfaces.pdf}
\end{frame}

\begin{frame}{Interfaces}
  \begin{itemize}
  \item Can be compared to a ``namespace'' in Java
  \item Has a unique name ressembling Java interface names, using dots (ie \code{org.ofono.Manager})
  \item Contains \textit{members}: properties, methods and signals
  \end{itemize}
  \includegraphics[width=0.6\textwidth,center]{drawings/07-std-interfaces.pdf}
\end{frame}

\begin{frame}{Interfaces}
  \begin{itemize}
  \item D-Bus defines a few standard interfaces
  \item They all belong to the namespace ``org.freedesktop.DBus'' :
    \begin{itemize}
    \item \textbf{\href{https://dbus.freedesktop.org/doc/dbus-specification.html\#standard-interfaces-introspectable}{org.freedesktop.DBus.Introspectable}} : Provides an introspection mechanism. Exposes information about the object (interfaces, methods and signals it implements)
    \item \textbf{\href{https://dbus.freedesktop.org/doc/dbus-specification.html\#standard-interfaces-peer}{org.freedesktop.DBus.Peer}} : Provides methods to know if a connection is alive (ping)
    \item \textbf{\href{https://dbus.freedesktop.org/doc/dbus-specification.html\#standard-interfaces-properties}{org.freedesktop.DBus.Properties}} : Provides methods and signals to handle properties
    \item \textbf{\href{https://dbus.freedesktop.org/doc/dbus-specification.html\#standard-interfaces-objectmanager}{org.freedesktop.DBus.ObjectManager}} : Provides an helpful API to handle sub-tree objects
    \end{itemize}
    \item Interfaces expose properties, methods and signals
  \end{itemize}
\end{frame}

\begin{frame}{Properties}
  \begin{itemize}
  \item Directly accessible fields
  \item Can be read / written
  \item Can be of different types defined by the D-Bus specification :
    \begin{itemize}
      \item \href{https://dbus.freedesktop.org/doc/dbus-specification.html\#basic-types}{basic types}: bytes, boolean, integer, double, ...
      \item string-like types : string, object path (must be valid) and signature
      \item \href{https://dbus.freedesktop.org/doc/dbus-specification.html\#container-types}{container-types}: structure, array, variant (complex types) and dictionnary entry (hash)
    \end{itemize}
  \item Very convenient standard interface : \code{org.freedesktop.DBus.Properties}
% Parler des signatures ? TODO
  \item Types are represented by characters
  \end{itemize}
 \centering   \begin{tabular}{ll | ll | ll}
      byte & y & string & s & variant & v\\
      boolean & b & object-path & o & array of int32 & ai\\
      int32 & i & array & a & array of an array of int32 & aai\\
      uint32 & u & struct & () & array of a struct with 2 int32 fields & a(ii)\\
      double & d & dict & \{\} & dict of string and int32 & \{si\}\\
    \end{tabular}
\end{frame}

\begin{frame}[fragile]{Methods}
  \begin{itemize}
  \item allow remote procedure calls from one process to another
  \item Can be passed one or several parameters
  \item Can return values/objects
  \item Look like any method you could know from other languages
  \end{itemize}

  \begin{minted}[fontsize=\small]{bash}
    org.freedesktop.DBus.Properties :
      Get (String interface_name, String property_name) => Variant value
      GetAll (String interface_name) => Dict of {String, Variant} props 
      Set (String interface_name, String property_name, Variant value)
    \end{minted}
\end{frame}

\begin{frame}[fragile]{Signals}
  \begin{itemize}
  \item Messages / notifications
  \item Unidirectionnal
  \item Sent to every clients that are listening to it
  \item Can contain parameters
  \item A client will subscribe to signals to get notifications
  \end{itemize}
    \begin{minted}[fontsize=\small]{bash}
      org.freedesktop.DBus.Properties :
         PropertiesChanged (String, Dict of {String, Variant}, Array of String)
    \end{minted}
\end{frame}

\begin{frame}{Policy}
  \begin{itemize}
  \item Adds a security mechanism
  \item Represented by XML files
  \item Handled by each \code{dbus-daemon} (under \code{/etc/dbus-1/session.d} and \code{/etc/dbus-1/system.d})
  \item Allows the administrator to control which user can talk to which interface, which user can send message to which interface, and so on
  \item If you are not able to talk with a D-Bus service or get an \code{org.freedesktop.DBus.Error.AccessDenied} error, check this file!
  \item \code{org.freedesktop.PolicyKit1} has been created to handle all security accesses
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Policy - file example}
  \begin{itemize}
  \item In this example, "toto" can :
    \begin{itemize}
    \item own the interface \code{org.ofono}
    \item send messages to the owner of the given service
    \item call \code{GetContexts} from interface \code{org.ofono.ConnectionManager}
    \end{itemize}
  \end{itemize}
  \begin{minted}[fontsize=\footnotesize]{xml}
<!DOCTYPE busconfig PUBLIC
 ``-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN''
 ``http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd''>
 <busconfig>
    <policy user="toto">
        <allow own="org.ofono"/>
        <allow send_destination="org.ofono"/>
        <allow send_interface="org.ofono.ConnectionManager" send_member="GetContexts"/>
    </policy>
</busconfig>
\end{minted}
  \begin{itemize}
    \item Can \code{allow} or \code{deny}
  \end{itemize}
\end{frame}

\subsection{Tools and libraries}

\begin{frame}{Libraries \& bindings}
  \begin{itemize}
  \item \href{https://dbus.freedesktop.org/doc/api/html/index.html}{Libdbus}
    \begin{itemize}
    \item This is the low-level library used by the dbus-daemon.
    \item As the homepage of the project says: \textit{``If you use this low-level API directly, you're signing up for some pain''.}
    \item Recommended to use it only for small programs and you do not want to add many dependencies
    \end{itemize}
  \item \href{https://developer.gnome.org/gio/stable/gdbus-convenience.html}{GDbus}
    \begin{itemize}
    \item Is part of GLib (GIO)
    \item Provides a very comfortable API
    \end{itemize}
  \item \href{http://doc.qt.io/qt-5/qtdbus-index.html}{QtDbus}
    \begin{itemize}
    \item Is a Qt module
    \item Is useful if you already have Qt on your system
    \item Contains many classes to handle/interact such as \code{QDBusInterface}
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Libraries \& bindings}
  \begin{itemize}
  \item Bindings exist for other languages: dbus-python, dbus-java, ...
  \item All the bindings allow to:
    \begin{itemize}
    \item Interact with existing D-Bus services
    \item Create your own D-Bus services, objects, interfaces, and so on!
    \item but... D-Bus is not a high performance IPC
    \item Should be used only for \textbf{control} and not data
    \item For example, you can use it to activate an audio pipeline but not to send the audio stream
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Tools}
  \begin{itemize}
  \item Will present every tool with a demo
  \item \href{https://dbus.freedesktop.org/doc/dbus-send.1.html}{dbus-send}: Command-line interface (cli) to call method of interfaces (and get/set properties)
  \item \href{https://dbus.freedesktop.org/doc/dbus-monitor.1.html}{dbus-monitor}: Cli to subscribe and monitor signals
  \item \href{https://developer.gnome.org/gio/stable/gdbus.html}{gdbus}: A GLib implementation of a more complete tool than dbus-send/monitor
  \item \href{https://wiki.gnome.org/action/show/Apps/DFeet?action=show\&redirect=DFeet}{d-feet}: A GUI application to handle all D-Bus services
  \item and others...
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Tools: dbus-send}
  \begin{itemize}
  \item Can chose the session or system bus (\code{--session} or \code{--system})
  \item Here is an example:
  \end{itemize}
  \includegraphics[width=\textwidth,center]{drawings/08-dbus-send.pdf}
\end{frame}

\begin{frame}[fragile]{Tools: dbus-send - demo}
  \begin{itemize}
  \item Get properties:
    \begin{minted}[fontsize=\footnotesize]{bash}
dbus-send --system --print-reply --dest=net.connman / net.connman.Clock.GetProperties
    \end{minted}
  \item Set property:
    \begin{minted}[fontsize=\footnotesize]{bash}
    dbus-send --system --print-reply --dest=net.connman \
               / net.connman.Clock.SetProperty \
               string:TimeUpdates variant:string:manual
    \end{minted}
  \item Using standard interfaces:
    \begin{minted}[fontsize=\footnotesize]{bash}
    dbus-send --system --print-reply --dest=net.connman \
               / org.freedesktop.DBus.Introspectable.Introspect

    dbus-send --system --print-reply --dest=fi.w1.wpa_supplicant1 \
               /fi/w1/wpa_supplicant1 org.freedesktop.DBus.Properties.Get \
               string:fi.w1.wpa_supplicant1 string:Interfaces
  \end{minted}
  \end{itemize}
\end{frame}

\begin{frame}{Tools: dbus-monitor}
  \begin{itemize}
  \item Can monitor all traffic (including methods and signals if enabled in policy):
    \code{dbus-monitor}
  \item Or filter messages based on the interface:
    \code{dbus-monitor --system type=signal interface=net.connman.Clock}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Tools: gdbus}
  \begin{itemize}
  \item Also provides a command line interface
  \item Is more featureful than \code{dbus-send} because it handles ``dict entry''
  \item Has a different interface: must add a ``command'' such as ``call'' or ``monitor''
    \begin{minted}[fontsize=\footnotesize]{bash}
    gdbus call --system --dest net.connman \
          --object-path / --method net.connman.Clock.GetProperties
    gdbus call --system --dest net.connman --object-path / \
          --method net.connman.Clock.SetProperty 'TimeUpdates' "<'manual'>"
    gdbus monitor --system --dest net.connman
  \end{minted}
  \item Can even emit signals
    \begin{minted}[fontsize=\footnotesize]{bash}
      gdbus emit --session --object-path / --signal \\
      	net.connman.Clock.PropertyChanged ``['TimeUpdates', ``\<'auto'\>'']''
  \end{minted}
  \end{itemize}
\end{frame}

\begin{frame}{Tools: d-feet}
  \begin{itemize}
  \item Is a GUI interface
  \item Handles system and session busses
  \item Can call methods with parameters
    \includegraphics[width=0.8\textwidth,center]{drawings/09-d-feet.png}
  \item Alternatives: {\em bustle} (dbus-monitor like), {\em D-Bus inspector}, ...
  \end{itemize}
\end{frame}

\subsection{Projects using D-Bus}

\begin{frame}{Projects using D-Bus}
  \begin{itemize}
  \item KDE: A desktop environment based on Qt
  \item Gnome: A desktop environment based on gtk
  \item Systemd: An init system
  \item Bluez: A project adding Bluetooth support under Linux
  \item Pidgin: An instant messaging client
  \item Network-manager: A daemon to manage network interfaces
  \item Modem-manager: A daemon to provide an API to dial with modems - works with Network-Manager
  \item Connman: Same as Network-Manager but works with Ofono for modem
  \item Ofono: A daemon that exposing features provided by telephony devices such as modem
  \end{itemize}
\end{frame}

%\begin{frame}{NetworkManager \& nm-applet \& GTK}
%  \begin{itemize}
%  \item Illustrate the difference between system bus and session bus :
%    \begin{itemize}
%    \item \code{NetworkManager} manages network interfaces (default on Ubuntu).
%    \item Handles all the IP stack of Linux $\,\to\,$ on the system bus
%    \item \code{nm-applet} is a GTK interface used by the user to control network interfaces.
%    \item Handles all the user settings $\,\to\,$ on the session bus
%    \item These two daemons expose D-Bus services : \code{Network-Manager} to be used by \code{nm-applet} and \code{nm-applet} to be used by \code{GTK} (to print notifications)
%    \end{itemize}
%  \end{itemize}
%    \includegraphics[width=0.8\textwidth,center]{drawings/10-nm.pdf}
%\end{frame}

\subsection{Use case with ofono \& connman}

\begin{frame}{Ofono}
    \includegraphics[width=0.2\textwidth,center]{drawings/ofono_logo.png}
  \begin{itemize}
  \item Started in 2009
  \item Developed by Intel and Nokia
  \item Used in 2013 by Canonical for Ubuntu-touch
  \item Handles all the different parts to connect a modem: pin code, network registration, etc
  \item Communicates with connman using D-Bus
  \end{itemize}
\end{frame}

\begin{frame}{Connman}
    \includegraphics[width=0.2\textwidth,center]{drawings/connman_logo.jpg}
  \begin{itemize}
  \item Started in 2008
  \item Developed by Intel
  \item Used by Sailfish OS and Jolla
  \item Manages internet connexion within embbeded devices
  \item Provides a plugin based architecture (ofono provides such a plugin to communicate with the ofono daemon)
  \end{itemize}
\end{frame}

\begin{frame}{Communication}
  \begin{itemize}
  \item Ofono and Connman communication is an interesting use case
  \item Ofono handles the connection with a modem
  \item The user interacts with Ofono to enter PIN code, for example
  \item Once the PPP connection is established, Ofono exchanges informations with Connman
  \item Connman handles all the IP stack of Linux and updates ofono's informations using its plugin
  \includegraphics[width=\textwidth,center]{drawings/11-ofono-connman.pdf}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Communication}
  \begin{itemize}
  \item Connman communicates with Ofono internally
  \item On the contrary, Ofono exposes its connman plugin so the user can interact with ConnMan via Ofono's service
  \end{itemize}
    \begin{minted}[fontsize=\small]{bash}
      # Get the properties from ConnMan
      dbus-send --system --print-reply --dest=org.ofono /mymodem_0 \
                     org.ofono.ConnectionManager.GetProperties
      # Create a context in ConnMan which is used to create the data connection
      dbus-send --system --print-reply --dest=org.ofono /mymodem_0 \
                     org.ofono.ConnectionManager.AddContext string:'internet'
      # Activate the ConnMan's context => Ofono's work ends and
      # and ConnMan takes over from Ofono
      dbus-send --system --print-reply --dest=org.ofono /mymodem_0/context1 \
                     org.ofono.ConnectionContext.SetProperty \
                     string:'Active' variant:boolean:true
    \end{minted}
\end{frame}

\begin{frame}{Example with \code{Active} property}
  \includegraphics[width=\textwidth,center]{drawings/12-ofono-connman-interaction.pdf}
\end{frame}

\begin{frame}{Example with \code{Active} property}
  \includegraphics[width=\textwidth,center]{drawings/13-ofono-connman-interaction-proxy.pdf}
\end{frame}

\iffalse  \code{dbus-send --system --print-reply --dest=net.connman /net/connman/service/vpn_neutrino_bootlin net.connman.Service.GetProperties}
\fi

\subsection{Conclusion}

\begin{frame}{Conclusion}
  \begin{itemize}
  \item D-Bus is an IPC mechanism using sockets
  \item Should be used only for \code{control}
  \item Uses services, interfaces and objects
  \item Provides methods, properties and signals
  \item Many bindings are available in different languages: Qt, C++, Python, Java, etc
  \item Used in many projects: the kernel has even tried to implement a \code{kdbus} but abandonned it
  \end{itemize}
\end{frame}

\begin{frame}
  \begin{center}
  \Huge
  Questions? Suggestions? Comments?\\
  \vspace{1.5cm}
  \huge
  Mylène Josserand\\
  \large
  \vspace{0.5cm}
  \code{mylene.josserand@bootlin.com}
  \vspace{0.5cm}
  \newline Slides under CC-BY-SA 3.0\\
  \scriptsize
  \url{http://bootlin.com/pub/conferences/2016/meetup/dbus/}
  \end{center}
\end{frame}

\end{document}