From e3af3d0d3597ec230c0259d9521a5eb2276008ab Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Tue, 27 Jan 2015 11:02:28 +0100 Subject: [PATCH] doc: add kdbus.match.xml Not finished yet. Signed-off-by: Daniel Mack --- doc/Makefile | 1 + doc/kdbus.match.xml | 464 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 465 insertions(+) create mode 100644 doc/kdbus.match.xml diff --git a/doc/Makefile b/doc/Makefile index 324988d..3aac6d3 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,6 +5,7 @@ docs= \ kdbus.endpoint.xml \ kdbus.fs.xml \ kdbus.item.xml \ + kdbus.match.xml \ kdbus.message.xml \ kdbus.names.xml \ kdbus.policy.xml \ diff --git a/doc/kdbus.match.xml b/doc/kdbus.match.xml new file mode 100644 index 0000000..647eb2f --- /dev/null +++ b/doc/kdbus.match.xml @@ -0,0 +1,464 @@ + + + + + + + kdbus.match + kdbus.match + + + + kdbus.match + 7 + + + + kdbus.match + kdbus match + + + + Description + + + TODO + + + + + Matches for broadcast messages from other connections + + A message addressed at the connection ID + KDBUS_DST_ID_BROADCAST (~0ULL) is a broadcast message, + delivered to all connected peers which installed a rule to match certain + properties of the message. Without any rules installed in the connection, + no broadcast message or kernel-side notifications will be delivered + to the connection. Broadcast messages are subject to policy rules and TALK + access checks - see + kdbus.policy7 + for more details on implicit policies. + + + Matches for messages from other connections (not kernel notifications) are + implemented as bloom filters. The sender adds certain properties of the message + as elements to a bloom filter bit field, and sends that along with the + broadcast message. + + The connection adds the message properties it is interested as elements to a + bloom mask bit field, and uploads the mask to the match rules of the + connection. + + The kernel will match the broadcast message's bloom filter against the + connections bloom mask (simply by &-ing it), and decide whether the + message should be delivered to the connection. + + + The kernel has no notion of any specific properties of the message, all it + sees are the bit fields of the bloom filter and 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 broadcasts 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 "generation" 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. + + + + + Matches for kernel notifications + + To receive kernel generated notifications (see + kdbus.message7 + ), a connection must install special match rules that are different from + the bloom filter matches described in the section above. They can be + filtered by a sender connection's ID, by one of the name the sender + connection owns at the time of sending the message, or by the type of + the notification (ID/name add/remove/change). + + + + + Matches for kernel notifications + + To add a match, the KDBUS_CMD_MATCH_ADD 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 'rule', and the collection of them, which is submitted as one block + via the ioctl, is called a 'match'. 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 userspace process wil be woken up. + + 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. + + + +struct kdbus_cmd_match { + __u64 size; + __u64 cookie; + __u64 flags; + __u64 return_flags; + struct kdbus_item items[0]; +}; + + + The fields in this struct are described below. + + + + size + + The overall size of the struct, including its items. + + + + + cookie + + A cookie which identifies the match, so it can be referred to when + removing it. + + + + + flags + Flags to control the behavior of the ioctl. + + + KDBUS_MATCH_REPLACE + + Make the endpoint file group-accessible + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + items + + + Items to define the actual rules of the matches. The following item + types are expected. Each item will create one new match rule. + + + + KDBUS_ITEM_BLOOM_MASK + + + 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. + + + + + + KDBUS_ITEM_NAME + + + Specify a name that a sending connection must own at the + time of sending a broadcast message in order to match this + rule. + + + + + + KDBUS_ITEM_ID + + + Specify a sender connection's ID that will match this rule. + + + + + + KDBUS_ITEM_NAME_ADD + KDBUS_ITEM_NAME_REMOVE + KDBUS_ITEM_NAME_CHANGE + + + These items request delivery of broadcast messages that + describe a name acquisition, loss, or change. The details + are stored in the item's + kdbus_notify_name_change member. + All information specified must be matched in order to make + the message pass. Use + KDBUS_MATCH_ID_ANY to + match against any unique connection ID. + + + + + + KDBUS_ITEM_ID_ADD + KDBUS_ITEM_ID_REMOVE + + + These items request delivery of kernel notofications that are + generated when a connection is created or terminated. + struct kdbus_notify_id_changeis 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 + KDBUS_MATCH_ID_ANY, all of them. + + + + + + + + Unrecognized items are rejected, and the ioctl will fail with + -EINVAL. + + + + + + + Refer to + kdbus.message7 + for more information on message types. + + + + + Removing a match + + Matches can be removed through the + KDBUS_CMD_MATCH_REMOVE ioctl, which takes + struct kdbus_cmd_match as argument, but its fields + usage slightly differs compared to that of + KDBUS_CMD_MATCH_ADD. + + + +struct kdbus_cmd_match { + __u64 size; + __u64 cookie; + __u64 flags; + __u64 kernel_flags; + __u64 return_flags; + struct kdbus_item items[0]; +}; + + + The fields in this struct are described below. + + + + size + + The overall size of the struct, including its items. + + + + + cookie + + The cookie of the match, as it was passed when the match was added. + All matches that have this cookie will be removed. + + + + + flags + + No flags are supported for this use case. + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + items + + + No items are supported for this use case. + + + + + + + + Bloom filters + + 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 + the Wikipedia article on bloom filters + + + The size of the bloom filter is defined per bus when it is created, in + kdbus_bloom_parameter.size. 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 on the userspace side. 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 + AND logic, but the mask may have more bits set than + the filter. Consequently, false positive matches are expected to happen, + and userspace must deal with that fact by checking the contents of the + payload again at receive time. + + + Masks are entities that are always passed to the kernel as part of a + match (with an item of type KDBUS_ITEM_BLOOM_MASK), + and filters can be attached to signals, with an item of type + KDBUS_ITEM_BLOOM_FILTER. For a filter to match, all + its bits have to be set in the match mask as well. + + + For example, consider a bus that has a bloom size of 8 bytes, and the following + mask/filter combinations: + + matches + + filter 0x0303030303030303 + mask 0x0101010101010101 + -> doesn't match + + filter 0x0101010101010101 + mask 0x0303030303030303 + -> matches + ]]> + + + Hence, in order to catch all messages, a mask filled with + 0xff bytes can be installed as a wildcard match rule. + + + + Generations + + + 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 + generation, 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 userspace to provide backward + compatible masks at upload time, while older clients can still match + against older versions of filters. + + + + + + Return value + + On success, all mentioned ioctl commands return 0. + + + + KDBUS_CMD_MATCH_ADD may return the following errors. + + + + + -EINVAL + + Illegal flags or items. + + + + + -EDOM + + Illegal bloom filter size. + + + + + -EMFILE + + Too many matches for this connection. + + + + + + KDBUS_CMD_MATCH_REMOVE may return the following errors. + + + + + -EINVAL + + Illegal flags. + + + + + -EBADSLT + + A match entry with the given cookie could not be found. + + + + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.match7 + kdbus.fs7 + kdbus.item7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + + + -- 2.34.1