X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=src%2Flibsystemd-bus%2Fkdbus.h;h=c59bdd859d79f4c0aa4cd417ce3fe1fbc0900351;hb=d8160f21fd295b451cee9679aa281fedf1cb8e8c;hp=71bf86d063547ec5260ced38047473688c84fcb9;hpb=7e94edc2a43b9fdb3d9fc743ab1994c3d4a13d9f;p=elogind.git

diff --git a/src/libsystemd-bus/kdbus.h b/src/libsystemd-bus/kdbus.h
index 71bf86d06..c59bdd859 100644
--- a/src/libsystemd-bus/kdbus.h
+++ b/src/libsystemd-bus/kdbus.h
@@ -193,6 +193,8 @@ struct kdbus_policy {
 
 /**
  * enum kdbus_item_type - item types to chain data in a list
+ * @_KDBUS_ITEM_NULL:		Uninitialized/invalid
+ * @_KDBUS_ITEM_USER_BASE:	Start of user items
  * @KDBUS_ITEM_PAYLOAD_VEC:	Vector to data
  * @KDBUS_ITEM_PAYLOAD_OFF:	Data at returned offset to message head
  * @KDBUS_ITEM_PAYLOAD_MEMFD:	Data as sealed memfd
@@ -200,10 +202,11 @@ struct kdbus_policy {
  * @KDBUS_ITEM_BLOOM:		For broadcasts, carries bloom filter
  * @KDBUS_ITEM_BLOOM_SIZE:	Desired bloom size, used by KDBUS_CMD_BUS_MAKE
  * @KDBUS_ITEM_DST_NAME:	Destination's well-known name
- * @KDBUS_ITEM_PRIORITY:	Queue priority for message
  * @KDBUS_ITEM_MAKE_NAME:	Name of namespace, bus, endpoint
+ * @_KDBUS_ITEM_POLICY_BASE:	Start of policy items
  * @KDBUS_ITEM_POLICY_NAME:	Policy in struct kdbus_policy
  * @KDBUS_ITEM_POLICY_ACCESS:	Policy in struct kdbus_policy
+ * @_KDBUS_ITEM_ATTACH_BASE:	Start of metadata attach items
  * @KDBUS_ITEM_NAME:		Well-know name with flags
  * @KDBUS_ITEM_ID:		Connection ID
  * @KDBUS_ITEM_TIMESTAMP:	Timestamp
@@ -216,6 +219,7 @@ struct kdbus_policy {
  * @KDBUS_ITEM_CAPS:		The process capabilities
  * @KDBUS_ITEM_SECLABEL:	The security label
  * @KDBUS_ITEM_AUDIT:		The audit IDs
+ * @_KDBUS_ITEM_KERNEL_BASE:	Start of kernel-generated message items
  * @KDBUS_ITEM_NAME_ADD:	Notify in struct kdbus_notify_name_change
  * @KDBUS_ITEM_NAME_REMOVE:	Notify in struct kdbus_notify_name_change
  * @KDBUS_ITEM_NAME_CHANGE:	Notify in struct kdbus_notify_name_change
@@ -234,7 +238,6 @@ enum kdbus_item_type {
 	KDBUS_ITEM_BLOOM,
 	KDBUS_ITEM_BLOOM_SIZE,
 	KDBUS_ITEM_DST_NAME,
-	KDBUS_ITEM_PRIORITY,
 	KDBUS_ITEM_MAKE_NAME,
 
 	_KDBUS_ITEM_POLICY_BASE	= 0x400,
@@ -329,11 +332,11 @@ enum kdbus_msg_flags {
 /**
  * enum kdbus_payload_type - type of payload carried by message
  * @KDBUS_PAYLOAD_KERNEL:	Kernel-generated simple message
- * @KDBUS_PAYLOAD_DBUS:		D-Bus marshalling
+ * @KDBUS_PAYLOAD_DBUS:		D-Bus marshalling "DBusDBus"
  */
 enum kdbus_payload_type {
 	KDBUS_PAYLOAD_KERNEL,
-	KDBUS_PAYLOAD_DBUS	= 0x4442757344427573ULL, /* 'DBusDBus' */
+	KDBUS_PAYLOAD_DBUS	= 0x4442757344427573ULL,
 };
 
 /**
@@ -345,21 +348,13 @@ enum kdbus_payload_type {
  * @payload_type:	Payload type (KDBUS_PAYLOAD_*)
  * @cookie:		Userspace-supplied cookie, for the connection
  * 			to identify its messages
- * @cookie_reply:	A reply to the message with the same cookie. The
- * 			reply itself has its own cookie, @cookie_reply
- * 			corresponds to the cookie of the request message
- * @timeout_ns:		For non-kernel-generated messages, this denotes the
- * 			message timeout in nanoseconds. A message has to be
- * 			received with KDBUS_CMD_MSG_RECV by the destination
- * 			connection within this time frame. For messages that
- * 			have KDBUS_MSG_FLAGS_EXPECT_REPLY set in @flags,
- * 			this value also denotes the timeout for the reply to
- * 			this message. If there is no reply, or the message is
- * 			not received in time by the other side, a
- * 			kernel-generated message with an attached
- * 			KDBUS_ITEM_REPLY_TIMEOUT item is sent to @src_id.
- * 			A 0-value is only valid if KDBUS_MSG_FLAGS_EXPECT_REPLY
- * 			is unset in @flags.
+ * @cookie_reply:	A reply to the requesting message with the same
+ * 			cookie. The requesting connection can match its
+ * 			request and the reply with this value
+ * @timeout_ns:		The time to wait for a message reply from the peer.
+ * 			If there is no reply, a kernel-generated message
+ * 			with an attached KDBUS_ITEM_REPLY_TIMEOUT item
+ * 			is sent to @src_id.
  * @items:		A list of kdbus_items containing the message payload
  */
 struct kdbus_msg {
@@ -369,13 +364,16 @@ struct kdbus_msg {
 	__u64 src_id;
 	__u64 payload_type;
 	__u64 cookie;
-	__u64 cookie_reply;
-	__u64 timeout_ns;
+	union {
+		__u64 cookie_reply;
+		__u64 timeout_ns;
+	};
 	struct kdbus_item items[0];
 } __attribute__((aligned(8)));
 
 /**
  * enum kdbus_policy_access_type - permissions of a policy record
+ * @_KDBUS_POLICY_ACCESS_NULL:	Uninitialized/invalid
  * @KDBUS_POLICY_ACCESS_USER:	Grant access to a uid
  * @KDBUS_POLICY_ACCESS_GROUP:	Grant access to gid
  * @KDBUS_POLICY_ACCESS_WORLD:	World-accessible
@@ -469,7 +467,8 @@ enum kdbus_attach_flags {
  * @id:			The ID of this connection (kernel → userspace)
  * @bloom_size:		The bloom filter size chosen by the owner
  * 			(kernel → userspace)
- * @pool_size:		Maximum size of the pool buffer (kernel → userspace)
+ * @pool_size:		Size of the connection's buffer where the received
+ * 			messages are placed
  * @id128:		Unique 128-bit ID of the bus (kernel → userspace)
  * @items:		A list of items
  *