From 6d461a4fe7896faa1aec5a5417888cf179e46b9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fabian=20Silva=20Delgado?= Date: Mon, 22 Feb 2016 01:12:47 -0300 Subject: Linux-libre 4.4.2-gnu --- Documentation/kdbus/kdbus.match.xml | 555 ------------------------------------ 1 file changed, 555 deletions(-) delete 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 deleted file mode 100644 index ae38e04ab..000000000 --- a/Documentation/kdbus/kdbus.match.xml +++ /dev/null @@ -1,555 +0,0 @@ - - - - - - - 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