From: Greg Kroah-Hartman <gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org>
To: arnd-r2nGTMty4D4@public.gmane.org,
ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org,
gnomes-qBU/x9rampVanCEyBjwyrvXRex20P6io@public.gmane.org,
teg-B22kvLQNl6c@public.gmane.org,
jkosina-AlSwsSmVLrQ@public.gmane.org,
luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org,
linux-api-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
Cc: daniel-cYrQPVfZoowdnm+yROfE0A@public.gmane.org,
dh.herrmann-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org,
tixxdz-Umm1ozX2/EEdnm+yROfE0A@public.gmane.org,
Greg Kroah-Hartman
<gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org>
Subject: [PATCH 01/14] kdbus: add documentation
Date: Mon, 9 Mar 2015 14:09:07 +0100 [thread overview]
Message-ID: <1425906560-13798-2-git-send-email-gregkh@linuxfoundation.org> (raw)
In-Reply-To: <1425906560-13798-1-git-send-email-gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org>
From: Daniel Mack <daniel-cYrQPVfZoowdnm+yROfE0A@public.gmane.org>
kdbus is a system for low-latency, low-overhead, easy to use
interprocess communication (IPC).
The interface to all functions in this driver is implemented via ioctls
on files exposed through a filesystem called 'kdbusfs'. The default
mount point of kdbusfs is /sys/fs/kdbus. This patch adds detailed
documentation about the kernel level API design.
This patch adds a set of comprehensive set of DocBook files which
can be turned into man-pages using 'make mandocs', or into HTML
files with 'make htmldocs'.
Signed-off-by: Daniel Mack <daniel-cYrQPVfZoowdnm+yROfE0A@public.gmane.org>
Signed-off-by: David Herrmann <dh.herrmann-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
Signed-off-by: Djalal Harouni <tixxdz-Umm1ozX2/EEdnm+yROfE0A@public.gmane.org>
Signed-off-by: Greg Kroah-Hartman <gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org>
---
Documentation/Makefile | 2 +-
Documentation/kdbus/Makefile | 30 +
Documentation/kdbus/kdbus.bus.xml | 360 +++++++++
Documentation/kdbus/kdbus.connection.xml | 1252 +++++++++++++++++++++++++++++
Documentation/kdbus/kdbus.endpoint.xml | 436 ++++++++++
Documentation/kdbus/kdbus.fs.xml | 124 +++
Documentation/kdbus/kdbus.item.xml | 840 ++++++++++++++++++++
Documentation/kdbus/kdbus.match.xml | 553 +++++++++++++
Documentation/kdbus/kdbus.message.xml | 1277 ++++++++++++++++++++++++++++++
Documentation/kdbus/kdbus.name.xml | 711 +++++++++++++++++
Documentation/kdbus/kdbus.policy.xml | 406 ++++++++++
Documentation/kdbus/kdbus.pool.xml | 320 ++++++++
Documentation/kdbus/kdbus.xml | 1012 +++++++++++++++++++++++
Documentation/kdbus/stylesheet.xsl | 16 +
Makefile | 1 +
15 files changed, 7339 insertions(+), 1 deletion(-)
create mode 100644 Documentation/kdbus/Makefile
create mode 100644 Documentation/kdbus/kdbus.bus.xml
create mode 100644 Documentation/kdbus/kdbus.connection.xml
create mode 100644 Documentation/kdbus/kdbus.endpoint.xml
create mode 100644 Documentation/kdbus/kdbus.fs.xml
create mode 100644 Documentation/kdbus/kdbus.item.xml
create mode 100644 Documentation/kdbus/kdbus.match.xml
create mode 100644 Documentation/kdbus/kdbus.message.xml
create mode 100644 Documentation/kdbus/kdbus.name.xml
create mode 100644 Documentation/kdbus/kdbus.policy.xml
create mode 100644 Documentation/kdbus/kdbus.pool.xml
create mode 100644 Documentation/kdbus/kdbus.xml
create mode 100644 Documentation/kdbus/stylesheet.xsl
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6883a1b9b351..5e3fde632d03 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,4 +1,4 @@
subdir-y := accounting arm auxdisplay blackfin connector \
- filesystems filesystems ia64 laptops mic misc-devices \
+ filesystems filesystems ia64 kdbus laptops mic misc-devices \
networking pcmcia prctl ptp spi timers vDSO video4linux \
watchdog
diff --git a/Documentation/kdbus/Makefile b/Documentation/kdbus/Makefile
new file mode 100644
index 000000000000..cd6b48ee41bf
--- /dev/null
+++ b/Documentation/kdbus/Makefile
@@ -0,0 +1,30 @@
+DOCS := \
+ kdbus.xml \
+ kdbus.bus.xml \
+ kdbus.connection.xml \
+ kdbus.endpoint.xml \
+ kdbus.fs.xml \
+ kdbus.item.xml \
+ kdbus.match.xml \
+ kdbus.message.xml \
+ kdbus.name.xml \
+ kdbus.policy.xml \
+ kdbus.pool.xml
+
+XMLFILES := $(addprefix $(obj)/,$(DOCS))
+MANFILES := $(patsubst %.xml, %.7, $(XMLFILES))
+HTMLFILES := $(patsubst %.xml, %.html, $(XMLFILES))
+
+XMLTO_ARGS := -m $(obj)/stylesheet.xsl
+
+%.7: %.xml
+ xmlto man $(XMLTO_ARGS) -o . $<
+
+%.html: %.xml
+ xmlto html-nochunks $(XMLTO_ARGS) -o . $<
+
+mandocs: $(MANFILES)
+
+htmldocs: $(HTMLFILES)
+
+clean-files := $(MANFILES) $(HTMLFILES)
diff --git a/Documentation/kdbus/kdbus.bus.xml b/Documentation/kdbus/kdbus.bus.xml
new file mode 100644
index 000000000000..4d875e59ac02
--- /dev/null
+++ b/Documentation/kdbus/kdbus.bus.xml
@@ -0,0 +1,360 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.bus">
+
+ <refentryinfo>
+ <title>kdbus.bus</title>
+ <productname>kdbus.bus</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.bus</refname>
+ <refpurpose>kdbus bus</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A bus is a resource that is shared between connections in order to
+ transmit messages (see
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ).
+ Each bus is independent, and operations on the bus will not have any
+ effect on other buses. A bus is a management entity that controls the
+ addresses of its connections, their policies and message transactions
+ performed via this bus.
+ </para>
+ <para>
+ Each bus is bound to the mount instance it was created on. It has a
+ custom name that is unique across all buses of a domain. In
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ , a bus is presented as a directory. No operations can be performed on
+ the bus itself; instead you need to perform the operations on an endpoint
+ associated with the bus. Endpoints are accessible as files underneath the
+ bus directory. A default endpoint called <constant>bus</constant> is
+ provided on each bus.
+ </para>
+ <para>
+ Bus names may be chosen freely except for one restriction: the name must
+ be prefixed with the numeric effective UID of the creator and a dash. This
+ is required to avoid namespace clashes between different users. When
+ creating a bus, the name that is passed in must be properly formatted, or
+ the kernel will refuse creation of the bus. Example:
+ <literal>1047-foobar</literal> is an acceptable name for a bus
+ registered by a user with UID 1047. However,
+ <literal>1024-foobar</literal> is not, and neither is
+ <literal>foobar</literal>. The UID must be provided in the
+ user-namespace of the bus owner.
+ </para>
+ <para>
+ To create a new bus, you need to open the control file of a domain and
+ employ the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl. The control
+ file descriptor that was used to issue
+ <constant>KDBUS_CMD_BUS_MAKE</constant> must not previously have been
+ used for any other control-ioctl and must be kept open for the entire
+ life-time of the created bus. Closing it will immediately cleanup the
+ entire bus and all its associated resources and endpoints. Every control
+ file descriptor can only be used to create a single new bus; from that
+ point on, it is not used for any further communication until the final
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ .
+ </para>
+ <para>
+ Each bus will generate a random, 128-bit UUID upon creation. This UUID
+ will be returned to creators of connections through
+ <varname>kdbus_cmd_hello.id128</varname> and can be used to uniquely
+ identify buses, even across different machines or containers. The UUID
+ will have its variant bits set to <literal>DCE</literal>, and denote
+ version 4 (random). For more details on UUIDs, see <ulink
+ url="https://en.wikipedia.org/wiki/Universally_unique_identifier">
+ the Wikipedia article on UUIDs</ulink>.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Creating buses</title>
+ <para>
+ To create a new bus, the <constant>KDBUS_CMD_BUS_MAKE</constant>
+ command is used. It takes a <type>struct kdbus_cmd</type> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>The flags for creation.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
+ <listitem>
+ <para>Make the bus file group-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
+ <listitem>
+ <para>Make the bus file world-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items (see
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ) are expected for <constant>KDBUS_CMD_BUS_MAKE</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
+ <listitem>
+ <para>
+ Contains a null-terminated string that identifies the
+ bus. The name must be unique across the kdbus domain and
+ must start with the effective UID of the caller, followed by
+ a '<literal>-</literal>' (dash). This item is mandatory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
+ <listitem>
+ <para>
+ Bus-wide bloom parameters passed in a
+ <type>struct kdbus_bloom_parameter</type>. These settings are
+ copied back to new connections verbatim. This item is
+ mandatory. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a more detailed description of this item.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
+ <listitem>
+ <para>
+ An optional item that contains a set of required attach flags
+ that connections must allow. This item is used as a
+ negotiation measure during connection creation. If connections
+ do not satisfy the bus requirements, they are not allowed on
+ the bus. If not set, the bus does not require any metadata to
+ be attached; in this case connections are free to set their
+ own attach flags.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
+ <listitem>
+ <para>
+ An optional item that contains a set of attach flags that are
+ returned to connections when they query the bus creator
+ metadata. If not set, no metadata is returned.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_BUS_MAKE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EBADMSG</constant></term>
+ <listitem><para>
+ A mandatory item is missing.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in the <constant>struct kdbus_cmd</constant>
+ are invalid or the supplied name does not start with the current
+ UID and a '<literal>-</literal>' (dash).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ A bus of that name already exists.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESHUTDOWN</constant></term>
+ <listitem><para>
+ The kdbus mount instance for the bus was already shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ The maximum number of buses for the current user is exhausted.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.connection.xml b/Documentation/kdbus/kdbus.connection.xml
new file mode 100644
index 000000000000..09852125b2d4
--- /dev/null
+++ b/Documentation/kdbus/kdbus.connection.xml
@@ -0,0 +1,1252 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.connection">
+
+ <refentryinfo>
+ <title>kdbus.connection</title>
+ <productname>kdbus.connection</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.connection</refname>
+ <refpurpose>kdbus connection</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Connections are identified by their <emphasis>connection ID</emphasis>,
+ internally implemented as a <type>uint64_t</type> counter.
+ The IDs of every newly created bus start at <constant>1</constant>, and
+ every new connection will increment the counter by <constant>1</constant>.
+ The IDs are not reused.
+ </para>
+ <para>
+ In higher level tools, the user visible representation of a connection is
+ defined by the D-Bus protocol specification as
+ <constant>":1.<ID>"</constant>.
+ </para>
+ <para>
+ Messages with a specific <type>uint64_t</type> destination ID are
+ directly delivered to the connection with the corresponding ID. Signal
+ messages (see
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>)
+ may be addressed to the special destination ID
+ <constant>KDBUS_DST_ID_BROADCAST</constant> (~0ULL) and will then
+ potentially be delivered to all currently active connections on the bus.
+ However, in order to receive any signal messages, clients must subscribe
+ to them by installing a match (see
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ).
+ </para>
+ <para>
+ Messages synthesized and sent directly by the kernel will carry the
+ special source ID <constant>KDBUS_SRC_ID_KERNEL</constant> (0).
+ </para>
+ <para>
+ In addition to the unique <type>uint64_t</type> connection ID,
+ established connections can request the ownership of
+ <emphasis>well-known names</emphasis>, under which they can be found and
+ addressed by other bus clients. A well-known name is associated with one
+ and only one connection at a time. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ on name acquisition, the name registry, and the validity of names.
+ </para>
+ <para>
+ Messages can specify the special destination ID
+ <constant>KDBUS_DST_ID_NAME</constant> (0) and carry a well-known name
+ in the message data. Such a message is delivered to the destination
+ connection which owns that well-known name.
+ </para>
+
+ <programlisting><![CDATA[
+ +-------------------------------------------------------------------------+
+ | +---------------+ +---------------------------+ |
+ | | Connection | | Message | -----------------+ |
+ | | :1.22 | --> | src: 22 | | |
+ | | | | dst: 25 | | |
+ | | | | | | |
+ | | | | | | |
+ | | | +---------------------------+ | |
+ | | | | |
+ | | | <--------------------------------------+ | |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ +---------------------------+ | | |
+ | | Connection | | Message | -----+ | |
+ | | :1.25 | --> | src: 25 | | |
+ | | | | dst: 0xffffffffffffffff | -------------+ | |
+ | | | | (KDBUS_DST_ID_BROADCAST) | | | |
+ | | | | | ---------+ | | |
+ | | | +---------------------------+ | | | |
+ | | | | | | |
+ | | | <--------------------------------------------------+ |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ +---------------------------+ | | |
+ | | Connection | | Message | --+ | | |
+ | | :1.55 | --> | src: 55 | | | | |
+ | | | | dst: 0 / org.foo.bar | | | | |
+ | | | | | | | | |
+ | | | | | | | | |
+ | | | +---------------------------+ | | | |
+ | | | | | | |
+ | | | <------------------------------------------+ | |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ | | |
+ | | Connection | | | |
+ | | :1.81 | | | |
+ | | org.foo.bar | | | |
+ | | | | | |
+ | | | | | |
+ | | | <-----------------------------------+ | |
+ | | | | |
+ | | | <----------------------------------------------+ |
+ | +---------------+ |
+ +-------------------------------------------------------------------------+
+ ]]></programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Privileged connections</title>
+ <para>
+ A connection is considered <emphasis>privileged</emphasis> if the user
+ it was created by is the same that created the bus, or if the creating
+ task had <constant>CAP_IPC_OWNER</constant> set when it called
+ <constant>KDBUS_CMD_HELLO</constant> (see below).
+ </para>
+ <para>
+ Privileged connections have permission to employ certain restricted
+ functions and commands, which are explained below and in other kdbus
+ man-pages.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Activator and policy holder connection</title>
+ <para>
+ An <emphasis>activator</emphasis> connection is a placeholder for a
+ <emphasis>well-known name</emphasis>. Messages sent to such a connection
+ can be used to start an implementer connection, which will then get all
+ the messages from the activator copied over. An activator connection
+ cannot be used to send any message.
+ </para>
+ <para>
+ A <emphasis>policy holder</emphasis> connection only installs a policy
+ for one or more names. These policy entries are kept active as long as
+ the connection is alive, and are removed once it terminates. Such a
+ policy connection type can be used to deploy restrictions for names that
+ are not yet active on the bus. A policy holder connection cannot be used
+ to send any message.
+ </para>
+ <para>
+ The creation of activator or policy holder connections is restricted to
+ privileged users on the bus (see above).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Monitor connections</title>
+ <para>
+ Monitors are eavesdropping connections that receive all the traffic on the
+ bus, but is invisible to other connections. Such connections have all
+ properties of any other, regular connection, except for the following
+ details:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ They will get every message sent over the bus, both unicasts and
+ broadcasts.
+ </para></listitem>
+
+ <listitem><para>
+ Installing matches for signal messages is neither necessary
+ nor allowed.
+ </para></listitem>
+
+ <listitem><para>
+ They cannot send messages or be directly addressed as receiver.
+ </para></listitem>
+
+ <listitem><para>
+ They cannot own well-known names. Therefore, they also can't operate as
+ activators.
+ </para></listitem>
+
+ <listitem><para>
+ Their creation and destruction will not cause
+ <constant>KDBUS_ITEM_ID_{ADD,REMOVE}</constant> (see
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>).
+ </para></listitem>
+
+ <listitem><para>
+ They are not listed with their unique name in name registry dumps
+ (see <constant>KDBUS_CMD_NAME_LIST</constant> in
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>), so other connections cannot detect the presence of
+ a monitor.
+ </para></listitem>
+ </itemizedlist>
+ <para>
+ The creation of monitor connections is restricted to privileged users on
+ the bus (see above).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Creating connections</title>
+ <para>
+ A connection to a bus is created by opening an endpoint file (see
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>)
+ of a bus and becoming an active client with the
+ <constant>KDBUS_CMD_HELLO</constant> ioctl. Every connection has a unique
+ identifier on the bus and can address messages to every other connection
+ on the same bus by using the peer's connection ID as the destination.
+ </para>
+ <para>
+ The <constant>KDBUS_CMD_HELLO</constant> ioctl takes a <type>struct
+ kdbus_cmd_hello</type> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_hello {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 attach_flags_send;
+ __u64 attach_flags_recv;
+ __u64 bus_flags;
+ __u64 id;
+ __u64 pool_size;
+ __u64 offset;
+ __u8 id128[16];
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem>
+ <para>Flags to apply to this connection</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_ACCEPT_FD</constant></term>
+ <listitem>
+ <para>
+ When this flag is set, the connection can be sent file
+ descriptors as message payload of unicast messages. If it's
+ not set, an attempt to send file descriptors will result in
+ <constant>-ECOMM</constant> on the sender's side.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_ACTIVATOR</constant></term>
+ <listitem>
+ <para>
+ Make this connection an activator (see above). With this bit
+ set, an item of type <constant>KDBUS_ITEM_NAME</constant> has
+ to be attached. This item describes the well-known name this
+ connection should be an activator for.
+ A connection can not be an activator and a policy holder at
+ the same time time, so this bit is not allowed together with
+ <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_POLICY_HOLDER</constant></term>
+ <listitem>
+ <para>
+ Make this connection a policy holder (see above). With this
+ bit set, an item of type <constant>KDBUS_ITEM_NAME</constant>
+ has to be attached. This item describes the well-known name
+ this connection should hold a policy for.
+ A connection can not be an activator and a policy holder at
+ the same time time, so this bit is not allowed together with
+ <constant>KDBUS_HELLO_ACTIVATOR</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_MONITOR</constant></term>
+ <listitem>
+ <para>
+ Make this connection a monitor connection (see above).
+ </para>
+ <para>
+ This flag can only be set by privileged bus connections. See
+ below for more information.
+ A connection can not be monitor and an activator or a policy
+ holder at the same time time, so this bit is not allowed
+ together with <constant>KDBUS_HELLO_ACTIVATOR</constant> or
+ <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>attach_flags_send</varname></term>
+ <listitem><para>
+ Set the bits for metadata this connection permits to be sent to the
+ receiving peer. Only metadata items that are both allowed to be sent
+ by the sender and that are requested by the receiver will be attached
+ to the message. Note, however, that the bus may optionally require
+ some of those bits to be set. If the match fails, the ioctl will fail
+ with <varname>errno</varname> set to
+ <constant>ECONNREFUSED</constant>. In either case, when returning the
+ field will be set to the mask of metadata items that are enforced by
+ the bus with the <constant>KDBUS_FLAGS_KERNEL</constant> bit set as
+ well.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>attach_flags_recv</varname></term>
+ <listitem><para>
+ Request the attachment of metadata for each message received by this
+ connection. See
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for information about metadata, and
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ regarding items in general.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>bus_flags</varname></term>
+ <listitem><para>
+ Upon successful completion of the ioctl, this member will contain the
+ flags of the bus it connected to.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ Upon successful completion of the command, this member will contain
+ the numerical ID of the new connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>pool_size</varname></term>
+ <listitem><para>
+ The size of the communication pool, in bytes. The pool can be
+ accessed by calling
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on the file descriptor that was used to issue the
+ <constant>KDBUS_CMD_HELLO</constant> ioctl.
+ The pool size of a connection must be greater than
+ <constant>0</constant> and a multiple of
+ <constant>PAGE_SIZE</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ The kernel will return the offset in the pool where returned details
+ will be stored. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id128</varname></term>
+ <listitem><para>
+ Upon successful completion of the ioctl, this member will contain the
+ <emphasis>128-bit UUID</emphasis> of the connected bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Variable list of items containing optional additional information.
+ The following items are currently expected/valid:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
+ <listitem>
+ <para>
+ Contains a string that describes this connection, so it can
+ be identified later.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ For activators and policy holders only, combinations of
+ these two items describe policy access entries. See
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CREDS</constant></term>
+ <term><constant>KDBUS_ITEM_PIDS</constant></term>
+ <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
+ <listitem>
+ <para>
+ Privileged bus users may submit these types in order to
+ create connections with faked credentials. This information
+ will be returned when peer information is queried by
+ <constant>KDBUS_CMD_CONN_INFO</constant>. See below for more
+ information on retrieving information on connections.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ At the offset returned in the <varname>offset</varname> field of
+ <type>struct kdbus_cmd_hello</type>, the kernel will store items
+ of the following types:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
+ <listitem>
+ <para>
+ Bloom filter parameter as defined by the bus creator.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The offset in the pool has to be freed with the
+ <constant>KDBUS_CMD_FREE</constant> ioctl. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Retrieving information on a connection</title>
+ <para>
+ The <constant>KDBUS_CMD_CONN_INFO</constant> ioctl can be used to
+ retrieve credentials and properties of the initial creator of a
+ connection. This ioctl uses the following struct.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_info {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 id;
+ __u64 attach_flags;
+ __u64 offset;
+ __u64 info_size;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently, no flags are supported.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The numerical ID of the connection for which information is to be
+ retrieved. If set to a non-zero value, the
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> item is ignored.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Specifies which metadata items should be attached to the answer. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ When the ioctl returns, this field will contain the offset of the
+ connection information inside the caller's pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>info_size</varname></term>
+ <listitem><para>
+ The kernel will return the size of the returned information, so
+ applications can optionally
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ specific parts of the pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <constant>KDBUS_CMD_CONN_INFO</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
+ <listitem>
+ <para>
+ Contains the well-known name of the connection to look up as.
+ This item is mandatory if the <varname>id</varname> field is
+ set to 0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ When the ioctl returns, the following struct will be stored in the
+ caller's pool at <varname>offset</varname>. The fields in this struct
+ are described below.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The connection's unique ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The connection's flags as specified when it was created.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Depending on the <varname>flags</varname> field in
+ <type>struct kdbus_cmd_info</type>, items of types
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> and
+ <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant> may follow here.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> is also allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Once the caller is finished with parsing the return buffer, it needs to
+ employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
+ order to free the buffer part. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Getting information about a connection's bus creator</title>
+ <para>
+ The <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> ioctl takes the same
+ struct as <constant>KDBUS_CMD_CONN_INFO</constant>, but is used to
+ retrieve information about the creator of the bus the connection is
+ attached to. The metadata returned by this call is collected during the
+ creation of the bus and is never altered afterwards, so it provides
+ pristine information on the task that created the bus, at the moment when
+ it did so.
+ </para>
+ <para>
+ In response to this call, a slice in the connection's pool is allocated
+ and filled with an object of type <type>struct kdbus_info</type>,
+ pointed to by the ioctl's <varname>offset</varname> field.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The bus ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The bus flags as specified when it was created.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Metadata information is stored in items here. The item list
+ contains a <constant>KDBUS_ITEM_MAKE_NAME</constant> item that
+ indicates the bus name of the calling connection.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed to probe
+ for known item types.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Once the caller is finished with parsing the return buffer, it needs to
+ employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
+ order to free the buffer part. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Updating connection details</title>
+ <para>
+ Some of a connection's details can be updated with the
+ <constant>KDBUS_CMD_CONN_UPDATE</constant> ioctl, using the file
+ descriptor that was used to create the connection. The update command
+ uses the following struct.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently, no flags are supported.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to describe the connection details to be updated. The
+ following item types are supported.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
+ <listitem>
+ <para>
+ Supply a new set of metadata items that this connection
+ permits to be sent along with messages.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
+ <listitem>
+ <para>
+ Supply a new set of metadata items that this connection
+ requests to be attached to each message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ Policy holder connections may supply a new set of policy
+ information with these items. For other connection types,
+ <constant>EOPNOTSUPP</constant> is returned in
+ <varname>errno</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Termination of connections</title>
+ <para>
+ A connection can be terminated by simply calling
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on its file descriptor. All pending incoming messages will be discarded,
+ and the memory allocated by the pool will be freed.
+ </para>
+
+ <para>
+ An alternative way of closing down a connection is via the
+ <constant>KDBUS_CMD_BYEBYE</constant> ioctl. This ioctl will succeed only
+ if the message queue of the connection is empty at the time of closing;
+ otherwise, the ioctl will fail with <varname>errno</varname> set to
+ <constant>EBUSY</constant>. When this ioctl returns
+ successfully, the connection has been terminated and won't accept any new
+ messages from remote peers. This way, a connection can be terminated
+ race-free, without losing any messages. The ioctl takes an argument of
+ type <type>struct kdbus_cmd</type>.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently, no flags are supported.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will fail with
+ <varname>errno</varname> set to <constant>EPROTO</constant>, and
+ the <varname>flags</varname> field is set to <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to describe the connection details to be updated. The
+ following item types are supported.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_HELLO</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EFAULT</constant></term>
+ <listitem><para>
+ The supplied pool size was 0 or not a multiple of the page size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in <type>struct kdbus_cmd_hello</type>
+ are invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ An illegal combination of
+ <constant>KDBUS_HELLO_MONITOR</constant>,
+ <constant>KDBUS_HELLO_ACTIVATOR</constant> and
+ <constant>KDBUS_HELLO_POLICY_HOLDER</constant> was passed in
+ <varname>flags</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ An invalid set of items was supplied.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECONNREFUSED</constant></term>
+ <listitem><para>
+ The attach_flags_send field did not satisfy the requirements of
+ the bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPERM</constant></term>
+ <listitem><para>
+ A <constant>KDBUS_ITEM_CREDS</constant> items was supplied, but the
+ current user is not privileged.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESHUTDOWN</constant></term>
+ <listitem><para>
+ The bus you were trying to connect to has already been shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ The maximum number of connections on the bus has been reached.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The endpoint does not support the connection flags supplied in
+ <type>struct kdbus_cmd_hello</type>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_BYEBYE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EALREADY</constant></term>
+ <listitem><para>
+ The connection has already been shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBUSY</constant></term>
+ <listitem><para>
+ There are still messages queued up in the connection's pool.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_CONN_INFO</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid flags, or neither an ID nor a name was provided, or the
+ name is invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ Connection lookup by name failed.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENXIO</constant></term>
+ <listitem><para>
+ No connection with the provided connection ID found.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_CONN_UPDATE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal flags or items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Wildcards submitted in policy entries, or illegal sequence
+ of policy items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ Operation not supported by connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ Too many policy items attached.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.endpoint.xml b/Documentation/kdbus/kdbus.endpoint.xml
new file mode 100644
index 000000000000..76e325d4e931
--- /dev/null
+++ b/Documentation/kdbus/kdbus.endpoint.xml
@@ -0,0 +1,436 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.endpoint">
+
+ <refentryinfo>
+ <title>kdbus.endpoint</title>
+ <productname>kdbus.endpoint</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.endpoint</refname>
+ <refpurpose>kdbus endpoint</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Endpoints are entry points to a bus (see
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>).
+ By default, each bus has a default
+ endpoint called 'bus'. The bus owner has the ability to create custom
+ endpoints with specific names, permissions, and policy databases
+ (see below). An endpoint is presented as file underneath the directory
+ of the parent bus.
+ </para>
+ <para>
+ To create a custom endpoint, open the default endpoint
+ (<literal>bus</literal>) and use the
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> ioctl with
+ <type>struct kdbus_cmd</type>. Custom endpoints always have a policy
+ database that, by default, forbids any operation. You have to explicitly
+ install policy entries to allow any operation on this endpoint.
+ </para>
+ <para>
+ Once <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> succeeded, the new
+ endpoint will appear in the filesystem
+ (<citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>), and the used file descriptor will manage the
+ newly created endpoint resource. It cannot be used to manage further
+ resources and must be kept open as long as the endpoint is needed. The
+ endpoint will be terminated as soon as the file descriptor is closed.
+ </para>
+ <para>
+ Endpoint names may be chosen freely except for one restriction: the name
+ must be prefixed with the numeric effective UID of the creator and a dash.
+ This is required to avoid namespace clashes between different users. When
+ creating an endpoint, the name that is passed in must be properly
+ formatted or the kernel will refuse creation of the endpoint. Example:
+ <literal>1047-my-endpoint</literal> is an acceptable name for an
+ endpoint registered by a user with UID 1047. However,
+ <literal>1024-my-endpoint</literal> is not, and neither is
+ <literal>my-endpoint</literal>. The UID must be provided in the
+ user-namespace of the bus.
+ </para>
+ <para>
+ To create connections to a bus, use <constant>KDBUS_CMD_HELLO</constant>
+ on a file descriptor returned by <function>open()</function> on an
+ endpoint node. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Creating custom endpoints</title>
+ <para>
+ To create a new endpoint, the
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> command is used. Along with
+ the endpoint's name, which will be used to expose the endpoint in the
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
+ the command also optionally takes items to set up the endpoint's
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> takes a
+ <type>struct kdbus_cmd</type> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>The flags for creation.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
+ <listitem>
+ <para>Make the endpoint file group-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
+ <listitem>
+ <para>Make the endpoint file world-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
+ <listitem>
+ <para>Contains a string to identify the endpoint name.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ These items are used to set the policy attached to the
+ endpoint. For more details on bus and endpoint policies, see
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <varname>EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Updating endpoints</title>
+ <para>
+ To update an existing endpoint, the
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> command is used on the file
+ descriptor that was used to create the update, using
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. The only relevant detail of
+ the endpoint that can be updated is the policy. When the command is
+ employed, the policy of the endpoint is <emphasis>replaced</emphasis>
+ atomically with the new set of rules.
+ The command takes a <type>struct kdbus_cmd</type> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Unused for this command.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ These items are used to set the policy attached to the
+ endpoint. For more details on bus and endpoint policies, see
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ Existing policy is atomically replaced with the new rules
+ provided.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> may fail with the
+ following errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in the <type>struct kdbus_cmd</type>
+ are invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ An endpoint of that name already exists.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPERM</constant></term>
+ <listitem><para>
+ The calling user is not privileged. See
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for information about privileged users.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the
+ following errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in <type>struct kdbus_cmd</type>
+ are invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ An endpoint of that name already exists.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.fs.xml b/Documentation/kdbus/kdbus.fs.xml
new file mode 100644
index 000000000000..8c2a90e10b66
--- /dev/null
+++ b/Documentation/kdbus/kdbus.fs.xml
@@ -0,0 +1,124 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus_fs">
+
+ <refentryinfo>
+ <title>kdbus.fs</title>
+ <productname>kdbus.fs</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.fs</refname>
+ <refpurpose>kdbus file system</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>File-system Layout</title>
+
+ <para>
+ The <emphasis>kdbusfs</emphasis> pseudo filesystem provides access to
+ kdbus entities, such as <emphasis>buses</emphasis> and
+ <emphasis>endpoints</emphasis>. Each time the filesystem is mounted,
+ a new, isolated kdbus instance is created, which is independent from the
+ other instances.
+ </para>
+ <para>
+ The system-wide standard mount point for <emphasis>kdbusfs</emphasis> is
+ <constant>/sys/fs/kdbus</constant>.
+ </para>
+
+ <para>
+ Buses are represented as directories in the file system layout, whereas
+ endpoints are exposed as files inside these directories. At the top-level,
+ a <emphasis>control</emphasis> node is present, which can be opened to
+ create new buses via the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl.
+ Each <emphasis>bus</emphasis> shows a default endpoint called
+ <varname>bus</varname>, which can be opened to either create a connection
+ with the <constant>KDBUS_CMD_HELLO</constant> ioctl, or to create new
+ custom endpoints for the bus with
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+
+ <para>Following, you can see an example layout of the
+ <emphasis>kdbusfs</emphasis> filesystem:</para>
+
+<programlisting>
+ /sys/fs/kdbus/ ; mount-point
+ |-- 0-system ; bus directory
+ | |-- bus ; default endpoint
+ | `-- 1017-custom ; custom endpoint
+ |-- 1000-user ; bus directory
+ | |-- bus ; default endpoint
+ | |-- 1000-service-A ; custom endpoint
+ | `-- 1000-service-B ; custom endpoint
+ `-- control ; control file
+</programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Mounting instances</title>
+ <para>
+ In order to get a new and separate kdbus environment, a new instance
+ of <emphasis>kdbusfs</emphasis> can be mounted like this:
+ </para>
+<programlisting>
+ # mount -t kdbusfs kdbusfs /tmp/new_kdbus/
+</programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>mount</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.item.xml b/Documentation/kdbus/kdbus.item.xml
new file mode 100644
index 000000000000..bfe47362097f
--- /dev/null
+++ b/Documentation/kdbus/kdbus.item.xml
@@ -0,0 +1,840 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus">
+
+ <refentryinfo>
+ <title>kdbus.item</title>
+ <productname>kdbus item</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.item</refname>
+ <refpurpose>kdbus item structure, layout and usage</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ To flexibly augment transport structures, data blobs of type
+ <type>struct kdbus_item</type> can be attached to the structs passed
+ into the ioctls. Some ioctls make items of certain types mandatory,
+ others are optional. Items that are unsupported by ioctls they are
+ attached to will cause the ioctl to fail with <varname>errno</varname>
+ set to <constant>EINVAL</constant>.
+ Items are also used for information stored in a connection's
+ <emphasis>pool</emphasis>, such as received messages, name lists or
+ requested connection or bus owner information. Depending on the type of
+ an item, its total size is either fixed or variable.
+ </para>
+
+ <refsect2>
+ <title>Chaining items</title>
+ <para>
+ Whenever items are used as part of the kdbus kernel API, they are
+ embedded in structs that are embedded inside structs that themselves
+ include a size field containing the overall size of the structure.
+ This allows multiple items to be chained up, and an item iterator
+ (see below) is capable of detecting the end of an item chain.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Alignment</title>
+ <para>
+ The kernel expects all items to be aligned to 8-byte boundaries.
+ Unaligned items will cause the ioctl they are used with to fail
+ with <varname>errno</varname> set to <constant>EINVAL</constant>.
+ An item that has an unaligned size itself hence needs to be padded
+ if it is followed by another item.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Iterating items</title>
+ <para>
+ A simple iterator would iterate over the items until the items have
+ reached the embedding structure's overall size. An example
+ implementation is shown below.
+ </para>
+
+ <programlisting><![CDATA[
+#define KDBUS_ALIGN8(val) (((val) + 7) & ~7)
+
+#define KDBUS_ITEM_NEXT(item) \
+ (typeof(item))(((uint8_t *)item) + KDBUS_ALIGN8((item)->size))
+
+#define KDBUS_ITEM_FOREACH(item, head, first) \
+ for (item = (head)->first; \
+ ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \
+ ((uint8_t *)(item) >= (uint8_t *)(head)); \
+ item = KDBUS_ITEM_NEXT(item))
+ ]]></programlisting>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Item layout</title>
+ <para>
+ A <type>struct kdbus_item</type> consists of a
+ <varname>size</varname> field, describing its overall size, and a
+ <varname>type</varname> field, both 64 bit wide. They are followed by
+ a union to store information that is specific to the item's type.
+ The struct layout is shown below.
+ </para>
+
+ <programlisting>
+struct kdbus_item {
+ __u64 size;
+ __u64 type;
+ /* item payload - see below */
+ union {
+ __u8 data[0];
+ __u32 data32[0];
+ __u64 data64[0];
+ char str[0];
+
+ __u64 id;
+ struct kdbus_vec vec;
+ struct kdbus_creds creds;
+ struct kdbus_pids pids;
+ struct kdbus_audit audit;
+ struct kdbus_caps caps;
+ struct kdbus_timestamp timestamp;
+ struct kdbus_name name;
+ struct kdbus_bloom_parameter bloom_parameter;
+ struct kdbus_bloom_filter bloom_filter;
+ struct kdbus_memfd memfd;
+ int fds[0];
+ struct kdbus_notify_name_change name_change;
+ struct kdbus_notify_id_change id_change;
+ struct kdbus_policy_access policy_access;
+ };
+};
+ </programlisting>
+
+ <para>
+ <type>struct kdbus_item</type> should never be used to allocate
+ an item instance, as its size may grow in future releases of the API.
+ Instead, it should be manually assembled by storing the
+ <varname>size</varname>, <varname>type</varname> and payload to a
+ struct of its own.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Item types</title>
+
+ <refsect2>
+ <title>Negotiation item</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item is attached to any ioctl, programs can
+ <emphasis>probe</emphasis> the kernel for known item items.
+ The item carries an array of <type>uint64_t</type> values in
+ <varname>item.data64</varname>, each set to an item type to
+ probe. The kernel will reset each member of this array that is
+ not recognized as valid item type to <constant>0</constant>.
+ This way, users can negotiate kernel features at start-up to
+ keep newer userspace compatible with older kernels. This item
+ is never attached by the kernel in response to any command.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Command specific items</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
+ <listitem><para>
+ Messages are directly copied by the sending process into the
+ receiver's
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ This way, two peers can exchange data by effectively doing a
+ single-copy from one process to another; the kernel will not buffer
+ the data anywhere else. <constant>KDBUS_ITEM_PAYLOAD_VEC</constant>
+ is used when <emphasis>sending</emphasis> message. The item
+ references a memory address when the payload data can be found.
+ <constant>KDBUS_ITEM_PAYLOAD_OFF</constant> is used when messages
+ are <emphasis>received</emphasis>, and the
+ <constant>offset</constant> value describes the offset inside the
+ receiving connection's
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ where the message payload can be found. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on passing of payload data along with a
+ message.
+ <programlisting>
+struct kdbus_vec {
+ __u64 size;
+ union {
+ __u64 address;
+ __u64 offset;
+ };
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <listitem><para>
+ Transports a file descriptor of a <emphasis>memfd</emphasis> in
+ <type>struct kdbus_memfd</type> in <varname>item.memfd</varname>.
+ The <varname>size</varname> field has to match the actual size of
+ the memfd that was specified when it was created. The
+ <varname>start</varname> parameter denotes the offset inside the
+ memfd at which the referenced payload starts. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on passing of payload data along with a
+ message.
+ <programlisting>
+struct kdbus_memfd {
+ __u64 start;
+ __u64 size;
+ int fd;
+ __u32 __pad;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem><para>
+ Contains an array of <emphasis>file descriptors</emphasis>.
+ When used with <constant>KDBUS_CMD_SEND</constant>, the values of
+ this array must be filled with valid file descriptor numbers.
+ When received as item attached to a message, the array will
+ contain the numbers of the installed file descriptors, or
+ <constant>-1</constant> in case an error occurred.
+ file descriptor.
+ In either case, the number of entries in the array is derived from
+ the item's total size. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Items specific to some commands</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
+ <listitem><para>
+ Transports a file descriptor that can be used to cancel a
+ synchronous <constant>KDBUS_CMD_SEND</constant> operation by
+ writing to it. The file descriptor is stored in
+ <varname>item.fd[0]</varname>. The item may only contain one
+ file descriptor. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on this item and how to use it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>bloom parameters</emphasis> as
+ <type>struct kdbus_bloom_parameter</type> in
+ <varname>item.bloom_parameter</varname>.
+ The item is passed from userspace to kernel during the
+ <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl, and returned
+ verbatim when <constant>KDBUS_CMD_HELLO</constant> is called.
+ The kernel does not use the bloom parameters, but they need to
+ be known by each connection on the bus in order to define the
+ bloom filter hash details. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ <programlisting>
+struct kdbus_bloom_parameter {
+ __u64 size;
+ __u64 n_hash;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
+ <listitem><para>
+ Carries a <emphasis>bloom filter</emphasis> as
+ <type>struct kdbus_bloom_filter</type> in
+ <varname>item.bloom_filter</varname>. It is mandatory to send this
+ item attached to a <type>struct kdbus_msg</type>, in case the
+ message is a signal. This item is never transported from kernel to
+ userspace. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ <programlisting>
+struct kdbus_bloom_filter {
+ __u64 generation;
+ __u64 data[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
+ <listitem><para>
+ Transports a <emphasis>bloom mask</emphasis> as binary data blob
+ stored in <varname>item.data</varname>. This item is used to
+ describe a match into a connection's match database. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>well-known name</emphasis> to send a
+ message to, as null-terminated string in
+ <varname>item.str</varname>. This item is used with
+ <constant>KDBUS_CMD_SEND</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on how to send a message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>bus name</emphasis> or
+ <emphasis>endpoint name</emphasis>, stored as null-terminated
+ string in <varname>item.str</varname>. This item is sent from
+ userspace to kernel when buses or endpoints are created, and
+ returned back to userspace when the bus creator information is
+ queried. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>attach flags</emphasis> at
+ <emphasis>send</emphasis> or <emphasis>receive</emphasis> time. See
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on attach flags.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID</constant></term>
+ <listitem><para>
+ Transports a connection's <emphasis>numerical ID</emphasis> of
+ a connection as <type>uint64_t</type> value in
+ <varname>item.id</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <listitem><para>
+ Transports a name associated with the
+ <emphasis>name registry</emphasis> as null-terminated string as
+ <type>struct kdbus_name</type> in
+ <varname>item.name</varname>. The <varname>flags</varname>
+ contains the flags of the name. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on how to access the name registry of a bus.
+ <programlisting>
+struct kdbus_name {
+ __u64 flags;
+ char name[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Items attached by the kernel as metadata</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_TIMESTAMP</constant></term>
+ <listitem><para>
+ Contains both the <emphasis>monotonic</emphasis> and the
+ <emphasis>realtime</emphasis> timestamp, taken when the message
+ was processed on the kernel side.
+ Stored as <type>struct kdbus_timestamp</type> in
+ <varname>item.timestamp</varname>.
+ <programlisting>
+struct kdbus_timestamp {
+ __u64 seqnum;
+ __u64 monotonic_ns;
+ __u64 realtime_ns;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CREDS</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>user</emphasis> and
+ <emphasis>group</emphasis> information as 32-bit values, in the
+ usual four flavors: real, effective, saved and filesystem related.
+ Stored as <type>struct kdbus_creds</type> in
+ <varname>item.creds</varname>.
+ <programlisting>
+struct kdbus_creds {
+ __u32 uid;
+ __u32 euid;
+ __u32 suid;
+ __u32 fsuid;
+ __u32 gid;
+ __u32 egid;
+ __u32 sgid;
+ __u32 fsgid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PIDS</constant></term>
+ <listitem><para>
+ Contains the <emphasis>PID</emphasis>, <emphasis>TID</emphasis>
+ and <emphasis>parent PID (PPID)</emphasis> of a remote peer.
+ Stored as <type>struct kdbus_pids</type> in
+ <varname>item.pids</varname>.
+ <programlisting>
+struct kdbus_pids {
+ __u64 pid;
+ __u64 tid;
+ __u64 ppid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_AUXGROUPS</constant></term>
+ <listitem><para>
+ Contains the <emphasis>auxiliary (supplementary) groups</emphasis>
+ a remote peer is a member of, stored as array of
+ <type>uint32_t</type> values in <varname>item.data32</varname>.
+ The array length can be determined by looking at the item's total
+ size, subtracting the size of the header and and dividing the
+ remainder by <constant>sizeof(uint32_t)</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>well-known name</emphasis> currently owned
+ by a connection. The name is stored as null-terminated string in
+ <varname>item.str</varname>. Its length can also be derived from
+ the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_TID_COMM</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>TID</emphasis> (thread ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PID_COMM</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>PID</emphasis> (process ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_EXE</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>path to the executable</emphasis> of a task,
+ stored as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size. Receivers of
+ this item should not use its contents for any kind of security
+ measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CMDLINE</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>command line arguments</emphasis> of a
+ task, stored as an <emphasis>array</emphasis> of null-terminated
+ strings in <varname>item.str</varname>. The total length of all
+ strings in the array can be derived from the item's total size.
+ Receivers of this item should not use its contents for any kind
+ of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CGROUP</constant></term>
+ <listitem><para>
+ Contains the <emphasis>cgroup path</emphasis> of a task, stored
+ as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CAPS</constant></term>
+ <listitem><para>
+ Contains sets of <emphasis>capabilities</emphasis>, stored as
+ <type>struct kdbus_caps</type> in <varname>item.caps</varname>.
+ As the item size may increase in the future, programs should be
+ written in a way that it takes
+ <varname>item.caps.last_cap</varname> into account, and derive
+ the number of sets and rows from the item size and the reported
+ number of valid capability bits.
+ <programlisting>
+struct kdbus_caps {
+ __u32 last_cap;
+ __u32 caps[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
+ <listitem><para>
+ Contains the <emphasis>LSM label</emphasis> of a task, stored as
+ null-terminated string in <varname>item.str</varname>. Its length
+ can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_AUDIT</constant></term>
+ <listitem><para>
+ Contains the audit <emphasis>sessionid</emphasis> and
+ <emphasis>loginuid</emphasis> of a task, stored as
+ <type>struct kdbus_audit</type> in
+ <varname>item.audit</varname>.
+ <programlisting>
+struct kdbus_audit {
+ __u32 sessionid;
+ __u32 loginuid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
+ <listitem><para>
+ Contains the <emphasis>connection description</emphasis>, as set
+ by <constant>KDBUS_CMD_HELLO</constant> or
+ <constant>KDBUS_CMD_CONN_UPDATE</constant>, stored as
+ null-terminated string in <varname>item.str</varname>. Its length
+ can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ All metadata is automatically translated into the
+ <emphasis>namespaces</emphasis> of the task that receives them. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+
+ <para>
+ [*] Note that the content stored in metadata items of type
+ <constant>KDBUS_ITEM_TID_COMM</constant>,
+ <constant>KDBUS_ITEM_PID_COMM</constant>,
+ <constant>KDBUS_ITEM_EXE</constant> and
+ <constant>KDBUS_ITEM_CMDLINE</constant>
+ can easily be tampered by the sending tasks. Therefore, they should
+ <emphasis>not</emphasis> be used for any sort of security relevant
+ assumptions. The only reason they are transmitted is to let
+ receivers know about details that were set when metadata was
+ collected, even though the task they were collected from is not
+ active any longer when the items are received.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Items used for policy entries, matches and notifications</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem><para>
+ This item describes a <emphasis>policy access</emphasis> entry to
+ access the policy database of a
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> or
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ Please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on the policy database and how to access it.
+ <programlisting>
+struct kdbus_policy_access {
+ __u64 type;
+ __u64 access;
+ __u64 id;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis> and indicates that a
+ new connection was created on the bus, or that a connection was
+ disconnected, respectively. It stores a
+ <type>struct kdbus_notify_id_change</type> in
+ <varname>item.id_change</varname>.
+ The <varname>id</varname> field contains the numeric ID of the
+ connection that was added or removed, and <varname>flags</varname>
+ is set to the connection flags, as passed by
+ <constant>KDBUS_CMD_HELLO</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matches and notification messages.
+ <programlisting>
+struct kdbus_notify_id_change {
+ __u64 id;
+ __u64 flags;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis> and indicates that a
+ <emphasis>well-known name</emphasis> appeared, disappeared or
+ transferred to another owner on the bus. It stores a
+ <type>struct kdbus_notify_name_change</type> in
+ <varname>item.name_change</varname>.
+ <varname>old_id</varname> describes the former owner of the name
+ and is set to <constant>0</constant> values in case of
+ <constant>KDBUS_ITEM_NAME_ADD</constant>.
+ <varname>new_id</varname> describes the new owner of the name and
+ is set to <constant>0</constant> values in case of
+ <constant>KDBUS_ITEM_NAME_REMOVE</constant>.
+ The <varname>name</varname> field contains the well-known name the
+ notification is about, as null-terminated string. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matches and notification messages.
+ <programlisting>
+struct kdbus_notify_name_change {
+ struct kdbus_notify_id_change old_id;
+ struct kdbus_notify_id_change new_id;
+ char name[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_REPLY_TIMEOUT</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis>. It informs the receiver
+ that an expected reply to a message was not received in time.
+ The remote peer ID and the message cookie is stored in the message
+ header. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about messages, timeouts and notifications.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_REPLY_DEAD</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis>. It informs the receiver
+ that a remote connection a reply is expected from was disconnected
+ before that reply was sent. The remote peer ID and the message
+ cookie is stored in the message header. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about messages, timeouts and notifications.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>memfd_create</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
diff --git a/Documentation/kdbus/kdbus.match.xml b/Documentation/kdbus/kdbus.match.xml
new file mode 100644
index 000000000000..ef77b64e5890
--- /dev/null
+++ b/Documentation/kdbus/kdbus.match.xml
@@ -0,0 +1,553 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.match">
+
+ <refentryinfo>
+ <title>kdbus.match</title>
+ <productname>kdbus.match</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.match</refname>
+ <refpurpose>kdbus match</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ kdbus connections can install matches in order to subscribe to signal
+ messages sent on the bus. Such signal messages can be either directed
+ to a single connection (by setting a specific connection ID in
+ <varname>struct kdbus_msg.dst_id</varname> or by sending it to a
+ well-known name), or to potentially <emphasis>all</emphasis> currently
+ active connections on the bus (by setting
+ <varname>struct kdbus_msg.dst_id</varname> to
+ <constant>KDBUS_DST_ID_BROADCAST</constant>).
+ A signal message always has the <constant>KDBUS_MSG_SIGNAL</constant>
+ bit set in the <varname>flags</varname> bitfield.
+ Also, signal messages can originate from either the kernel (called
+ <emphasis>notifications</emphasis>), or from other bus connections.
+ In either case, a bus connection needs to have a suitable
+ <emphasis>match</emphasis> installed in order to receive any signal
+ message. Without any rules installed in the connection, no signal message
+ will be received.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Matches for signal messages from other connections</title>
+ <para>
+ Matches for messages from other connections (not kernel notifications)
+ are implemented as bloom filters (see below). The sender adds certain
+ properties of the message as elements to a bloom filter bit field, and
+ sends that along with the signal message.
+
+ The receiving connection adds the message properties it is interested in
+ as elements to a bloom mask bit field, and uploads the mask as match rule,
+ possibly along with some other rules to further limit the match.
+
+ The kernel will match the signal message's bloom filter against the
+ connections bloom mask (simply by &-ing it), and will decide whether
+ the message should be delivered to a connection.
+ </para>
+ <para>
+ The kernel has no notion of any specific properties of the signal message,
+ all it sees are the bit fields of the bloom filter and the mask to match
+ against. The use of bloom filters allows simple and efficient matching,
+ without exposing any message properties or internals to the kernel side.
+ Clients need to deal with the fact that they might receive signal messages
+ which they did not subscribe to, as the bloom filter might allow
+ false-positives to pass the filter.
+
+ To allow the future extension of the set of elements in the bloom filter,
+ the filter specifies a <emphasis>generation</emphasis> number. A later
+ generation must always contain all elements of the set of the previous
+ generation, but can add new elements to the set. The match rules mask can
+ carry an array with all previous generations of masks individually stored.
+ When the filter and mask are matched by the kernel, the mask with the
+ closest matching generation is selected as the index into the mask array.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Bloom filters</title>
+ <para>
+ Bloom filters allow checking whether a given word is present in a
+ dictionary. This allows connections to set up a mask for information it
+ is interested in, and will be delivered signal messages that have a
+ matching filter.
+
+ For general information, see
+ <ulink url="https://en.wikipedia.org/wiki/Bloom_filter">the Wikipedia
+ article on bloom filters</ulink>.
+ </para>
+ <para>
+ The size of the bloom filter is defined per bus when it is created, in
+ <varname>kdbus_bloom_parameter.size</varname>. All bloom filters attached
+ to signal messages on the bus must match this size, and all bloom filter
+ matches uploaded by connections must also match the size, or a multiple
+ thereof (see below).
+
+ The calculation of the mask has to be done in userspace applications. The
+ kernel just checks the bitmasks to decide whether or not to let the
+ message pass. All bits in the mask must match the filter in and bit-wise
+ <emphasis>AND</emphasis> logic, but the mask may have more bits set than
+ the filter. Consequently, false positive matches are expected to happen,
+ and programs must deal with that fact by checking the contents of the
+ payload again at receive time.
+ </para>
+ <para>
+ Masks are entities that are always passed to the kernel as part of a
+ match (with an item of type <constant>KDBUS_ITEM_BLOOM_MASK</constant>),
+ and filters can be attached to signals, with an item of type
+ <constant>KDBUS_ITEM_BLOOM_FILTER</constant>. For a filter to match, all
+ its bits have to be set in the match mask as well.
+ </para>
+ <para>
+ For example, consider a bus that has a bloom size of 8 bytes, and the
+ following mask/filter combinations:
+ </para>
+ <programlisting><![CDATA[
+ filter 0x0101010101010101
+ mask 0x0101010101010101
+ -> matches
+
+ filter 0x0303030303030303
+ mask 0x0101010101010101
+ -> doesn't match
+
+ filter 0x0101010101010101
+ mask 0x0303030303030303
+ -> matches
+ ]]></programlisting>
+
+ <para>
+ Hence, in order to catch all messages, a mask filled with
+ <constant>0xff</constant> bytes can be installed as a wildcard match rule.
+ </para>
+
+ <refsect2>
+ <title>Generations</title>
+
+ <para>
+ Uploaded matches may contain multiple masks, which have are as large as
+ the bloom size defined by the bus. Each block of a mask is called a
+ <emphasis>generation</emphasis>, starting at index 0.
+
+ At match time, when a signal is about to be delivered, a bloom mask
+ generation is passed, which denotes which of the bloom masks the filter
+ should be matched against. This allows programs to provide backward
+ compatible masks at upload time, while older clients can still match
+ against older versions of filters.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Matches for kernel notifications</title>
+ <para>
+ To receive kernel generated notifications (see
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>),
+ a connection must install match rules that are different from
+ the bloom filter matches described in the section above. They can be
+ filtered by the connection ID that caused the notification to be sent, by
+ one of the names it currently owns, or by the type of the notification
+ (ID/name add/remove/change).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Adding a match</title>
+ <para>
+ To add a match, the <constant>KDBUS_CMD_MATCH_ADD</constant> ioctl is
+ used, which takes a struct of the struct described below.
+
+ Note that each of the items attached to this command will internally
+ create one match <emphasis>rule</emphasis>, and the collection of them,
+ which is submitted as one block via the ioctl, is called a
+ <emphasis>match</emphasis>. To allow a message to pass, all rules of a
+ match have to be satisfied. Hence, adding more items to the command will
+ only narrow the possibility of a match to effectively let the message
+ pass, and will decrease the chance that the connection's process will be
+ woken up needlessly.
+
+ Multiple matches can be installed per connection. As long as one of it has
+ a set of rules which allows the message to pass, this one will be
+ decisive.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_match {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 cookie;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to control the behavior of the ioctl.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MATCH_REPLACE</constant></term>
+ <listitem>
+ <para>Make the endpoint file group-accessible</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie</varname></term>
+ <listitem><para>
+ A cookie which identifies the match, so it can be referred to when
+ removing it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to define the actual rules of the matches. The following item
+ types are expected. Each item will create one new match rule.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
+ <listitem>
+ <para>
+ An item that carries the bloom filter mask to match against
+ in its data field. The payload size must match the bloom
+ filter size that was specified when the bus was created.
+ See the section below for more information on bloom filters.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <listitem>
+ <para>
+ When used as part of kernel notifications, this item specifies
+ a name that is acquired, lost or that changed its owner (see
+ below). When used as part of a match for user-generated signal
+ messages, it specifies a name that the sending connection must
+ own at the time of sending the signal.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID</constant></term>
+ <listitem>
+ <para>
+ Specify a sender connection's ID that will match this rule.
+ For kernel notifications, this specifies the ID of a
+ connection that was added to or removed from the bus.
+ For used-generated signals, it specifies the ID of the
+ connection that sent the signal message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
+ <listitem>
+ <para>
+ These items request delivery of kernel notifications that
+ describe a name acquisition, loss, or change. The details
+ are stored in the item's
+ <varname>kdbus_notify_name_change</varname> member.
+ All information specified must be matched in order to make
+ the message pass. Use
+ <constant>KDBUS_MATCH_ID_ANY</constant> to
+ match against any unique connection ID.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
+ <listitem>
+ <para>
+ These items request delivery of kernel notifications that are
+ generated when a connection is created or terminated.
+ <type>struct kdbus_notify_id_change</type> is used to
+ store the actual match information. This item can be used to
+ monitor one particular connection ID, or, when the ID field
+ is set to <constant>KDBUS_MATCH_ID_ANY</constant>,
+ all of them.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Refer to
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on message types.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Removing a match</title>
+ <para>
+ Matches can be removed with the
+ <constant>KDBUS_CMD_MATCH_REMOVE</constant> ioctl, which takes
+ <type>struct kdbus_cmd_match</type> as argument, but its fields
+ usage slightly differs compared to that of
+ <constant>KDBUS_CMD_MATCH_ADD</constant>.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_match {
+ __u64 size;
+ __u64 cookie;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie</varname></term>
+ <listitem><para>
+ The cookie of the match, as it was passed when the match was added.
+ All matches that have this cookie will be removed.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ No flags are supported for this use case.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname> is set to
+ <constant>EPROTO</constant>, and the <varname>flags</varname> field
+ is set to <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ No items are supported for this use case, but
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed nevertheless.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_MATCH_ADD</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal flags or items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDOM</constant></term>
+ <listitem><para>
+ Illegal bloom filter size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ Too many matches for this connection.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_MATCH_REMOVE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal flags.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADSLT</constant></term>
+ <listitem><para>
+ A match entry with the given cookie could not be found.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.message.xml b/Documentation/kdbus/kdbus.message.xml
new file mode 100644
index 000000000000..c25000dcfbc7
--- /dev/null
+++ b/Documentation/kdbus/kdbus.message.xml
@@ -0,0 +1,1277 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.message">
+
+ <refentryinfo>
+ <title>kdbus.message</title>
+ <productname>kdbus.message</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.message</refname>
+ <refpurpose>kdbus message</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A kdbus message is used to exchange information between two connections
+ on a bus, or to transport notifications from the kernel to one or many
+ connections. This document describes the layout of messages, how payload
+ is added to them and how they are sent and received.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Message layout</title>
+
+ <para>The layout of a message is shown below.</para>
+
+ <programlisting>
+ +-------------------------------------------------------------------------+
+ | Message |
+ | +---------------------------------------------------------------------+ |
+ | | Header | |
+ | | size: overall message size, including the data records | |
+ | | destination: connection ID of the receiver | |
+ | | source: connection ID of the sender (set by kernel) | |
+ | | payload_type: "DBusDBus" textual identifier stored as uint64_t | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size (without padding) | |
+ | | type: type of data | |
+ | | data: reference to data (address or file descriptor) | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | padding bytes to the next 8 byte alignment | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size (without padding) | |
+ | | ... | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | padding bytes to the next 8 byte alignment | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size | |
+ | | ... | |
+ | +---------------------------------------------------------------------+ |
+ | ... further data records ... |
+ +-------------------------------------------------------------------------+
+ </programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Message payload</title>
+
+ <para>
+ When connecting to the bus, receivers request a memory pool of a given
+ size, large enough to carry all backlog of data enqueued for the
+ connection. The pool is internally backed by a shared memory file which
+ can be <function>mmap()</function>ed by the receiver. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+
+ <para>
+ Message payload must be described in items attached to a message when
+ it is sent. A receiver can access the payload by looking at the items
+ that are attached to a message in its pool. The following items are used.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <listitem>
+ <para>
+ This item references a piece of memory on the sender side which is
+ directly copied into the receiver's pool. This way, two peers can
+ exchange data by effectively doing a single-copy from one process
+ to another; the kernel will not buffer the data anywhere else.
+ This item is never found in a message received by a connection.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
+ <listitem>
+ <para>
+ This item is attached to messages on the receiving side and points
+ to a memory area inside the receiver's pool. The
+ <varname>offset</varname> variable in the item denotes the memory
+ location relative to the message itself.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <listitem>
+ <para>
+ Messages can reference <emphasis>memfd</emphasis> files which
+ contain the data. memfd files are tmpfs-backed files that allow
+ sealing of the content of the file, which prevents all writable
+ access to the file content.
+ </para>
+ <para>
+ Only memfds that have
+ <constant>(F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL)
+ </constant>
+ set are accepted as payload data, which enforces reliable passing of
+ data. The receiver can assume that neither the sender nor anyone
+ else can alter the content after the message is sent. If those
+ seals are not set on the memfd, the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname> will be
+ set to <constant>ETXTBUSY</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem>
+ <para>
+ Messages can transport regular file descriptors via
+ <constant>KDBUS_ITEM_FDS</constant>. This item carries an array
+ of <type>int</type> values in <varname>item.fd</varname>. The
+ maximum number of file descriptors in the item is
+ <constant>253</constant>, and only one item of this type is
+ accepted per message. All passed values must be valid file
+ descriptors; the open count of each file descriptors is increased
+ by installing it to the receiver's task. This item can only be
+ used for directed messages, not for broadcasts, and only to
+ remote peers that have opted-in for receiving file descriptors
+ at connection time (<constant>KDBUS_HELLO_ACCEPT_FD</constant>).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The sender must not make any assumptions on the type in which data is
+ received by the remote peer. The kernel is free to re-pack multiple
+ <constant>KDBUS_ITEM_PAYLOAD_VEC</constant> and
+ <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> payloads. For instance, the
+ kernel may decide to merge multiple <constant>VECs</constant> into a
+ single <constant>VEC</constant>, inline <constant>MEMFD</constant>
+ payloads into memory, or merge all passed <constant>VECs</constant> into a
+ single <constant>MEMFD</constant>. However, the kernel preserves the order
+ of passed data. This means that the order of all <constant>VEC</constant>
+ and <constant>MEMFD</constant> items is not changed in respect to each
+ other. In other words: All passed <constant>VEC</constant> and
+ <constant>MEMFD</constant> data payloads are treated as a single stream
+ of data that may be received by the remote peer in a different set of
+ chunks than it was sent as.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Sending messages</title>
+
+ <para>
+ Messages are passed to the kernel with the
+ <constant>KDBUS_CMD_SEND</constant> ioctl. Depending on the destination
+ address of the message, the kernel delivers the message to the specific
+ destination connection, or to some subset of all connections on the same
+ bus. Sending messages across buses is not possible. Messages are always
+ queued in the memory pool of the destination connection (see above).
+ </para>
+
+ <para>
+ The <constant>KDBUS_CMD_SEND</constant> ioctl uses a
+ <type>struct kdbus_cmd_send</type> to describe the message
+ transfer.
+ </para>
+ <programlisting>
+struct kdbus_cmd_send {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 msg_address;
+ struct kdbus_msg_info reply;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags for message delivery</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_SEND_SYNC_REPLY</constant></term>
+ <listitem>
+ <para>
+ By default, all calls to kdbus are considered asynchronous,
+ non-blocking. However, as there are many use cases that need
+ to wait for a remote peer to answer a method call, there's a
+ way to send a message and wait for a reply in a synchronous
+ fashion. This is what the
+ <constant>KDBUS_SEND_SYNC_REPLY</constant> controls. The
+ <constant>KDBUS_CMD_SEND</constant> ioctl will block until the
+ reply has arrived, the timeout limit is reached, in case the
+ remote connection was shut down, or if interrupted by a signal
+ before any reply; see
+ <citerefentry>
+ <refentrytitle>signal</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+
+ The offset of the reply message in the sender's pool is stored
+ in in <varname>offset_reply</varname> when the ioctl has
+ returned without error. Hence, there is no need for another
+ <constant>KDBUS_CMD_RECV</constant> ioctl or anything else to
+ receive the reply.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg_address</varname></term>
+ <listitem><para>
+ In this field, users have to provide a pointer to a message
+ (<type>struct kdbus_msg</type>) to send. See below for a
+ detailed description.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>reply</varname></term>
+ <listitem><para>
+ Only used for synchronous replies. See description of
+ <type>struct kdbus_cmd_recv</type> for more details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are currently recognized.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
+ <listitem>
+ <para>
+ When this optional item is passed in, and the call is
+ executed as SYNC call, the passed in file descriptor can be
+ used as alternative cancellation point. The kernel will call
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on this file descriptor, and once it reports any incoming
+ bytes, the blocking send operation will be canceled; the
+ blocking, synchronous ioctl call will return
+ <errorcode>-1</errorcode>, and <varname>errno</varname> will
+ be set to <errorname>ECANCELED</errorname>.
+ Any type of file descriptor on which
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ can be called on can be used as payload to this item; for
+ example, an eventfd can be used for this purpose, see
+ <citerefentry>
+ <refentrytitle>eventfd</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ For asynchronous message sending, this item is allowed but
+ ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The fields in this struct are described below.
+ The message referenced the <varname>msg_address</varname> above has
+ the following layout.
+ </para>
+
+ <programlisting>
+struct kdbus_msg {
+ __u64 size;
+ __u64 flags;
+ __s64 priority;
+ __u64 dst_id;
+ __u64 src_id;
+ __u64 payload_type;
+ __u64 cookie;
+ __u64 timeout_ns;
+ __u64 cookie_reply;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to describe message details.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MSG_EXPECT_REPLY</constant></term>
+ <listitem>
+ <para>
+ Expect a reply to this message from the remote peer. With
+ this bit set, the timeout_ns field must be set to a non-zero
+ number of nanoseconds in which the receiving peer is expected
+ to reply. If such a reply is not received in time, the sender
+ will be notified with a timeout message (see below). The
+ value must be an absolute value, in nanoseconds and based on
+ <constant>CLOCK_MONOTONIC</constant>.
+ </para><para>
+ For a message to be accepted as reply, it must be a direct
+ message to the original sender (not a broadcast and not a
+ signal message), and its
+ <varname>kdbus_msg.reply_cookie</varname> must match the
+ previous message's <varname>kdbus_msg.cookie</varname>.
+ </para><para>
+ Expected replies also temporarily open the policy of the
+ sending connection, so the other peer is allowed to respond
+ within the given time window.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_MSG_NO_AUTO_START</constant></term>
+ <listitem>
+ <para>
+ By default, when a message is sent to an activator
+ connection, the activator is notified and will start an
+ implementer. This flag inhibits that behavior. With this bit
+ set, and the remote being an activator, the ioctl will fail
+ with <varname>errno</varname> set to
+ <constant>EADDRNOTAVAIL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>priority</varname></term>
+ <listitem><para>
+ The priority of this message. Receiving messages (see below) may
+ optionally be constrained to messages of a minimal priority. This
+ allows for use cases where timing critical data is interleaved with
+ control data on the same connection. If unused, the priority field
+ should be set to <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dst_id</varname></term>
+ <listitem><para>
+ The numeric ID of the destination connection, or
+ <constant>KDBUS_DST_ID_BROADCAST</constant>
+ (~0ULL) to address every peer on the bus, or
+ <constant>KDBUS_DST_ID_NAME</constant> (0) to look
+ it up dynamically from the bus' name registry.
+ In the latter case, an item of type
+ <constant>KDBUS_ITEM_DST_NAME</constant> is mandatory.
+ Also see
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ .
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>src_id</varname></term>
+ <listitem><para>
+ Upon return of the ioctl, this member will contain the sending
+ connection's numerical ID. Should be 0 at send time.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>payload_type</varname></term>
+ <listitem><para>
+ Type of the payload in the actual data records. Currently, only
+ <constant>KDBUS_PAYLOAD_DBUS</constant> is accepted as input value
+ of this field. When receiving messages that are generated by the
+ kernel (notifications), this field will contain
+ <constant>KDBUS_PAYLOAD_KERNEL</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie</varname></term>
+ <listitem><para>
+ Cookie of this message, for later recognition. Also, when replying
+ to a message (see above), the <varname>cookie_reply</varname>
+ field must match this value.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>timeout_ns</varname></term>
+ <listitem><para>
+ If the message sent requires a reply from the remote peer (see above),
+ this field contains the timeout in absolute nanoseconds based on
+ <constant>CLOCK_MONOTONIC</constant>. Also see
+ <citerefentry>
+ <refentrytitle>clock_gettime</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie_reply</varname></term>
+ <listitem><para>
+ If the message sent is a reply to another message, this field must
+ match the cookie of the formerly received message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ A dynamically sized list of items to contain additional information.
+ The following items are expected/valid:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem>
+ <para>
+ Actual data records containing the payload. See section
+ "Passing of Payload Data".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
+ <listitem>
+ <para>
+ Bloom filter for matches (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
+ <listitem>
+ <para>
+ Well-known name to send this message to. Required if
+ <varname>dst_id</varname> is set to
+ <constant>KDBUS_DST_ID_NAME</constant>.
+ If a connection holding the given name can't be found,
+ the ioctl will fail with <varname>errno</varname> set to
+ <constant>ESRCH</constant> is returned.
+ </para>
+ <para>
+ For messages to a unique name (ID), this item is optional. If
+ present, the kernel will make sure the name owner matches the
+ given unique name. This allows programs to tie the message
+ sending to the condition that a name is currently owned by a
+ certain unique name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The message will be augmented by the requested metadata items when
+ queued into the receiver's pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on metadata.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Receiving messages</title>
+
+ <para>
+ Messages are received by the client with the
+ <constant>KDBUS_CMD_RECV</constant> ioctl. The endpoint file of the bus
+ supports <function>poll()/epoll()/select()</function>; when new messages
+ are available on the connection's file descriptor,
+ <constant>POLLIN</constant> is reported. For compatibility reasons,
+ <constant>POLLOUT</constant> is always reported as well. Note, however,
+ that the latter does not guarantee that a message can in fact be sent, as
+ this depends on how many pending messages the receiver has in its pool.
+ </para>
+
+ <para>
+ With the <constant>KDBUS_CMD_RECV</constant> ioctl, a
+ <type>struct kdbus_cmd_recv</type> is used.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_recv {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __s64 priority;
+ __u64 dropped_msgs;
+ struct kdbus_msg_info msg;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to control the receive command.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_RECV_PEEK</constant></term>
+ <listitem>
+ <para>
+ Just return the location of the next message. Do not install
+ file descriptors or anything else. This is usually used to
+ determine the sender of the next queued message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_RECV_DROP</constant></term>
+ <listitem>
+ <para>
+ Drop the next message without doing anything else with it,
+ and free the pool slice. This a short-cut for
+ <constant>KDBUS_RECV_PEEK</constant> and
+ <constant>KDBUS_CMD_FREE</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_RECV_USE_PRIORITY</constant></term>
+ <listitem>
+ <para>
+ Dequeue the messages ordered by their priority, and filtering
+ them with the priority field (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. If the <varname>dropped_msgs</varname>
+ field is non-zero, <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant>
+ is set. If a file descriptor could not be installed, the
+ <constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant> flag is set.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>priority</varname></term>
+ <listitem><para>
+ With <constant>KDBUS_RECV_USE_PRIORITY</constant> set in
+ <varname>flags</varname>, messages will be dequeued ordered by their
+ priority, starting with the highest value. Also, messages will be
+ filtered by the value given in this field, so the returned message
+ will at least have the requested priority. If no such message is
+ waiting in the queue, the ioctl will fail, and
+ <varname>errno</varname> will be set to <constant>EAGAIN</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dropped_msgs</varname></term>
+ <listitem><para>
+ Whenever a message with <constant>KDBUS_MSG_SIGNAL</constant> is sent
+ but cannot be queued on a peer (e.g., as it contains FDs but the peer
+ does not support FDs, or there is no space left in the peer's pool..)
+ the 'dropped_msgs' counter of the peer is incremented. On the next
+ RECV ioctl, the 'dropped_msgs' field is copied into the ioctl struct
+ and cleared on the peer. If it was non-zero, the
+ <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant> flag will be set
+ in <varname>return_flags</varname>. Note that this will only happen
+ if the ioctl succeeded or failed with <constant>EAGAIN</constant>. In
+ other error cases, the 'dropped_msgs' field of the peer is left
+ untouched.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg</varname></term>
+ <listitem><para>
+ Embedded struct containing information on the received message when
+ this command succeeded (see below).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem><para>
+ Items to specify further details for the receive command.
+ Currently unused, and all items will be rejected with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Both <type>struct kdbus_cmd_recv</type> and
+ <type>struct kdbus_cmd_send</type> embed
+ <type>struct kdbus_msg_info</type>.
+ For the <constant>KDBUS_CMD_SEND</constant> ioctl, it is used to catch
+ synchronous replies, if one was requested, and is unused otherwise.
+ </para>
+
+ <programlisting>
+struct kdbus_msg_info {
+ __u64 offset;
+ __u64 msg_size;
+ __u64 return_flags;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ Upon return of the ioctl, this field contains the offset in the
+ receiver's memory pool. The memory must be freed with
+ <constant>KDBUS_CMD_FREE</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg_size</varname></term>
+ <listitem><para>
+ Upon successful return of the ioctl, this field contains the size of
+ the allocated slice at offset <varname>offset</varname>.
+ It is the combination of the size of the stored
+ <type>struct kdbus_msg</type> object plus all appended VECs.
+ You can use it in combination with <varname>offset</varname> to map
+ a single message, instead of mapping the entire pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem>
+ <para>
+ Kernel-provided return flags. Currently, the following flags are
+ defined.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant></term>
+ <listitem>
+ <para>
+ The message contained memfds or file descriptors, and the
+ kernel failed to install one or more of them at receive time.
+ Most probably that happened because the maximum number of
+ file descriptors for the receiver's task were exceeded.
+ In such cases, the message is still delivered, so this is not
+ a fatal condition. File descriptors numbers inside the
+ <constant>KDBUS_ITEM_FDS</constant> item or memfd files
+ referenced by <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant>
+ items which could not be installed will be set to
+ <constant>-1</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unless <constant>KDBUS_RECV_DROP</constant> was passed, the
+ <varname>offset</varname> field contains the location of the new message
+ inside the receiver's pool after the <constant>KDBUS_CMD_RECV</constant>
+ ioctl was employed. The message is stored as <type>struct kdbus_msg</type>
+ at this offset, and can be interpreted with the semantics described above.
+ </para>
+ <para>
+ Also, if the connection allowed for file descriptor to be passed
+ (<constant>KDBUS_HELLO_ACCEPT_FD</constant>), and if the message contained
+ any, they will be installed into the receiving process when the
+ <constant>KDBUS_CMD_RECV</constant> ioctl is called.
+ <emphasis>memfds</emphasis> may always be part of the message payload.
+ The receiving task is obliged to close all file descriptors appropriately
+ once no longer needed. If <constant>KDBUS_RECV_PEEK</constant> is set, no
+ file descriptors are installed. This allows for peeking at a message,
+ looking at its metadata only and dropping it via
+ <constant>KDBUS_RECV_DROP</constant>, without installing any of the file
+ descriptors into the receiving process.
+ </para>
+ <para>
+ The caller is obliged to call the <constant>KDBUS_CMD_FREE</constant>
+ ioctl with the returned offset when the memory is no longer needed.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notifications</title>
+ <para>
+ A kernel notification is a regular kdbus message with the following
+ details.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ kdbus_msg.src_id == <constant>KDBUS_SRC_ID_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ kdbus_msg.dst_id == <constant>KDBUS_DST_ID_BROADCAST</constant>
+ </para></listitem>
+ <listitem><para>
+ kdbus_msg.payload_type == <constant>KDBUS_PAYLOAD_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ Has exactly one of the items attached that are described below.
+ </para></listitem>
+ <listitem><para>
+ Always has a timestamp item (<constant>KDBUS_ITEM_TIMESTAMP</constant>)
+ attached.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ The kernel will notify its users of the following events.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ When connection <emphasis>A</emphasis> is terminated while connection
+ <emphasis>B</emphasis> is waiting for a reply from it, connection
+ <emphasis>B</emphasis> is notified with a message with an item of
+ type <constant>KDBUS_ITEM_REPLY_DEAD</constant>.
+ </para></listitem>
+
+ <listitem><para>
+ When connection <emphasis>A</emphasis> does not receive a reply from
+ connection <emphasis>B</emphasis> within the specified timeout window,
+ connection <emphasis>A</emphasis> will receive a message with an
+ item of type <constant>KDBUS_ITEM_REPLY_TIMEOUT</constant>.
+ </para></listitem>
+
+ <listitem><para>
+ When an ordinary connection (not a monitor) is created on or removed
+ from a bus, messages with an item of type
+ <constant>KDBUS_ITEM_ID_ADD</constant> or
+ <constant>KDBUS_ITEM_ID_REMOVE</constant>, respectively, are delivered
+ to all bus members that match these messages through their match
+ database. Eavesdroppers (monitor connections) do not cause such
+ notifications to be sent. They are invisible on the bus.
+ </para></listitem>
+
+ <listitem><para>
+ When a connection gains or loses ownership of a name, messages with an
+ item of type <constant>KDBUS_ITEM_NAME_ADD</constant>,
+ <constant>KDBUS_ITEM_NAME_REMOVE</constant> or
+ <constant>KDBUS_ITEM_NAME_CHANGE</constant> are delivered to all bus
+ members that match these messages through their match database.
+ </para></listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_SEND</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The connection is not an ordinary connection, or the passed
+ file descriptors in <constant>KDBUS_ITEM_FDS</constant> item are
+ either kdbus handles or unix domain sockets. Both are currently
+ unsupported.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The submitted payload type is
+ <constant>KDBUS_PAYLOAD_KERNEL</constant>,
+ <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set without timeout
+ or cookie values, <constant>KDBUS_SEND_SYNC_REPLY</constant> was
+ set without <constant>KDBUS_MSG_EXPECT_REPLY</constant>, an invalid
+ item was supplied, <constant>src_id</constant> was non-zero and was
+ different from the current connection's ID, a supplied memfd had a
+ size of 0, or a string was not properly null-terminated.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOTUNIQ</constant></term>
+ <listitem><para>
+ The supplied destination is
+ <constant>KDBUS_DST_ID_BROADCAST</constant> and either
+ file descriptors were passed, or
+ <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set,
+ or a timeout was given.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ Too many items
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMSGSIZE</constant></term>
+ <listitem><para>
+ The size of the message header and items or the payload vector
+ is excessive.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ Multiple <constant>KDBUS_ITEM_FDS</constant>,
+ <constant>KDBUS_ITEM_BLOOM_FILTER</constant> or
+ <constant>KDBUS_ITEM_DST_NAME</constant> items were supplied.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADF</constant></term>
+ <listitem><para>
+ The supplied <constant>KDBUS_ITEM_FDS</constant> or
+ <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> items
+ contained an illegal file descriptor.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMEDIUMTYPE</constant></term>
+ <listitem><para>
+ The supplied memfd is not a sealed kdbus memfd.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ Too many file descriptors inside a
+ <constant>KDBUS_ITEM_FDS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADMSG</constant></term>
+ <listitem><para>
+ An item had illegal size, both a <constant>dst_id</constant> and a
+ <constant>KDBUS_ITEM_DST_NAME</constant> was given, or both a name
+ and a bloom filter was given.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ETXTBSY</constant></term>
+ <listitem><para>
+ The supplied kdbus memfd file cannot be sealed or the seal
+ was removed, because it is shared with other processes or
+ still mapped with
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECOMM</constant></term>
+ <listitem><para>
+ A peer does not accept the file descriptors addressed to it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EFAULT</constant></term>
+ <listitem><para>
+ The supplied bloom filter size was not 64-bit aligned, or supplied
+ memory could not be accessed by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDOM</constant></term>
+ <listitem><para>
+ The supplied bloom filter size did not match the bloom filter
+ size of the bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDESTADDRREQ</constant></term>
+ <listitem><para>
+ <constant>dst_id</constant> was set to
+ <constant>KDBUS_DST_ID_NAME</constant>, but no
+ <constant>KDBUS_ITEM_DST_NAME</constant> was attached.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ The name to look up was not found in the name registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EADDRNOTAVAIL</constant></term>
+ <listitem><para>
+ <constant>KDBUS_MSG_NO_AUTO_START</constant> was given but the
+ destination connection is an activator.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENXIO</constant></term>
+ <listitem><para>
+ The passed numeric destination connection ID couldn't be found,
+ or is not connected.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECONNRESET</constant></term>
+ <listitem><para>
+ The destination connection is no longer active.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ETIMEDOUT</constant></term>
+ <listitem><para>
+ Timeout while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINTR</constant></term>
+ <listitem><para>
+ Interrupted system call while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPIPE</constant></term>
+ <listitem><para>
+ When sending a message, a synchronous reply from the receiving
+ connection was expected but the connection died before answering.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOBUFS</constant></term>
+ <listitem><para>
+ Too many pending messages on the receiver side.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EREMCHG</constant></term>
+ <listitem><para>
+ Both a well-known name and a unique name (ID) was given, but
+ the name is not currently owned by that connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EXFULL</constant></term>
+ <listitem><para>
+ The memory pool of the receiver is full.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EREMOTEIO</constant></term>
+ <listitem><para>
+ While synchronously waiting for a reply, the remote peer
+ failed with an I/O error.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_RECV</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The connection is not an ordinary connection, or the passed
+ file descriptors are either kdbus handles or unix domain
+ sockets. Both are currently unsupported.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid flags or offset.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EAGAIN</constant></term>
+ <listitem><para>
+ No message found in the queue
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>clock_gettime</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>ioctl</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>select</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>epoll</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>eventfd</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>memfd_create</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.name.xml b/Documentation/kdbus/kdbus.name.xml
new file mode 100644
index 000000000000..3f5f6a6c5ed6
--- /dev/null
+++ b/Documentation/kdbus/kdbus.name.xml
@@ -0,0 +1,711 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.name">
+
+ <refentryinfo>
+ <title>kdbus.name</title>
+ <productname>kdbus.name</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.name</refname>
+ <refpurpose>kdbus.name</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Each
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ instantiates a name registry to resolve well-known names into unique
+ connection IDs for message delivery. The registry will be queried when a
+ message is sent with <varname>kdbus_msg.dst_id</varname> set to
+ <constant>KDBUS_DST_ID_NAME</constant>, or when a registry dump is
+ requested with <constant>KDBUS_CMD_NAME_LIST</constant>.
+ </para>
+
+ <para>
+ All of the below is subject to policy rules for <emphasis>SEE</emphasis>
+ and <emphasis>OWN</emphasis> permissions. See
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Name validity</title>
+ <para>
+ A name has to comply with the following rules in order to be considered
+ valid.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The name has two or more elements separated by a
+ '<literal>.</literal>' (period) character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All elements must contain at least one character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Each element must only contain the ASCII characters
+ <literal>[A-Z][a-z][0-9]_</literal> and must not begin with a
+ digit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must contain at least one '<literal>.</literal>' (period)
+ character (and thus at least two elements).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must not begin with a '<literal>.</literal>' (period)
+ character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must not exceed <constant>255</constant> characters in
+ length.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Acquiring a name</title>
+ <para>
+ To acquire a name, a client uses the
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> ioctl with
+ <type>struct kdbus_cmd</type> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to control details in the name acquisition.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_REPLACE_EXISTING</constant></term>
+ <listitem>
+ <para>
+ Acquiring a name that is already present usually fails,
+ unless this flag is set in the call, and
+ <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> (see below)
+ was set when the current owner of the name acquired it, or
+ if the current owner is an activator connection (see
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
+ <listitem>
+ <para>
+ Allow other connections to take over this name. When this
+ happens, the former owner of the connection will be notified
+ of the name loss.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_QUEUE</constant></term>
+ <listitem>
+ <para>
+ A name that is already acquired by a connection can not be
+ acquired again (unless the
+ <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> flag was
+ set during acquisition; see above).
+ However, a connection can put itself in a queue of
+ connections waiting for the name to be released. Once that
+ happens, the first connection in that queue becomes the new
+ owner and is notified accordingly.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem>
+ <para>
+ Flags returned by the kernel. Currently, the following may be
+ returned by the kernel.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
+ <listitem>
+ <para>
+ The name was not acquired yet, but the connection was
+ placed in the queue of peers waiting for the name.
+ This can only happen if <constant>KDBUS_NAME_QUEUE</constant>
+ was set in the <varname>flags</varname> member (see above).
+ The connection will receive a name owner change notification
+ once the current owner has given up the name and its
+ ownership was transferred.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to submit the name. Currently, one item of type
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
+ the contained string must be a valid bus name.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
+ valid item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a detailed description of how this item is used.
+ </para>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <errorname>>EINVAL</errorname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Releasing a name</title>
+ <para>
+ A connection may release a name explicitly with the
+ <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl. If the connection was
+ an implementer of an activatable name, its pending messages are moved
+ back to the activator. If there are any connections queued up as waiters
+ for the name, the first one in the queue (the oldest entry) will become
+ the new owner. The same happens implicitly for all names once a
+ connection terminates. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on connections.
+ </para>
+ <para>
+ The <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl uses the same data
+ structure as the acquisition call
+ (<constant>KDBUS_CMD_NAME_ACQUIRE</constant>),
+ but with slightly different field usage.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Flags to the command. Currently unused.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to submit the name. Currently, one item of type
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
+ the contained string must be a valid bus name.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
+ valid item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a detailed description of how this item is used.
+ </para>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Dumping the name registry</title>
+ <para>
+ A connection may request a complete or filtered dump of currently active
+ bus names with the <constant>KDBUS_CMD_LIST</constant> ioctl, which
+ takes a <type>struct kdbus_cmd_list</type> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_list {
+ __u64 flags;
+ __u64 return_flags;
+ __u64 offset;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem>
+ <para>
+ Any combination of flags to specify which names should be dumped.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_LIST_UNIQUE</constant></term>
+ <listitem>
+ <para>
+ List the unique (numeric) IDs of the connection, whether it
+ owns a name or not.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_NAMES</constant></term>
+ <listitem>
+ <para>
+ List well-known names stored in the database which are
+ actively owned by a real connection (not an activator).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_ACTIVATORS</constant></term>
+ <listitem>
+ <para>
+ List names that are owned by an activator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_QUEUED</constant></term>
+ <listitem>
+ <para>
+ List connections that are not yet owning a name but are
+ waiting for it to become available.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ When the ioctl returns successfully, the offset to the name registry
+ dump inside the connection's pool will be stored in this field.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The returned list of names is stored in a <type>struct kdbus_list</type>
+ that in turn contains an array of type <type>struct kdbus_info</type>,
+ The array-size in bytes is given as <varname>list_size</varname>.
+ The fields inside <type>struct kdbus_info</type> is described next.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The owning connection's unique ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The flags of the owning connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items containing the actual name. Currently, one item of type
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> will be attached,
+ including the name's flags. In that item, the flags field of the
+ name may carry the following bits:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
+ <listitem>
+ <para>
+ Other connections are allowed to take over this name from the
+ connection that owns it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
+ <listitem>
+ <para>
+ When retrieving a list of currently acquired names in the
+ registry, this flag indicates whether the connection
+ actually owns the name or is currently waiting for it to
+ become available.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ACTIVATOR</constant></term>
+ <listitem>
+ <para>
+ An activator connection owns a name as a placeholder for an
+ implementer, which is started on demand by programs as soon
+ as the first message arrives. There's some more information
+ on this topic in
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ .
+ </para>
+ <para>
+ In contrast to
+ <constant>KDBUS_NAME_REPLACE_EXISTING</constant>,
+ when a name is taken over from an activator connection, all
+ the messages that have been queued in the activator
+ connection will be moved over to the new owner. The activator
+ connection will still be tracked for the name and will take
+ control again if the implementer connection terminates.
+ </para>
+ <para>
+ This flag can not be used when acquiring a name, but is
+ implicitly set through <constant>KDBUS_CMD_HELLO</constant>
+ with <constant>KDBUS_HELLO_ACTIVATOR</constant> set in
+ <varname>kdbus_cmd_hello.conn_flags</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The returned buffer must be freed with the
+ <constant>KDBUS_CMD_FREE</constant> ioctl when the user is finished with
+ it. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal command flags, illegal name provided, or an activator
+ tried to acquire a second name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPERM</constant></term>
+ <listitem><para>
+ Policy prohibited name ownership.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EALREADY</constant></term>
+ <listitem><para>
+ Connection already owns that name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ The name already exists and can not be taken over.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ The maximum number of well-known names per connection is exhausted.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_NAME_RELEASE</constant>
+ may fail with the following errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid command flags, or invalid name provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ Name is not found in the registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EADDRINUSE</constant></term>
+ <listitem><para>
+ Name is owned by a different connection and can't be released.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_LIST</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid command flags
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOBUFS</constant></term>
+ <listitem><para>
+ No available memory in the connection's pool.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.policy.xml b/Documentation/kdbus/kdbus.policy.xml
new file mode 100644
index 000000000000..67324163880a
--- /dev/null
+++ b/Documentation/kdbus/kdbus.policy.xml
@@ -0,0 +1,406 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.policy">
+
+ <refentryinfo>
+ <title>kdbus.policy</title>
+ <productname>kdbus.policy</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.policy</refname>
+ <refpurpose>kdbus policy</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A kdbus policy restricts the possibilities of connections to own, see and
+ talk to well-known names. A policy can be associated with a bus (through a
+ policy holder connection) or a custom endpoint. kdbus stores its policy
+ information in a database that can be accessed through the following
+ ioctl commands:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_HELLO</constant></term>
+ <listitem><para>
+ When creating, or updating, a policy holder connection. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></term>
+ <term><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></term>
+ <listitem><para>
+ When creating, or updating, a bus custom endpoint. See
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ In all cases, the name and policy access information is stored in items
+ of type <constant>KDBUS_ITEM_NAME</constant> and
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant>. For this transport, the
+ following rules apply.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ An item of type <constant>KDBUS_ITEM_NAME</constant> must be followed
+ by at least one <constant>KDBUS_ITEM_POLICY_ACCESS</constant> item.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ An item of type <constant>KDBUS_ITEM_NAME</constant> can be followed
+ by an arbitrary number of
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> items.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ An arbitrary number of groups of names and access levels can be given.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Names passed in items of type <constant>KDBUS_ITEM_NAME</constant> must
+ comply to the rules of valid kdbus.name. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+
+ The payload of an item of type
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> is defined by the following
+ struct. For more information on the layout of items, please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+
+ <programlisting>
+struct kdbus_policy_access {
+ __u64 type;
+ __u64 access;
+ __u64 id;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>type</varname></term>
+ <listitem>
+ <para>
+ One of the following.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_ACCESS_USER</constant></term>
+ <listitem><para>
+ Grant access to a user with the UID stored in the
+ <varname>id</varname> field.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_ACCESS_GROUP</constant></term>
+ <listitem><para>
+ Grant access to a user with the GID stored in the
+ <varname>id</varname> field.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_ACCESS_WORLD</constant></term>
+ <listitem><para>
+ Grant access to everyone. The <varname>id</varname> field
+ is ignored.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>access</varname></term>
+ <listitem>
+ <para>
+ The access to grant. One of the following.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_SEE</constant></term>
+ <listitem><para>
+ Allow the name to be seen.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_TALK</constant></term>
+ <listitem><para>
+ Allow the name to be talked to.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_OWN</constant></term>
+ <listitem><para>
+ Allow the name to be owned.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ For <constant>KDBUS_POLICY_ACCESS_USER</constant>, stores the UID.
+ For <constant>KDBUS_POLICY_ACCESS_GROUP</constant>, stores the GID.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ All endpoints of buses have an empty policy database by default.
+ Therefore, unless policy rules are added, all operations will also be
+ denied by default. Also see
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Wildcard names</title>
+ <para>
+ Policy holder connections may upload names that contain the wildcard
+ suffix (<literal>".*"</literal>). Such a policy entry is effective for
+ every well-known name that extends the provided name by exactly one more
+ level.
+
+ For example, the name <literal>foo.bar.*</literal> matches both
+ <literal>"foo.bar.baz"</literal> and
+ <literal>"foo.bar.bazbaz"</literal> are, but not
+ <literal>"foo.bar.baz.baz"</literal>.
+
+ This allows connections to take control over multiple names that the
+ policy holder doesn't need to know about when uploading the policy.
+
+ Such wildcard entries are not allowed for custom endpoints.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Privileged connections</title>
+ <para>
+ The policy database is overruled when action is taken by a privileged
+ connection. Please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on what makes a connection privileged.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+ <para>
+ For instance, a set of policy rules may look like this:
+ </para>
+
+ <programlisting>
+KDBUS_ITEM_NAME: str='org.foo.bar'
+KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=1000
+KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, ID=1001
+KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=SEE
+
+KDBUS_ITEM_NAME: str='org.blah.baz'
+KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=0
+KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK
+ </programlisting>
+
+ <para>
+ That means that 'org.foo.bar' may only be owned by UID 1000, but every
+ user on the bus is allowed to see the name. However, only UID 1001 may
+ actually send a message to the connection and receive a reply from it.
+
+ The second rule allows 'org.blah.baz' to be owned by UID 0 only, but
+ every user may talk to it.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>TALK access and multiple well-known names per connection</title>
+ <para>
+ Note that TALK access is checked against all names of a connection. For
+ example, if a connection owns both <constant>'org.foo.bar'</constant> and
+ <constant>'org.blah.baz'</constant>, and the policy database allows
+ <constant>'org.blah.baz'</constant> to be talked to by WORLD, then this
+ permission is also granted to <constant>'org.foo.bar'</constant>. That
+ might sound illogical, but after all, we allow messages to be directed to
+ either the ID or a well-known name, and policy is applied to the
+ connection, not the name. In other words, the effective TALK policy for a
+ connection is the most permissive of all names the connection owns.
+
+ For broadcast messages, the receiver needs TALK permissions to the sender
+ to receive the broadcast.
+ </para>
+ <para>
+ Both the endpoint and the bus policy databases are consulted to allow
+ name registry listing, owning a well-known name and message delivery.
+ If either one fails, the operation is failed with
+ <varname>errno</varname> set to <constant>EPERM</constant>.
+
+ For best practices, connections that own names with a restricted TALK
+ access should not install matches. This avoids cases where the sent
+ message may pass the bloom filter due to false-positives and may also
+ satisfy the policy rules.
+
+ Also see
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Implicit policies</title>
+ <para>
+ Depending on the type of the endpoint, a set of implicit rules that
+ override installed policies might be enforced.
+
+ On default endpoints, the following set is enforced and checked before
+ any user-supplied policy is checked.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Privileged connections always override any installed policy. Those
+ connections could easily install their own policies, so there is no
+ reason to enforce installed policies.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Connections can always talk to connections of the same user. This
+ includes broadcast messages.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Custom endpoints have stricter policies. The following rules apply:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Policy rules are always enforced, even if the connection is a
+ privileged connection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Policy rules are always enforced for <constant>TALK</constant> access,
+ even if both ends are running under the same user. This includes
+ broadcast messages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To restrict the set of names that can be seen, endpoint policies can
+ install <constant>SEE</constant> policies.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.pool.xml b/Documentation/kdbus/kdbus.pool.xml
new file mode 100644
index 000000000000..05fd01902ad4
--- /dev/null
+++ b/Documentation/kdbus/kdbus.pool.xml
@@ -0,0 +1,320 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.pool">
+
+ <refentryinfo>
+ <title>kdbus.pool</title>
+ <productname>kdbus.pool</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.pool</refname>
+ <refpurpose>kdbus pool</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ A pool for data received from the kernel is installed for every
+ <emphasis>connection</emphasis> of the <emphasis>bus</emphasis>, and
+ is sized according to the information stored in the
+ <varname>pool_size</varname> member of <type>struct kdbus_cmd_hello</type>
+ when <constant>KDBUS_CMD_HELLO</constant> is employed. Internally, the
+ pool is segmented into <emphasis>slices</emphasis>, each referenced by its
+ <emphasis>offset</emphasis> in the pool, expressed in <type>bytes</type>.
+ See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about <constant>KDBUS_CMD_HELLO</constant>.
+ </para>
+
+ <para>
+ The pool is written to by the kernel when one of the following
+ <emphasis>ioctls</emphasis> is issued:
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_HELLO</constant></term>
+ <listitem><para>
+ ... to receive details about the bus the connection was made to
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_RECV</constant></term>
+ <listitem><para>
+ ... to receive a message
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_LIST</constant></term>
+ <listitem><para>
+ ... to dump the name registry
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_CONN_INFO</constant></term>
+ <listitem><para>
+ ... to retrieve information on a connection
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ <para>
+ The <varname>offset</varname> fields returned by either one of the
+ aforementioned ioctls describe offsets inside the pool. In order to make
+ the slice available for subsequent calls,
+ <constant>KDBUS_CMD_FREE</constant> has to be called on that offset
+ (see below). Otherwise, the pool will fill up, and the connection won't
+ be able to receive any more information through its pool.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Pool slice allocation</title>
+ <para>
+ Pool slices are allocated by the kernel in order to report information
+ back to a task, such as messages, returned name list etc.
+ Allocation of pool slices cannot be initiated by userspace. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for examples of commands that use the <emphasis>pool</emphasis> to
+ return data.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Accessing the pool memory</title>
+ <para>
+ Memory in the pool is read-only for userspace and may only be written
+ to by the kernel. To read from the pool memory, the caller is expected to
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ the buffer into its task, like this:
+ </para>
+ <programlisting>
+uint8_t *buf = mmap(NULL, size, PROT_READ, MAP_SHARED, conn_fd, 0);
+ </programlisting>
+
+ <para>
+ In order to map the entire pool, the <varname>size</varname> parameter in
+ the example above should be set to the value of the
+ <varname>pool_size</varname> member of
+ <type>struct kdbus_cmd_hello</type> when
+ <constant>KDBUS_CMD_HELLO</constant> was employed to create the
+ connection (see above).
+ </para>
+
+ <para>
+ The <emphasis>file descriptor</emphasis> used to map the memory must be
+ the one that was used to create the <emphasis>connection</emphasis>.
+ In other words, the one that was used to call
+ <constant>KDBUS_CMD_HELLO</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+
+ <para>
+ Alternatively, instead of mapping the entire pool buffer, only parts
+ of it can be mapped. Every kdbus command that returns an
+ <emphasis>offset</emphasis> (see above) also reports a
+ <emphasis>size</emphasis> along with it, so programs can be written
+ in a way that it only maps portions of the pool to access a specific
+ <emphasis>slice</emphasis>.
+ </para>
+
+ <para>
+ When access to the pool memory is no longer needed, programs should
+ call <function>munmap()</function> on the pointer returned by
+ <function>mmap()</function>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Freeing pool slices</title>
+ <para>
+ The <constant>KDBUS_CMD_FREE</constant> ioctl is used to free a slice
+ inside the pool, describing an offset that was returned in an
+ <varname>offset</varname> field of another ioctl struct.
+ The <constant>KDBUS_CMD_FREE</constant> command takes a
+ <type>struct kdbus_cmd_free</type> as argument.
+ </para>
+
+<programlisting>
+struct kdbus_cmd_free {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 offset;
+ struct kdbus_item items[0];
+};
+</programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently unused.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ The offset to free, as returned by other ioctls that allocated
+ memory for returned information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem><para>
+ Items to specify further details for the receive command.
+ Currently unused.
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ All items except for
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> (see
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ) will be rejected.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_FREE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>ENXIO</constant></term>
+ <listitem><para>
+ No pool slice found at given offset.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid flags provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The offset is valid, but the user is not allowed to free the slice.
+ This happens, for example, if the offset was retrieved with
+ <constant>KDBUS_RECV_PEEK</constant>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>munmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.xml b/Documentation/kdbus/kdbus.xml
new file mode 100644
index 000000000000..194abd2e76cc
--- /dev/null
+++ b/Documentation/kdbus/kdbus.xml
@@ -0,0 +1,1012 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus">
+
+ <refentryinfo>
+ <title>kdbus</title>
+ <productname>kdbus</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus</refname>
+ <refpurpose>Kernel Message Bus</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Synopsis</title>
+ <para>
+ kdbus is an inter-process communication bus system controlled by the
+ kernel. It provides user-space with an API to create buses and send
+ unicast and multicast messages to one, or many, peers connected to the
+ same bus. It does not enforce any layout on the transmitted data, but
+ only provides the transport layer used for message interchange between
+ peers.
+ </para>
+ <para>
+ This set of man-pages gives a comprehensive overview of the kernel-level
+ API, with all ioctl commands, associated structs and bit masks. However,
+ most people will not use this API level directly, but rather let one of
+ the high-level abstraction libraries help them integrate D-Bus
+ functionality into their applications.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ kdbus provides a pseudo filesystem called <emphasis>kdbusfs</emphasis>,
+ which is usually mounted on <filename>/sys/fs/kdbus</filename>. Bus
+ primitives can be accessed as files and sub-directories underneath this
+ mount-point. Any advanced operations are done via
+ <function>ioctl()</function> on files created by
+ <emphasis>kdbusfs</emphasis>. Multiple mount-points of
+ <emphasis>kdbusfs</emphasis> are independent of each other. This allows
+ namespacing of kdbus by mounting a new instance of
+ <emphasis>kdbusfs</emphasis> in a new mount-namespace. kdbus calls these
+ mount instances domains and each bus belongs to exactly one domain.
+ </para>
+
+ <para>
+ kdbus was designed as a transport layer for D-Bus, but is in no way
+ limited, nor controlled by the D-Bus protocol specification. The D-Bus
+ protocol is one possible application layer on top of kdbus.
+ </para>
+
+ <para>
+ For the general D-Bus protocol specification, its payload format, its
+ marshaling, and its communication semantics, please refer to the
+ <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">
+ D-Bus specification</ulink>.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Terminology</title>
+
+ <refsect2>
+ <title>Domain</title>
+ <para>
+ A domain is a <emphasis>kdbusfs</emphasis> mount-point containing all
+ the bus primitives. Each domain is independent, and separate domains
+ do not affect each other.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Bus</title>
+ <para>
+ A bus is a named object inside a domain. Clients exchange messages
+ over a bus. Multiple buses themselves have no connection to each other;
+ messages can only be exchanged on the same bus. The default endpoint of
+ a bus, to which clients establish connections, is the "bus" file
+ /sys/fs/kdbus/<bus name>/bus.
+ Common operating system setups create one "system bus" per system,
+ and one "user bus" for every logged-in user. Applications or services
+ may create their own private buses. The kernel driver does not
+ distinguish between different bus types, they are all handled the same
+ way. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Endpoint</title>
+ <para>
+ An endpoint provides a file to talk to a bus. Opening an endpoint
+ creates a new connection to the bus to which the endpoint belongs. All
+ endpoints have unique names and are accessible as files underneath the
+ directory of a bus, e.g., /sys/fs/kdbus/<bus>/<endpoint>
+ Every bus has a default endpoint called "bus".
+ A bus can optionally offer additional endpoints with custom names
+ to provide restricted access to the bus. Custom endpoints carry
+ additional policy which can be used to create sandboxes with
+ locked-down, limited, filtered access to a bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Connection</title>
+ <para>
+ A connection to a bus is created by opening an endpoint file of a
+ bus. Every ordinary client connection has a unique identifier on the
+ bus and can address messages to every other connection on the same
+ bus by using the peer's connection ID as the destination. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Pool</title>
+ <para>
+ Each connection allocates a piece of shmem-backed memory that is
+ used to receive messages and answers to ioctl commands from the kernel.
+ It is never used to send anything to the kernel. In order to access that
+ memory, an application must mmap() it into its address space. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Well-known Name</title>
+ <para>
+ A connection can, in addition to its implicit unique connection ID,
+ request the ownership of a textual well-known name. Well-known names are
+ noted in reverse-domain notation, such as com.example.service1. A
+ connection that offers a service on a bus is usually reached by its
+ well-known name. An analogy of connection ID and well-known name is an
+ IP address and a DNS name associated with that address. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Message</title>
+ <para>
+ Connections can exchange messages with other connections by addressing
+ the peers with their connection ID or well-known name. A message
+ consists of a message header with information on how to route the
+ message, and the message payload, which is a logical byte stream of
+ arbitrary size. Messages can carry additional file descriptors to be
+ passed from one connection to another, just like passing file
+ descriptors over UNIX domain sockets. Every connection can specify which
+ set of metadata the kernel should attach to the message when it is
+ delivered to the receiving connection. Metadata contains information
+ like: system time stamps, UID, GID, TID, proc-starttime, well-known
+ names, process comm, process exe, process argv, cgroup, capabilities,
+ seclabel, audit session, loginuid and the connection's human-readable
+ name. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Item</title>
+ <para>
+ The API of kdbus implements the notion of items, submitted through and
+ returned by most ioctls, and stored inside data structures in the
+ connection's pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Broadcast, signal, filter, match</title>
+ <para>
+ Signals are messages that a receiver opts in for by installing a blob of
+ bytes, called a 'match'. Signal messages must always carry a
+ counter-part blob, called a 'filter', and signals are only delivered to
+ peers which have a match that white-lists the message's filter. Senders
+ of signal messages can use either a single connection ID as receiver,
+ or the special connection ID
+ <constant>KDBUS_DST_ID_BROADCAST</constant> to potentially send it to
+ all connections of a bus, following the logic described above. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Policy</title>
+ <para>
+ A policy is a set of rules that define which connections can see, talk
+ to, or register a well-known name on the bus. A policy is attached to
+ buses and custom endpoints, and modified by policy holder connections or
+ owners of custom endpoints. See
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Privileged bus users</title>
+ <para>
+ A user connecting to the bus is considered privileged if it is either
+ the creator of the bus, or if it has the CAP_IPC_OWNER capability flag
+ set. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Bus Layout</title>
+
+ <para>
+ A <emphasis>bus</emphasis> provides and defines an environment that peers
+ can connect to for message interchange. A bus is created via the kdbus
+ control interface and can be modified by the bus creator. It applies the
+ policy that control all bus operations. The bus creator itself does not
+ participate as a peer. To establish a peer
+ <emphasis>connection</emphasis>, you have to open one of the
+ <emphasis>endpoints</emphasis> of a bus. Each bus provides a default
+ endpoint, but further endpoints can be created on-demand. Endpoints are
+ used to apply additional policies for all connections on this endpoint.
+ Thus, they provide additional filters to further restrict access of
+ specific connections to the bus.
+ </para>
+
+ <para>
+ Following, you can see an example bus layout:
+ </para>
+
+ <programlisting><![CDATA[
+ Bus Creator
+ |
+ |
+ +-----+
+ | Bus |
+ +-----+
+ |
+ __________________/ \__________________
+ / \
+ | |
+ +----------+ +----------+
+ | Endpoint | | Endpoint |
+ +----------+ +----------+
+ _________/|\_________ _________/|\_________
+ / | \ / | \
+ | | | | | |
+ | | | | | |
+ Connection Connection Connection Connection Connection Connection
+ ]]></programlisting>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Data structures and interconnections</title>
+ <programlisting><![CDATA[
+ +--------------------------------------------------------------------------+
+ | Domain (Mount Point) |
+ | /sys/fs/kdbus/control |
+ | +----------------------------------------------------------------------+ |
+ | | Bus (System Bus) | |
+ | | /sys/fs/kdbus/0-system/ | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | | Endpoint | | Endpoint | | |
+ | | | /sys/fs/kdbus/0-system/bus | | /sys/fs/kdbus/0-system/ep.app | | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | | | Connection | | Connection | | Connection | | Connection | | |
+ | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | +----------------------------------------------------------------------+ |
+ | |
+ | +----------------------------------------------------------------------+ |
+ | | Bus (User Bus for UID 2702) | |
+ | | /sys/fs/kdbus/2702-user/ | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | | Endpoint | | Endpoint | | |
+ | | | /sys/fs/kdbus/2702-user/bus | | /sys/fs/kdbus/2702-user/ep.app | | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | | | Connection | | Connection | | Connection | | Connection | | |
+ | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | |
+ | | +--------------+ +--------------+ +--------------------------------+ | |
+ | +----------------------------------------------------------------------+ |
+ +--------------------------------------------------------------------------+
+ ]]></programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Metadata</title>
+
+ <refsect2>
+ <title>When metadata is collected</title>
+ <para>
+ kdbus records data about the system in certain situations. Such metadata
+ can refer to the currently active process (creds, PIDs, current user
+ groups, process names and its executable path, cgroup membership,
+ capabilities, security label and audit information), connection
+ information (description string, currently owned names) and time stamps.
+ </para>
+ <para>
+ Metadata is collected at the following times.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ When a bus is created (<constant>KDBUS_CMD_MAKE</constant>),
+ information about the calling task is collected. This data is returned
+ by the kernel via the <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant>
+ call.
+ </para></listitem>
+
+ <listitem>
+ <para>
+ When a connection is created (<constant>KDBUS_CMD_HELLO</constant>),
+ information about the calling task is collected. Alternatively, a
+ privileged connection may provide 'faked' information about
+ credentials, PIDs and security labels which will be stored instead.
+ This data is returned by the kernel as information on a connection
+ (<constant>KDBUS_CMD_CONN_INFO</constant>). Only metadata that a
+ connection allowed to be sent (by setting its bit in
+ <varname>attach_flags_send</varname>) will be exported in this way.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a message is sent (<constant>KDBUS_CMD_SEND</constant>),
+ information about the sending task and the sending connection are
+ collected. This metadata will be attached to the message when it
+ arrives in the receiver's pool. If the connection sending the
+ message installed faked credentials (see
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>),
+ the message will not be augmented by any information about the
+ currently sending task. Note that only metadata that was requested
+ by the receiving connection will be collected and attached to
+ messages.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Which metadata items are actually delivered depends on the following
+ sets and masks:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ (a) the system-wide kmod creds mask
+ (module parameter <varname>attach_flags_mask</varname>)
+ </para></listitem>
+
+ <listitem><para>
+ (b) the per-connection send creds mask, set by the connecting client
+ </para></listitem>
+
+ <listitem><para>
+ (c) the per-connection receive creds mask, set by the connecting
+ client
+ </para></listitem>
+
+ <listitem><para>
+ (d) the per-bus minimal creds mask, set by the bus creator
+ </para></listitem>
+
+ <listitem><para>
+ (e) the per-bus owner creds mask, set by the bus creator
+ </para></listitem>
+
+ <listitem><para>
+ (f) the mask specified when querying creds of a bus peer
+ </para></listitem>
+
+ <listitem><para>
+ (g) the mask specified when querying creds of a bus owner
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ With the following rules:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ [1] The creds attached to messages are determined as
+ <constant>a & b & c</constant>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [2] When connecting to a bus (<constant>KDBUS_CMD_HELLO</constant>),
+ and <constant>~b & d != 0</constant>, the call will fail with,
+ <errorcode>-1</errorcode>, and <varname>errno</varname> is set to
+ <constant>ECONNREFUSED</constant>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [3] When querying creds of a bus peer, the creds returned are
+ <constant>a & b & f</constant>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [4] When querying creds of a bus owner, the creds returned are
+ <constant>a & e & g</constant>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Hence, programs might not always get all requested metadata items that
+ it requested. Code must be written so that it can cope with this fact.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Benefits and heads-up</title>
+ <para>
+ Attaching metadata to messages has two major benefits.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Metadata attached to messages is gathered at the moment when the
+ other side calls <constant>KDBUS_CMD_SEND</constant>, or,
+ respectively, then the kernel notification is generated. There is
+ no need for the receiving peer to retrieve information about the
+ task in a second step. This closes a race gap that would otherwise
+ be inherent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ As metadata is delivered along with messages in the same data
+ blob, no extra calls to kernel functions etc. are needed to gather
+ them.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Note, however, that collecting metadata does come at a price for
+ performance, so developers should carefully assess which metadata to
+ really opt-in for. For best practice, data that is not needed as part
+ of a message should not be requested by the connection in the first
+ place (see <varname>attach_flags_recv</varname> in
+ <constant>KDBUS_CMD_HELLO</constant>).
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Attach flags for metadata items</title>
+ <para>
+ To let the kernel know which metadata information to attach as items
+ to the aforementioned commands, it uses a bitmask. In those, the
+ following <emphasis>attach flags</emphasis> are currently supported.
+ Both the the <varname>attach_flags_recv</varname> and
+ <varname>attach_flags_send</varname> fields of
+ <type>struct kdbus_cmd_hello</type>, as well as the payload of the
+ <constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant> and
+ <constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant> items follow this
+ scheme.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_TIMESTAMP</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_TIMESTAMP</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CREDS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CREDS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_PIDS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_PIDS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_AUXGROUPS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_AUXGROUPS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_NAMES</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_OWNED_NAME</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_TID_COMM</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_TID_COMM</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_PID_COMM</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_PID_COMM</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_EXE</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_EXE</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CMDLINE</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CMDLINE</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CGROUP</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CGROUP</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CAPS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CAPS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_SECLABEL</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_SECLABEL</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_AUDIT</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_AUDIT</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CONN_DESCRIPTION</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for detailed information about the layout and payload of items and
+ what metadata should be used to.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>The ioctl interface</title>
+
+ <para>
+ As stated in the 'synopsis' section above, application developers are
+ strongly encouraged to use kdbus through one of the high-level D-Bus
+ abstraction libraries, rather than using the low-level API directly.
+ </para>
+
+ <para>
+ kdbus on the kernel level exposes its functions exclusively through
+ <citerefentry>
+ <refentrytitle>ioctl</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>,
+ employed on file descriptors returned by
+ <citerefentry>
+ <refentrytitle>open</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on pseudo files exposed by
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ <para>
+ Following is a list of all the ioctls, along with the command structs
+ they must be used with.
+ </para>
+
+ <informaltable frame="none">
+ <tgroup cols="3" colsep="1">
+ <thead>
+ <row>
+ <entry>ioctl signature</entry>
+ <entry>command</entry>
+ <entry>transported struct</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><constant>0x40189500</constant></entry>
+ <entry><constant>KDBUS_CMD_BUS_MAKE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x40189510</constant></entry>
+ <entry><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0xc0609580</constant></entry>
+ <entry><constant>KDBUS_CMD_HELLO</constant></entry>
+ <entry><type>struct kdbus_cmd_hello *</type></entry>
+ </row><row>
+ <entry><constant>0x40189582</constant></entry>
+ <entry><constant>KDBUS_CMD_BYEBYE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x40389590</constant></entry>
+ <entry><constant>KDBUS_CMD_SEND</constant></entry>
+ <entry><type>struct kdbus_cmd_send *</type></entry>
+ </row><row>
+ <entry><constant>0x80409591</constant></entry>
+ <entry><constant>KDBUS_CMD_RECV</constant></entry>
+ <entry><type>struct kdbus_cmd_recv *</type></entry>
+ </row><row>
+ <entry><constant>0x40209583</constant></entry>
+ <entry><constant>KDBUS_CMD_FREE</constant></entry>
+ <entry><type>struct kdbus_cmd_free *</type></entry>
+ </row><row>
+ <entry><constant>0x401895a0</constant></entry>
+ <entry><constant>KDBUS_CMD_NAME_ACQUIRE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x401895a1</constant></entry>
+ <entry><constant>KDBUS_CMD_NAME_RELEASE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x80289586</constant></entry>
+ <entry><constant>KDBUS_CMD_LIST</constant></entry>
+ <entry><type>struct kdbus_cmd_list *</type></entry>
+ </row><row>
+ <entry><constant>0x80309584</constant></entry>
+ <entry><constant>KDBUS_CMD_CONN_INFO</constant></entry>
+ <entry><type>struct kdbus_cmd_info *</type></entry>
+ </row><row>
+ <entry><constant>0x40209551</constant></entry>
+ <entry><constant>KDBUS_CMD_UPDATE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x80309585</constant></entry>
+ <entry><constant>KDBUS_CMD_BUS_CREATOR_INFO</constant></entry>
+ <entry><type>struct kdbus_cmd_info *</type></entry>
+ </row><row>
+ <entry><constant>0x40189511</constant></entry>
+ <entry><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x402095b0</constant></entry>
+ <entry><constant>KDBUS_CMD_MATCH_ADD</constant></entry>
+ <entry><type>struct kdbus_cmd_match *</type></entry>
+ </row><row>
+ <entry><constant>0x402095b1</constant></entry>
+ <entry><constant>KDBUS_CMD_MATCH_REMOVE</constant></entry>
+ <entry><type>struct kdbus_cmd_match *</type></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ Depending on the type of <emphasis>kdbusfs</emphasis> node that was
+ opened and what ioctls have been executed on a file descriptor before,
+ a different sub-set of ioctl commands is allowed.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ On a file descriptor resulting from opening a
+ <emphasis>control node</emphasis>, only the
+ <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl may be executed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On a file descriptor resulting from opening a
+ <emphasis>bus endpoint node</emphasis>, only the
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> and
+ <constant>KDBUS_CMD_HELLO</constant> ioctls may be executed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A file descriptor that was used to create a bus
+ (via <constant>KDBUS_CMD_BUS_MAKE</constant>) is called a
+ <emphasis>bus owner</emphasis> file descriptor. The bus will be
+ active as long as the file descriptor is kept open.
+ A bus owner file descriptor can not be used to
+ employ any further ioctls. As soon as
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ is called on it, the bus will be shut down, along will all associated
+ endpoints and connections. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A file descriptor that was used to create an endpoint
+ (via <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>) is called an
+ <emphasis>endpoint owner</emphasis> file descriptor. The endpoint
+ will be active as long as the file descriptor is kept open.
+ An endpoint owner file descriptor can only be used
+ to update details of an endpoint through the
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> ioctl. As soon as
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ is called on it, the endpoint will be removed from the bus, and all
+ connections that are connected to the bus through it are shut down.
+ See
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A file descriptor that was used to create a connection
+ (via <constant>KDBUS_CMD_HELLO</constant>) is called a
+ <emphasis>connection owner</emphasis> file descriptor. The connection
+ will be active as long as the file descriptor is kept open.
+ A connection owner file descriptor may be used to
+ issue any of the following ioctls.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ <constant>KDBUS_CMD_UPDATE</constant> to tweak details of the
+ connection. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_BYEBYE</constant> to shut down a connection
+ without losing messages. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_FREE</constant> to free a slice of memory in
+ the pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_CONN_INFO</constant> to retrieve information
+ on other connections on the bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> to retrieve
+ information on the bus creator. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_LIST</constant> to retrieve a list of
+ currently active well-known names and unique IDs on the bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_SEND</constant> and
+ <constant>KDBUS_CMD_RECV</constant> to send or receive a message.
+ See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> and
+ <constant>KDBUS_CMD_NAME_RELEASE</constant> to acquire or release
+ a well-known name on the bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_MATCH_ADD</constant> and
+ <constant>KDBUS_CMD_MATCH_REMOVE</constant> to add or remove
+ a match for signal messages. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ These ioctls, along with the structs they transport, are explained in
+ detail in the other documents linked to in the 'see also' section below.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>ioctl</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>open</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>
+ </member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
diff --git a/Documentation/kdbus/stylesheet.xsl b/Documentation/kdbus/stylesheet.xsl
new file mode 100644
index 000000000000..52565eac7d0d
--- /dev/null
+++ b/Documentation/kdbus/stylesheet.xsl
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <param name="chunk.quietly">1</param>
+ <param name="funcsynopsis.style">ansi</param>
+ <param name="funcsynopsis.tabular.threshold">80</param>
+ <param name="callout.graphics">0</param>
+ <param name="paper.type">A4</param>
+ <param name="generate.section.toc.level">2</param>
+ <param name="use.id.as.filename">1</param>
+ <param name="citerefentry.link">1</param>
+ <strip-space elements="*"/>
+ <template name="generate.citerefentry.link">
+ <value-of select="refentrytitle"/>
+ <text>.html</text>
+ </template>
+</stylesheet>
diff --git a/Makefile b/Makefile
index 1100ff3c77e3..08c98188a37a 100644
--- a/Makefile
+++ b/Makefile
@@ -1350,6 +1350,7 @@ $(help-board-dirs): help-%:
%docs: scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
+ $(Q)$(MAKE) $(build)=Documentation/kdbus $@
else # KBUILD_EXTMOD
--
2.3.1
WARNING: multiple messages have this Message-ID (diff)
From: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
To: arnd@arndb.de, ebiederm@xmission.com, gnomes@lxorguk.ukuu.org.uk,
teg@jklm.no, jkosina@suse.cz, luto@amacapital.net,
linux-api@vger.kernel.org, linux-kernel@vger.kernel.org
Cc: daniel@zonque.org, dh.herrmann@gmail.com, tixxdz@opendz.org,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Subject: [PATCH 01/14] kdbus: add documentation
Date: Mon, 9 Mar 2015 14:09:07 +0100 [thread overview]
Message-ID: <1425906560-13798-2-git-send-email-gregkh@linuxfoundation.org> (raw)
In-Reply-To: <1425906560-13798-1-git-send-email-gregkh@linuxfoundation.org>
From: Daniel Mack <daniel@zonque.org>
kdbus is a system for low-latency, low-overhead, easy to use
interprocess communication (IPC).
The interface to all functions in this driver is implemented via ioctls
on files exposed through a filesystem called 'kdbusfs'. The default
mount point of kdbusfs is /sys/fs/kdbus. This patch adds detailed
documentation about the kernel level API design.
This patch adds a set of comprehensive set of DocBook files which
can be turned into man-pages using 'make mandocs', or into HTML
files with 'make htmldocs'.
Signed-off-by: Daniel Mack <daniel@zonque.org>
Signed-off-by: David Herrmann <dh.herrmann@gmail.com>
Signed-off-by: Djalal Harouni <tixxdz@opendz.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
---
Documentation/Makefile | 2 +-
Documentation/kdbus/Makefile | 30 +
Documentation/kdbus/kdbus.bus.xml | 360 +++++++++
Documentation/kdbus/kdbus.connection.xml | 1252 +++++++++++++++++++++++++++++
Documentation/kdbus/kdbus.endpoint.xml | 436 ++++++++++
Documentation/kdbus/kdbus.fs.xml | 124 +++
Documentation/kdbus/kdbus.item.xml | 840 ++++++++++++++++++++
Documentation/kdbus/kdbus.match.xml | 553 +++++++++++++
Documentation/kdbus/kdbus.message.xml | 1277 ++++++++++++++++++++++++++++++
Documentation/kdbus/kdbus.name.xml | 711 +++++++++++++++++
Documentation/kdbus/kdbus.policy.xml | 406 ++++++++++
Documentation/kdbus/kdbus.pool.xml | 320 ++++++++
Documentation/kdbus/kdbus.xml | 1012 +++++++++++++++++++++++
Documentation/kdbus/stylesheet.xsl | 16 +
Makefile | 1 +
15 files changed, 7339 insertions(+), 1 deletion(-)
create mode 100644 Documentation/kdbus/Makefile
create mode 100644 Documentation/kdbus/kdbus.bus.xml
create mode 100644 Documentation/kdbus/kdbus.connection.xml
create mode 100644 Documentation/kdbus/kdbus.endpoint.xml
create mode 100644 Documentation/kdbus/kdbus.fs.xml
create mode 100644 Documentation/kdbus/kdbus.item.xml
create mode 100644 Documentation/kdbus/kdbus.match.xml
create mode 100644 Documentation/kdbus/kdbus.message.xml
create mode 100644 Documentation/kdbus/kdbus.name.xml
create mode 100644 Documentation/kdbus/kdbus.policy.xml
create mode 100644 Documentation/kdbus/kdbus.pool.xml
create mode 100644 Documentation/kdbus/kdbus.xml
create mode 100644 Documentation/kdbus/stylesheet.xsl
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6883a1b9b351..5e3fde632d03 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,4 +1,4 @@
subdir-y := accounting arm auxdisplay blackfin connector \
- filesystems filesystems ia64 laptops mic misc-devices \
+ filesystems filesystems ia64 kdbus laptops mic misc-devices \
networking pcmcia prctl ptp spi timers vDSO video4linux \
watchdog
diff --git a/Documentation/kdbus/Makefile b/Documentation/kdbus/Makefile
new file mode 100644
index 000000000000..cd6b48ee41bf
--- /dev/null
+++ b/Documentation/kdbus/Makefile
@@ -0,0 +1,30 @@
+DOCS := \
+ kdbus.xml \
+ kdbus.bus.xml \
+ kdbus.connection.xml \
+ kdbus.endpoint.xml \
+ kdbus.fs.xml \
+ kdbus.item.xml \
+ kdbus.match.xml \
+ kdbus.message.xml \
+ kdbus.name.xml \
+ kdbus.policy.xml \
+ kdbus.pool.xml
+
+XMLFILES := $(addprefix $(obj)/,$(DOCS))
+MANFILES := $(patsubst %.xml, %.7, $(XMLFILES))
+HTMLFILES := $(patsubst %.xml, %.html, $(XMLFILES))
+
+XMLTO_ARGS := -m $(obj)/stylesheet.xsl
+
+%.7: %.xml
+ xmlto man $(XMLTO_ARGS) -o . $<
+
+%.html: %.xml
+ xmlto html-nochunks $(XMLTO_ARGS) -o . $<
+
+mandocs: $(MANFILES)
+
+htmldocs: $(HTMLFILES)
+
+clean-files := $(MANFILES) $(HTMLFILES)
diff --git a/Documentation/kdbus/kdbus.bus.xml b/Documentation/kdbus/kdbus.bus.xml
new file mode 100644
index 000000000000..4d875e59ac02
--- /dev/null
+++ b/Documentation/kdbus/kdbus.bus.xml
@@ -0,0 +1,360 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.bus">
+
+ <refentryinfo>
+ <title>kdbus.bus</title>
+ <productname>kdbus.bus</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.bus</refname>
+ <refpurpose>kdbus bus</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A bus is a resource that is shared between connections in order to
+ transmit messages (see
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ).
+ Each bus is independent, and operations on the bus will not have any
+ effect on other buses. A bus is a management entity that controls the
+ addresses of its connections, their policies and message transactions
+ performed via this bus.
+ </para>
+ <para>
+ Each bus is bound to the mount instance it was created on. It has a
+ custom name that is unique across all buses of a domain. In
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ , a bus is presented as a directory. No operations can be performed on
+ the bus itself; instead you need to perform the operations on an endpoint
+ associated with the bus. Endpoints are accessible as files underneath the
+ bus directory. A default endpoint called <constant>bus</constant> is
+ provided on each bus.
+ </para>
+ <para>
+ Bus names may be chosen freely except for one restriction: the name must
+ be prefixed with the numeric effective UID of the creator and a dash. This
+ is required to avoid namespace clashes between different users. When
+ creating a bus, the name that is passed in must be properly formatted, or
+ the kernel will refuse creation of the bus. Example:
+ <literal>1047-foobar</literal> is an acceptable name for a bus
+ registered by a user with UID 1047. However,
+ <literal>1024-foobar</literal> is not, and neither is
+ <literal>foobar</literal>. The UID must be provided in the
+ user-namespace of the bus owner.
+ </para>
+ <para>
+ To create a new bus, you need to open the control file of a domain and
+ employ the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl. The control
+ file descriptor that was used to issue
+ <constant>KDBUS_CMD_BUS_MAKE</constant> must not previously have been
+ used for any other control-ioctl and must be kept open for the entire
+ life-time of the created bus. Closing it will immediately cleanup the
+ entire bus and all its associated resources and endpoints. Every control
+ file descriptor can only be used to create a single new bus; from that
+ point on, it is not used for any further communication until the final
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ .
+ </para>
+ <para>
+ Each bus will generate a random, 128-bit UUID upon creation. This UUID
+ will be returned to creators of connections through
+ <varname>kdbus_cmd_hello.id128</varname> and can be used to uniquely
+ identify buses, even across different machines or containers. The UUID
+ will have its variant bits set to <literal>DCE</literal>, and denote
+ version 4 (random). For more details on UUIDs, see <ulink
+ url="https://en.wikipedia.org/wiki/Universally_unique_identifier">
+ the Wikipedia article on UUIDs</ulink>.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Creating buses</title>
+ <para>
+ To create a new bus, the <constant>KDBUS_CMD_BUS_MAKE</constant>
+ command is used. It takes a <type>struct kdbus_cmd</type> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>The flags for creation.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
+ <listitem>
+ <para>Make the bus file group-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
+ <listitem>
+ <para>Make the bus file world-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items (see
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ) are expected for <constant>KDBUS_CMD_BUS_MAKE</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
+ <listitem>
+ <para>
+ Contains a null-terminated string that identifies the
+ bus. The name must be unique across the kdbus domain and
+ must start with the effective UID of the caller, followed by
+ a '<literal>-</literal>' (dash). This item is mandatory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
+ <listitem>
+ <para>
+ Bus-wide bloom parameters passed in a
+ <type>struct kdbus_bloom_parameter</type>. These settings are
+ copied back to new connections verbatim. This item is
+ mandatory. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a more detailed description of this item.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
+ <listitem>
+ <para>
+ An optional item that contains a set of required attach flags
+ that connections must allow. This item is used as a
+ negotiation measure during connection creation. If connections
+ do not satisfy the bus requirements, they are not allowed on
+ the bus. If not set, the bus does not require any metadata to
+ be attached; in this case connections are free to set their
+ own attach flags.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
+ <listitem>
+ <para>
+ An optional item that contains a set of attach flags that are
+ returned to connections when they query the bus creator
+ metadata. If not set, no metadata is returned.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_BUS_MAKE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EBADMSG</constant></term>
+ <listitem><para>
+ A mandatory item is missing.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in the <constant>struct kdbus_cmd</constant>
+ are invalid or the supplied name does not start with the current
+ UID and a '<literal>-</literal>' (dash).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ A bus of that name already exists.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESHUTDOWN</constant></term>
+ <listitem><para>
+ The kdbus mount instance for the bus was already shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ The maximum number of buses for the current user is exhausted.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.connection.xml b/Documentation/kdbus/kdbus.connection.xml
new file mode 100644
index 000000000000..09852125b2d4
--- /dev/null
+++ b/Documentation/kdbus/kdbus.connection.xml
@@ -0,0 +1,1252 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.connection">
+
+ <refentryinfo>
+ <title>kdbus.connection</title>
+ <productname>kdbus.connection</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.connection</refname>
+ <refpurpose>kdbus connection</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Connections are identified by their <emphasis>connection ID</emphasis>,
+ internally implemented as a <type>uint64_t</type> counter.
+ The IDs of every newly created bus start at <constant>1</constant>, and
+ every new connection will increment the counter by <constant>1</constant>.
+ The IDs are not reused.
+ </para>
+ <para>
+ In higher level tools, the user visible representation of a connection is
+ defined by the D-Bus protocol specification as
+ <constant>":1.<ID>"</constant>.
+ </para>
+ <para>
+ Messages with a specific <type>uint64_t</type> destination ID are
+ directly delivered to the connection with the corresponding ID. Signal
+ messages (see
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>)
+ may be addressed to the special destination ID
+ <constant>KDBUS_DST_ID_BROADCAST</constant> (~0ULL) and will then
+ potentially be delivered to all currently active connections on the bus.
+ However, in order to receive any signal messages, clients must subscribe
+ to them by installing a match (see
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ).
+ </para>
+ <para>
+ Messages synthesized and sent directly by the kernel will carry the
+ special source ID <constant>KDBUS_SRC_ID_KERNEL</constant> (0).
+ </para>
+ <para>
+ In addition to the unique <type>uint64_t</type> connection ID,
+ established connections can request the ownership of
+ <emphasis>well-known names</emphasis>, under which they can be found and
+ addressed by other bus clients. A well-known name is associated with one
+ and only one connection at a time. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ on name acquisition, the name registry, and the validity of names.
+ </para>
+ <para>
+ Messages can specify the special destination ID
+ <constant>KDBUS_DST_ID_NAME</constant> (0) and carry a well-known name
+ in the message data. Such a message is delivered to the destination
+ connection which owns that well-known name.
+ </para>
+
+ <programlisting><![CDATA[
+ +-------------------------------------------------------------------------+
+ | +---------------+ +---------------------------+ |
+ | | Connection | | Message | -----------------+ |
+ | | :1.22 | --> | src: 22 | | |
+ | | | | dst: 25 | | |
+ | | | | | | |
+ | | | | | | |
+ | | | +---------------------------+ | |
+ | | | | |
+ | | | <--------------------------------------+ | |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ +---------------------------+ | | |
+ | | Connection | | Message | -----+ | |
+ | | :1.25 | --> | src: 25 | | |
+ | | | | dst: 0xffffffffffffffff | -------------+ | |
+ | | | | (KDBUS_DST_ID_BROADCAST) | | | |
+ | | | | | ---------+ | | |
+ | | | +---------------------------+ | | | |
+ | | | | | | |
+ | | | <--------------------------------------------------+ |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ +---------------------------+ | | |
+ | | Connection | | Message | --+ | | |
+ | | :1.55 | --> | src: 55 | | | | |
+ | | | | dst: 0 / org.foo.bar | | | | |
+ | | | | | | | | |
+ | | | | | | | | |
+ | | | +---------------------------+ | | | |
+ | | | | | | |
+ | | | <------------------------------------------+ | |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ | | |
+ | | Connection | | | |
+ | | :1.81 | | | |
+ | | org.foo.bar | | | |
+ | | | | | |
+ | | | | | |
+ | | | <-----------------------------------+ | |
+ | | | | |
+ | | | <----------------------------------------------+ |
+ | +---------------+ |
+ +-------------------------------------------------------------------------+
+ ]]></programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Privileged connections</title>
+ <para>
+ A connection is considered <emphasis>privileged</emphasis> if the user
+ it was created by is the same that created the bus, or if the creating
+ task had <constant>CAP_IPC_OWNER</constant> set when it called
+ <constant>KDBUS_CMD_HELLO</constant> (see below).
+ </para>
+ <para>
+ Privileged connections have permission to employ certain restricted
+ functions and commands, which are explained below and in other kdbus
+ man-pages.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Activator and policy holder connection</title>
+ <para>
+ An <emphasis>activator</emphasis> connection is a placeholder for a
+ <emphasis>well-known name</emphasis>. Messages sent to such a connection
+ can be used to start an implementer connection, which will then get all
+ the messages from the activator copied over. An activator connection
+ cannot be used to send any message.
+ </para>
+ <para>
+ A <emphasis>policy holder</emphasis> connection only installs a policy
+ for one or more names. These policy entries are kept active as long as
+ the connection is alive, and are removed once it terminates. Such a
+ policy connection type can be used to deploy restrictions for names that
+ are not yet active on the bus. A policy holder connection cannot be used
+ to send any message.
+ </para>
+ <para>
+ The creation of activator or policy holder connections is restricted to
+ privileged users on the bus (see above).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Monitor connections</title>
+ <para>
+ Monitors are eavesdropping connections that receive all the traffic on the
+ bus, but is invisible to other connections. Such connections have all
+ properties of any other, regular connection, except for the following
+ details:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ They will get every message sent over the bus, both unicasts and
+ broadcasts.
+ </para></listitem>
+
+ <listitem><para>
+ Installing matches for signal messages is neither necessary
+ nor allowed.
+ </para></listitem>
+
+ <listitem><para>
+ They cannot send messages or be directly addressed as receiver.
+ </para></listitem>
+
+ <listitem><para>
+ They cannot own well-known names. Therefore, they also can't operate as
+ activators.
+ </para></listitem>
+
+ <listitem><para>
+ Their creation and destruction will not cause
+ <constant>KDBUS_ITEM_ID_{ADD,REMOVE}</constant> (see
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>).
+ </para></listitem>
+
+ <listitem><para>
+ They are not listed with their unique name in name registry dumps
+ (see <constant>KDBUS_CMD_NAME_LIST</constant> in
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>), so other connections cannot detect the presence of
+ a monitor.
+ </para></listitem>
+ </itemizedlist>
+ <para>
+ The creation of monitor connections is restricted to privileged users on
+ the bus (see above).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Creating connections</title>
+ <para>
+ A connection to a bus is created by opening an endpoint file (see
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>)
+ of a bus and becoming an active client with the
+ <constant>KDBUS_CMD_HELLO</constant> ioctl. Every connection has a unique
+ identifier on the bus and can address messages to every other connection
+ on the same bus by using the peer's connection ID as the destination.
+ </para>
+ <para>
+ The <constant>KDBUS_CMD_HELLO</constant> ioctl takes a <type>struct
+ kdbus_cmd_hello</type> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_hello {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 attach_flags_send;
+ __u64 attach_flags_recv;
+ __u64 bus_flags;
+ __u64 id;
+ __u64 pool_size;
+ __u64 offset;
+ __u8 id128[16];
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem>
+ <para>Flags to apply to this connection</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_ACCEPT_FD</constant></term>
+ <listitem>
+ <para>
+ When this flag is set, the connection can be sent file
+ descriptors as message payload of unicast messages. If it's
+ not set, an attempt to send file descriptors will result in
+ <constant>-ECOMM</constant> on the sender's side.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_ACTIVATOR</constant></term>
+ <listitem>
+ <para>
+ Make this connection an activator (see above). With this bit
+ set, an item of type <constant>KDBUS_ITEM_NAME</constant> has
+ to be attached. This item describes the well-known name this
+ connection should be an activator for.
+ A connection can not be an activator and a policy holder at
+ the same time time, so this bit is not allowed together with
+ <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_POLICY_HOLDER</constant></term>
+ <listitem>
+ <para>
+ Make this connection a policy holder (see above). With this
+ bit set, an item of type <constant>KDBUS_ITEM_NAME</constant>
+ has to be attached. This item describes the well-known name
+ this connection should hold a policy for.
+ A connection can not be an activator and a policy holder at
+ the same time time, so this bit is not allowed together with
+ <constant>KDBUS_HELLO_ACTIVATOR</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_HELLO_MONITOR</constant></term>
+ <listitem>
+ <para>
+ Make this connection a monitor connection (see above).
+ </para>
+ <para>
+ This flag can only be set by privileged bus connections. See
+ below for more information.
+ A connection can not be monitor and an activator or a policy
+ holder at the same time time, so this bit is not allowed
+ together with <constant>KDBUS_HELLO_ACTIVATOR</constant> or
+ <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>attach_flags_send</varname></term>
+ <listitem><para>
+ Set the bits for metadata this connection permits to be sent to the
+ receiving peer. Only metadata items that are both allowed to be sent
+ by the sender and that are requested by the receiver will be attached
+ to the message. Note, however, that the bus may optionally require
+ some of those bits to be set. If the match fails, the ioctl will fail
+ with <varname>errno</varname> set to
+ <constant>ECONNREFUSED</constant>. In either case, when returning the
+ field will be set to the mask of metadata items that are enforced by
+ the bus with the <constant>KDBUS_FLAGS_KERNEL</constant> bit set as
+ well.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>attach_flags_recv</varname></term>
+ <listitem><para>
+ Request the attachment of metadata for each message received by this
+ connection. See
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for information about metadata, and
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ regarding items in general.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>bus_flags</varname></term>
+ <listitem><para>
+ Upon successful completion of the ioctl, this member will contain the
+ flags of the bus it connected to.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ Upon successful completion of the command, this member will contain
+ the numerical ID of the new connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>pool_size</varname></term>
+ <listitem><para>
+ The size of the communication pool, in bytes. The pool can be
+ accessed by calling
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on the file descriptor that was used to issue the
+ <constant>KDBUS_CMD_HELLO</constant> ioctl.
+ The pool size of a connection must be greater than
+ <constant>0</constant> and a multiple of
+ <constant>PAGE_SIZE</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ The kernel will return the offset in the pool where returned details
+ will be stored. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id128</varname></term>
+ <listitem><para>
+ Upon successful completion of the ioctl, this member will contain the
+ <emphasis>128-bit UUID</emphasis> of the connected bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Variable list of items containing optional additional information.
+ The following items are currently expected/valid:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
+ <listitem>
+ <para>
+ Contains a string that describes this connection, so it can
+ be identified later.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ For activators and policy holders only, combinations of
+ these two items describe policy access entries. See
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CREDS</constant></term>
+ <term><constant>KDBUS_ITEM_PIDS</constant></term>
+ <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
+ <listitem>
+ <para>
+ Privileged bus users may submit these types in order to
+ create connections with faked credentials. This information
+ will be returned when peer information is queried by
+ <constant>KDBUS_CMD_CONN_INFO</constant>. See below for more
+ information on retrieving information on connections.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ At the offset returned in the <varname>offset</varname> field of
+ <type>struct kdbus_cmd_hello</type>, the kernel will store items
+ of the following types:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
+ <listitem>
+ <para>
+ Bloom filter parameter as defined by the bus creator.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The offset in the pool has to be freed with the
+ <constant>KDBUS_CMD_FREE</constant> ioctl. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Retrieving information on a connection</title>
+ <para>
+ The <constant>KDBUS_CMD_CONN_INFO</constant> ioctl can be used to
+ retrieve credentials and properties of the initial creator of a
+ connection. This ioctl uses the following struct.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_info {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 id;
+ __u64 attach_flags;
+ __u64 offset;
+ __u64 info_size;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently, no flags are supported.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The numerical ID of the connection for which information is to be
+ retrieved. If set to a non-zero value, the
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> item is ignored.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Specifies which metadata items should be attached to the answer. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ When the ioctl returns, this field will contain the offset of the
+ connection information inside the caller's pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>info_size</varname></term>
+ <listitem><para>
+ The kernel will return the size of the returned information, so
+ applications can optionally
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ specific parts of the pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <constant>KDBUS_CMD_CONN_INFO</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
+ <listitem>
+ <para>
+ Contains the well-known name of the connection to look up as.
+ This item is mandatory if the <varname>id</varname> field is
+ set to 0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ When the ioctl returns, the following struct will be stored in the
+ caller's pool at <varname>offset</varname>. The fields in this struct
+ are described below.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The connection's unique ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The connection's flags as specified when it was created.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Depending on the <varname>flags</varname> field in
+ <type>struct kdbus_cmd_info</type>, items of types
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> and
+ <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant> may follow here.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> is also allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Once the caller is finished with parsing the return buffer, it needs to
+ employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
+ order to free the buffer part. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Getting information about a connection's bus creator</title>
+ <para>
+ The <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> ioctl takes the same
+ struct as <constant>KDBUS_CMD_CONN_INFO</constant>, but is used to
+ retrieve information about the creator of the bus the connection is
+ attached to. The metadata returned by this call is collected during the
+ creation of the bus and is never altered afterwards, so it provides
+ pristine information on the task that created the bus, at the moment when
+ it did so.
+ </para>
+ <para>
+ In response to this call, a slice in the connection's pool is allocated
+ and filled with an object of type <type>struct kdbus_info</type>,
+ pointed to by the ioctl's <varname>offset</varname> field.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The bus ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The bus flags as specified when it was created.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Metadata information is stored in items here. The item list
+ contains a <constant>KDBUS_ITEM_MAKE_NAME</constant> item that
+ indicates the bus name of the calling connection.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed to probe
+ for known item types.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Once the caller is finished with parsing the return buffer, it needs to
+ employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
+ order to free the buffer part. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Updating connection details</title>
+ <para>
+ Some of a connection's details can be updated with the
+ <constant>KDBUS_CMD_CONN_UPDATE</constant> ioctl, using the file
+ descriptor that was used to create the connection. The update command
+ uses the following struct.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently, no flags are supported.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to describe the connection details to be updated. The
+ following item types are supported.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
+ <listitem>
+ <para>
+ Supply a new set of metadata items that this connection
+ permits to be sent along with messages.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
+ <listitem>
+ <para>
+ Supply a new set of metadata items that this connection
+ requests to be attached to each message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ Policy holder connections may supply a new set of policy
+ information with these items. For other connection types,
+ <constant>EOPNOTSUPP</constant> is returned in
+ <varname>errno</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Termination of connections</title>
+ <para>
+ A connection can be terminated by simply calling
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on its file descriptor. All pending incoming messages will be discarded,
+ and the memory allocated by the pool will be freed.
+ </para>
+
+ <para>
+ An alternative way of closing down a connection is via the
+ <constant>KDBUS_CMD_BYEBYE</constant> ioctl. This ioctl will succeed only
+ if the message queue of the connection is empty at the time of closing;
+ otherwise, the ioctl will fail with <varname>errno</varname> set to
+ <constant>EBUSY</constant>. When this ioctl returns
+ successfully, the connection has been terminated and won't accept any new
+ messages from remote peers. This way, a connection can be terminated
+ race-free, without losing any messages. The ioctl takes an argument of
+ type <type>struct kdbus_cmd</type>.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently, no flags are supported.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will fail with
+ <varname>errno</varname> set to <constant>EPROTO</constant>, and
+ the <varname>flags</varname> field is set to <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to describe the connection details to be updated. The
+ following item types are supported.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_HELLO</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EFAULT</constant></term>
+ <listitem><para>
+ The supplied pool size was 0 or not a multiple of the page size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in <type>struct kdbus_cmd_hello</type>
+ are invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ An illegal combination of
+ <constant>KDBUS_HELLO_MONITOR</constant>,
+ <constant>KDBUS_HELLO_ACTIVATOR</constant> and
+ <constant>KDBUS_HELLO_POLICY_HOLDER</constant> was passed in
+ <varname>flags</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ An invalid set of items was supplied.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECONNREFUSED</constant></term>
+ <listitem><para>
+ The attach_flags_send field did not satisfy the requirements of
+ the bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPERM</constant></term>
+ <listitem><para>
+ A <constant>KDBUS_ITEM_CREDS</constant> items was supplied, but the
+ current user is not privileged.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESHUTDOWN</constant></term>
+ <listitem><para>
+ The bus you were trying to connect to has already been shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ The maximum number of connections on the bus has been reached.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The endpoint does not support the connection flags supplied in
+ <type>struct kdbus_cmd_hello</type>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_BYEBYE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EALREADY</constant></term>
+ <listitem><para>
+ The connection has already been shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBUSY</constant></term>
+ <listitem><para>
+ There are still messages queued up in the connection's pool.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_CONN_INFO</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid flags, or neither an ID nor a name was provided, or the
+ name is invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ Connection lookup by name failed.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENXIO</constant></term>
+ <listitem><para>
+ No connection with the provided connection ID found.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_CONN_UPDATE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal flags or items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Wildcards submitted in policy entries, or illegal sequence
+ of policy items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ Operation not supported by connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ Too many policy items attached.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.endpoint.xml b/Documentation/kdbus/kdbus.endpoint.xml
new file mode 100644
index 000000000000..76e325d4e931
--- /dev/null
+++ b/Documentation/kdbus/kdbus.endpoint.xml
@@ -0,0 +1,436 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.endpoint">
+
+ <refentryinfo>
+ <title>kdbus.endpoint</title>
+ <productname>kdbus.endpoint</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.endpoint</refname>
+ <refpurpose>kdbus endpoint</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Endpoints are entry points to a bus (see
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>).
+ By default, each bus has a default
+ endpoint called 'bus'. The bus owner has the ability to create custom
+ endpoints with specific names, permissions, and policy databases
+ (see below). An endpoint is presented as file underneath the directory
+ of the parent bus.
+ </para>
+ <para>
+ To create a custom endpoint, open the default endpoint
+ (<literal>bus</literal>) and use the
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> ioctl with
+ <type>struct kdbus_cmd</type>. Custom endpoints always have a policy
+ database that, by default, forbids any operation. You have to explicitly
+ install policy entries to allow any operation on this endpoint.
+ </para>
+ <para>
+ Once <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> succeeded, the new
+ endpoint will appear in the filesystem
+ (<citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>), and the used file descriptor will manage the
+ newly created endpoint resource. It cannot be used to manage further
+ resources and must be kept open as long as the endpoint is needed. The
+ endpoint will be terminated as soon as the file descriptor is closed.
+ </para>
+ <para>
+ Endpoint names may be chosen freely except for one restriction: the name
+ must be prefixed with the numeric effective UID of the creator and a dash.
+ This is required to avoid namespace clashes between different users. When
+ creating an endpoint, the name that is passed in must be properly
+ formatted or the kernel will refuse creation of the endpoint. Example:
+ <literal>1047-my-endpoint</literal> is an acceptable name for an
+ endpoint registered by a user with UID 1047. However,
+ <literal>1024-my-endpoint</literal> is not, and neither is
+ <literal>my-endpoint</literal>. The UID must be provided in the
+ user-namespace of the bus.
+ </para>
+ <para>
+ To create connections to a bus, use <constant>KDBUS_CMD_HELLO</constant>
+ on a file descriptor returned by <function>open()</function> on an
+ endpoint node. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Creating custom endpoints</title>
+ <para>
+ To create a new endpoint, the
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> command is used. Along with
+ the endpoint's name, which will be used to expose the endpoint in the
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
+ the command also optionally takes items to set up the endpoint's
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> takes a
+ <type>struct kdbus_cmd</type> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>The flags for creation.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
+ <listitem>
+ <para>Make the endpoint file group-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
+ <listitem>
+ <para>Make the endpoint file world-accessible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
+ <listitem>
+ <para>Contains a string to identify the endpoint name.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ These items are used to set the policy attached to the
+ endpoint. For more details on bus and endpoint policies, see
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <varname>EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Updating endpoints</title>
+ <para>
+ To update an existing endpoint, the
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> command is used on the file
+ descriptor that was used to create the update, using
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. The only relevant detail of
+ the endpoint that can be updated is the policy. When the command is
+ employed, the policy of the endpoint is <emphasis>replaced</emphasis>
+ atomically with the new set of rules.
+ The command takes a <type>struct kdbus_cmd</type> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Unused for this command.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem>
+ <para>
+ These items are used to set the policy attached to the
+ endpoint. For more details on bus and endpoint policies, see
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ Existing policy is atomically replaced with the new rules
+ provided.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> may fail with the
+ following errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in the <type>struct kdbus_cmd</type>
+ are invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ An endpoint of that name already exists.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPERM</constant></term>
+ <listitem><para>
+ The calling user is not privileged. See
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for information about privileged users.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the
+ following errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The flags supplied in <type>struct kdbus_cmd</type>
+ are invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ An endpoint of that name already exists.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.fs.xml b/Documentation/kdbus/kdbus.fs.xml
new file mode 100644
index 000000000000..8c2a90e10b66
--- /dev/null
+++ b/Documentation/kdbus/kdbus.fs.xml
@@ -0,0 +1,124 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus_fs">
+
+ <refentryinfo>
+ <title>kdbus.fs</title>
+ <productname>kdbus.fs</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.fs</refname>
+ <refpurpose>kdbus file system</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>File-system Layout</title>
+
+ <para>
+ The <emphasis>kdbusfs</emphasis> pseudo filesystem provides access to
+ kdbus entities, such as <emphasis>buses</emphasis> and
+ <emphasis>endpoints</emphasis>. Each time the filesystem is mounted,
+ a new, isolated kdbus instance is created, which is independent from the
+ other instances.
+ </para>
+ <para>
+ The system-wide standard mount point for <emphasis>kdbusfs</emphasis> is
+ <constant>/sys/fs/kdbus</constant>.
+ </para>
+
+ <para>
+ Buses are represented as directories in the file system layout, whereas
+ endpoints are exposed as files inside these directories. At the top-level,
+ a <emphasis>control</emphasis> node is present, which can be opened to
+ create new buses via the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl.
+ Each <emphasis>bus</emphasis> shows a default endpoint called
+ <varname>bus</varname>, which can be opened to either create a connection
+ with the <constant>KDBUS_CMD_HELLO</constant> ioctl, or to create new
+ custom endpoints for the bus with
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+
+ <para>Following, you can see an example layout of the
+ <emphasis>kdbusfs</emphasis> filesystem:</para>
+
+<programlisting>
+ /sys/fs/kdbus/ ; mount-point
+ |-- 0-system ; bus directory
+ | |-- bus ; default endpoint
+ | `-- 1017-custom ; custom endpoint
+ |-- 1000-user ; bus directory
+ | |-- bus ; default endpoint
+ | |-- 1000-service-A ; custom endpoint
+ | `-- 1000-service-B ; custom endpoint
+ `-- control ; control file
+</programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Mounting instances</title>
+ <para>
+ In order to get a new and separate kdbus environment, a new instance
+ of <emphasis>kdbusfs</emphasis> can be mounted like this:
+ </para>
+<programlisting>
+ # mount -t kdbusfs kdbusfs /tmp/new_kdbus/
+</programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>mount</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.item.xml b/Documentation/kdbus/kdbus.item.xml
new file mode 100644
index 000000000000..bfe47362097f
--- /dev/null
+++ b/Documentation/kdbus/kdbus.item.xml
@@ -0,0 +1,840 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus">
+
+ <refentryinfo>
+ <title>kdbus.item</title>
+ <productname>kdbus item</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.item</refname>
+ <refpurpose>kdbus item structure, layout and usage</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ To flexibly augment transport structures, data blobs of type
+ <type>struct kdbus_item</type> can be attached to the structs passed
+ into the ioctls. Some ioctls make items of certain types mandatory,
+ others are optional. Items that are unsupported by ioctls they are
+ attached to will cause the ioctl to fail with <varname>errno</varname>
+ set to <constant>EINVAL</constant>.
+ Items are also used for information stored in a connection's
+ <emphasis>pool</emphasis>, such as received messages, name lists or
+ requested connection or bus owner information. Depending on the type of
+ an item, its total size is either fixed or variable.
+ </para>
+
+ <refsect2>
+ <title>Chaining items</title>
+ <para>
+ Whenever items are used as part of the kdbus kernel API, they are
+ embedded in structs that are embedded inside structs that themselves
+ include a size field containing the overall size of the structure.
+ This allows multiple items to be chained up, and an item iterator
+ (see below) is capable of detecting the end of an item chain.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Alignment</title>
+ <para>
+ The kernel expects all items to be aligned to 8-byte boundaries.
+ Unaligned items will cause the ioctl they are used with to fail
+ with <varname>errno</varname> set to <constant>EINVAL</constant>.
+ An item that has an unaligned size itself hence needs to be padded
+ if it is followed by another item.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Iterating items</title>
+ <para>
+ A simple iterator would iterate over the items until the items have
+ reached the embedding structure's overall size. An example
+ implementation is shown below.
+ </para>
+
+ <programlisting><![CDATA[
+#define KDBUS_ALIGN8(val) (((val) + 7) & ~7)
+
+#define KDBUS_ITEM_NEXT(item) \
+ (typeof(item))(((uint8_t *)item) + KDBUS_ALIGN8((item)->size))
+
+#define KDBUS_ITEM_FOREACH(item, head, first) \
+ for (item = (head)->first; \
+ ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \
+ ((uint8_t *)(item) >= (uint8_t *)(head)); \
+ item = KDBUS_ITEM_NEXT(item))
+ ]]></programlisting>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Item layout</title>
+ <para>
+ A <type>struct kdbus_item</type> consists of a
+ <varname>size</varname> field, describing its overall size, and a
+ <varname>type</varname> field, both 64 bit wide. They are followed by
+ a union to store information that is specific to the item's type.
+ The struct layout is shown below.
+ </para>
+
+ <programlisting>
+struct kdbus_item {
+ __u64 size;
+ __u64 type;
+ /* item payload - see below */
+ union {
+ __u8 data[0];
+ __u32 data32[0];
+ __u64 data64[0];
+ char str[0];
+
+ __u64 id;
+ struct kdbus_vec vec;
+ struct kdbus_creds creds;
+ struct kdbus_pids pids;
+ struct kdbus_audit audit;
+ struct kdbus_caps caps;
+ struct kdbus_timestamp timestamp;
+ struct kdbus_name name;
+ struct kdbus_bloom_parameter bloom_parameter;
+ struct kdbus_bloom_filter bloom_filter;
+ struct kdbus_memfd memfd;
+ int fds[0];
+ struct kdbus_notify_name_change name_change;
+ struct kdbus_notify_id_change id_change;
+ struct kdbus_policy_access policy_access;
+ };
+};
+ </programlisting>
+
+ <para>
+ <type>struct kdbus_item</type> should never be used to allocate
+ an item instance, as its size may grow in future releases of the API.
+ Instead, it should be manually assembled by storing the
+ <varname>size</varname>, <varname>type</varname> and payload to a
+ struct of its own.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Item types</title>
+
+ <refsect2>
+ <title>Negotiation item</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item is attached to any ioctl, programs can
+ <emphasis>probe</emphasis> the kernel for known item items.
+ The item carries an array of <type>uint64_t</type> values in
+ <varname>item.data64</varname>, each set to an item type to
+ probe. The kernel will reset each member of this array that is
+ not recognized as valid item type to <constant>0</constant>.
+ This way, users can negotiate kernel features at start-up to
+ keep newer userspace compatible with older kernels. This item
+ is never attached by the kernel in response to any command.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Command specific items</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
+ <listitem><para>
+ Messages are directly copied by the sending process into the
+ receiver's
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ This way, two peers can exchange data by effectively doing a
+ single-copy from one process to another; the kernel will not buffer
+ the data anywhere else. <constant>KDBUS_ITEM_PAYLOAD_VEC</constant>
+ is used when <emphasis>sending</emphasis> message. The item
+ references a memory address when the payload data can be found.
+ <constant>KDBUS_ITEM_PAYLOAD_OFF</constant> is used when messages
+ are <emphasis>received</emphasis>, and the
+ <constant>offset</constant> value describes the offset inside the
+ receiving connection's
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ where the message payload can be found. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on passing of payload data along with a
+ message.
+ <programlisting>
+struct kdbus_vec {
+ __u64 size;
+ union {
+ __u64 address;
+ __u64 offset;
+ };
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <listitem><para>
+ Transports a file descriptor of a <emphasis>memfd</emphasis> in
+ <type>struct kdbus_memfd</type> in <varname>item.memfd</varname>.
+ The <varname>size</varname> field has to match the actual size of
+ the memfd that was specified when it was created. The
+ <varname>start</varname> parameter denotes the offset inside the
+ memfd at which the referenced payload starts. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on passing of payload data along with a
+ message.
+ <programlisting>
+struct kdbus_memfd {
+ __u64 start;
+ __u64 size;
+ int fd;
+ __u32 __pad;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem><para>
+ Contains an array of <emphasis>file descriptors</emphasis>.
+ When used with <constant>KDBUS_CMD_SEND</constant>, the values of
+ this array must be filled with valid file descriptor numbers.
+ When received as item attached to a message, the array will
+ contain the numbers of the installed file descriptors, or
+ <constant>-1</constant> in case an error occurred.
+ file descriptor.
+ In either case, the number of entries in the array is derived from
+ the item's total size. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Items specific to some commands</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
+ <listitem><para>
+ Transports a file descriptor that can be used to cancel a
+ synchronous <constant>KDBUS_CMD_SEND</constant> operation by
+ writing to it. The file descriptor is stored in
+ <varname>item.fd[0]</varname>. The item may only contain one
+ file descriptor. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on this item and how to use it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>bloom parameters</emphasis> as
+ <type>struct kdbus_bloom_parameter</type> in
+ <varname>item.bloom_parameter</varname>.
+ The item is passed from userspace to kernel during the
+ <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl, and returned
+ verbatim when <constant>KDBUS_CMD_HELLO</constant> is called.
+ The kernel does not use the bloom parameters, but they need to
+ be known by each connection on the bus in order to define the
+ bloom filter hash details. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ <programlisting>
+struct kdbus_bloom_parameter {
+ __u64 size;
+ __u64 n_hash;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
+ <listitem><para>
+ Carries a <emphasis>bloom filter</emphasis> as
+ <type>struct kdbus_bloom_filter</type> in
+ <varname>item.bloom_filter</varname>. It is mandatory to send this
+ item attached to a <type>struct kdbus_msg</type>, in case the
+ message is a signal. This item is never transported from kernel to
+ userspace. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ <programlisting>
+struct kdbus_bloom_filter {
+ __u64 generation;
+ __u64 data[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
+ <listitem><para>
+ Transports a <emphasis>bloom mask</emphasis> as binary data blob
+ stored in <varname>item.data</varname>. This item is used to
+ describe a match into a connection's match database. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>well-known name</emphasis> to send a
+ message to, as null-terminated string in
+ <varname>item.str</varname>. This item is used with
+ <constant>KDBUS_CMD_SEND</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on how to send a message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>bus name</emphasis> or
+ <emphasis>endpoint name</emphasis>, stored as null-terminated
+ string in <varname>item.str</varname>. This item is sent from
+ userspace to kernel when buses or endpoints are created, and
+ returned back to userspace when the bus creator information is
+ queried. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>attach flags</emphasis> at
+ <emphasis>send</emphasis> or <emphasis>receive</emphasis> time. See
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on attach flags.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID</constant></term>
+ <listitem><para>
+ Transports a connection's <emphasis>numerical ID</emphasis> of
+ a connection as <type>uint64_t</type> value in
+ <varname>item.id</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <listitem><para>
+ Transports a name associated with the
+ <emphasis>name registry</emphasis> as null-terminated string as
+ <type>struct kdbus_name</type> in
+ <varname>item.name</varname>. The <varname>flags</varname>
+ contains the flags of the name. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on how to access the name registry of a bus.
+ <programlisting>
+struct kdbus_name {
+ __u64 flags;
+ char name[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Items attached by the kernel as metadata</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_TIMESTAMP</constant></term>
+ <listitem><para>
+ Contains both the <emphasis>monotonic</emphasis> and the
+ <emphasis>realtime</emphasis> timestamp, taken when the message
+ was processed on the kernel side.
+ Stored as <type>struct kdbus_timestamp</type> in
+ <varname>item.timestamp</varname>.
+ <programlisting>
+struct kdbus_timestamp {
+ __u64 seqnum;
+ __u64 monotonic_ns;
+ __u64 realtime_ns;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CREDS</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>user</emphasis> and
+ <emphasis>group</emphasis> information as 32-bit values, in the
+ usual four flavors: real, effective, saved and filesystem related.
+ Stored as <type>struct kdbus_creds</type> in
+ <varname>item.creds</varname>.
+ <programlisting>
+struct kdbus_creds {
+ __u32 uid;
+ __u32 euid;
+ __u32 suid;
+ __u32 fsuid;
+ __u32 gid;
+ __u32 egid;
+ __u32 sgid;
+ __u32 fsgid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PIDS</constant></term>
+ <listitem><para>
+ Contains the <emphasis>PID</emphasis>, <emphasis>TID</emphasis>
+ and <emphasis>parent PID (PPID)</emphasis> of a remote peer.
+ Stored as <type>struct kdbus_pids</type> in
+ <varname>item.pids</varname>.
+ <programlisting>
+struct kdbus_pids {
+ __u64 pid;
+ __u64 tid;
+ __u64 ppid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_AUXGROUPS</constant></term>
+ <listitem><para>
+ Contains the <emphasis>auxiliary (supplementary) groups</emphasis>
+ a remote peer is a member of, stored as array of
+ <type>uint32_t</type> values in <varname>item.data32</varname>.
+ The array length can be determined by looking at the item's total
+ size, subtracting the size of the header and and dividing the
+ remainder by <constant>sizeof(uint32_t)</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>well-known name</emphasis> currently owned
+ by a connection. The name is stored as null-terminated string in
+ <varname>item.str</varname>. Its length can also be derived from
+ the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_TID_COMM</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>TID</emphasis> (thread ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PID_COMM</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>PID</emphasis> (process ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_EXE</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>path to the executable</emphasis> of a task,
+ stored as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size. Receivers of
+ this item should not use its contents for any kind of security
+ measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CMDLINE</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>command line arguments</emphasis> of a
+ task, stored as an <emphasis>array</emphasis> of null-terminated
+ strings in <varname>item.str</varname>. The total length of all
+ strings in the array can be derived from the item's total size.
+ Receivers of this item should not use its contents for any kind
+ of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CGROUP</constant></term>
+ <listitem><para>
+ Contains the <emphasis>cgroup path</emphasis> of a task, stored
+ as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CAPS</constant></term>
+ <listitem><para>
+ Contains sets of <emphasis>capabilities</emphasis>, stored as
+ <type>struct kdbus_caps</type> in <varname>item.caps</varname>.
+ As the item size may increase in the future, programs should be
+ written in a way that it takes
+ <varname>item.caps.last_cap</varname> into account, and derive
+ the number of sets and rows from the item size and the reported
+ number of valid capability bits.
+ <programlisting>
+struct kdbus_caps {
+ __u32 last_cap;
+ __u32 caps[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
+ <listitem><para>
+ Contains the <emphasis>LSM label</emphasis> of a task, stored as
+ null-terminated string in <varname>item.str</varname>. Its length
+ can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_AUDIT</constant></term>
+ <listitem><para>
+ Contains the audit <emphasis>sessionid</emphasis> and
+ <emphasis>loginuid</emphasis> of a task, stored as
+ <type>struct kdbus_audit</type> in
+ <varname>item.audit</varname>.
+ <programlisting>
+struct kdbus_audit {
+ __u32 sessionid;
+ __u32 loginuid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
+ <listitem><para>
+ Contains the <emphasis>connection description</emphasis>, as set
+ by <constant>KDBUS_CMD_HELLO</constant> or
+ <constant>KDBUS_CMD_CONN_UPDATE</constant>, stored as
+ null-terminated string in <varname>item.str</varname>. Its length
+ can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ All metadata is automatically translated into the
+ <emphasis>namespaces</emphasis> of the task that receives them. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+
+ <para>
+ [*] Note that the content stored in metadata items of type
+ <constant>KDBUS_ITEM_TID_COMM</constant>,
+ <constant>KDBUS_ITEM_PID_COMM</constant>,
+ <constant>KDBUS_ITEM_EXE</constant> and
+ <constant>KDBUS_ITEM_CMDLINE</constant>
+ can easily be tampered by the sending tasks. Therefore, they should
+ <emphasis>not</emphasis> be used for any sort of security relevant
+ assumptions. The only reason they are transmitted is to let
+ receivers know about details that were set when metadata was
+ collected, even though the task they were collected from is not
+ active any longer when the items are received.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Items used for policy entries, matches and notifications</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem><para>
+ This item describes a <emphasis>policy access</emphasis> entry to
+ access the policy database of a
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> or
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ Please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on the policy database and how to access it.
+ <programlisting>
+struct kdbus_policy_access {
+ __u64 type;
+ __u64 access;
+ __u64 id;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis> and indicates that a
+ new connection was created on the bus, or that a connection was
+ disconnected, respectively. It stores a
+ <type>struct kdbus_notify_id_change</type> in
+ <varname>item.id_change</varname>.
+ The <varname>id</varname> field contains the numeric ID of the
+ connection that was added or removed, and <varname>flags</varname>
+ is set to the connection flags, as passed by
+ <constant>KDBUS_CMD_HELLO</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matches and notification messages.
+ <programlisting>
+struct kdbus_notify_id_change {
+ __u64 id;
+ __u64 flags;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis> and indicates that a
+ <emphasis>well-known name</emphasis> appeared, disappeared or
+ transferred to another owner on the bus. It stores a
+ <type>struct kdbus_notify_name_change</type> in
+ <varname>item.name_change</varname>.
+ <varname>old_id</varname> describes the former owner of the name
+ and is set to <constant>0</constant> values in case of
+ <constant>KDBUS_ITEM_NAME_ADD</constant>.
+ <varname>new_id</varname> describes the new owner of the name and
+ is set to <constant>0</constant> values in case of
+ <constant>KDBUS_ITEM_NAME_REMOVE</constant>.
+ The <varname>name</varname> field contains the well-known name the
+ notification is about, as null-terminated string. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matches and notification messages.
+ <programlisting>
+struct kdbus_notify_name_change {
+ struct kdbus_notify_id_change old_id;
+ struct kdbus_notify_id_change new_id;
+ char name[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_REPLY_TIMEOUT</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis>. It informs the receiver
+ that an expected reply to a message was not received in time.
+ The remote peer ID and the message cookie is stored in the message
+ header. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about messages, timeouts and notifications.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_REPLY_DEAD</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis>. It informs the receiver
+ that a remote connection a reply is expected from was disconnected
+ before that reply was sent. The remote peer ID and the message
+ cookie is stored in the message header. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about messages, timeouts and notifications.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>memfd_create</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
diff --git a/Documentation/kdbus/kdbus.match.xml b/Documentation/kdbus/kdbus.match.xml
new file mode 100644
index 000000000000..ef77b64e5890
--- /dev/null
+++ b/Documentation/kdbus/kdbus.match.xml
@@ -0,0 +1,553 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.match">
+
+ <refentryinfo>
+ <title>kdbus.match</title>
+ <productname>kdbus.match</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.match</refname>
+ <refpurpose>kdbus match</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ kdbus connections can install matches in order to subscribe to signal
+ messages sent on the bus. Such signal messages can be either directed
+ to a single connection (by setting a specific connection ID in
+ <varname>struct kdbus_msg.dst_id</varname> or by sending it to a
+ well-known name), or to potentially <emphasis>all</emphasis> currently
+ active connections on the bus (by setting
+ <varname>struct kdbus_msg.dst_id</varname> to
+ <constant>KDBUS_DST_ID_BROADCAST</constant>).
+ A signal message always has the <constant>KDBUS_MSG_SIGNAL</constant>
+ bit set in the <varname>flags</varname> bitfield.
+ Also, signal messages can originate from either the kernel (called
+ <emphasis>notifications</emphasis>), or from other bus connections.
+ In either case, a bus connection needs to have a suitable
+ <emphasis>match</emphasis> installed in order to receive any signal
+ message. Without any rules installed in the connection, no signal message
+ will be received.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Matches for signal messages from other connections</title>
+ <para>
+ Matches for messages from other connections (not kernel notifications)
+ are implemented as bloom filters (see below). The sender adds certain
+ properties of the message as elements to a bloom filter bit field, and
+ sends that along with the signal message.
+
+ The receiving connection adds the message properties it is interested in
+ as elements to a bloom mask bit field, and uploads the mask as match rule,
+ possibly along with some other rules to further limit the match.
+
+ The kernel will match the signal message's bloom filter against the
+ connections bloom mask (simply by &-ing it), and will decide whether
+ the message should be delivered to a connection.
+ </para>
+ <para>
+ The kernel has no notion of any specific properties of the signal message,
+ all it sees are the bit fields of the bloom filter and the mask to match
+ against. The use of bloom filters allows simple and efficient matching,
+ without exposing any message properties or internals to the kernel side.
+ Clients need to deal with the fact that they might receive signal messages
+ which they did not subscribe to, as the bloom filter might allow
+ false-positives to pass the filter.
+
+ To allow the future extension of the set of elements in the bloom filter,
+ the filter specifies a <emphasis>generation</emphasis> number. A later
+ generation must always contain all elements of the set of the previous
+ generation, but can add new elements to the set. The match rules mask can
+ carry an array with all previous generations of masks individually stored.
+ When the filter and mask are matched by the kernel, the mask with the
+ closest matching generation is selected as the index into the mask array.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Bloom filters</title>
+ <para>
+ Bloom filters allow checking whether a given word is present in a
+ dictionary. This allows connections to set up a mask for information it
+ is interested in, and will be delivered signal messages that have a
+ matching filter.
+
+ For general information, see
+ <ulink url="https://en.wikipedia.org/wiki/Bloom_filter">the Wikipedia
+ article on bloom filters</ulink>.
+ </para>
+ <para>
+ The size of the bloom filter is defined per bus when it is created, in
+ <varname>kdbus_bloom_parameter.size</varname>. All bloom filters attached
+ to signal messages on the bus must match this size, and all bloom filter
+ matches uploaded by connections must also match the size, or a multiple
+ thereof (see below).
+
+ The calculation of the mask has to be done in userspace applications. The
+ kernel just checks the bitmasks to decide whether or not to let the
+ message pass. All bits in the mask must match the filter in and bit-wise
+ <emphasis>AND</emphasis> logic, but the mask may have more bits set than
+ the filter. Consequently, false positive matches are expected to happen,
+ and programs must deal with that fact by checking the contents of the
+ payload again at receive time.
+ </para>
+ <para>
+ Masks are entities that are always passed to the kernel as part of a
+ match (with an item of type <constant>KDBUS_ITEM_BLOOM_MASK</constant>),
+ and filters can be attached to signals, with an item of type
+ <constant>KDBUS_ITEM_BLOOM_FILTER</constant>. For a filter to match, all
+ its bits have to be set in the match mask as well.
+ </para>
+ <para>
+ For example, consider a bus that has a bloom size of 8 bytes, and the
+ following mask/filter combinations:
+ </para>
+ <programlisting><![CDATA[
+ filter 0x0101010101010101
+ mask 0x0101010101010101
+ -> matches
+
+ filter 0x0303030303030303
+ mask 0x0101010101010101
+ -> doesn't match
+
+ filter 0x0101010101010101
+ mask 0x0303030303030303
+ -> matches
+ ]]></programlisting>
+
+ <para>
+ Hence, in order to catch all messages, a mask filled with
+ <constant>0xff</constant> bytes can be installed as a wildcard match rule.
+ </para>
+
+ <refsect2>
+ <title>Generations</title>
+
+ <para>
+ Uploaded matches may contain multiple masks, which have are as large as
+ the bloom size defined by the bus. Each block of a mask is called a
+ <emphasis>generation</emphasis>, starting at index 0.
+
+ At match time, when a signal is about to be delivered, a bloom mask
+ generation is passed, which denotes which of the bloom masks the filter
+ should be matched against. This allows programs to provide backward
+ compatible masks at upload time, while older clients can still match
+ against older versions of filters.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Matches for kernel notifications</title>
+ <para>
+ To receive kernel generated notifications (see
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>),
+ a connection must install match rules that are different from
+ the bloom filter matches described in the section above. They can be
+ filtered by the connection ID that caused the notification to be sent, by
+ one of the names it currently owns, or by the type of the notification
+ (ID/name add/remove/change).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Adding a match</title>
+ <para>
+ To add a match, the <constant>KDBUS_CMD_MATCH_ADD</constant> ioctl is
+ used, which takes a struct of the struct described below.
+
+ Note that each of the items attached to this command will internally
+ create one match <emphasis>rule</emphasis>, and the collection of them,
+ which is submitted as one block via the ioctl, is called a
+ <emphasis>match</emphasis>. To allow a message to pass, all rules of a
+ match have to be satisfied. Hence, adding more items to the command will
+ only narrow the possibility of a match to effectively let the message
+ pass, and will decrease the chance that the connection's process will be
+ woken up needlessly.
+
+ Multiple matches can be installed per connection. As long as one of it has
+ a set of rules which allows the message to pass, this one will be
+ decisive.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_match {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 cookie;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to control the behavior of the ioctl.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MATCH_REPLACE</constant></term>
+ <listitem>
+ <para>Make the endpoint file group-accessible</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie</varname></term>
+ <listitem><para>
+ A cookie which identifies the match, so it can be referred to when
+ removing it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to define the actual rules of the matches. The following item
+ types are expected. Each item will create one new match rule.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
+ <listitem>
+ <para>
+ An item that carries the bloom filter mask to match against
+ in its data field. The payload size must match the bloom
+ filter size that was specified when the bus was created.
+ See the section below for more information on bloom filters.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <listitem>
+ <para>
+ When used as part of kernel notifications, this item specifies
+ a name that is acquired, lost or that changed its owner (see
+ below). When used as part of a match for user-generated signal
+ messages, it specifies a name that the sending connection must
+ own at the time of sending the signal.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID</constant></term>
+ <listitem>
+ <para>
+ Specify a sender connection's ID that will match this rule.
+ For kernel notifications, this specifies the ID of a
+ connection that was added to or removed from the bus.
+ For used-generated signals, it specifies the ID of the
+ connection that sent the signal message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
+ <listitem>
+ <para>
+ These items request delivery of kernel notifications that
+ describe a name acquisition, loss, or change. The details
+ are stored in the item's
+ <varname>kdbus_notify_name_change</varname> member.
+ All information specified must be matched in order to make
+ the message pass. Use
+ <constant>KDBUS_MATCH_ID_ANY</constant> to
+ match against any unique connection ID.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
+ <listitem>
+ <para>
+ These items request delivery of kernel notifications that are
+ generated when a connection is created or terminated.
+ <type>struct kdbus_notify_id_change</type> is used to
+ store the actual match information. This item can be used to
+ monitor one particular connection ID, or, when the ID field
+ is set to <constant>KDBUS_MATCH_ID_ANY</constant>,
+ all of them.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item, programs can <emphasis>probe</emphasis> the
+ kernel for known item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Refer to
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on message types.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Removing a match</title>
+ <para>
+ Matches can be removed with the
+ <constant>KDBUS_CMD_MATCH_REMOVE</constant> ioctl, which takes
+ <type>struct kdbus_cmd_match</type> as argument, but its fields
+ usage slightly differs compared to that of
+ <constant>KDBUS_CMD_MATCH_ADD</constant>.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_match {
+ __u64 size;
+ __u64 cookie;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie</varname></term>
+ <listitem><para>
+ The cookie of the match, as it was passed when the match was added.
+ All matches that have this cookie will be removed.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ No flags are supported for this use case.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname> is set to
+ <constant>EPROTO</constant>, and the <varname>flags</varname> field
+ is set to <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ No items are supported for this use case, but
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed nevertheless.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_MATCH_ADD</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal flags or items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDOM</constant></term>
+ <listitem><para>
+ Illegal bloom filter size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ Too many matches for this connection.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_MATCH_REMOVE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal flags.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADSLT</constant></term>
+ <listitem><para>
+ A match entry with the given cookie could not be found.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.message.xml b/Documentation/kdbus/kdbus.message.xml
new file mode 100644
index 000000000000..c25000dcfbc7
--- /dev/null
+++ b/Documentation/kdbus/kdbus.message.xml
@@ -0,0 +1,1277 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.message">
+
+ <refentryinfo>
+ <title>kdbus.message</title>
+ <productname>kdbus.message</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.message</refname>
+ <refpurpose>kdbus message</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A kdbus message is used to exchange information between two connections
+ on a bus, or to transport notifications from the kernel to one or many
+ connections. This document describes the layout of messages, how payload
+ is added to them and how they are sent and received.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Message layout</title>
+
+ <para>The layout of a message is shown below.</para>
+
+ <programlisting>
+ +-------------------------------------------------------------------------+
+ | Message |
+ | +---------------------------------------------------------------------+ |
+ | | Header | |
+ | | size: overall message size, including the data records | |
+ | | destination: connection ID of the receiver | |
+ | | source: connection ID of the sender (set by kernel) | |
+ | | payload_type: "DBusDBus" textual identifier stored as uint64_t | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size (without padding) | |
+ | | type: type of data | |
+ | | data: reference to data (address or file descriptor) | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | padding bytes to the next 8 byte alignment | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size (without padding) | |
+ | | ... | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | padding bytes to the next 8 byte alignment | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size | |
+ | | ... | |
+ | +---------------------------------------------------------------------+ |
+ | ... further data records ... |
+ +-------------------------------------------------------------------------+
+ </programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Message payload</title>
+
+ <para>
+ When connecting to the bus, receivers request a memory pool of a given
+ size, large enough to carry all backlog of data enqueued for the
+ connection. The pool is internally backed by a shared memory file which
+ can be <function>mmap()</function>ed by the receiver. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+
+ <para>
+ Message payload must be described in items attached to a message when
+ it is sent. A receiver can access the payload by looking at the items
+ that are attached to a message in its pool. The following items are used.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <listitem>
+ <para>
+ This item references a piece of memory on the sender side which is
+ directly copied into the receiver's pool. This way, two peers can
+ exchange data by effectively doing a single-copy from one process
+ to another; the kernel will not buffer the data anywhere else.
+ This item is never found in a message received by a connection.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
+ <listitem>
+ <para>
+ This item is attached to messages on the receiving side and points
+ to a memory area inside the receiver's pool. The
+ <varname>offset</varname> variable in the item denotes the memory
+ location relative to the message itself.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <listitem>
+ <para>
+ Messages can reference <emphasis>memfd</emphasis> files which
+ contain the data. memfd files are tmpfs-backed files that allow
+ sealing of the content of the file, which prevents all writable
+ access to the file content.
+ </para>
+ <para>
+ Only memfds that have
+ <constant>(F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL)
+ </constant>
+ set are accepted as payload data, which enforces reliable passing of
+ data. The receiver can assume that neither the sender nor anyone
+ else can alter the content after the message is sent. If those
+ seals are not set on the memfd, the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname> will be
+ set to <constant>ETXTBUSY</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem>
+ <para>
+ Messages can transport regular file descriptors via
+ <constant>KDBUS_ITEM_FDS</constant>. This item carries an array
+ of <type>int</type> values in <varname>item.fd</varname>. The
+ maximum number of file descriptors in the item is
+ <constant>253</constant>, and only one item of this type is
+ accepted per message. All passed values must be valid file
+ descriptors; the open count of each file descriptors is increased
+ by installing it to the receiver's task. This item can only be
+ used for directed messages, not for broadcasts, and only to
+ remote peers that have opted-in for receiving file descriptors
+ at connection time (<constant>KDBUS_HELLO_ACCEPT_FD</constant>).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The sender must not make any assumptions on the type in which data is
+ received by the remote peer. The kernel is free to re-pack multiple
+ <constant>KDBUS_ITEM_PAYLOAD_VEC</constant> and
+ <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> payloads. For instance, the
+ kernel may decide to merge multiple <constant>VECs</constant> into a
+ single <constant>VEC</constant>, inline <constant>MEMFD</constant>
+ payloads into memory, or merge all passed <constant>VECs</constant> into a
+ single <constant>MEMFD</constant>. However, the kernel preserves the order
+ of passed data. This means that the order of all <constant>VEC</constant>
+ and <constant>MEMFD</constant> items is not changed in respect to each
+ other. In other words: All passed <constant>VEC</constant> and
+ <constant>MEMFD</constant> data payloads are treated as a single stream
+ of data that may be received by the remote peer in a different set of
+ chunks than it was sent as.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Sending messages</title>
+
+ <para>
+ Messages are passed to the kernel with the
+ <constant>KDBUS_CMD_SEND</constant> ioctl. Depending on the destination
+ address of the message, the kernel delivers the message to the specific
+ destination connection, or to some subset of all connections on the same
+ bus. Sending messages across buses is not possible. Messages are always
+ queued in the memory pool of the destination connection (see above).
+ </para>
+
+ <para>
+ The <constant>KDBUS_CMD_SEND</constant> ioctl uses a
+ <type>struct kdbus_cmd_send</type> to describe the message
+ transfer.
+ </para>
+ <programlisting>
+struct kdbus_cmd_send {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 msg_address;
+ struct kdbus_msg_info reply;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags for message delivery</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_SEND_SYNC_REPLY</constant></term>
+ <listitem>
+ <para>
+ By default, all calls to kdbus are considered asynchronous,
+ non-blocking. However, as there are many use cases that need
+ to wait for a remote peer to answer a method call, there's a
+ way to send a message and wait for a reply in a synchronous
+ fashion. This is what the
+ <constant>KDBUS_SEND_SYNC_REPLY</constant> controls. The
+ <constant>KDBUS_CMD_SEND</constant> ioctl will block until the
+ reply has arrived, the timeout limit is reached, in case the
+ remote connection was shut down, or if interrupted by a signal
+ before any reply; see
+ <citerefentry>
+ <refentrytitle>signal</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+
+ The offset of the reply message in the sender's pool is stored
+ in in <varname>offset_reply</varname> when the ioctl has
+ returned without error. Hence, there is no need for another
+ <constant>KDBUS_CMD_RECV</constant> ioctl or anything else to
+ receive the reply.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg_address</varname></term>
+ <listitem><para>
+ In this field, users have to provide a pointer to a message
+ (<type>struct kdbus_msg</type>) to send. See below for a
+ detailed description.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>reply</varname></term>
+ <listitem><para>
+ Only used for synchronous replies. See description of
+ <type>struct kdbus_cmd_recv</type> for more details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are currently recognized.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
+ <listitem>
+ <para>
+ When this optional item is passed in, and the call is
+ executed as SYNC call, the passed in file descriptor can be
+ used as alternative cancellation point. The kernel will call
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on this file descriptor, and once it reports any incoming
+ bytes, the blocking send operation will be canceled; the
+ blocking, synchronous ioctl call will return
+ <errorcode>-1</errorcode>, and <varname>errno</varname> will
+ be set to <errorname>ECANCELED</errorname>.
+ Any type of file descriptor on which
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ can be called on can be used as payload to this item; for
+ example, an eventfd can be used for this purpose, see
+ <citerefentry>
+ <refentrytitle>eventfd</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ For asynchronous message sending, this item is allowed but
+ ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The fields in this struct are described below.
+ The message referenced the <varname>msg_address</varname> above has
+ the following layout.
+ </para>
+
+ <programlisting>
+struct kdbus_msg {
+ __u64 size;
+ __u64 flags;
+ __s64 priority;
+ __u64 dst_id;
+ __u64 src_id;
+ __u64 payload_type;
+ __u64 cookie;
+ __u64 timeout_ns;
+ __u64 cookie_reply;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to describe message details.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MSG_EXPECT_REPLY</constant></term>
+ <listitem>
+ <para>
+ Expect a reply to this message from the remote peer. With
+ this bit set, the timeout_ns field must be set to a non-zero
+ number of nanoseconds in which the receiving peer is expected
+ to reply. If such a reply is not received in time, the sender
+ will be notified with a timeout message (see below). The
+ value must be an absolute value, in nanoseconds and based on
+ <constant>CLOCK_MONOTONIC</constant>.
+ </para><para>
+ For a message to be accepted as reply, it must be a direct
+ message to the original sender (not a broadcast and not a
+ signal message), and its
+ <varname>kdbus_msg.reply_cookie</varname> must match the
+ previous message's <varname>kdbus_msg.cookie</varname>.
+ </para><para>
+ Expected replies also temporarily open the policy of the
+ sending connection, so the other peer is allowed to respond
+ within the given time window.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_MSG_NO_AUTO_START</constant></term>
+ <listitem>
+ <para>
+ By default, when a message is sent to an activator
+ connection, the activator is notified and will start an
+ implementer. This flag inhibits that behavior. With this bit
+ set, and the remote being an activator, the ioctl will fail
+ with <varname>errno</varname> set to
+ <constant>EADDRNOTAVAIL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>priority</varname></term>
+ <listitem><para>
+ The priority of this message. Receiving messages (see below) may
+ optionally be constrained to messages of a minimal priority. This
+ allows for use cases where timing critical data is interleaved with
+ control data on the same connection. If unused, the priority field
+ should be set to <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dst_id</varname></term>
+ <listitem><para>
+ The numeric ID of the destination connection, or
+ <constant>KDBUS_DST_ID_BROADCAST</constant>
+ (~0ULL) to address every peer on the bus, or
+ <constant>KDBUS_DST_ID_NAME</constant> (0) to look
+ it up dynamically from the bus' name registry.
+ In the latter case, an item of type
+ <constant>KDBUS_ITEM_DST_NAME</constant> is mandatory.
+ Also see
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ .
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>src_id</varname></term>
+ <listitem><para>
+ Upon return of the ioctl, this member will contain the sending
+ connection's numerical ID. Should be 0 at send time.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>payload_type</varname></term>
+ <listitem><para>
+ Type of the payload in the actual data records. Currently, only
+ <constant>KDBUS_PAYLOAD_DBUS</constant> is accepted as input value
+ of this field. When receiving messages that are generated by the
+ kernel (notifications), this field will contain
+ <constant>KDBUS_PAYLOAD_KERNEL</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie</varname></term>
+ <listitem><para>
+ Cookie of this message, for later recognition. Also, when replying
+ to a message (see above), the <varname>cookie_reply</varname>
+ field must match this value.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>timeout_ns</varname></term>
+ <listitem><para>
+ If the message sent requires a reply from the remote peer (see above),
+ this field contains the timeout in absolute nanoseconds based on
+ <constant>CLOCK_MONOTONIC</constant>. Also see
+ <citerefentry>
+ <refentrytitle>clock_gettime</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie_reply</varname></term>
+ <listitem><para>
+ If the message sent is a reply to another message, this field must
+ match the cookie of the formerly received message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ A dynamically sized list of items to contain additional information.
+ The following items are expected/valid:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem>
+ <para>
+ Actual data records containing the payload. See section
+ "Passing of Payload Data".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
+ <listitem>
+ <para>
+ Bloom filter for matches (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
+ <listitem>
+ <para>
+ Well-known name to send this message to. Required if
+ <varname>dst_id</varname> is set to
+ <constant>KDBUS_DST_ID_NAME</constant>.
+ If a connection holding the given name can't be found,
+ the ioctl will fail with <varname>errno</varname> set to
+ <constant>ESRCH</constant> is returned.
+ </para>
+ <para>
+ For messages to a unique name (ID), this item is optional. If
+ present, the kernel will make sure the name owner matches the
+ given unique name. This allows programs to tie the message
+ sending to the condition that a name is currently owned by a
+ certain unique name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The message will be augmented by the requested metadata items when
+ queued into the receiver's pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on metadata.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Receiving messages</title>
+
+ <para>
+ Messages are received by the client with the
+ <constant>KDBUS_CMD_RECV</constant> ioctl. The endpoint file of the bus
+ supports <function>poll()/epoll()/select()</function>; when new messages
+ are available on the connection's file descriptor,
+ <constant>POLLIN</constant> is reported. For compatibility reasons,
+ <constant>POLLOUT</constant> is always reported as well. Note, however,
+ that the latter does not guarantee that a message can in fact be sent, as
+ this depends on how many pending messages the receiver has in its pool.
+ </para>
+
+ <para>
+ With the <constant>KDBUS_CMD_RECV</constant> ioctl, a
+ <type>struct kdbus_cmd_recv</type> is used.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_recv {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __s64 priority;
+ __u64 dropped_msgs;
+ struct kdbus_msg_info msg;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to control the receive command.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_RECV_PEEK</constant></term>
+ <listitem>
+ <para>
+ Just return the location of the next message. Do not install
+ file descriptors or anything else. This is usually used to
+ determine the sender of the next queued message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_RECV_DROP</constant></term>
+ <listitem>
+ <para>
+ Drop the next message without doing anything else with it,
+ and free the pool slice. This a short-cut for
+ <constant>KDBUS_RECV_PEEK</constant> and
+ <constant>KDBUS_CMD_FREE</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_RECV_USE_PRIORITY</constant></term>
+ <listitem>
+ <para>
+ Dequeue the messages ordered by their priority, and filtering
+ them with the priority field (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. If the <varname>dropped_msgs</varname>
+ field is non-zero, <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant>
+ is set. If a file descriptor could not be installed, the
+ <constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant> flag is set.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>priority</varname></term>
+ <listitem><para>
+ With <constant>KDBUS_RECV_USE_PRIORITY</constant> set in
+ <varname>flags</varname>, messages will be dequeued ordered by their
+ priority, starting with the highest value. Also, messages will be
+ filtered by the value given in this field, so the returned message
+ will at least have the requested priority. If no such message is
+ waiting in the queue, the ioctl will fail, and
+ <varname>errno</varname> will be set to <constant>EAGAIN</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dropped_msgs</varname></term>
+ <listitem><para>
+ Whenever a message with <constant>KDBUS_MSG_SIGNAL</constant> is sent
+ but cannot be queued on a peer (e.g., as it contains FDs but the peer
+ does not support FDs, or there is no space left in the peer's pool..)
+ the 'dropped_msgs' counter of the peer is incremented. On the next
+ RECV ioctl, the 'dropped_msgs' field is copied into the ioctl struct
+ and cleared on the peer. If it was non-zero, the
+ <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant> flag will be set
+ in <varname>return_flags</varname>. Note that this will only happen
+ if the ioctl succeeded or failed with <constant>EAGAIN</constant>. In
+ other error cases, the 'dropped_msgs' field of the peer is left
+ untouched.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg</varname></term>
+ <listitem><para>
+ Embedded struct containing information on the received message when
+ this command succeeded (see below).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem><para>
+ Items to specify further details for the receive command.
+ Currently unused, and all items will be rejected with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Both <type>struct kdbus_cmd_recv</type> and
+ <type>struct kdbus_cmd_send</type> embed
+ <type>struct kdbus_msg_info</type>.
+ For the <constant>KDBUS_CMD_SEND</constant> ioctl, it is used to catch
+ synchronous replies, if one was requested, and is unused otherwise.
+ </para>
+
+ <programlisting>
+struct kdbus_msg_info {
+ __u64 offset;
+ __u64 msg_size;
+ __u64 return_flags;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ Upon return of the ioctl, this field contains the offset in the
+ receiver's memory pool. The memory must be freed with
+ <constant>KDBUS_CMD_FREE</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg_size</varname></term>
+ <listitem><para>
+ Upon successful return of the ioctl, this field contains the size of
+ the allocated slice at offset <varname>offset</varname>.
+ It is the combination of the size of the stored
+ <type>struct kdbus_msg</type> object plus all appended VECs.
+ You can use it in combination with <varname>offset</varname> to map
+ a single message, instead of mapping the entire pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem>
+ <para>
+ Kernel-provided return flags. Currently, the following flags are
+ defined.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant></term>
+ <listitem>
+ <para>
+ The message contained memfds or file descriptors, and the
+ kernel failed to install one or more of them at receive time.
+ Most probably that happened because the maximum number of
+ file descriptors for the receiver's task were exceeded.
+ In such cases, the message is still delivered, so this is not
+ a fatal condition. File descriptors numbers inside the
+ <constant>KDBUS_ITEM_FDS</constant> item or memfd files
+ referenced by <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant>
+ items which could not be installed will be set to
+ <constant>-1</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unless <constant>KDBUS_RECV_DROP</constant> was passed, the
+ <varname>offset</varname> field contains the location of the new message
+ inside the receiver's pool after the <constant>KDBUS_CMD_RECV</constant>
+ ioctl was employed. The message is stored as <type>struct kdbus_msg</type>
+ at this offset, and can be interpreted with the semantics described above.
+ </para>
+ <para>
+ Also, if the connection allowed for file descriptor to be passed
+ (<constant>KDBUS_HELLO_ACCEPT_FD</constant>), and if the message contained
+ any, they will be installed into the receiving process when the
+ <constant>KDBUS_CMD_RECV</constant> ioctl is called.
+ <emphasis>memfds</emphasis> may always be part of the message payload.
+ The receiving task is obliged to close all file descriptors appropriately
+ once no longer needed. If <constant>KDBUS_RECV_PEEK</constant> is set, no
+ file descriptors are installed. This allows for peeking at a message,
+ looking at its metadata only and dropping it via
+ <constant>KDBUS_RECV_DROP</constant>, without installing any of the file
+ descriptors into the receiving process.
+ </para>
+ <para>
+ The caller is obliged to call the <constant>KDBUS_CMD_FREE</constant>
+ ioctl with the returned offset when the memory is no longer needed.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notifications</title>
+ <para>
+ A kernel notification is a regular kdbus message with the following
+ details.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ kdbus_msg.src_id == <constant>KDBUS_SRC_ID_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ kdbus_msg.dst_id == <constant>KDBUS_DST_ID_BROADCAST</constant>
+ </para></listitem>
+ <listitem><para>
+ kdbus_msg.payload_type == <constant>KDBUS_PAYLOAD_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ Has exactly one of the items attached that are described below.
+ </para></listitem>
+ <listitem><para>
+ Always has a timestamp item (<constant>KDBUS_ITEM_TIMESTAMP</constant>)
+ attached.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ The kernel will notify its users of the following events.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ When connection <emphasis>A</emphasis> is terminated while connection
+ <emphasis>B</emphasis> is waiting for a reply from it, connection
+ <emphasis>B</emphasis> is notified with a message with an item of
+ type <constant>KDBUS_ITEM_REPLY_DEAD</constant>.
+ </para></listitem>
+
+ <listitem><para>
+ When connection <emphasis>A</emphasis> does not receive a reply from
+ connection <emphasis>B</emphasis> within the specified timeout window,
+ connection <emphasis>A</emphasis> will receive a message with an
+ item of type <constant>KDBUS_ITEM_REPLY_TIMEOUT</constant>.
+ </para></listitem>
+
+ <listitem><para>
+ When an ordinary connection (not a monitor) is created on or removed
+ from a bus, messages with an item of type
+ <constant>KDBUS_ITEM_ID_ADD</constant> or
+ <constant>KDBUS_ITEM_ID_REMOVE</constant>, respectively, are delivered
+ to all bus members that match these messages through their match
+ database. Eavesdroppers (monitor connections) do not cause such
+ notifications to be sent. They are invisible on the bus.
+ </para></listitem>
+
+ <listitem><para>
+ When a connection gains or loses ownership of a name, messages with an
+ item of type <constant>KDBUS_ITEM_NAME_ADD</constant>,
+ <constant>KDBUS_ITEM_NAME_REMOVE</constant> or
+ <constant>KDBUS_ITEM_NAME_CHANGE</constant> are delivered to all bus
+ members that match these messages through their match database.
+ </para></listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_SEND</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The connection is not an ordinary connection, or the passed
+ file descriptors in <constant>KDBUS_ITEM_FDS</constant> item are
+ either kdbus handles or unix domain sockets. Both are currently
+ unsupported.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The submitted payload type is
+ <constant>KDBUS_PAYLOAD_KERNEL</constant>,
+ <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set without timeout
+ or cookie values, <constant>KDBUS_SEND_SYNC_REPLY</constant> was
+ set without <constant>KDBUS_MSG_EXPECT_REPLY</constant>, an invalid
+ item was supplied, <constant>src_id</constant> was non-zero and was
+ different from the current connection's ID, a supplied memfd had a
+ size of 0, or a string was not properly null-terminated.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOTUNIQ</constant></term>
+ <listitem><para>
+ The supplied destination is
+ <constant>KDBUS_DST_ID_BROADCAST</constant> and either
+ file descriptors were passed, or
+ <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set,
+ or a timeout was given.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ Too many items
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMSGSIZE</constant></term>
+ <listitem><para>
+ The size of the message header and items or the payload vector
+ is excessive.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ Multiple <constant>KDBUS_ITEM_FDS</constant>,
+ <constant>KDBUS_ITEM_BLOOM_FILTER</constant> or
+ <constant>KDBUS_ITEM_DST_NAME</constant> items were supplied.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADF</constant></term>
+ <listitem><para>
+ The supplied <constant>KDBUS_ITEM_FDS</constant> or
+ <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> items
+ contained an illegal file descriptor.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMEDIUMTYPE</constant></term>
+ <listitem><para>
+ The supplied memfd is not a sealed kdbus memfd.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ Too many file descriptors inside a
+ <constant>KDBUS_ITEM_FDS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADMSG</constant></term>
+ <listitem><para>
+ An item had illegal size, both a <constant>dst_id</constant> and a
+ <constant>KDBUS_ITEM_DST_NAME</constant> was given, or both a name
+ and a bloom filter was given.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ETXTBSY</constant></term>
+ <listitem><para>
+ The supplied kdbus memfd file cannot be sealed or the seal
+ was removed, because it is shared with other processes or
+ still mapped with
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECOMM</constant></term>
+ <listitem><para>
+ A peer does not accept the file descriptors addressed to it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EFAULT</constant></term>
+ <listitem><para>
+ The supplied bloom filter size was not 64-bit aligned, or supplied
+ memory could not be accessed by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDOM</constant></term>
+ <listitem><para>
+ The supplied bloom filter size did not match the bloom filter
+ size of the bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDESTADDRREQ</constant></term>
+ <listitem><para>
+ <constant>dst_id</constant> was set to
+ <constant>KDBUS_DST_ID_NAME</constant>, but no
+ <constant>KDBUS_ITEM_DST_NAME</constant> was attached.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ The name to look up was not found in the name registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EADDRNOTAVAIL</constant></term>
+ <listitem><para>
+ <constant>KDBUS_MSG_NO_AUTO_START</constant> was given but the
+ destination connection is an activator.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENXIO</constant></term>
+ <listitem><para>
+ The passed numeric destination connection ID couldn't be found,
+ or is not connected.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECONNRESET</constant></term>
+ <listitem><para>
+ The destination connection is no longer active.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ETIMEDOUT</constant></term>
+ <listitem><para>
+ Timeout while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINTR</constant></term>
+ <listitem><para>
+ Interrupted system call while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPIPE</constant></term>
+ <listitem><para>
+ When sending a message, a synchronous reply from the receiving
+ connection was expected but the connection died before answering.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOBUFS</constant></term>
+ <listitem><para>
+ Too many pending messages on the receiver side.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EREMCHG</constant></term>
+ <listitem><para>
+ Both a well-known name and a unique name (ID) was given, but
+ the name is not currently owned by that connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EXFULL</constant></term>
+ <listitem><para>
+ The memory pool of the receiver is full.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EREMOTEIO</constant></term>
+ <listitem><para>
+ While synchronously waiting for a reply, the remote peer
+ failed with an I/O error.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_RECV</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The connection is not an ordinary connection, or the passed
+ file descriptors are either kdbus handles or unix domain
+ sockets. Both are currently unsupported.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid flags or offset.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EAGAIN</constant></term>
+ <listitem><para>
+ No message found in the queue
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>clock_gettime</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>ioctl</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>select</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>epoll</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>eventfd</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>memfd_create</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.name.xml b/Documentation/kdbus/kdbus.name.xml
new file mode 100644
index 000000000000..3f5f6a6c5ed6
--- /dev/null
+++ b/Documentation/kdbus/kdbus.name.xml
@@ -0,0 +1,711 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.name">
+
+ <refentryinfo>
+ <title>kdbus.name</title>
+ <productname>kdbus.name</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.name</refname>
+ <refpurpose>kdbus.name</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Each
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ instantiates a name registry to resolve well-known names into unique
+ connection IDs for message delivery. The registry will be queried when a
+ message is sent with <varname>kdbus_msg.dst_id</varname> set to
+ <constant>KDBUS_DST_ID_NAME</constant>, or when a registry dump is
+ requested with <constant>KDBUS_CMD_NAME_LIST</constant>.
+ </para>
+
+ <para>
+ All of the below is subject to policy rules for <emphasis>SEE</emphasis>
+ and <emphasis>OWN</emphasis> permissions. See
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Name validity</title>
+ <para>
+ A name has to comply with the following rules in order to be considered
+ valid.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The name has two or more elements separated by a
+ '<literal>.</literal>' (period) character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All elements must contain at least one character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Each element must only contain the ASCII characters
+ <literal>[A-Z][a-z][0-9]_</literal> and must not begin with a
+ digit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must contain at least one '<literal>.</literal>' (period)
+ character (and thus at least two elements).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must not begin with a '<literal>.</literal>' (period)
+ character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must not exceed <constant>255</constant> characters in
+ length.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Acquiring a name</title>
+ <para>
+ To acquire a name, a client uses the
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> ioctl with
+ <type>struct kdbus_cmd</type> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to control details in the name acquisition.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_REPLACE_EXISTING</constant></term>
+ <listitem>
+ <para>
+ Acquiring a name that is already present usually fails,
+ unless this flag is set in the call, and
+ <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> (see below)
+ was set when the current owner of the name acquired it, or
+ if the current owner is an activator connection (see
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
+ <listitem>
+ <para>
+ Allow other connections to take over this name. When this
+ happens, the former owner of the connection will be notified
+ of the name loss.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_QUEUE</constant></term>
+ <listitem>
+ <para>
+ A name that is already acquired by a connection can not be
+ acquired again (unless the
+ <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> flag was
+ set during acquisition; see above).
+ However, a connection can put itself in a queue of
+ connections waiting for the name to be released. Once that
+ happens, the first connection in that queue becomes the new
+ owner and is notified accordingly.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem>
+ <para>
+ Flags returned by the kernel. Currently, the following may be
+ returned by the kernel.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
+ <listitem>
+ <para>
+ The name was not acquired yet, but the connection was
+ placed in the queue of peers waiting for the name.
+ This can only happen if <constant>KDBUS_NAME_QUEUE</constant>
+ was set in the <varname>flags</varname> member (see above).
+ The connection will receive a name owner change notification
+ once the current owner has given up the name and its
+ ownership was transferred.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to submit the name. Currently, one item of type
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
+ the contained string must be a valid bus name.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
+ valid item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a detailed description of how this item is used.
+ </para>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <errorname>>EINVAL</errorname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Releasing a name</title>
+ <para>
+ A connection may release a name explicitly with the
+ <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl. If the connection was
+ an implementer of an activatable name, its pending messages are moved
+ back to the activator. If there are any connections queued up as waiters
+ for the name, the first one in the queue (the oldest entry) will become
+ the new owner. The same happens implicitly for all names once a
+ connection terminates. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on connections.
+ </para>
+ <para>
+ The <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl uses the same data
+ structure as the acquisition call
+ (<constant>KDBUS_CMD_NAME_ACQUIRE</constant>),
+ but with slightly different field usage.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Flags to the command. Currently unused.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to submit the name. Currently, one item of type
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
+ the contained string must be a valid bus name.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
+ valid item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a detailed description of how this item is used.
+ </para>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Dumping the name registry</title>
+ <para>
+ A connection may request a complete or filtered dump of currently active
+ bus names with the <constant>KDBUS_CMD_LIST</constant> ioctl, which
+ takes a <type>struct kdbus_cmd_list</type> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_list {
+ __u64 flags;
+ __u64 return_flags;
+ __u64 offset;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem>
+ <para>
+ Any combination of flags to specify which names should be dumped.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_LIST_UNIQUE</constant></term>
+ <listitem>
+ <para>
+ List the unique (numeric) IDs of the connection, whether it
+ owns a name or not.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_NAMES</constant></term>
+ <listitem>
+ <para>
+ List well-known names stored in the database which are
+ actively owned by a real connection (not an activator).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_ACTIVATORS</constant></term>
+ <listitem>
+ <para>
+ List names that are owned by an activator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_QUEUED</constant></term>
+ <listitem>
+ <para>
+ List connections that are not yet owning a name but are
+ waiting for it to become available.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ When the ioctl returns successfully, the offset to the name registry
+ dump inside the connection's pool will be stored in this field.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The returned list of names is stored in a <type>struct kdbus_list</type>
+ that in turn contains an array of type <type>struct kdbus_info</type>,
+ The array-size in bytes is given as <varname>list_size</varname>.
+ The fields inside <type>struct kdbus_info</type> is described next.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The owning connection's unique ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The flags of the owning connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items containing the actual name. Currently, one item of type
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> will be attached,
+ including the name's flags. In that item, the flags field of the
+ name may carry the following bits:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
+ <listitem>
+ <para>
+ Other connections are allowed to take over this name from the
+ connection that owns it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
+ <listitem>
+ <para>
+ When retrieving a list of currently acquired names in the
+ registry, this flag indicates whether the connection
+ actually owns the name or is currently waiting for it to
+ become available.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ACTIVATOR</constant></term>
+ <listitem>
+ <para>
+ An activator connection owns a name as a placeholder for an
+ implementer, which is started on demand by programs as soon
+ as the first message arrives. There's some more information
+ on this topic in
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ .
+ </para>
+ <para>
+ In contrast to
+ <constant>KDBUS_NAME_REPLACE_EXISTING</constant>,
+ when a name is taken over from an activator connection, all
+ the messages that have been queued in the activator
+ connection will be moved over to the new owner. The activator
+ connection will still be tracked for the name and will take
+ control again if the implementer connection terminates.
+ </para>
+ <para>
+ This flag can not be used when acquiring a name, but is
+ implicitly set through <constant>KDBUS_CMD_HELLO</constant>
+ with <constant>KDBUS_HELLO_ACTIVATOR</constant> set in
+ <varname>kdbus_cmd_hello.conn_flags</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The returned buffer must be freed with the
+ <constant>KDBUS_CMD_FREE</constant> ioctl when the user is finished with
+ it. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal command flags, illegal name provided, or an activator
+ tried to acquire a second name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPERM</constant></term>
+ <listitem><para>
+ Policy prohibited name ownership.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EALREADY</constant></term>
+ <listitem><para>
+ Connection already owns that name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ The name already exists and can not be taken over.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ The maximum number of well-known names per connection is exhausted.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_NAME_RELEASE</constant>
+ may fail with the following errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid command flags, or invalid name provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ Name is not found in the registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EADDRINUSE</constant></term>
+ <listitem><para>
+ Name is owned by a different connection and can't be released.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_LIST</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid command flags
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOBUFS</constant></term>
+ <listitem><para>
+ No available memory in the connection's pool.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.policy.xml b/Documentation/kdbus/kdbus.policy.xml
new file mode 100644
index 000000000000..67324163880a
--- /dev/null
+++ b/Documentation/kdbus/kdbus.policy.xml
@@ -0,0 +1,406 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.policy">
+
+ <refentryinfo>
+ <title>kdbus.policy</title>
+ <productname>kdbus.policy</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.policy</refname>
+ <refpurpose>kdbus policy</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A kdbus policy restricts the possibilities of connections to own, see and
+ talk to well-known names. A policy can be associated with a bus (through a
+ policy holder connection) or a custom endpoint. kdbus stores its policy
+ information in a database that can be accessed through the following
+ ioctl commands:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_HELLO</constant></term>
+ <listitem><para>
+ When creating, or updating, a policy holder connection. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></term>
+ <term><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></term>
+ <listitem><para>
+ When creating, or updating, a bus custom endpoint. See
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ In all cases, the name and policy access information is stored in items
+ of type <constant>KDBUS_ITEM_NAME</constant> and
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant>. For this transport, the
+ following rules apply.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ An item of type <constant>KDBUS_ITEM_NAME</constant> must be followed
+ by at least one <constant>KDBUS_ITEM_POLICY_ACCESS</constant> item.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ An item of type <constant>KDBUS_ITEM_NAME</constant> can be followed
+ by an arbitrary number of
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> items.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ An arbitrary number of groups of names and access levels can be given.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Names passed in items of type <constant>KDBUS_ITEM_NAME</constant> must
+ comply to the rules of valid kdbus.name. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+
+ The payload of an item of type
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> is defined by the following
+ struct. For more information on the layout of items, please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+
+ <programlisting>
+struct kdbus_policy_access {
+ __u64 type;
+ __u64 access;
+ __u64 id;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>type</varname></term>
+ <listitem>
+ <para>
+ One of the following.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_ACCESS_USER</constant></term>
+ <listitem><para>
+ Grant access to a user with the UID stored in the
+ <varname>id</varname> field.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_ACCESS_GROUP</constant></term>
+ <listitem><para>
+ Grant access to a user with the GID stored in the
+ <varname>id</varname> field.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_ACCESS_WORLD</constant></term>
+ <listitem><para>
+ Grant access to everyone. The <varname>id</varname> field
+ is ignored.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>access</varname></term>
+ <listitem>
+ <para>
+ The access to grant. One of the following.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_SEE</constant></term>
+ <listitem><para>
+ Allow the name to be seen.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_TALK</constant></term>
+ <listitem><para>
+ Allow the name to be talked to.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_POLICY_OWN</constant></term>
+ <listitem><para>
+ Allow the name to be owned.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ For <constant>KDBUS_POLICY_ACCESS_USER</constant>, stores the UID.
+ For <constant>KDBUS_POLICY_ACCESS_GROUP</constant>, stores the GID.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ All endpoints of buses have an empty policy database by default.
+ Therefore, unless policy rules are added, all operations will also be
+ denied by default. Also see
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Wildcard names</title>
+ <para>
+ Policy holder connections may upload names that contain the wildcard
+ suffix (<literal>".*"</literal>). Such a policy entry is effective for
+ every well-known name that extends the provided name by exactly one more
+ level.
+
+ For example, the name <literal>foo.bar.*</literal> matches both
+ <literal>"foo.bar.baz"</literal> and
+ <literal>"foo.bar.bazbaz"</literal> are, but not
+ <literal>"foo.bar.baz.baz"</literal>.
+
+ This allows connections to take control over multiple names that the
+ policy holder doesn't need to know about when uploading the policy.
+
+ Such wildcard entries are not allowed for custom endpoints.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Privileged connections</title>
+ <para>
+ The policy database is overruled when action is taken by a privileged
+ connection. Please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on what makes a connection privileged.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+ <para>
+ For instance, a set of policy rules may look like this:
+ </para>
+
+ <programlisting>
+KDBUS_ITEM_NAME: str='org.foo.bar'
+KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=1000
+KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, ID=1001
+KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=SEE
+
+KDBUS_ITEM_NAME: str='org.blah.baz'
+KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=0
+KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK
+ </programlisting>
+
+ <para>
+ That means that 'org.foo.bar' may only be owned by UID 1000, but every
+ user on the bus is allowed to see the name. However, only UID 1001 may
+ actually send a message to the connection and receive a reply from it.
+
+ The second rule allows 'org.blah.baz' to be owned by UID 0 only, but
+ every user may talk to it.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>TALK access and multiple well-known names per connection</title>
+ <para>
+ Note that TALK access is checked against all names of a connection. For
+ example, if a connection owns both <constant>'org.foo.bar'</constant> and
+ <constant>'org.blah.baz'</constant>, and the policy database allows
+ <constant>'org.blah.baz'</constant> to be talked to by WORLD, then this
+ permission is also granted to <constant>'org.foo.bar'</constant>. That
+ might sound illogical, but after all, we allow messages to be directed to
+ either the ID or a well-known name, and policy is applied to the
+ connection, not the name. In other words, the effective TALK policy for a
+ connection is the most permissive of all names the connection owns.
+
+ For broadcast messages, the receiver needs TALK permissions to the sender
+ to receive the broadcast.
+ </para>
+ <para>
+ Both the endpoint and the bus policy databases are consulted to allow
+ name registry listing, owning a well-known name and message delivery.
+ If either one fails, the operation is failed with
+ <varname>errno</varname> set to <constant>EPERM</constant>.
+
+ For best practices, connections that own names with a restricted TALK
+ access should not install matches. This avoids cases where the sent
+ message may pass the bloom filter due to false-positives and may also
+ satisfy the policy rules.
+
+ Also see
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Implicit policies</title>
+ <para>
+ Depending on the type of the endpoint, a set of implicit rules that
+ override installed policies might be enforced.
+
+ On default endpoints, the following set is enforced and checked before
+ any user-supplied policy is checked.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Privileged connections always override any installed policy. Those
+ connections could easily install their own policies, so there is no
+ reason to enforce installed policies.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Connections can always talk to connections of the same user. This
+ includes broadcast messages.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Custom endpoints have stricter policies. The following rules apply:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Policy rules are always enforced, even if the connection is a
+ privileged connection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Policy rules are always enforced for <constant>TALK</constant> access,
+ even if both ends are running under the same user. This includes
+ broadcast messages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To restrict the set of names that can be seen, endpoint policies can
+ install <constant>SEE</constant> policies.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.pool.xml b/Documentation/kdbus/kdbus.pool.xml
new file mode 100644
index 000000000000..05fd01902ad4
--- /dev/null
+++ b/Documentation/kdbus/kdbus.pool.xml
@@ -0,0 +1,320 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.pool">
+
+ <refentryinfo>
+ <title>kdbus.pool</title>
+ <productname>kdbus.pool</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.pool</refname>
+ <refpurpose>kdbus pool</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ A pool for data received from the kernel is installed for every
+ <emphasis>connection</emphasis> of the <emphasis>bus</emphasis>, and
+ is sized according to the information stored in the
+ <varname>pool_size</varname> member of <type>struct kdbus_cmd_hello</type>
+ when <constant>KDBUS_CMD_HELLO</constant> is employed. Internally, the
+ pool is segmented into <emphasis>slices</emphasis>, each referenced by its
+ <emphasis>offset</emphasis> in the pool, expressed in <type>bytes</type>.
+ See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about <constant>KDBUS_CMD_HELLO</constant>.
+ </para>
+
+ <para>
+ The pool is written to by the kernel when one of the following
+ <emphasis>ioctls</emphasis> is issued:
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_HELLO</constant></term>
+ <listitem><para>
+ ... to receive details about the bus the connection was made to
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_RECV</constant></term>
+ <listitem><para>
+ ... to receive a message
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_LIST</constant></term>
+ <listitem><para>
+ ... to dump the name registry
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>KDBUS_CMD_CONN_INFO</constant></term>
+ <listitem><para>
+ ... to retrieve information on a connection
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ <para>
+ The <varname>offset</varname> fields returned by either one of the
+ aforementioned ioctls describe offsets inside the pool. In order to make
+ the slice available for subsequent calls,
+ <constant>KDBUS_CMD_FREE</constant> has to be called on that offset
+ (see below). Otherwise, the pool will fill up, and the connection won't
+ be able to receive any more information through its pool.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Pool slice allocation</title>
+ <para>
+ Pool slices are allocated by the kernel in order to report information
+ back to a task, such as messages, returned name list etc.
+ Allocation of pool slices cannot be initiated by userspace. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for examples of commands that use the <emphasis>pool</emphasis> to
+ return data.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Accessing the pool memory</title>
+ <para>
+ Memory in the pool is read-only for userspace and may only be written
+ to by the kernel. To read from the pool memory, the caller is expected to
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ the buffer into its task, like this:
+ </para>
+ <programlisting>
+uint8_t *buf = mmap(NULL, size, PROT_READ, MAP_SHARED, conn_fd, 0);
+ </programlisting>
+
+ <para>
+ In order to map the entire pool, the <varname>size</varname> parameter in
+ the example above should be set to the value of the
+ <varname>pool_size</varname> member of
+ <type>struct kdbus_cmd_hello</type> when
+ <constant>KDBUS_CMD_HELLO</constant> was employed to create the
+ connection (see above).
+ </para>
+
+ <para>
+ The <emphasis>file descriptor</emphasis> used to map the memory must be
+ the one that was used to create the <emphasis>connection</emphasis>.
+ In other words, the one that was used to call
+ <constant>KDBUS_CMD_HELLO</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+
+ <para>
+ Alternatively, instead of mapping the entire pool buffer, only parts
+ of it can be mapped. Every kdbus command that returns an
+ <emphasis>offset</emphasis> (see above) also reports a
+ <emphasis>size</emphasis> along with it, so programs can be written
+ in a way that it only maps portions of the pool to access a specific
+ <emphasis>slice</emphasis>.
+ </para>
+
+ <para>
+ When access to the pool memory is no longer needed, programs should
+ call <function>munmap()</function> on the pointer returned by
+ <function>mmap()</function>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Freeing pool slices</title>
+ <para>
+ The <constant>KDBUS_CMD_FREE</constant> ioctl is used to free a slice
+ inside the pool, describing an offset that was returned in an
+ <varname>offset</varname> field of another ioctl struct.
+ The <constant>KDBUS_CMD_FREE</constant> command takes a
+ <type>struct kdbus_cmd_free</type> as argument.
+ </para>
+
+<programlisting>
+struct kdbus_cmd_free {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 offset;
+ struct kdbus_item items[0];
+};
+</programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ Currently unused.
+ <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
+ valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
+ and the <varname>flags</varname> field is set to
+ <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ The offset to free, as returned by other ioctls that allocated
+ memory for returned information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem><para>
+ Items to specify further details for the receive command.
+ Currently unused.
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ All items except for
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> (see
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ ) will be rejected.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_FREE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>ENXIO</constant></term>
+ <listitem><para>
+ No pool slice found at given offset.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid flags provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The offset is valid, but the user is not allowed to free the slice.
+ This happens, for example, if the offset was retrieved with
+ <constant>KDBUS_RECV_PEEK</constant>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>munmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/kdbus/kdbus.xml b/Documentation/kdbus/kdbus.xml
new file mode 100644
index 000000000000..194abd2e76cc
--- /dev/null
+++ b/Documentation/kdbus/kdbus.xml
@@ -0,0 +1,1012 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus">
+
+ <refentryinfo>
+ <title>kdbus</title>
+ <productname>kdbus</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus</refname>
+ <refpurpose>Kernel Message Bus</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Synopsis</title>
+ <para>
+ kdbus is an inter-process communication bus system controlled by the
+ kernel. It provides user-space with an API to create buses and send
+ unicast and multicast messages to one, or many, peers connected to the
+ same bus. It does not enforce any layout on the transmitted data, but
+ only provides the transport layer used for message interchange between
+ peers.
+ </para>
+ <para>
+ This set of man-pages gives a comprehensive overview of the kernel-level
+ API, with all ioctl commands, associated structs and bit masks. However,
+ most people will not use this API level directly, but rather let one of
+ the high-level abstraction libraries help them integrate D-Bus
+ functionality into their applications.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ kdbus provides a pseudo filesystem called <emphasis>kdbusfs</emphasis>,
+ which is usually mounted on <filename>/sys/fs/kdbus</filename>. Bus
+ primitives can be accessed as files and sub-directories underneath this
+ mount-point. Any advanced operations are done via
+ <function>ioctl()</function> on files created by
+ <emphasis>kdbusfs</emphasis>. Multiple mount-points of
+ <emphasis>kdbusfs</emphasis> are independent of each other. This allows
+ namespacing of kdbus by mounting a new instance of
+ <emphasis>kdbusfs</emphasis> in a new mount-namespace. kdbus calls these
+ mount instances domains and each bus belongs to exactly one domain.
+ </para>
+
+ <para>
+ kdbus was designed as a transport layer for D-Bus, but is in no way
+ limited, nor controlled by the D-Bus protocol specification. The D-Bus
+ protocol is one possible application layer on top of kdbus.
+ </para>
+
+ <para>
+ For the general D-Bus protocol specification, its payload format, its
+ marshaling, and its communication semantics, please refer to the
+ <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">
+ D-Bus specification</ulink>.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Terminology</title>
+
+ <refsect2>
+ <title>Domain</title>
+ <para>
+ A domain is a <emphasis>kdbusfs</emphasis> mount-point containing all
+ the bus primitives. Each domain is independent, and separate domains
+ do not affect each other.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Bus</title>
+ <para>
+ A bus is a named object inside a domain. Clients exchange messages
+ over a bus. Multiple buses themselves have no connection to each other;
+ messages can only be exchanged on the same bus. The default endpoint of
+ a bus, to which clients establish connections, is the "bus" file
+ /sys/fs/kdbus/<bus name>/bus.
+ Common operating system setups create one "system bus" per system,
+ and one "user bus" for every logged-in user. Applications or services
+ may create their own private buses. The kernel driver does not
+ distinguish between different bus types, they are all handled the same
+ way. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Endpoint</title>
+ <para>
+ An endpoint provides a file to talk to a bus. Opening an endpoint
+ creates a new connection to the bus to which the endpoint belongs. All
+ endpoints have unique names and are accessible as files underneath the
+ directory of a bus, e.g., /sys/fs/kdbus/<bus>/<endpoint>
+ Every bus has a default endpoint called "bus".
+ A bus can optionally offer additional endpoints with custom names
+ to provide restricted access to the bus. Custom endpoints carry
+ additional policy which can be used to create sandboxes with
+ locked-down, limited, filtered access to a bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Connection</title>
+ <para>
+ A connection to a bus is created by opening an endpoint file of a
+ bus. Every ordinary client connection has a unique identifier on the
+ bus and can address messages to every other connection on the same
+ bus by using the peer's connection ID as the destination. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Pool</title>
+ <para>
+ Each connection allocates a piece of shmem-backed memory that is
+ used to receive messages and answers to ioctl commands from the kernel.
+ It is never used to send anything to the kernel. In order to access that
+ memory, an application must mmap() it into its address space. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Well-known Name</title>
+ <para>
+ A connection can, in addition to its implicit unique connection ID,
+ request the ownership of a textual well-known name. Well-known names are
+ noted in reverse-domain notation, such as com.example.service1. A
+ connection that offers a service on a bus is usually reached by its
+ well-known name. An analogy of connection ID and well-known name is an
+ IP address and a DNS name associated with that address. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Message</title>
+ <para>
+ Connections can exchange messages with other connections by addressing
+ the peers with their connection ID or well-known name. A message
+ consists of a message header with information on how to route the
+ message, and the message payload, which is a logical byte stream of
+ arbitrary size. Messages can carry additional file descriptors to be
+ passed from one connection to another, just like passing file
+ descriptors over UNIX domain sockets. Every connection can specify which
+ set of metadata the kernel should attach to the message when it is
+ delivered to the receiving connection. Metadata contains information
+ like: system time stamps, UID, GID, TID, proc-starttime, well-known
+ names, process comm, process exe, process argv, cgroup, capabilities,
+ seclabel, audit session, loginuid and the connection's human-readable
+ name. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Item</title>
+ <para>
+ The API of kdbus implements the notion of items, submitted through and
+ returned by most ioctls, and stored inside data structures in the
+ connection's pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Broadcast, signal, filter, match</title>
+ <para>
+ Signals are messages that a receiver opts in for by installing a blob of
+ bytes, called a 'match'. Signal messages must always carry a
+ counter-part blob, called a 'filter', and signals are only delivered to
+ peers which have a match that white-lists the message's filter. Senders
+ of signal messages can use either a single connection ID as receiver,
+ or the special connection ID
+ <constant>KDBUS_DST_ID_BROADCAST</constant> to potentially send it to
+ all connections of a bus, following the logic described above. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Policy</title>
+ <para>
+ A policy is a set of rules that define which connections can see, talk
+ to, or register a well-known name on the bus. A policy is attached to
+ buses and custom endpoints, and modified by policy holder connections or
+ owners of custom endpoints. See
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Privileged bus users</title>
+ <para>
+ A user connecting to the bus is considered privileged if it is either
+ the creator of the bus, or if it has the CAP_IPC_OWNER capability flag
+ set. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Bus Layout</title>
+
+ <para>
+ A <emphasis>bus</emphasis> provides and defines an environment that peers
+ can connect to for message interchange. A bus is created via the kdbus
+ control interface and can be modified by the bus creator. It applies the
+ policy that control all bus operations. The bus creator itself does not
+ participate as a peer. To establish a peer
+ <emphasis>connection</emphasis>, you have to open one of the
+ <emphasis>endpoints</emphasis> of a bus. Each bus provides a default
+ endpoint, but further endpoints can be created on-demand. Endpoints are
+ used to apply additional policies for all connections on this endpoint.
+ Thus, they provide additional filters to further restrict access of
+ specific connections to the bus.
+ </para>
+
+ <para>
+ Following, you can see an example bus layout:
+ </para>
+
+ <programlisting><![CDATA[
+ Bus Creator
+ |
+ |
+ +-----+
+ | Bus |
+ +-----+
+ |
+ __________________/ \__________________
+ / \
+ | |
+ +----------+ +----------+
+ | Endpoint | | Endpoint |
+ +----------+ +----------+
+ _________/|\_________ _________/|\_________
+ / | \ / | \
+ | | | | | |
+ | | | | | |
+ Connection Connection Connection Connection Connection Connection
+ ]]></programlisting>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Data structures and interconnections</title>
+ <programlisting><![CDATA[
+ +--------------------------------------------------------------------------+
+ | Domain (Mount Point) |
+ | /sys/fs/kdbus/control |
+ | +----------------------------------------------------------------------+ |
+ | | Bus (System Bus) | |
+ | | /sys/fs/kdbus/0-system/ | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | | Endpoint | | Endpoint | | |
+ | | | /sys/fs/kdbus/0-system/bus | | /sys/fs/kdbus/0-system/ep.app | | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | | | Connection | | Connection | | Connection | | Connection | | |
+ | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | +----------------------------------------------------------------------+ |
+ | |
+ | +----------------------------------------------------------------------+ |
+ | | Bus (User Bus for UID 2702) | |
+ | | /sys/fs/kdbus/2702-user/ | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | | Endpoint | | Endpoint | | |
+ | | | /sys/fs/kdbus/2702-user/bus | | /sys/fs/kdbus/2702-user/ep.app | | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | | | Connection | | Connection | | Connection | | Connection | | |
+ | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | |
+ | | +--------------+ +--------------+ +--------------------------------+ | |
+ | +----------------------------------------------------------------------+ |
+ +--------------------------------------------------------------------------+
+ ]]></programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Metadata</title>
+
+ <refsect2>
+ <title>When metadata is collected</title>
+ <para>
+ kdbus records data about the system in certain situations. Such metadata
+ can refer to the currently active process (creds, PIDs, current user
+ groups, process names and its executable path, cgroup membership,
+ capabilities, security label and audit information), connection
+ information (description string, currently owned names) and time stamps.
+ </para>
+ <para>
+ Metadata is collected at the following times.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ When a bus is created (<constant>KDBUS_CMD_MAKE</constant>),
+ information about the calling task is collected. This data is returned
+ by the kernel via the <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant>
+ call.
+ </para></listitem>
+
+ <listitem>
+ <para>
+ When a connection is created (<constant>KDBUS_CMD_HELLO</constant>),
+ information about the calling task is collected. Alternatively, a
+ privileged connection may provide 'faked' information about
+ credentials, PIDs and security labels which will be stored instead.
+ This data is returned by the kernel as information on a connection
+ (<constant>KDBUS_CMD_CONN_INFO</constant>). Only metadata that a
+ connection allowed to be sent (by setting its bit in
+ <varname>attach_flags_send</varname>) will be exported in this way.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a message is sent (<constant>KDBUS_CMD_SEND</constant>),
+ information about the sending task and the sending connection are
+ collected. This metadata will be attached to the message when it
+ arrives in the receiver's pool. If the connection sending the
+ message installed faked credentials (see
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>),
+ the message will not be augmented by any information about the
+ currently sending task. Note that only metadata that was requested
+ by the receiving connection will be collected and attached to
+ messages.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Which metadata items are actually delivered depends on the following
+ sets and masks:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ (a) the system-wide kmod creds mask
+ (module parameter <varname>attach_flags_mask</varname>)
+ </para></listitem>
+
+ <listitem><para>
+ (b) the per-connection send creds mask, set by the connecting client
+ </para></listitem>
+
+ <listitem><para>
+ (c) the per-connection receive creds mask, set by the connecting
+ client
+ </para></listitem>
+
+ <listitem><para>
+ (d) the per-bus minimal creds mask, set by the bus creator
+ </para></listitem>
+
+ <listitem><para>
+ (e) the per-bus owner creds mask, set by the bus creator
+ </para></listitem>
+
+ <listitem><para>
+ (f) the mask specified when querying creds of a bus peer
+ </para></listitem>
+
+ <listitem><para>
+ (g) the mask specified when querying creds of a bus owner
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ With the following rules:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ [1] The creds attached to messages are determined as
+ <constant>a & b & c</constant>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [2] When connecting to a bus (<constant>KDBUS_CMD_HELLO</constant>),
+ and <constant>~b & d != 0</constant>, the call will fail with,
+ <errorcode>-1</errorcode>, and <varname>errno</varname> is set to
+ <constant>ECONNREFUSED</constant>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [3] When querying creds of a bus peer, the creds returned are
+ <constant>a & b & f</constant>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ [4] When querying creds of a bus owner, the creds returned are
+ <constant>a & e & g</constant>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Hence, programs might not always get all requested metadata items that
+ it requested. Code must be written so that it can cope with this fact.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Benefits and heads-up</title>
+ <para>
+ Attaching metadata to messages has two major benefits.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Metadata attached to messages is gathered at the moment when the
+ other side calls <constant>KDBUS_CMD_SEND</constant>, or,
+ respectively, then the kernel notification is generated. There is
+ no need for the receiving peer to retrieve information about the
+ task in a second step. This closes a race gap that would otherwise
+ be inherent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ As metadata is delivered along with messages in the same data
+ blob, no extra calls to kernel functions etc. are needed to gather
+ them.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Note, however, that collecting metadata does come at a price for
+ performance, so developers should carefully assess which metadata to
+ really opt-in for. For best practice, data that is not needed as part
+ of a message should not be requested by the connection in the first
+ place (see <varname>attach_flags_recv</varname> in
+ <constant>KDBUS_CMD_HELLO</constant>).
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Attach flags for metadata items</title>
+ <para>
+ To let the kernel know which metadata information to attach as items
+ to the aforementioned commands, it uses a bitmask. In those, the
+ following <emphasis>attach flags</emphasis> are currently supported.
+ Both the the <varname>attach_flags_recv</varname> and
+ <varname>attach_flags_send</varname> fields of
+ <type>struct kdbus_cmd_hello</type>, as well as the payload of the
+ <constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant> and
+ <constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant> items follow this
+ scheme.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_TIMESTAMP</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_TIMESTAMP</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CREDS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CREDS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_PIDS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_PIDS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_AUXGROUPS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_AUXGROUPS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_NAMES</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_OWNED_NAME</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_TID_COMM</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_TID_COMM</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_PID_COMM</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_PID_COMM</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_EXE</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_EXE</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CMDLINE</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CMDLINE</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CGROUP</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CGROUP</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CAPS</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CAPS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_SECLABEL</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_SECLABEL</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_AUDIT</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_AUDIT</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ATTACH_CONN_DESCRIPTION</constant></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for detailed information about the layout and payload of items and
+ what metadata should be used to.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>The ioctl interface</title>
+
+ <para>
+ As stated in the 'synopsis' section above, application developers are
+ strongly encouraged to use kdbus through one of the high-level D-Bus
+ abstraction libraries, rather than using the low-level API directly.
+ </para>
+
+ <para>
+ kdbus on the kernel level exposes its functions exclusively through
+ <citerefentry>
+ <refentrytitle>ioctl</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>,
+ employed on file descriptors returned by
+ <citerefentry>
+ <refentrytitle>open</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on pseudo files exposed by
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+ <para>
+ Following is a list of all the ioctls, along with the command structs
+ they must be used with.
+ </para>
+
+ <informaltable frame="none">
+ <tgroup cols="3" colsep="1">
+ <thead>
+ <row>
+ <entry>ioctl signature</entry>
+ <entry>command</entry>
+ <entry>transported struct</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><constant>0x40189500</constant></entry>
+ <entry><constant>KDBUS_CMD_BUS_MAKE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x40189510</constant></entry>
+ <entry><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0xc0609580</constant></entry>
+ <entry><constant>KDBUS_CMD_HELLO</constant></entry>
+ <entry><type>struct kdbus_cmd_hello *</type></entry>
+ </row><row>
+ <entry><constant>0x40189582</constant></entry>
+ <entry><constant>KDBUS_CMD_BYEBYE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x40389590</constant></entry>
+ <entry><constant>KDBUS_CMD_SEND</constant></entry>
+ <entry><type>struct kdbus_cmd_send *</type></entry>
+ </row><row>
+ <entry><constant>0x80409591</constant></entry>
+ <entry><constant>KDBUS_CMD_RECV</constant></entry>
+ <entry><type>struct kdbus_cmd_recv *</type></entry>
+ </row><row>
+ <entry><constant>0x40209583</constant></entry>
+ <entry><constant>KDBUS_CMD_FREE</constant></entry>
+ <entry><type>struct kdbus_cmd_free *</type></entry>
+ </row><row>
+ <entry><constant>0x401895a0</constant></entry>
+ <entry><constant>KDBUS_CMD_NAME_ACQUIRE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x401895a1</constant></entry>
+ <entry><constant>KDBUS_CMD_NAME_RELEASE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x80289586</constant></entry>
+ <entry><constant>KDBUS_CMD_LIST</constant></entry>
+ <entry><type>struct kdbus_cmd_list *</type></entry>
+ </row><row>
+ <entry><constant>0x80309584</constant></entry>
+ <entry><constant>KDBUS_CMD_CONN_INFO</constant></entry>
+ <entry><type>struct kdbus_cmd_info *</type></entry>
+ </row><row>
+ <entry><constant>0x40209551</constant></entry>
+ <entry><constant>KDBUS_CMD_UPDATE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x80309585</constant></entry>
+ <entry><constant>KDBUS_CMD_BUS_CREATOR_INFO</constant></entry>
+ <entry><type>struct kdbus_cmd_info *</type></entry>
+ </row><row>
+ <entry><constant>0x40189511</constant></entry>
+ <entry><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></entry>
+ <entry><type>struct kdbus_cmd *</type></entry>
+ </row><row>
+ <entry><constant>0x402095b0</constant></entry>
+ <entry><constant>KDBUS_CMD_MATCH_ADD</constant></entry>
+ <entry><type>struct kdbus_cmd_match *</type></entry>
+ </row><row>
+ <entry><constant>0x402095b1</constant></entry>
+ <entry><constant>KDBUS_CMD_MATCH_REMOVE</constant></entry>
+ <entry><type>struct kdbus_cmd_match *</type></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ Depending on the type of <emphasis>kdbusfs</emphasis> node that was
+ opened and what ioctls have been executed on a file descriptor before,
+ a different sub-set of ioctl commands is allowed.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ On a file descriptor resulting from opening a
+ <emphasis>control node</emphasis>, only the
+ <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl may be executed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On a file descriptor resulting from opening a
+ <emphasis>bus endpoint node</emphasis>, only the
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> and
+ <constant>KDBUS_CMD_HELLO</constant> ioctls may be executed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A file descriptor that was used to create a bus
+ (via <constant>KDBUS_CMD_BUS_MAKE</constant>) is called a
+ <emphasis>bus owner</emphasis> file descriptor. The bus will be
+ active as long as the file descriptor is kept open.
+ A bus owner file descriptor can not be used to
+ employ any further ioctls. As soon as
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ is called on it, the bus will be shut down, along will all associated
+ endpoints and connections. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A file descriptor that was used to create an endpoint
+ (via <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>) is called an
+ <emphasis>endpoint owner</emphasis> file descriptor. The endpoint
+ will be active as long as the file descriptor is kept open.
+ An endpoint owner file descriptor can only be used
+ to update details of an endpoint through the
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> ioctl. As soon as
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ is called on it, the endpoint will be removed from the bus, and all
+ connections that are connected to the bus through it are shut down.
+ See
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A file descriptor that was used to create a connection
+ (via <constant>KDBUS_CMD_HELLO</constant>) is called a
+ <emphasis>connection owner</emphasis> file descriptor. The connection
+ will be active as long as the file descriptor is kept open.
+ A connection owner file descriptor may be used to
+ issue any of the following ioctls.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ <constant>KDBUS_CMD_UPDATE</constant> to tweak details of the
+ connection. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_BYEBYE</constant> to shut down a connection
+ without losing messages. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_FREE</constant> to free a slice of memory in
+ the pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_CONN_INFO</constant> to retrieve information
+ on other connections on the bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> to retrieve
+ information on the bus creator. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_LIST</constant> to retrieve a list of
+ currently active well-known names and unique IDs on the bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_SEND</constant> and
+ <constant>KDBUS_CMD_RECV</constant> to send or receive a message.
+ See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> and
+ <constant>KDBUS_CMD_NAME_RELEASE</constant> to acquire or release
+ a well-known name on the bus. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+
+ <listitem><para>
+ <constant>KDBUS_CMD_MATCH_ADD</constant> and
+ <constant>KDBUS_CMD_MATCH_REMOVE</constant> to add or remove
+ a match for signal messages. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ These ioctls, along with the structs they transport, are explained in
+ detail in the other documents linked to in the 'see also' section below.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>ioctl</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>open</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>close</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>
+ </member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
diff --git a/Documentation/kdbus/stylesheet.xsl b/Documentation/kdbus/stylesheet.xsl
new file mode 100644
index 000000000000..52565eac7d0d
--- /dev/null
+++ b/Documentation/kdbus/stylesheet.xsl
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <param name="chunk.quietly">1</param>
+ <param name="funcsynopsis.style">ansi</param>
+ <param name="funcsynopsis.tabular.threshold">80</param>
+ <param name="callout.graphics">0</param>
+ <param name="paper.type">A4</param>
+ <param name="generate.section.toc.level">2</param>
+ <param name="use.id.as.filename">1</param>
+ <param name="citerefentry.link">1</param>
+ <strip-space elements="*"/>
+ <template name="generate.citerefentry.link">
+ <value-of select="refentrytitle"/>
+ <text>.html</text>
+ </template>
+</stylesheet>
diff --git a/Makefile b/Makefile
index 1100ff3c77e3..08c98188a37a 100644
--- a/Makefile
+++ b/Makefile
@@ -1350,6 +1350,7 @@ $(help-board-dirs): help-%:
%docs: scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
+ $(Q)$(MAKE) $(build)=Documentation/kdbus $@
else # KBUILD_EXTMOD
--
2.3.1
next prev parent reply other threads:[~2015-03-09 13:09 UTC|newest]
Thread overview: 77+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-03-09 13:09 [PATCH v4 00/14] Add kdbus implementation Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 02/14] kdbus: add uapi header file Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 05/14] kdbus: add connection, queue handling and message validation code Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 06/14] kdbus: add node and filesystem implementation Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 07/14] kdbus: add code to gather metadata Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 08/14] kdbus: add code for notifications and matches Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 09/14] kdbus: add code for buses, domains and endpoints Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 11/14] kdbus: add policy database implementation Greg Kroah-Hartman
[not found] ` <1425906560-13798-1-git-send-email-gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org>
2015-03-09 13:09 ` Greg Kroah-Hartman [this message]
2015-03-09 13:09 ` [PATCH 01/14] kdbus: add documentation Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 03/14] kdbus: add driver skeleton, ioctl entry points and utility functions Greg Kroah-Hartman
2015-03-09 13:09 ` Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 04/14] kdbus: add connection pool implementation Greg Kroah-Hartman
2015-03-09 13:09 ` Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 10/14] kdbus: add name registry implementation Greg Kroah-Hartman
2015-03-09 13:09 ` Greg Kroah-Hartman
2015-03-09 13:09 ` [PATCH 12/14] kdbus: add Makefile, Kconfig and MAINTAINERS entry Greg Kroah-Hartman
2015-03-09 13:09 ` Greg Kroah-Hartman
2015-03-24 15:15 ` Jiri Slaby
2015-03-24 18:51 ` [PATCH] kdbus: Fix CONFIG_KDBUS help text Daniel Mack
2015-03-25 1:05 ` David Herrmann
2015-03-25 9:51 ` Greg KH
2015-03-09 13:09 ` [PATCH 13/14] kdbus: add walk-through user space example Greg Kroah-Hartman
2015-03-09 13:09 ` Greg Kroah-Hartman
2015-03-12 14:52 ` Sasha Levin
2015-03-12 16:27 ` [PATCH] samples/kdbus: add -lrt David Herrmann
2015-03-12 21:40 ` [PATCH] kdbus: " Greg Kroah-Hartman
[not found] ` <5501A848.5080402-QHcLZuEGTsvQT0dZR+AlfA@public.gmane.org>
2015-03-12 16:34 ` [PATCH 13/14] kdbus: add walk-through user space example David Herrmann
2015-03-12 16:34 ` David Herrmann
[not found] ` <1425906560-13798-14-git-send-email-gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org>
2015-03-24 16:46 ` Jiri Slaby
2015-03-24 16:46 ` Jiri Slaby
[not found] ` <551194C8.4070707-AlSwsSmVLrQ@public.gmane.org>
2015-03-24 17:15 ` David Herrmann
2015-03-24 17:15 ` David Herrmann
2015-03-24 17:37 ` Jiri Slaby
2015-03-24 18:22 ` Michal Marek
2015-03-24 18:51 ` Daniel Mack
2015-03-31 13:11 ` [PATCH] samples: kdbus: build kdbus-workers conditionally Daniel Mack
2015-04-01 12:47 ` Greg KH
2015-04-01 21:41 ` Andrew Morton
2015-04-03 11:02 ` Daniel Mack
2015-03-09 13:09 ` [PATCH 14/14] kdbus: add selftests Greg Kroah-Hartman
2015-03-15 5:13 ` [PATCH] kdbus: fix minor typo in the walk-through example Nicolas Iooss
2015-03-15 9:32 ` Greg KH
2015-03-17 19:24 ` [PATCH v4 00/14] Add kdbus implementation Andy Lutomirski
[not found] ` <CALCETrUjqTH14fZCeqU_OBoKX_6x4B=712WTeSqSAztpgXGiDw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-18 13:54 ` David Herrmann
2015-03-18 13:54 ` David Herrmann
[not found] ` <CANq1E4Tf_6Cn+sxY=BPEbRpEr5WY+-rRX5gipz-_=4PNLa9bnQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-18 18:24 ` Andy Lutomirski
2015-03-18 18:24 ` Andy Lutomirski
[not found] ` <CALCETrVWbz7YudNQXQD_2PjC1HR0P0cB_1ea8NiYoQPDfQxERg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-19 11:26 ` David Herrmann
2015-03-19 11:26 ` David Herrmann
[not found] ` <CANq1E4RA1ok=3Z5W2LkzqaUOKtbMVX_Joxe7_LRbLnQgfRUEYA-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-19 15:48 ` Andy Lutomirski
2015-03-19 15:48 ` Andy Lutomirski
2015-03-23 15:28 ` David Herrmann
[not found] ` <CANq1E4TtXq02Ug22fsTr8j0X6+vJKvyryALiTEMbT4SMQB1j3g-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-23 23:24 ` Andy Lutomirski
2015-03-23 23:24 ` Andy Lutomirski
[not found] ` <CALCETrXqYBeZuOWhm9mz_nt+aWPXHFwkQPEAfwBXzDxnAP7f+g-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-24 0:20 ` Eric W. Biederman
2015-03-24 0:20 ` Eric W. Biederman
2015-03-25 17:29 ` David Herrmann
2015-03-25 17:29 ` David Herrmann
[not found] ` <CANq1E4QiErHp8Q6bzFLkK9=7eBZC8dvh+Xnrh9_D5DAAogyaZA-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-25 18:12 ` Andy Lutomirski
2015-03-25 18:12 ` Andy Lutomirski
[not found] ` <CALCETrUuWhtJ9w9vyCGgaJDMGithJad4A4wf-BuxWLb_af5eDg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-30 16:56 ` David Herrmann
2015-03-30 16:56 ` David Herrmann
[not found] ` <CANq1E4TTt3qanQse30KOZsuo2tfNoj7YSueh3AZ7bY1nQQeZNA-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-31 13:58 ` Andy Lutomirski
2015-03-31 13:58 ` Andy Lutomirski
[not found] ` <CALCETrV-cHYzcWu3t6tJ1eP0UZHTqoGH0KTYHTpJNit9-59TAA-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-31 15:10 ` Tom Gundersen
2015-03-31 15:10 ` Tom Gundersen
[not found] ` <CAG-2HqVwfH5fK0YV1+k3T4bFqd5v3Yd-hpL-bTSBK23FFY-zMA-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-03-31 18:29 ` Andy Lutomirski
2015-03-31 18:29 ` Andy Lutomirski
[not found] ` <CALCETrX3vDZsymwC=LK=oK0=QLZqyB2Nv4N8jcjsx2yp1rjBvg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-04-03 11:51 ` David Herrmann
2015-04-03 11:51 ` David Herrmann
[not found] ` <CANq1E4QSja-KhVL2p-d406uLJT600zMpK2UAcwsb0LkMwa8F7w-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2015-04-05 12:09 ` Eric W. Biederman
2015-04-05 12:09 ` Eric W. Biederman
[not found] ` <FFF43E89-B796-4BDE-893A-5CC2AE77AED7-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
2015-04-05 13:46 ` Greg Kroah-Hartman
2015-04-05 13:46 ` Greg Kroah-Hartman
2015-04-08 22:38 ` Andy Lutomirski
2015-04-08 22:38 ` Andy Lutomirski
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1425906560-13798-2-git-send-email-gregkh@linuxfoundation.org \
--to=gregkh-hqyy1w1ycw8ekmwlsbkhg0b+6bgklq7r@public.gmane.org \
--cc=arnd-r2nGTMty4D4@public.gmane.org \
--cc=daniel-cYrQPVfZoowdnm+yROfE0A@public.gmane.org \
--cc=dh.herrmann-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org \
--cc=ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org \
--cc=gnomes-qBU/x9rampVanCEyBjwyrvXRex20P6io@public.gmane.org \
--cc=jkosina-AlSwsSmVLrQ@public.gmane.org \
--cc=linux-api-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
--cc=linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
--cc=luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org \
--cc=teg-B22kvLQNl6c@public.gmane.org \
--cc=tixxdz-Umm1ozX2/EEdnm+yROfE0A@public.gmane.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.