diff options
Diffstat (limited to 'kdbus-add-documentation.patch')
| -rw-r--r-- | kdbus-add-documentation.patch | 7488 |
1 files changed, 7488 insertions, 0 deletions
diff --git a/kdbus-add-documentation.patch b/kdbus-add-documentation.patch new file mode 100644 index 000000000..7aef55a01 --- /dev/null +++ b/kdbus-add-documentation.patch @@ -0,0 +1,7488 @@ +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 + |