chiark
/
gitweb
/
~ianmdlvl
/
elogind.git
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
Merge commit 'b39a2770ba55637da80e2e389222c59dbea73507'
[elogind.git]
/
src
/
libsystemd
/
sd-bus
/
PORTING-DBUS1
diff --git
a/src/libsystemd/sd-bus/PORTING-DBUS1
b/src/libsystemd/sd-bus/PORTING-DBUS1
index eccb9e628ae123bd9c343612c408210f309dfa4b..6205e32736789e1fd0989c9045ae73bf116ad715 100644
(file)
--- a/
src/libsystemd/sd-bus/PORTING-DBUS1
+++ b/
src/libsystemd/sd-bus/PORTING-DBUS1
@@
-51,7
+51,9
@@
client does not know what they mean, it must disconnect. The upper
system, the lower 32bit indicate "compatible" feature additions. A
client that does not support a "compatible" feature addition can go on
communicating with the bus, however a client that does not support an
system, the lower 32bit indicate "compatible" feature additions. A
client that does not support a "compatible" feature addition can go on
communicating with the bus, however a client that does not support an
-"incompatible" feature must not proceed with the connection.
+"incompatible" feature must not proceed with the connection. When a
+client encountes such an "incompatible" feature it should immediately
+try the next bus address configured in the bus address string.
The hello structure also contains another flags field "attach_flags"
which indicates metadata that is optionally attached to all incoming
The hello structure also contains another flags field "attach_flags"
which indicates metadata that is optionally attached to all incoming
@@
-66,8
+68,9
@@
The kernel will return in the "id" field your unique id. This is a
simple numeric value. For compatibility with classic dbus1 simply
format this as string and prefix ":0.".
simple numeric value. For compatibility with classic dbus1 simply
format this as string and prefix ":0.".
-The kernel will also return the bloom filter size used for the signal
-broadcast bloom filter (see below).
+The kernel will also return the bloom filter size and bloom filter
+hash function number used for the signal broadcast bloom filter (see
+below).
The kernel will also return the bus ID of the bus in a 128bit field.
The kernel will also return the bus ID of the bus in a 128bit field.
@@
-120,8
+123,8
@@
at the same time!
This pretty much explains the ioctl header. The actual payload of the
data is now referenced in additional items that are attached to this
ioctl header structure at the end. When sending a message, you attach
This pretty much explains the ioctl header. The actual payload of the
data is now referenced in additional items that are attached to this
ioctl header structure at the end. When sending a message, you attach
-items of the type PAYLOAD_VEC, PAYLOAD_MEMFD, FDS, BLOOM
, DST_NAME to
-it:
+items of the type PAYLOAD_VEC, PAYLOAD_MEMFD, FDS, BLOOM
_FILTER,
+
DST_NAME to
it:
KDBUS_ITEM_PAYLOAD_VEC: contains a pointer + length pair for
referencing arbitrary user memory. This is how you reference most
KDBUS_ITEM_PAYLOAD_VEC: contains a pointer + length pair for
referencing arbitrary user memory. This is how you reference most
@@
-131,15
+134,15
@@
it:
to send prepared "memfds" (see below) over. This item contains an
fd for a memfd plus a size.
to send prepared "memfds" (see below) over. This item contains an
fd for a memfd plus a size.
- KDBUS_ITEM_
PAYLOAD_FDS: for sending over fds attach an item of this
-
type with
an array of fds.
+ KDBUS_ITEM_
FDS: for sending over fds attach an item of this type with
+ an array of fds.
- KDBUS_ITEM_BLOOM
: the calculated bloom filter of this message, only
- for undirected (broadcast) message.
+ KDBUS_ITEM_BLOOM
_FILTER: the calculated bloom filter of this message,
+
only
for undirected (broadcast) message.
- KDBUS_
DST_NAME: for messages that are directed to a well-known name
- (instead of a unique name), this item contains the well-known name
- field.
+ KDBUS_
ITEM_DST_NAME: for messages that are directed to a well-known
+ name (instead of a unique name), this item contains the well-known
+
name
field.
A single message may consists of no, one or more payload items of type
PAYLOAD_VEC or PAYLOAD_MEMFD. D-Bus protocol implementations should
A single message may consists of no, one or more payload items of type
PAYLOAD_VEC or PAYLOAD_MEMFD. D-Bus protocol implementations should
@@
-233,13
+236,14
@@
positives.
The parameters for the bloom filters that need to be included in
broadcast message is communicated to userspace as part of the hello
The parameters for the bloom filters that need to be included in
broadcast message is communicated to userspace as part of the hello
-response structure. By default it has the parameters m=512 (bits in
-the filter), k=8 (nr of hash functions). Note however, that this is
-subject to change later on, and userspace implementations must be
-capable of handling m values between at least m=8 and m=2^32, and k
-values between at least k=1 and k=32. The underlying hash function is
-SipHash-2-4. It is used with a number of constant (yet originally
-randomly generated) 128bit hash keys, more specifically:
+response structure (see above). By default it has the parameters m=512
+(bits in the filter), k=8 (nr of hash functions). Note however, that
+this is subject to change in later versions, and userspace
+implementations must be capable of handling m values between at least
+m=8 and m=2^32, and k values between at least k=1 and k=32. The
+underlying hash function is SipHash-2-4. It is used with a number of
+constant (yet originally randomly generated) 128bit hash keys, more
+specifically:
b9,66,0b,f0,46,70,47,c1,88,75,c4,9c,54,b9,bd,15,
aa,a1,54,a2,e0,71,4b,39,bf,e1,dd,2e,9f,c5,4a,3b,
b9,66,0b,f0,46,70,47,c1,88,75,c4,9c,54,b9,bd,15,
aa,a1,54,a2,e0,71,4b,39,bf,e1,dd,2e,9f,c5,4a,3b,
@@
-253,7
+257,7
@@
randomly generated) 128bit hash keys, more specifically:
When calculating the first bit index into the bloom filter, the
SipHash-2-4 hash value is calculated for the input data and the first
16 bytes of the array above as hash key. Of the resulting 8 bytes of
When calculating the first bit index into the bloom filter, the
SipHash-2-4 hash value is calculated for the input data and the first
16 bytes of the array above as hash key. Of the resulting 8 bytes of
-output, as many full bytes are taken for the index as necessary,
+output, as many full bytes are taken for the
bit
index as necessary,
starting from the output's first byte. For the second bit index the
same hash value is used, continuing with the next unused output byte,
and so on. Each time the bytes returned by the hash function are
starting from the output's first byte. For the second bit index the
same hash value is used, continuing with the next unused output byte,
and so on. Each time the bytes returned by the hash function are
@@
-314,6
+318,11
@@
messages (which it needs to anyway, given that transfers are
relatively unrestricted on kdbus and people can send you all kinds of
non-sense).
relatively unrestricted on kdbus and people can send you all kinds of
non-sense).
+If a client connects to a bus whose bloom filter metrics (i.e. filter
+size and number of hash functions) are outside of the range the client
+supports it must immediately disconnect and continue connection with
+the next bus address of the bus connection string.
+
INSTALLING MATCHES
To install matches for broadcast messages, use the KDBUS_CMD_ADD_MATCH
INSTALLING MATCHES
To install matches for broadcast messages, use the KDBUS_CMD_ADD_MATCH
@@
-333,7
+342,7
@@
items of the same type as the kernel messages include,
i.e. KDBUS_ITEM_NAME_ADD, KDBUS_ITEM_NAME_REMOVE,
KDBUS_ITEM_NAME_CHANGE, KDBUS_ITEM_ID_ADD, KDBUS_ITEM_ID_REMOVE and
fill them out. Note however, that you have some wildcards in this
i.e. KDBUS_ITEM_NAME_ADD, KDBUS_ITEM_NAME_REMOVE,
KDBUS_ITEM_NAME_CHANGE, KDBUS_ITEM_ID_ADD, KDBUS_ITEM_ID_REMOVE and
fill them out. Note however, that you have some wildcards in this
-case, for example the .id field of KDBUS_ITEM_
ADD/KDBUS_ITEM
_REMOVE
+case, for example the .id field of KDBUS_ITEM_
ID_ADD/KDBUS_ITEM_ID
_REMOVE
structures may be set to 0 to match against any id addition/removal.
Note that dbus match strings do no map 1:1 to these ioctl() calls. In
structures may be set to 0 to match against any id addition/removal.
Note that dbus match strings do no map 1:1 to these ioctl() calls. In
@@
-499,7
+508,7
@@
have attached. Note that when issuing the ioctl, you can select a
different set of credentials to gather, than what was originally requested
for being attached to incoming messages.
different set of credentials to gather, than what was originally requested
for being attached to incoming messages.
-Credentials are always specific to the sender
namespace
that was
+Credentials are always specific to the sender
's domain
that was
current at the time of sending, and of the process that opened the
bus connection at the time of opening it. Note that this latter data
is cached!
current at the time of sending, and of the process that opened the
bus connection at the time of opening it. Note that this latter data
is cached!
@@
-527,7
+536,7
@@
parameter.
Client libraries should use the following connection string when
connecting to the system bus:
Client libraries should use the following connection string when
connecting to the system bus:
- kernel:path=/dev/kdbus/0-system/bus;unix:path=/run/dbus/system_bus_socket
+ kernel:path=/dev/kdbus/0-system/bus;unix:path=/
var/
run/dbus/system_bus_socket
This will ensure that kdbus is preferred over the legacy AF_UNIX
socket, but compatibility is kept. For the user bus use:
This will ensure that kdbus is preferred over the legacy AF_UNIX
socket, but compatibility is kept. For the user bus use: