Meetup Toulouse, May 2016

Understanding D-Bus
Mylène Josserand
[email protected]

© Copyright 2004-2018, Bootlin.

embedded Linux and kernel engineering
Creative Commons BY-SA 3.0 license.
Corrections, suggestions, contributions and translations are welcome!

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 1/1
 What is this talk about?

I D-Bus generality & IPC

I The D-Bus principles
I Differents tools and libraries with demo
I Different projects using D-Bus
I A short use case with Connman and Ofono

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 2/1
 Understanding D-Bus

D-Bus generality

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 3/1
 D-Bus

I Created in 2002
I Is part of the freedesktop.org project
I Maintained by RedHat and the community
I Is an Inter-process communication mechanism
I Initiated to standardize services of Linux
desktop environments

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 4/1
 Inter-Process Communication (IPC)

I Mechanisms allowing processes to

communicate with each other
I Shared memory: read/write into a
defined memory location
I Memory-mapped file: same as
shared memory but uses a file
I Pipe: two-way data stream
(standard input / output)
I Named pipe: same as pipe but
uses a file (FIFO)
I Socket: communication even on
distant machines
I and others

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 5/1
 IPC using D-Bus

I Uses the socket mechanism

I Provides software bus abstraction
I Way simpler than most alternatives

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 6/1
 Understanding D-Bus

How D-Bus is working ?

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 7/1
 D-Bus elements

I D-Bus includes:
I libdbus: a low-level library
I dbus-daemon: a daemon based on libdbus. Handles and controls data transfers
between DBus peers
I two types of busses: a system and a session one. Each bus instance is managed
by a dbus-daemon
I a security mechanism using policy files

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 8/1
 System & Session busses

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

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 9/1
 Understanding D-Bus

The principles

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 10/1
 Generality

I D-Bus is working with different elements:

I Services
I Objects
I Interfaces
I Clients: applications using a D-Bus service
I One D-Bus service contains object(s) which implements interface(s)

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 11/1
 Service
I An application can expose its services to all D-Bus users by registering to a bus
instance
I A service is a collection of objects providing a specific set of features
I When an application opens a connection to a bus instance, it is assigned a unique
name (ie :1.40)
I Can request a more human-readable service name: the well-known name (ie
org.ofono) See the freedesktop.org specification

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 12/1
 Objects

I Are attached to one service

I Can be dynamically created or removed
I Are uniquely identified by an object path (ie / or
/net/connman/technology/cellular)
I Implement one or several interfaces

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 13/1
 Interfaces

I Can be compared to a “namespace” in Java

I Has a unique name ressembling Java interface names, using dots (ie
org.ofono.Manager)
I Contains members: properties, methods and signals

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 14/1
 Interfaces

I Can be compared to a “namespace” in Java

I Has a unique name ressembling Java interface names, using dots (ie
org.ofono.Manager)
I Contains members: properties, methods and signals

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 15/1
 Interfaces

I D-Bus defines a few standard interfaces

I They all belong to the namespace “org.freedesktop.DBus” :
I org.freedesktop.DBus.Introspectable : Provides an introspection mechanism.
Exposes information about the object (interfaces, methods and signals it implements)
I org.freedesktop.DBus.Peer : Provides methods to know if a connection is alive
(ping)
I org.freedesktop.DBus.Properties : Provides methods and signals to handle
properties
I org.freedesktop.DBus.ObjectManager : Provides an helpful API to handle
sub-tree objects
I Interfaces expose properties, methods and signals

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 16/1
 Properties

I Directly accessible fields

I Can be read / written
I Can be of different types defined by the D-Bus specification :
I basic types: bytes, boolean, integer, double, ...
I string-like types : string, object path (must be valid) and signature
I container-types: structure, array, variant (complex types) and dictionnary entry
(hash)
I Very convenient standard interface : org.freedesktop.DBus.Properties
I Types are represented by characters
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}
- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 17/1
 Methods

I allow remote procedure calls from one process to another

I Can be passed one or several parameters
I Can return values/objects
I Look like any method you could know from other languages
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)

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 18/1
 Signals

I Messages / notifications
I Unidirectionnal
I Sent to every clients that are listening to it
I Can contain parameters
I A client will subscribe to signals to get notifications
org.freedesktop.DBus.Properties :
PropertiesChanged (String, Dict of {String, Variant}, Array of String)

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 19/1
 Policy

I Adds a security mechanism

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

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 20/1
 Policy - file example

I In this example, ”toto” can :

I own the interface org.ofono
I send messages to the owner of the given service
I call GetContexts from interface org.ofono.ConnectionManager
<!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>

I Can allow or deny

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 21/1
 Understanding D-Bus

Tools and libraries

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 22/1
 Libraries & bindings

I Libdbus
I This is the low-level library used by the dbus-daemon.
I As the homepage of the project says: “If you use this low-level API directly, you’re
signing up for some pain”.
I Recommended to use it only for small programs and you do not want to add many
dependencies
I GDbus
I Is part of GLib (GIO)
I Provides a very comfortable API
I QtDbus
I Is a Qt module
I Is useful if you already have Qt on your system
I Contains many classes to handle/interact such as QDBusInterface

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 23/1
 Libraries & bindings

I Bindings exist for other languages: dbus-python, dbus-java, ...

I All the bindings allow to:
I Interact with existing D-Bus services
I Create your own D-Bus services, objects, interfaces, and so on!
I but... D-Bus is not a high performance IPC
I Should be used only for control and not data
I For example, you can use it to activate an audio pipeline but not to send the audio
stream

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 24/1
 Tools

I Will present every tool with a demo

I dbus-send: Command-line interface (cli) to call method of interfaces (and get/set
properties)
I dbus-monitor: Cli to subscribe and monitor signals
I gdbus: A GLib implementation of a more complete tool than dbus-send/monitor
I d-feet: A GUI application to handle all D-Bus services
I and others...

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 25/1
 Tools: dbus-send

I Can chose the session or system bus (--session or --system)

I Here is an example:

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 26/1
 Tools: dbus-send - demo

I Get properties:
dbus-send --system --print-reply --dest=net.connman / net.connman.Clock.GetProperties
I Set property:
dbus-send --system --print-reply --dest=net.connman \
/ net.connman.Clock.SetProperty \
string:TimeUpdates variant:string:manual
I Using standard interfaces:
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

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 27/1
 Tools: dbus-monitor

I Can monitor all traffic (including methods and signals if enabled in policy):
dbus-monitor
I Or filter messages based on the interface:
dbus-monitor --system type=signal interface=net.connman.Clock

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 28/1
 Tools: gdbus

I Also provides a command line interface

I Is more featureful than dbus-send because it handles “dict entry”
I Has a different interface: must add a “command” such as “call” or “monitor”
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
I Can even emit signals
gdbus emit --session --object-path / --signal \\
net.connman.Clock.PropertyChanged ``['TimeUpdates', ``\<'auto'\>'']''

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 29/1
 Tools: d-feet

I Is a GUI interface
I Handles system and session busses
I Can call methods with parameters

I Alternatives: bustle (dbus-monitor like), D-Bus inspector, ...

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 30/1
 Understanding D-Bus

Projects using D-Bus

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 31/1
 Projects using D-Bus

I KDE: A desktop environment based on Qt

I Gnome: A desktop environment based on gtk
I Systemd: An init system
I Bluez: A project adding Bluetooth support under Linux
I Pidgin: An instant messaging client
I Network-manager: A daemon to manage network interfaces
I Modem-manager: A daemon to provide an API to dial with modems - works with
Network-Manager
I Connman: Same as Network-Manager but works with Ofono for modem
I Ofono: A daemon that exposing features provided by telephony devices such as
modem

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 32/1
 Understanding D-Bus

Use case with ofono & connman

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 33/1
 Ofono

I Started in 2009
I Developed by Intel and Nokia
I Used in 2013 by Canonical for Ubuntu-touch
I Handles all the different parts to connect a modem: pin code, network
registration, etc
I Communicates with connman using D-Bus

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 34/1
 Connman

I Started in 2008
I Developed by Intel
I Used by Sailfish OS and Jolla
I Manages internet connexion within embbeded devices
I Provides a plugin based architecture (ofono provides such a plugin to
communicate with the ofono daemon)

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 35/1
 Communication

I Ofono and Connman communication is an interesting use case

I Ofono handles the connection with a modem
I The user interacts with Ofono to enter PIN code, for example
I Once the PPP connection is established, Ofono exchanges informations with
Connman
I Connman handles all the IP stack of Linux and updates ofono’s informations using
its plugin

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 36/1
 Communication

I Connman communicates with Ofono internally

I On the contrary, Ofono exposes its connman plugin so the user can interact with
ConnMan via Ofono’s service
# 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

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 37/1
 Example with Active property

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 38/1
 Example with Active property

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 39/1
 Understanding D-Bus

Conclusion

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 40/1
 Conclusion

I D-Bus is an IPC mechanism using sockets

I Should be used only for control
I Uses services, interfaces and objects
I Provides methods, properties and signals
I Many bindings are available in different languages: Qt, C++, Python, Java, etc
I Used in many projects: the kernel has even tried to implement a kdbus but
abandonned it

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 41/1
 Questions? Suggestions? Comments?

Mylène Josserand
[email protected]

Slides under CC-BY-SA 3.0

http://bootlin.com/pub/conferences/2016/meetup/dbus/

- Kernel, drivers and embedded Linux - Development, consulting, training and support - https://bootlin.com 42/1