From ed9048f201b264da2b0a6dcabf52b2bfed88a1b4 Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Thu, 29 Jan 2015 00:14:41 +0100 Subject: [PATCH] doc: annotate more strings, break more lines ... Signed-off-by: Daniel Mack --- doc/kdbus.connection.xml | 3 ++- doc/kdbus.item.xml | 35 +++++++++++++++-------------- doc/kdbus.message.xml | 57 +++++++++++++++++++++++++++++++----------------- doc/kdbus.names.xml | 11 ---------- doc/kdbus.pool.xml | 4 ++-- doc/kdbus.xml | 4 ++-- 6 files changed, 60 insertions(+), 54 deletions(-) diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml index 270ecca..666cbe4 100644 --- a/doc/kdbus.connection.xml +++ b/doc/kdbus.connection.xml @@ -134,7 +134,8 @@ on the same bus by using the peer's connection ID as the destination. - The KDBUS_CMD_HELLO ioctl takes the following struct as argument. + The KDBUS_CMD_HELLO ioctl takes a struct + kdbus_cmd_hello as argument. diff --git a/doc/kdbus.item.xml b/doc/kdbus.item.xml index 9f8ed9c..3222ae1 100644 --- a/doc/kdbus.item.xml +++ b/doc/kdbus.item.xml @@ -500,36 +500,33 @@ struct kdbus_pids { KDBUS_ITEM_TID_COMM [*] - Contains the comm of a task's - TID, stored as null-terminated string in - item.str. Its length can also be derived from - the item's total size. - Receivers of this item should not use its contents for any kind - of security measures. See below. + Contains the comm string of a task's + TID (thread ID), stored as null-terminated + string in item.str. Its length can also be + derived from the item's total size. Receivers of this item should + not use its contents for any kind of security measures. See below. KDBUS_ITEM_PID_COMM [*] - Contains the comm of a task's - PID, stored as null-terminated string in - item.str. Its length can also be derived from - the item's total size. - Receivers of this item should not use its contents for any kind - of security measures. See below. + Contains the comm string of a task's + PID (process ID), stored as null-terminated + string in item.str. Its length can also be + derived from the item's total size. Receivers of this item should + not use its contents for any kind of security measures. See below. KDBUS_ITEM_EXE [*] - Contains the path to the executable of a - task, stored as null-terminated string in - item.str. Its length can also be derived from - the item's total size. - Receivers of this item should not use its contents for any kind - of security measures. See below. + Contains the path to the executable of a task, + stored as null-terminated string in item.str. Its + length can also be derived from the item's total size. Receivers of + this item should not use its contents for any kind of security + measures. See below. @@ -719,6 +716,8 @@ struct kdbus_notify_id_change { new_id describes the new owner of the name and is set to 0 values in case of KDBUS_ITEM_NAME_REMOVE. + The name field contains the well-known name the + notification is about, as null-terminated string. See kdbus.match diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml index 7a9f9f1..d33c00a 100644 --- a/doc/kdbus.message.xml +++ b/doc/kdbus.message.xml @@ -68,18 +68,25 @@ struct kdbus_cmd_send { By default, all calls to kdbus are considered asynchronous, - non-blocking. However, as there are many use cases that need to wait - for a remote peer to answer a method call, there's a way to send a - message and wait for a reply in a synchronous fashion. This is what - the KDBUS_SEND_SYNC_REPLY controls. The KDBUS_CMD_SEND ioctl will block - until the reply has arrived, the timeout limit is reached, in case the - remote connection was shut down, or if interrupted by a signal before - any reply; see signal(7). - - The offset of the reply message in the sender's pool is stored in in - 'offset_reply' when the ioctl has returned without error. Hence, there - is no need for another KDBUS_CMD_RECV ioctl or anything else to receive - the reply. + non-blocking. However, as there are many use cases that need + to wait for a remote peer to answer a method call, there's a + way to send a message and wait for a reply in a synchronous + fashion. This is what the + KDBUS_SEND_SYNC_REPLY controls. The + KDBUS_CMD_SEND ioctl will block until the + reply has arrived, the timeout limit is reached, in case the + remote connection was shut down, or if interrupted by a signal + before any reply; see + + signal + 7 + . + + The offset of the reply message in the sender's pool is stored + in in offset_reply when the ioctl has + returned without error. Hence, there is no need for another + KDBUS_CMD_RECV ioctl or anything else to + receive the reply. @@ -501,9 +508,10 @@ struct kdbus_msg { Receiving messages - Messages are received by the client with the KDBUS_CMD_RECV ioctl. - The endpoint file of the bus supports poll/epoll/select - to wake up the receiving process when new messages are queued up to be received. + Messages are received by the client with the + KDBUS_CMD_RECV ioctl. The endpoint file of the bus + supports poll()/epoll()/select() to wake up the + receiving process when new messages are queued up to be received. @@ -740,14 +748,23 @@ struct kdbus_msg_info { - kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL - kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST - kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL - Has exactly one of the aforementioned items attached + + kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL + + + kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST + + + kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL + + + Has exactly one of the aforementioned items attached + - Kernel notifications have an item of type KDBUS_ITEM_TIMESTAMP attached. + Kernel notifications have an item of type + KDBUS_ITEM_TIMESTAMP attached. diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml index 5736bd0..1a28fb0 100644 --- a/doc/kdbus.names.xml +++ b/doc/kdbus.names.xml @@ -227,21 +227,10 @@ struct kdbus_cmd_name { struct kdbus_cmd_name { __u64 size; - The overall size of this struct, including the null-terminated name string. - __u64 flags; - Flags to the command. Currently unused and must be zero. - __u64 kernel_flags; - Valid flags for this command, returned by the kernel upon each call. - __u64 return_flags; - Flags returned by the kernel. Currently unused and always set to zero by - the kernel. - struct kdbus_item items[0]; - Items to submit the name. Currently, one item of type KDBUS_ITEM_NAME is - expected and allowed, and the contained string must be a valid bus name. }; diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml index 8fa2a86..de222f2 100644 --- a/doc/kdbus.pool.xml +++ b/doc/kdbus.pool.xml @@ -28,7 +28,7 @@ KDBUS_ITEM_BLOOM_PARAMETER item that is returned by KDBUS_CMD_HELLO. Internally, the pool is segmented into slices, each referenced by its - offset in the pool. + offset in the pool, expressed in bytes. @@ -108,7 +108,7 @@ uint8_t *buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); Alternatively, instead of mapping the entire pool buffer, only parts of it can be mapped. Every kdbus command that returns an - offset (see above) also reports a + offset (see above) also reports a size along with it, so userspace can be written in a way that it only maps portions of the part to access a specific slice. diff --git a/doc/kdbus.xml b/doc/kdbus.xml index 2b85b5d..a64d4e6 100644 --- a/doc/kdbus.xml +++ b/doc/kdbus.xml @@ -213,8 +213,8 @@ counter-part blob, called a 'filter', and signals are only delivered to peers which have a match that whitelists the message's filter. Senders of signal messages can use either a single connection ID as receiver, or - KDBUS_DST_ID_BROADCAST to potentially send it to all connections of a - bus, following the logic described above. See + KDBUS_DST_ID_BROADCAST to potentially send it to + all connections of a bus, following the logic described above. See kdbus.match 7 -- 2.7.4