7489 lines
274 KiB
Diff
7489 lines
274 KiB
Diff
From: Daniel Mack <daniel@zonque.org>
|
|
Date: Thu, 11 Sep 2014 21:50:47 +0200
|
|
Subject: [PATCH] kdbus: add documentation
|
|
|
|
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 bc0548201755..e2127a76b5d6 100644
|
|
--- a/Documentation/Makefile
|
|
+++ b/Documentation/Makefile
|
|
@@ -1,4 +1,4 @@
|
|
subdir-y := accounting 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 4ce793e576cf..1df89975465f 100644
|
|
--- a/Makefile
|
|
+++ b/Makefile
|
|
@@ -1344,6 +1344,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
|
|
|