kdbus.txt: fix things spotted by Alban Crequy

Signed-off-by: Daniel Mack <daniel@zonque.org>

diff --git a/kdbus.txt b/kdbus.txt
index 61d664dc063d1d82086fbbb4d96a729f3b634425..0abb1b1280cbc03ce5f79be5cce8d3597679870d 100644 (file)
--- a/kdbus.txt
+++ b/kdbus.txt
@@ -618,8 +618,8 @@ struct kdbus_cmd_update {
 ---------------
 
 A connection can be terminated by simply closing the file descriptor that was
-used to start the connection. All pending messages will be discarded, and the
-memory in the pool will be freed.
+used to start the connection. All pending incoming messages will be discarded,
+and the memory in the pool will be freed.
 
 An alternative way of way of closing down a connection is calling the
 KDBUS_CMD_BYEBYE ioctl on it, which will only succeed if the message queue
@@ -698,7 +698,8 @@ struct kdbus_msg {
     The priority of this message. Receiving messages (see below) may
     optionally be constrained to messages of a minimal priority. This
     allows for use cases where timing critical data is interleaved with
-    control data on the same connection.
+    control data on the same connection. If unused, the priority should be
+    set to zero.
 
   __u64 dst_id;
     The numeric ID of the destination connection, or KDBUS_DST_ID_BROADCAST
@@ -884,7 +885,8 @@ When a connection sends a message with KDBUS_MSG_FLAGS_SYNC_REPLY and
 blocks while waiting for the reply, the KDBUS_CMD_MSG_CANCEL ioctl can be
 used on the same file descriptor to cancel the message, based on its cookie.
 If there are multiple messages with the same cookie that are all synchronously
-waiting for a reply, all of them will be canceled.
+waiting for a reply, all of them will be canceled. Obviously, this is only
+possible in multi-threaded applications.
 
 
 8. Name registry
@@ -1234,28 +1236,32 @@ 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
-filter may have more bits set than the mask. Consequently, false positive
+mask may have more bits set than the filter. Consequently, false positive
 matches are expected to happen, and userspace must deal with that fact.
 
 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
 broadcast messages (with an item of type KDBUS_ITEM_BLOOM_FILTER).
 
-For example, consider a bus has a bloom size of 8 bytes, and the following
-mask/filter combinations:
+For a broadcast to match, all set bits in the filter have to be set in the
+installed match mask as well. For example, consider a bus has a bloom size
+of 8 bytes, and the following mask/filter combinations:
 
     filter  0x0101010101010101
     mask    0x0101010101010101
             -> matches
 
-    filter  0x0101010101010101
-    mask    0x0303030303030303
-            -> doesn't match
-
     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, each of which in the size of the
 bloom size defined by the bus. Each block of a mask is called a 'generation',
 starting at index 0.