path: root/Documentation/kdbus/kdbus.match.xml

<?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
      connection's bloom mask (simply by &amp;-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 to be as large
        as the bloom filter 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 <type>struct kdbus_cmd_match</type> as an argument
      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 "Bloom filters" section above 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>