kdbus.match kdbus.match 7 kdbus.match kdbus match 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 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. 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 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. 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 programs to provide backward compatible masks at upload time, while older clients can still match against older versions of filters. 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). 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 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 section below 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. 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. 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. EINVAL Illegal flags or items. EDOM Illegal bloom filter size. EMFILE Too many matches for this connection. EINVAL Illegal flags. EBADSLT A match entry with the given cookie could not be found. kdbus 7 kdbus.bus 7 kdbus.match 7 kdbus.fs 7 kdbus.item 7 kdbus.message 7 kdbus.name 7 kdbus.pool 7