ipc/kdbus/Documentation/kdbus.match.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <refentry id="kdbus.match">
   6
   7   <refentryinfo>
   8     <title>kdbus.match</title>
   9     <productname>kdbus.match</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus.match</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus.match</refname>
  19     <refpurpose>kdbus match</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24
  25     <para>
  26       kdbus connections can install matches in order to subscribe to signal
  27       messages sent on the bus. Such signal messages can be either directed
  28       to a single connection (by setting a specific connection ID in
  29       <varname>struct kdbus_msg.dst_id</varname> or by sending it to a
  30       well-known name), or to potentially <emphasis>all</emphasis> currently
  31       active connections on the bus (by setting
  32       <varname>struct kdbus_msg.dst_id</varname> to
  33       <constant>KDBUS_DST_ID_BROADCAST</constant>).
  34       A signal message always has the <constant>KDBUS_MSG_SIGNAL</constant>
  35       bit set in the <varname>flags</varname> bitfield.
  36       Also, signal messages can originate from either the kernel (called
  37       <emphasis>notifications</emphasis>), or from other bus connections.
  38       In either case, a bus connection needs to have a suitable
  39       <emphasis>match</emphasis> installed in order to receive any signal
  40       message. Without any rules installed in the connection, no signal message
  41       will be received.
  42     </para>
  43   </refsect1>
  44
  45   <refsect1>
  46     <title>Matches for signal messages from other connections</title>
  47     <para>
  48       Matches for messages from other connections (not kernel notifications)
  49       are implemented as bloom filters (see below). The sender adds certain
  50       properties of the message as elements to a bloom filter bit field, and
  51       sends that along with the signal message.
  52
  53       The receiving connection adds the message properties it is interested in
  54       as elements to a bloom mask bit field, and uploads the mask as match rule,
  55       possibly along with some other rules to further limit the match.
  56
  57       The kernel will match the signal message's bloom filter against the
  58       connection's bloom mask (simply by &amp;-ing it), and will decide whether
  59       the message should be delivered to a connection.
  60     </para>
  61     <para>
  62       The kernel has no notion of any specific properties of the signal message,
  63       all it sees are the bit fields of the bloom filter and the mask to match
  64       against. The use of bloom filters allows simple and efficient matching,
  65       without exposing any message properties or internals to the kernel side.
  66       Clients need to deal with the fact that they might receive signal messages
  67       which they did not subscribe to, as the bloom filter might allow
  68       false-positives to pass the filter.
  69
  70       To allow the future extension of the set of elements in the bloom filter,
  71       the filter specifies a <emphasis>generation</emphasis> number. A later
  72       generation must always contain all elements of the set of the previous
  73       generation, but can add new elements to the set. The match rules mask can
  74       carry an array with all previous generations of masks individually stored.
  75       When the filter and mask are matched by the kernel, the mask with the
  76       closest matching generation is selected as the index into the mask array.
  77     </para>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Bloom filters</title>
  82     <para>
  83       Bloom filters allow checking whether a given word is present in a
  84       dictionary.  This allows connections to set up a mask for information it
  85       is interested in, and will be delivered signal messages that have a
  86       matching filter.
  87
  88       For general information, see
  89       <ulink url="https://en.wikipedia.org/wiki/Bloom_filter">the Wikipedia
  90       article on bloom filters</ulink>.
  91     </para>
  92     <para>
  93       The size of the bloom filter is defined per bus when it is created, in
  94       <varname>kdbus_bloom_parameter.size</varname>. All bloom filters attached
  95       to signal messages on the bus must match this size, and all bloom filter
  96       matches uploaded by connections must also match the size, or a multiple
  97       thereof (see below).
  98
  99       The calculation of the mask has to be done in userspace applications. The
 100       kernel just checks the bitmasks to decide whether or not to let the
 101       message pass. All bits in the mask must match the filter in and bit-wise
 102       <emphasis>AND</emphasis> logic, but the mask may have more bits set than
 103       the filter. Consequently, false positive matches are expected to happen,
 104       and programs must deal with that fact by checking the contents of the
 105       payload again at receive time.
 106     </para>
 107     <para>
 108       Masks are entities that are always passed to the kernel as part of a
 109       match (with an item of type <constant>KDBUS_ITEM_BLOOM_MASK</constant>),
 110       and filters can be attached to signals, with an item of type
 111       <constant>KDBUS_ITEM_BLOOM_FILTER</constant>. For a filter to match, all
 112       its bits have to be set in the match mask as well.
 113     </para>
 114     <para>
 115       For example, consider a bus that has a bloom size of 8 bytes, and the
 116       following mask/filter combinations:
 117     </para>
 118     <programlisting><![CDATA[
 119           filter  0x0101010101010101
 120           mask    0x0101010101010101
 121                   -> matches
 122
 123           filter  0x0303030303030303
 124           mask    0x0101010101010101
 125                   -> doesn't match
 126
 127           filter  0x0101010101010101
 128           mask    0x0303030303030303
 129                   -> matches
 130     ]]></programlisting>
 131
 132     <para>
 133       Hence, in order to catch all messages, a mask filled with
 134       <constant>0xff</constant> bytes can be installed as a wildcard match rule.
 135     </para>
 136
 137     <refsect2>
 138       <title>Generations</title>
 139
 140       <para>
 141         Uploaded matches may contain multiple masks, which have to be as large
 142         as the bloom filter size defined by the bus. Each block of a mask is
 143         called a <emphasis>generation</emphasis>, starting at index 0.
 144
 145         At match time, when a signal is about to be delivered, a bloom mask
 146         generation is passed, which denotes which of the bloom masks the filter
 147         should be matched against. This allows programs to provide backward
 148         compatible masks at upload time, while older clients can still match
 149         against older versions of filters.
 150       </para>
 151     </refsect2>
 152   </refsect1>
 153
 154   <refsect1>
 155     <title>Matches for kernel notifications</title>
 156     <para>
 157       To receive kernel generated notifications (see
 158       <citerefentry>
 159         <refentrytitle>kdbus.message</refentrytitle>
 160         <manvolnum>7</manvolnum>
 161       </citerefentry>),
 162       a connection must install match rules that are different from
 163       the bloom filter matches described in the section above. They can be
 164       filtered by the connection ID that caused the notification to be sent, by
 165       one of the names it currently owns, or by the type of the notification
 166       (ID/name add/remove/change).
 167     </para>
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>Adding a match</title>
 172     <para>
 173       To add a match, the <constant>KDBUS_CMD_MATCH_ADD</constant> ioctl is
 174       used, which takes a <type>struct kdbus_cmd_match</type> as an argument
 175       described below.
 176
 177       Note that each of the items attached to this command will internally
 178       create one match <emphasis>rule</emphasis>, and the collection of them,
 179       which is submitted as one block via the ioctl, is called a
 180       <emphasis>match</emphasis>. To allow a message to pass, all rules of a
 181       match have to be satisfied. Hence, adding more items to the command will
 182       only narrow the possibility of a match to effectively let the message
 183       pass, and will decrease the chance that the connection's process will be
 184       woken up needlessly.
 185
 186       Multiple matches can be installed per connection. As long as one of it has
 187       a set of rules which allows the message to pass, this one will be
 188       decisive.
 189     </para>
 190
 191     <programlisting>
 192 struct kdbus_cmd_match {
 193   __u64 size;
 194   __u64 flags;
 195   __u64 return_flags;
 196   __u64 cookie;
 197   struct kdbus_item items[0];
 198 };
 199     </programlisting>
 200
 201     <para>The fields in this struct are described below.</para>
 202
 203     <variablelist>
 204       <varlistentry>
 205         <term><varname>size</varname></term>
 206         <listitem><para>
 207           The overall size of the struct, including its items.
 208         </para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><varname>flags</varname></term>
 213         <listitem><para>Flags to control the behavior of the ioctl.</para>
 214           <variablelist>
 215             <varlistentry>
 216               <term><constant>KDBUS_MATCH_REPLACE</constant></term>
 217               <listitem>
 218                 <para>Make the endpoint file group-accessible</para>
 219               </listitem>
 220             </varlistentry>
 221
 222             <varlistentry>
 223               <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
 224               <listitem>
 225                 <para>
 226                   Requests a set of valid flags for this ioctl. When this bit is
 227                   set, no action is taken; the ioctl will return
 228                   <errorcode>0</errorcode>, and the <varname>flags</varname>
 229                   field will have all bits set that are valid for this command.
 230                   The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
 231                   cleared by the operation.
 232                 </para>
 233               </listitem>
 234             </varlistentry>
 235           </variablelist>
 236         </listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term><varname>return_flags</varname></term>
 241         <listitem><para>
 242           Flags returned by the kernel. Currently unused and always set to
 243           <constant>0</constant> by the kernel.
 244         </para></listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><varname>cookie</varname></term>
 249         <listitem><para>
 250           A cookie which identifies the match, so it can be referred to when
 251           removing it.
 252         </para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><varname>items</varname></term>
 257         <listitem>
 258         <para>
 259           Items to define the actual rules of the matches. The following item
 260           types are expected. Each item will create one new match rule.
 261         </para>
 262           <variablelist>
 263             <varlistentry>
 264               <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
 265               <listitem>
 266                 <para>
 267                   An item that carries the bloom filter mask to match against
 268                   in its data field. The payload size must match the bloom
 269                   filter size that was specified when the bus was created.
 270                   See the "Bloom filters" section above for more information on
 271                   bloom filters.
 272                 </para>
 273               </listitem>
 274             </varlistentry>
 275
 276             <varlistentry>
 277               <term><constant>KDBUS_ITEM_NAME</constant></term>
 278               <listitem>
 279                 <para>
 280                   When used as part of kernel notifications, this item specifies
 281                   a name that is acquired, lost or that changed its owner (see
 282                   below). When used as part of a match for user-generated signal
 283                   messages, it specifies a name that the sending connection must
 284                   own at the time of sending the signal.
 285                 </para>
 286               </listitem>
 287             </varlistentry>
 288
 289             <varlistentry>
 290               <term><constant>KDBUS_ITEM_ID</constant></term>
 291               <listitem>
 292                 <para>
 293                   Specify a sender connection's ID that will match this rule.
 294                   For kernel notifications, this specifies the ID of a
 295                   connection that was added to or removed from the bus.
 296                   For used-generated signals, it specifies the ID of the
 297                   connection that sent the signal message.
 298                 </para>
 299               </listitem>
 300             </varlistentry>
 301
 302             <varlistentry>
 303               <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
 304               <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
 305               <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
 306               <listitem>
 307                 <para>
 308                   These items request delivery of kernel notifications that
 309                   describe a name acquisition, loss, or change. The details
 310                   are stored in the item's
 311                   <varname>kdbus_notify_name_change</varname> member.
 312                   All information specified must be matched in order to make
 313                   the message pass. Use
 314                   <constant>KDBUS_MATCH_ID_ANY</constant> to
 315                   match against any unique connection ID.
 316                 </para>
 317               </listitem>
 318             </varlistentry>
 319
 320             <varlistentry>
 321               <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
 322               <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
 323               <listitem>
 324                 <para>
 325                   These items request delivery of kernel notifications that are
 326                   generated when a connection is created or terminated.
 327                   <type>struct kdbus_notify_id_change</type> is used to
 328                   store the actual match information. This item can be used to
 329                   monitor one particular connection ID, or, when the ID field
 330                   is set to <constant>KDBUS_MATCH_ID_ANY</constant>,
 331                   all of them.
 332                 </para>
 333               </listitem>
 334             </varlistentry>
 335
 336             <varlistentry>
 337               <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
 338               <listitem><para>
 339                 With this item, programs can <emphasis>probe</emphasis> the
 340                 kernel for known item types. See
 341                 <citerefentry>
 342                   <refentrytitle>kdbus.item</refentrytitle>
 343                   <manvolnum>7</manvolnum>
 344                 </citerefentry>
 345                 for more details.
 346               </para></listitem>
 347             </varlistentry>
 348           </variablelist>
 349
 350           <para>
 351             Unrecognized items are rejected, and the ioctl will fail with
 352             <varname>errno</varname> set to <constant>EINVAL</constant>.
 353           </para>
 354         </listitem>
 355       </varlistentry>
 356     </variablelist>
 357
 358     <para>
 359       Refer to
 360       <citerefentry>
 361         <refentrytitle>kdbus.message</refentrytitle>
 362         <manvolnum>7</manvolnum>
 363       </citerefentry>
 364       for more information on message types.
 365     </para>
 366   </refsect1>
 367
 368   <refsect1>
 369     <title>Removing a match</title>
 370     <para>
 371       Matches can be removed with the
 372       <constant>KDBUS_CMD_MATCH_REMOVE</constant> ioctl, which takes
 373       <type>struct kdbus_cmd_match</type> as argument, but its fields
 374       usage slightly differs compared to that of
 375       <constant>KDBUS_CMD_MATCH_ADD</constant>.
 376     </para>
 377
 378     <programlisting>
 379 struct kdbus_cmd_match {
 380   __u64 size;
 381   __u64 cookie;
 382   __u64 flags;
 383   __u64 return_flags;
 384   struct kdbus_item items[0];
 385 };
 386     </programlisting>
 387
 388     <para>The fields in this struct are described below.</para>
 389
 390     <variablelist>
 391       <varlistentry>
 392         <term><varname>size</varname></term>
 393         <listitem><para>
 394           The overall size of the struct, including its items.
 395         </para></listitem>
 396       </varlistentry>
 397
 398       <varlistentry>
 399         <term><varname>cookie</varname></term>
 400         <listitem><para>
 401           The cookie of the match, as it was passed when the match was added.
 402           All matches that have this cookie will be removed.
 403         </para></listitem>
 404       </varlistentry>
 405
 406       <varlistentry>
 407         <term><varname>flags</varname></term>
 408         <listitem><para>
 409           No flags are supported for this use case.
 410           <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
 411           valid flags. If set, the ioctl will fail with
 412           <errorcode>-1</errorcode>, <varname>errno</varname> is set to
 413           <constant>EPROTO</constant>, and the <varname>flags</varname> field
 414           is set to <constant>0</constant>.
 415         </para></listitem>
 416       </varlistentry>
 417
 418       <varlistentry>
 419         <term><varname>return_flags</varname></term>
 420         <listitem><para>
 421           Flags returned by the kernel. Currently unused and always set to
 422           <constant>0</constant> by the kernel.
 423         </para></listitem>
 424       </varlistentry>
 425
 426       <varlistentry>
 427         <term><varname>items</varname></term>
 428         <listitem>
 429           <para>
 430             No items are supported for this use case, but
 431             <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed nevertheless.
 432           </para>
 433         </listitem>
 434       </varlistentry>
 435     </variablelist>
 436   </refsect1>
 437
 438   <refsect1>
 439     <title>Return value</title>
 440     <para>
 441       On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
 442       on error, <errorcode>-1</errorcode> is returned, and
 443       <varname>errno</varname> is set to indicate the error.
 444       If the issued ioctl is illegal for the file descriptor used,
 445       <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
 446     </para>
 447
 448     <refsect2>
 449       <title>
 450         <constant>KDBUS_CMD_MATCH_ADD</constant> may fail with the following
 451         errors
 452       </title>
 453
 454       <variablelist>
 455         <varlistentry>
 456           <term><constant>EINVAL</constant></term>
 457           <listitem><para>
 458             Illegal flags or items.
 459           </para></listitem>
 460         </varlistentry>
 461
 462         <varlistentry>
 463           <term><constant>EDOM</constant></term>
 464           <listitem><para>
 465             Illegal bloom filter size.
 466           </para></listitem>
 467         </varlistentry>
 468
 469         <varlistentry>
 470           <term><constant>EMFILE</constant></term>
 471           <listitem><para>
 472             Too many matches for this connection.
 473           </para></listitem>
 474         </varlistentry>
 475       </variablelist>
 476     </refsect2>
 477
 478     <refsect2>
 479       <title>
 480         <constant>KDBUS_CMD_MATCH_REMOVE</constant> may fail with the following
 481         errors
 482       </title>
 483
 484       <variablelist>
 485         <varlistentry>
 486           <term><constant>EINVAL</constant></term>
 487           <listitem><para>
 488             Illegal flags.
 489           </para></listitem>
 490         </varlistentry>
 491
 492         <varlistentry>
 493           <term><constant>EBADSLT</constant></term>
 494           <listitem><para>
 495             A match entry with the given cookie could not be found.
 496           </para></listitem>
 497         </varlistentry>
 498       </variablelist>
 499     </refsect2>
 500   </refsect1>
 501
 502   <refsect1>
 503     <title>See Also</title>
 504     <simplelist type="inline">
 505       <member>
 506         <citerefentry>
 507           <refentrytitle>kdbus</refentrytitle>
 508           <manvolnum>7</manvolnum>
 509         </citerefentry>
 510       </member>
 511       <member>
 512         <citerefentry>
 513           <refentrytitle>kdbus.bus</refentrytitle>
 514           <manvolnum>7</manvolnum>
 515         </citerefentry>
 516       </member>
 517       <member>
 518         <citerefentry>
 519           <refentrytitle>kdbus.match</refentrytitle>
 520           <manvolnum>7</manvolnum>
 521         </citerefentry>
 522       </member>
 523       <member>
 524         <citerefentry>
 525           <refentrytitle>kdbus.fs</refentrytitle>
 526           <manvolnum>7</manvolnum>
 527         </citerefentry>
 528       </member>
 529       <member>
 530         <citerefentry>
 531           <refentrytitle>kdbus.item</refentrytitle>
 532           <manvolnum>7</manvolnum>
 533         </citerefentry>
 534       </member>
 535       <member>
 536         <citerefentry>
 537           <refentrytitle>kdbus.message</refentrytitle>
 538           <manvolnum>7</manvolnum>
 539         </citerefentry>
 540       </member>
 541       <member>
 542         <citerefentry>
 543           <refentrytitle>kdbus.name</refentrytitle>
 544           <manvolnum>7</manvolnum>
 545         </citerefentry>
 546       </member>
 547       <member>
 548         <citerefentry>
 549           <refentrytitle>kdbus.pool</refentrytitle>
 550           <manvolnum>7</manvolnum>
 551         </citerefentry>
 552       </member>
 553     </simplelist>
 554   </refsect1>
 555 </refentry>