From 57f0f512b273f60d52568b8c6b77e17f5636edc0 Mon Sep 17 00:00:00 2001 From: André Fabian Silva Delgado Date: Wed, 5 Aug 2015 17:04:01 -0300 Subject: Initial import --- Documentation/kdbus/kdbus.match.xml | 555 ++++++++++++++++++++++++++++++++++++ 1 file changed, 555 insertions(+) create mode 100644 Documentation/kdbus/kdbus.match.xml (limited to 'Documentation/kdbus/kdbus.match.xml') diff --git a/Documentation/kdbus/kdbus.match.xml b/Documentation/kdbus/kdbus.match.xml new file mode 100644 index 000000000..ae38e04ab --- /dev/null +++ b/Documentation/kdbus/kdbus.match.xml @@ -0,0 +1,555 @@ + + + + + + + kdbus.match + kdbus.match + + + + kdbus.match + 7 + + + + kdbus.match + kdbus match + + + + Description + + + 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 + struct kdbus_msg.dst_id or by sending it to a + well-known name), or to potentially all currently + active connections on the bus (by setting + struct kdbus_msg.dst_id to + KDBUS_DST_ID_BROADCAST). + A signal message always has the KDBUS_MSG_SIGNAL + bit set in the flags bitfield. + Also, signal messages can originate from either the kernel (called + notifications), or from other bus connections. + In either case, a bus connection needs to have a suitable + match installed in order to receive any signal + message. Without any rules installed in the connection, no signal message + will be received. + + + + + Matches for signal messages from other connections + + 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 &-ing it), and will decide whether + the message should be delivered to a connection. + + + 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 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. + + + + + 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 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 + AND 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. + + + 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 to be as large + as the bloom filter 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 programs to provide backward + compatible masks at upload time, while older clients can still match + against older versions of filters. + + + + + + Matches for kernel notifications + + To receive kernel generated notifications (see + + kdbus.message + 7 + ), + 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). + + + + + Adding a match + + To add a match, the KDBUS_CMD_MATCH_ADD ioctl is + used, which takes a struct kdbus_cmd_match as an argument + 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 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. + + + +struct kdbus_cmd_match { + __u64 size; + __u64 flags; + __u64 return_flags; + __u64 cookie; + struct kdbus_item items[0]; +}; + + + The fields in this struct are described below. + + + + size + + The overall size of the struct, including its items. + + + + + flags + Flags to control the behavior of the ioctl. + + + KDBUS_MATCH_REPLACE + + Make the endpoint file group-accessible + + + + + KDBUS_FLAG_NEGOTIATE + + + Requests a set of valid flags for this ioctl. When this bit is + set, no action is taken; the ioctl will return + 0, and the flags + field will have all bits set that are valid for this command. + The KDBUS_FLAG_NEGOTIATE bit will be + cleared by the operation. + + + + + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + 0 by the kernel. + + + + + cookie + + A cookie which identifies the match, so it can be referred to when + removing it. + + + + + 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 "Bloom filters" section above for more information on + bloom filters. + + + + + + KDBUS_ITEM_NAME + + + 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. + + + + + + KDBUS_ITEM_ID + + + 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. + + + + + + KDBUS_ITEM_NAME_ADD + KDBUS_ITEM_NAME_REMOVE + KDBUS_ITEM_NAME_CHANGE + + + These items request delivery of kernel notifications 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 notifications that are + generated when a connection is created or terminated. + struct kdbus_notify_id_change 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 KDBUS_MATCH_ID_ANY, + all of them. + + + + + + KDBUS_ITEM_NEGOTIATE + + With this item, programs can probe the + kernel for known item types. See + + kdbus.item + 7 + + for more details. + + + + + + Unrecognized items are rejected, and the ioctl will fail with + errno set to EINVAL. + + + + + + + Refer to + + kdbus.message + 7 + + for more information on message types. + + + + + Removing a match + + Matches can be removed with 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 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. + KDBUS_FLAG_NEGOTIATE is accepted to probe for + valid flags. If set, the ioctl will fail with + -1, errno is set to + EPROTO, and the flags field + is set to 0. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + 0 by the kernel. + + + + + items + + + No items are supported for this use case, but + KDBUS_ITEM_NEGOTIATE is allowed nevertheless. + + + + + + + + Return value + + On success, all mentioned ioctl commands return 0; + on error, -1 is returned, and + errno is set to indicate the error. + If the issued ioctl is illegal for the file descriptor used, + errno will be set to ENOTTY. + + + + + <constant>KDBUS_CMD_MATCH_ADD</constant> may fail with the following + errors + + + + + EINVAL + + Illegal flags or items. + + + + + EDOM + + Illegal bloom filter size. + + + + + EMFILE + + Too many matches for this connection. + + + + + + + + <constant>KDBUS_CMD_MATCH_REMOVE</constant> may fail with the following + errors + + + + + EINVAL + + Illegal flags. + + + + + EBADSLT + + A match entry with the given cookie could not be found. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.match + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + -- cgit v1.2.3-54-g00ecf