From: Daniel Mack Date: Thu, 11 Sep 2014 21:50:47 +0200 Subject: [PATCH] kdbus: add documentation kdbus is a system for low-latency, low-overhead, easy to use interprocess communication (IPC). The interface to all functions in this driver is implemented via ioctls on files exposed through a filesystem called 'kdbusfs'. The default mount point of kdbusfs is /sys/fs/kdbus. This patch adds detailed documentation about the kernel level API design. This patch adds a set of comprehensive set of DocBook files which can be turned into man-pages using 'make mandocs', or into HTML files with 'make htmldocs'. Signed-off-by: Daniel Mack Signed-off-by: David Herrmann Signed-off-by: Djalal Harouni Signed-off-by: Greg Kroah-Hartman --- Documentation/Makefile | 2 +- Documentation/kdbus/Makefile | 30 + Documentation/kdbus/kdbus.bus.xml | 360 +++++++++ Documentation/kdbus/kdbus.connection.xml | 1252 +++++++++++++++++++++++++++++ Documentation/kdbus/kdbus.endpoint.xml | 436 ++++++++++ Documentation/kdbus/kdbus.fs.xml | 124 +++ Documentation/kdbus/kdbus.item.xml | 840 ++++++++++++++++++++ Documentation/kdbus/kdbus.match.xml | 553 +++++++++++++ Documentation/kdbus/kdbus.message.xml | 1277 ++++++++++++++++++++++++++++++ Documentation/kdbus/kdbus.name.xml | 711 +++++++++++++++++ Documentation/kdbus/kdbus.policy.xml | 406 ++++++++++ Documentation/kdbus/kdbus.pool.xml | 320 ++++++++ Documentation/kdbus/kdbus.xml | 1012 +++++++++++++++++++++++ Documentation/kdbus/stylesheet.xsl | 16 + Makefile | 1 + 15 files changed, 7339 insertions(+), 1 deletion(-) create mode 100644 Documentation/kdbus/Makefile create mode 100644 Documentation/kdbus/kdbus.bus.xml create mode 100644 Documentation/kdbus/kdbus.connection.xml create mode 100644 Documentation/kdbus/kdbus.endpoint.xml create mode 100644 Documentation/kdbus/kdbus.fs.xml create mode 100644 Documentation/kdbus/kdbus.item.xml create mode 100644 Documentation/kdbus/kdbus.match.xml create mode 100644 Documentation/kdbus/kdbus.message.xml create mode 100644 Documentation/kdbus/kdbus.name.xml create mode 100644 Documentation/kdbus/kdbus.policy.xml create mode 100644 Documentation/kdbus/kdbus.pool.xml create mode 100644 Documentation/kdbus/kdbus.xml create mode 100644 Documentation/kdbus/stylesheet.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile index bc0548201755..e2127a76b5d6 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,4 +1,4 @@ subdir-y := accounting auxdisplay blackfin connector \ - filesystems filesystems ia64 laptops mic misc-devices \ + filesystems filesystems ia64 kdbus laptops mic misc-devices \ networking pcmcia prctl ptp spi timers vDSO video4linux \ watchdog diff --git a/Documentation/kdbus/Makefile b/Documentation/kdbus/Makefile new file mode 100644 index 000000000000..cd6b48ee41bf --- /dev/null +++ b/Documentation/kdbus/Makefile @@ -0,0 +1,30 @@ +DOCS := \ + kdbus.xml \ + kdbus.bus.xml \ + kdbus.connection.xml \ + kdbus.endpoint.xml \ + kdbus.fs.xml \ + kdbus.item.xml \ + kdbus.match.xml \ + kdbus.message.xml \ + kdbus.name.xml \ + kdbus.policy.xml \ + kdbus.pool.xml + +XMLFILES := $(addprefix $(obj)/,$(DOCS)) +MANFILES := $(patsubst %.xml, %.7, $(XMLFILES)) +HTMLFILES := $(patsubst %.xml, %.html, $(XMLFILES)) + +XMLTO_ARGS := -m $(obj)/stylesheet.xsl + +%.7: %.xml + xmlto man $(XMLTO_ARGS) -o . $< + +%.html: %.xml + xmlto html-nochunks $(XMLTO_ARGS) -o . $< + +mandocs: $(MANFILES) + +htmldocs: $(HTMLFILES) + +clean-files := $(MANFILES) $(HTMLFILES) diff --git a/Documentation/kdbus/kdbus.bus.xml b/Documentation/kdbus/kdbus.bus.xml new file mode 100644 index 000000000000..4d875e59ac02 --- /dev/null +++ b/Documentation/kdbus/kdbus.bus.xml @@ -0,0 +1,360 @@ + + + + + + + kdbus.bus + kdbus.bus + + + + kdbus.bus + 7 + + + + kdbus.bus + kdbus bus + + + + Description + + + A bus is a resource that is shared between connections in order to + transmit messages (see + + kdbus.message + 7 + + ). + Each bus is independent, and operations on the bus will not have any + effect on other buses. A bus is a management entity that controls the + addresses of its connections, their policies and message transactions + performed via this bus. + + + Each bus is bound to the mount instance it was created on. It has a + custom name that is unique across all buses of a domain. In + + kdbus.fs + 7 + + , a bus is presented as a directory. No operations can be performed on + the bus itself; instead you need to perform the operations on an endpoint + associated with the bus. Endpoints are accessible as files underneath the + bus directory. A default endpoint called bus is + provided on each bus. + + + Bus names may be chosen freely except for one restriction: the name must + be prefixed with the numeric effective UID of the creator and a dash. This + is required to avoid namespace clashes between different users. When + creating a bus, the name that is passed in must be properly formatted, or + the kernel will refuse creation of the bus. Example: + 1047-foobar is an acceptable name for a bus + registered by a user with UID 1047. However, + 1024-foobar is not, and neither is + foobar. The UID must be provided in the + user-namespace of the bus owner. + + + To create a new bus, you need to open the control file of a domain and + employ the KDBUS_CMD_BUS_MAKE ioctl. The control + file descriptor that was used to issue + KDBUS_CMD_BUS_MAKE must not previously have been + used for any other control-ioctl and must be kept open for the entire + life-time of the created bus. Closing it will immediately cleanup the + entire bus and all its associated resources and endpoints. Every control + file descriptor can only be used to create a single new bus; from that + point on, it is not used for any further communication until the final + + close + 2 + + . + + + Each bus will generate a random, 128-bit UUID upon creation. This UUID + will be returned to creators of connections through + kdbus_cmd_hello.id128 and can be used to uniquely + identify buses, even across different machines or containers. The UUID + will have its variant bits set to DCE, and denote + version 4 (random). For more details on UUIDs, see + the Wikipedia article on UUIDs. + + + + + + Creating buses + + To create a new bus, the KDBUS_CMD_BUS_MAKE + command is used. It takes a struct kdbus_cmd argument. + + +struct kdbus_cmd { + __u64 size; + __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. + + + + + flags + The flags for creation. + + + KDBUS_MAKE_ACCESS_GROUP + + Make the bus file group-accessible. + + + + + KDBUS_MAKE_ACCESS_WORLD + + Make the bus file world-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. + + + + + items + + + The following items (see + + kdbus.item + 7 + + ) are expected for KDBUS_CMD_BUS_MAKE. + + + + KDBUS_ITEM_MAKE_NAME + + + Contains a null-terminated string that identifies the + bus. The name must be unique across the kdbus domain and + must start with the effective UID of the caller, followed by + a '-' (dash). This item is mandatory. + + + + + + KDBUS_ITEM_BLOOM_PARAMETER + + + Bus-wide bloom parameters passed in a + struct kdbus_bloom_parameter. These settings are + copied back to new connections verbatim. This item is + mandatory. See + + kdbus.item + 7 + + for a more detailed description of this item. + + + + + + KDBUS_ITEM_ATTACH_FLAGS_RECV + + + An optional item that contains a set of required attach flags + that connections must allow. This item is used as a + negotiation measure during connection creation. If connections + do not satisfy the bus requirements, they are not allowed on + the bus. If not set, the bus does not require any metadata to + be attached; in this case connections are free to set their + own attach flags. + + + + + + KDBUS_ITEM_ATTACH_FLAGS_SEND + + + An optional item that contains a set of attach flags that are + returned to connections when they query the bus creator + metadata. If not set, no metadata is returned. + + + + + + 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. + + + + + 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_BUS_MAKE</constant> may fail with the following + errors + + + + + EBADMSG + + A mandatory item is missing. + + + + + EINVAL + + The flags supplied in the struct kdbus_cmd + are invalid or the supplied name does not start with the current + UID and a '-' (dash). + + + + + EEXIST + + A bus of that name already exists. + + + + + ESHUTDOWN + + The kdbus mount instance for the bus was already shut down. + + + + + EMFILE + + The maximum number of buses for the current user is exhausted. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + diff --git a/Documentation/kdbus/kdbus.connection.xml b/Documentation/kdbus/kdbus.connection.xml new file mode 100644 index 000000000000..09852125b2d4 --- /dev/null +++ b/Documentation/kdbus/kdbus.connection.xml @@ -0,0 +1,1252 @@ + + + + + + + kdbus.connection + kdbus.connection + + + + kdbus.connection + 7 + + + + kdbus.connection + kdbus connection + + + + Description + + + Connections are identified by their connection ID, + internally implemented as a uint64_t counter. + The IDs of every newly created bus start at 1, and + every new connection will increment the counter by 1. + The IDs are not reused. + + + In higher level tools, the user visible representation of a connection is + defined by the D-Bus protocol specification as + ":1.<ID>". + + + Messages with a specific uint64_t destination ID are + directly delivered to the connection with the corresponding ID. Signal + messages (see + + kdbus.message + 7 + ) + may be addressed to the special destination ID + KDBUS_DST_ID_BROADCAST (~0ULL) and will then + potentially be delivered to all currently active connections on the bus. + However, in order to receive any signal messages, clients must subscribe + to them by installing a match (see + + kdbus.match + 7 + + ). + + + Messages synthesized and sent directly by the kernel will carry the + special source ID KDBUS_SRC_ID_KERNEL (0). + + + In addition to the unique uint64_t connection ID, + established connections can request the ownership of + well-known names, under which they can be found and + addressed by other bus clients. A well-known name is associated with one + and only one connection at a time. See + + kdbus.name + 7 + + on name acquisition, the name registry, and the validity of names. + + + Messages can specify the special destination ID + KDBUS_DST_ID_NAME (0) and carry a well-known name + in the message data. Such a message is delivered to the destination + connection which owns that well-known name. + + + | src: 22 | | | + | | | | dst: 25 | | | + | | | | | | | + | | | | | | | + | | | +---------------------------+ | | + | | | | | + | | | <--------------------------------------+ | | + | +---------------+ | | | + | | | | + | +---------------+ +---------------------------+ | | | + | | Connection | | Message | -----+ | | + | | :1.25 | --> | src: 25 | | | + | | | | dst: 0xffffffffffffffff | -------------+ | | + | | | | (KDBUS_DST_ID_BROADCAST) | | | | + | | | | | ---------+ | | | + | | | +---------------------------+ | | | | + | | | | | | | + | | | <--------------------------------------------------+ | + | +---------------+ | | | + | | | | + | +---------------+ +---------------------------+ | | | + | | Connection | | Message | --+ | | | + | | :1.55 | --> | src: 55 | | | | | + | | | | dst: 0 / org.foo.bar | | | | | + | | | | | | | | | + | | | | | | | | | + | | | +---------------------------+ | | | | + | | | | | | | + | | | <------------------------------------------+ | | + | +---------------+ | | | + | | | | + | +---------------+ | | | + | | Connection | | | | + | | :1.81 | | | | + | | org.foo.bar | | | | + | | | | | | + | | | | | | + | | | <-----------------------------------+ | | + | | | | | + | | | <----------------------------------------------+ | + | +---------------+ | + +-------------------------------------------------------------------------+ + ]]> + + + + Privileged connections + + A connection is considered privileged if the user + it was created by is the same that created the bus, or if the creating + task had CAP_IPC_OWNER set when it called + KDBUS_CMD_HELLO (see below). + + + Privileged connections have permission to employ certain restricted + functions and commands, which are explained below and in other kdbus + man-pages. + + + + + Activator and policy holder connection + + An activator connection is a placeholder for a + well-known name. Messages sent to such a connection + can be used to start an implementer connection, which will then get all + the messages from the activator copied over. An activator connection + cannot be used to send any message. + + + A policy holder connection only installs a policy + for one or more names. These policy entries are kept active as long as + the connection is alive, and are removed once it terminates. Such a + policy connection type can be used to deploy restrictions for names that + are not yet active on the bus. A policy holder connection cannot be used + to send any message. + + + The creation of activator or policy holder connections is restricted to + privileged users on the bus (see above). + + + + + Monitor connections + + Monitors are eavesdropping connections that receive all the traffic on the + bus, but is invisible to other connections. Such connections have all + properties of any other, regular connection, except for the following + details: + + + + + They will get every message sent over the bus, both unicasts and + broadcasts. + + + + Installing matches for signal messages is neither necessary + nor allowed. + + + + They cannot send messages or be directly addressed as receiver. + + + + They cannot own well-known names. Therefore, they also can't operate as + activators. + + + + Their creation and destruction will not cause + KDBUS_ITEM_ID_{ADD,REMOVE} (see + + kdbus.item + 7 + ). + + + + They are not listed with their unique name in name registry dumps + (see KDBUS_CMD_NAME_LIST in + + kdbus.name + 7 + ), so other connections cannot detect the presence of + a monitor. + + + + The creation of monitor connections is restricted to privileged users on + the bus (see above). + + + + + Creating connections + + A connection to a bus is created by opening an endpoint file (see + + kdbus.endpoint + 7 + ) + of a bus and becoming an active client with the + KDBUS_CMD_HELLO ioctl. Every connection has a unique + identifier on the bus and can address messages to every other connection + on the same bus by using the peer's connection ID as the destination. + + + The KDBUS_CMD_HELLO ioctl takes a struct + kdbus_cmd_hello as argument. + + + +struct kdbus_cmd_hello { + __u64 size; + __u64 flags; + __u64 return_flags; + __u64 attach_flags_send; + __u64 attach_flags_recv; + __u64 bus_flags; + __u64 id; + __u64 pool_size; + __u64 offset; + __u8 id128[16]; + 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 apply to this connection + + + KDBUS_HELLO_ACCEPT_FD + + + When this flag is set, the connection can be sent file + descriptors as message payload of unicast messages. If it's + not set, an attempt to send file descriptors will result in + -ECOMM on the sender's side. + + + + + + KDBUS_HELLO_ACTIVATOR + + + Make this connection an activator (see above). With this bit + set, an item of type KDBUS_ITEM_NAME has + to be attached. This item describes the well-known name this + connection should be an activator for. + A connection can not be an activator and a policy holder at + the same time time, so this bit is not allowed together with + KDBUS_HELLO_POLICY_HOLDER. + + + + + + KDBUS_HELLO_POLICY_HOLDER + + + Make this connection a policy holder (see above). With this + bit set, an item of type KDBUS_ITEM_NAME + has to be attached. This item describes the well-known name + this connection should hold a policy for. + A connection can not be an activator and a policy holder at + the same time time, so this bit is not allowed together with + KDBUS_HELLO_ACTIVATOR. + + + + + + KDBUS_HELLO_MONITOR + + + Make this connection a monitor connection (see above). + + + This flag can only be set by privileged bus connections. See + below for more information. + A connection can not be monitor and an activator or a policy + holder at the same time time, so this bit is not allowed + together with KDBUS_HELLO_ACTIVATOR or + KDBUS_HELLO_POLICY_HOLDER. + + + + + + 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. + + + + + attach_flags_send + + Set the bits for metadata this connection permits to be sent to the + receiving peer. Only metadata items that are both allowed to be sent + by the sender and that are requested by the receiver will be attached + to the message. Note, however, that the bus may optionally require + some of those bits to be set. If the match fails, the ioctl will fail + with errno set to + ECONNREFUSED. In either case, when returning the + field will be set to the mask of metadata items that are enforced by + the bus with the KDBUS_FLAGS_KERNEL bit set as + well. + + + + + attach_flags_recv + + Request the attachment of metadata for each message received by this + connection. See + + kdbus + 7 + + for information about metadata, and + + kdbus.item + 7 + + regarding items in general. + + + + + bus_flags + + Upon successful completion of the ioctl, this member will contain the + flags of the bus it connected to. + + + + + id + + Upon successful completion of the command, this member will contain + the numerical ID of the new connection. + + + + + pool_size + + The size of the communication pool, in bytes. The pool can be + accessed by calling + + mmap + 2 + + on the file descriptor that was used to issue the + KDBUS_CMD_HELLO ioctl. + The pool size of a connection must be greater than + 0 and a multiple of + PAGE_SIZE. See + + kdbus.pool + 7 + + for more information. + + + + + offset + + The kernel will return the offset in the pool where returned details + will be stored. See below. + + + + + id128 + + Upon successful completion of the ioctl, this member will contain the + 128-bit UUID of the connected bus. + + + + + items + + + Variable list of items containing optional additional information. + The following items are currently expected/valid: + + + + KDBUS_ITEM_CONN_DESCRIPTION + + + Contains a string that describes this connection, so it can + be identified later. + + + + + + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS + + + For activators and policy holders only, combinations of + these two items describe policy access entries. See + + kdbus.policy + 7 + + for further details. + + + + + + KDBUS_ITEM_CREDS + KDBUS_ITEM_PIDS + KDBUS_ITEM_SECLABEL + + + Privileged bus users may submit these types in order to + create connections with faked credentials. This information + will be returned when peer information is queried by + KDBUS_CMD_CONN_INFO. See below for more + information on retrieving information on connections. + + + + + + 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. + + + + + + + At the offset returned in the offset field of + struct kdbus_cmd_hello, the kernel will store items + of the following types: + + + + + KDBUS_ITEM_BLOOM_PARAMETER + + + Bloom filter parameter as defined by the bus creator. + + + + + + + The offset in the pool has to be freed with the + KDBUS_CMD_FREE ioctl. See + + kdbus.pool + 7 + + for further information. + + + + + Retrieving information on a connection + + The KDBUS_CMD_CONN_INFO ioctl can be used to + retrieve credentials and properties of the initial creator of a + connection. This ioctl uses the following struct. + + + +struct kdbus_cmd_info { + __u64 size; + __u64 flags; + __u64 return_flags; + __u64 id; + __u64 attach_flags; + __u64 offset; + __u64 info_size; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + flags + + Currently, no flags are supported. + KDBUS_FLAG_NEGOTIATE is accepted to probe for + valid flags. If set, the ioctl will return 0, + 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. + + + + + id + + The numerical ID of the connection for which information is to be + retrieved. If set to a non-zero value, the + KDBUS_ITEM_OWNED_NAME item is ignored. + + + + + flags + + Specifies which metadata items should be attached to the answer. See + + kdbus.message + 7 + + + + + + offset + + When the ioctl returns, this field will contain the offset of the + connection information inside the caller's pool. See + + kdbus.pool + 7 + + for further information. + + + + + info_size + + The kernel will return the size of the returned information, so + applications can optionally + + mmap + 2 + + specific parts of the pool. See + + kdbus.pool + 7 + + for further information. + + + + + items + + + The following items are expected for + KDBUS_CMD_CONN_INFO. + + + + KDBUS_ITEM_OWNED_NAME + + + Contains the well-known name of the connection to look up as. + This item is mandatory if the id field is + set to 0. + + + + + + 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. + + + + + + + When the ioctl returns, the following struct will be stored in the + caller's pool at offset. The fields in this struct + are described below. + + + +struct kdbus_info { + __u64 size; + __u64 id; + __u64 flags; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + id + + The connection's unique ID. + + + + + flags + + The connection's flags as specified when it was created. + + + + + items + + + Depending on the flags field in + struct kdbus_cmd_info, items of types + KDBUS_ITEM_OWNED_NAME and + KDBUS_ITEM_CONN_DESCRIPTION may follow here. + KDBUS_ITEM_NEGOTIATE is also allowed. + + + + + + + Once the caller is finished with parsing the return buffer, it needs to + employ the KDBUS_CMD_FREE command for the offset, in + order to free the buffer part. See + + kdbus.pool + 7 + + for further information. + + + + + Getting information about a connection's bus creator + + The KDBUS_CMD_BUS_CREATOR_INFO ioctl takes the same + struct as KDBUS_CMD_CONN_INFO, but is used to + retrieve information about the creator of the bus the connection is + attached to. The metadata returned by this call is collected during the + creation of the bus and is never altered afterwards, so it provides + pristine information on the task that created the bus, at the moment when + it did so. + + + In response to this call, a slice in the connection's pool is allocated + and filled with an object of type struct kdbus_info, + pointed to by the ioctl's offset field. + + + +struct kdbus_info { + __u64 size; + __u64 id; + __u64 flags; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + id + + The bus ID. + + + + + flags + + The bus flags as specified when it was created. + + + + + items + + + Metadata information is stored in items here. The item list + contains a KDBUS_ITEM_MAKE_NAME item that + indicates the bus name of the calling connection. + KDBUS_ITEM_NEGOTIATE is allowed to probe + for known item types. + + + + + + + Once the caller is finished with parsing the return buffer, it needs to + employ the KDBUS_CMD_FREE command for the offset, in + order to free the buffer part. See + + kdbus.pool + 7 + + for further information. + + + + + Updating connection details + + Some of a connection's details can be updated with the + KDBUS_CMD_CONN_UPDATE ioctl, using the file + descriptor that was used to create the connection. The update command + uses the following struct. + + + +struct kdbus_cmd { + __u64 size; + __u64 flags; + __u64 return_flags; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + flags + + Currently, no flags are supported. + KDBUS_FLAG_NEGOTIATE is accepted to probe for + valid flags. If set, the ioctl will return 0, + 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 + + + Items to describe the connection details to be updated. The + following item types are supported. + + + + KDBUS_ITEM_ATTACH_FLAGS_SEND + + + Supply a new set of metadata items that this connection + permits to be sent along with messages. + + + + + + KDBUS_ITEM_ATTACH_FLAGS_RECV + + + Supply a new set of metadata items that this connection + requests to be attached to each message. + + + + + + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS + + + Policy holder connections may supply a new set of policy + information with these items. For other connection types, + EOPNOTSUPP is returned in + errno. + + + + + + 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. + + + + + + + + Termination of connections + + A connection can be terminated by simply calling + + close + 2 + + on its file descriptor. All pending incoming messages will be discarded, + and the memory allocated by the pool will be freed. + + + + An alternative way of closing down a connection is via the + KDBUS_CMD_BYEBYE ioctl. This ioctl will succeed only + if the message queue of the connection is empty at the time of closing; + otherwise, the ioctl will fail with errno set to + EBUSY. When this ioctl returns + successfully, the connection has been terminated and won't accept any new + messages from remote peers. This way, a connection can be terminated + race-free, without losing any messages. The ioctl takes an argument of + type struct kdbus_cmd. + + + +struct kdbus_cmd { + __u64 size; + __u64 flags; + __u64 return_flags; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + flags + + Currently, no flags are supported. + KDBUS_FLAG_NEGOTIATE is accepted to probe for + valid flags. If set, the ioctl will fail with + errno 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 + + + Items to describe the connection details to be updated. The + following item types are supported. + + + + 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. + + + + + + + + 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_HELLO</constant> may fail with the following + errors + + + + + EFAULT + + The supplied pool size was 0 or not a multiple of the page size. + + + + + EINVAL + + The flags supplied in struct kdbus_cmd_hello + are invalid. + + + + + EINVAL + + An illegal combination of + KDBUS_HELLO_MONITOR, + KDBUS_HELLO_ACTIVATOR and + KDBUS_HELLO_POLICY_HOLDER was passed in + flags. + + + + + EINVAL + + An invalid set of items was supplied. + + + + + ECONNREFUSED + + The attach_flags_send field did not satisfy the requirements of + the bus. + + + + + EPERM + + A KDBUS_ITEM_CREDS items was supplied, but the + current user is not privileged. + + + + + ESHUTDOWN + + The bus you were trying to connect to has already been shut down. + + + + + EMFILE + + The maximum number of connections on the bus has been reached. + + + + + EOPNOTSUPP + + The endpoint does not support the connection flags supplied in + struct kdbus_cmd_hello. + + + + + + + + <constant>KDBUS_CMD_BYEBYE</constant> may fail with the following + errors + + + + + EALREADY + + The connection has already been shut down. + + + + + EBUSY + + There are still messages queued up in the connection's pool. + + + + + + + + <constant>KDBUS_CMD_CONN_INFO</constant> may fail with the following + errors + + + + + EINVAL + + Invalid flags, or neither an ID nor a name was provided, or the + name is invalid. + + + + + ESRCH + + Connection lookup by name failed. + + + + + ENXIO + + No connection with the provided connection ID found. + + + + + + + + <constant>KDBUS_CMD_CONN_UPDATE</constant> may fail with the following + errors + + + + + EINVAL + + Illegal flags or items. + + + + + EINVAL + + Wildcards submitted in policy entries, or illegal sequence + of policy items. + + + + + EOPNOTSUPP + + Operation not supported by connection. + + + + + E2BIG + + Too many policy items attached. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.policy + 7 + + + + + kdbus.pool + 7 + + + + + kdbus.item + 7 + + + + + diff --git a/Documentation/kdbus/kdbus.endpoint.xml b/Documentation/kdbus/kdbus.endpoint.xml new file mode 100644 index 000000000000..76e325d4e931 --- /dev/null +++ b/Documentation/kdbus/kdbus.endpoint.xml @@ -0,0 +1,436 @@ + + + + + + + kdbus.endpoint + kdbus.endpoint + + + + kdbus.endpoint + 7 + + + + kdbus.endpoint + kdbus endpoint + + + + Description + + + Endpoints are entry points to a bus (see + + kdbus.bus + 7 + ). + By default, each bus has a default + endpoint called 'bus'. The bus owner has the ability to create custom + endpoints with specific names, permissions, and policy databases + (see below). An endpoint is presented as file underneath the directory + of the parent bus. + + + To create a custom endpoint, open the default endpoint + (bus) and use the + KDBUS_CMD_ENDPOINT_MAKE ioctl with + struct kdbus_cmd. Custom endpoints always have a policy + database that, by default, forbids any operation. You have to explicitly + install policy entries to allow any operation on this endpoint. + + + Once KDBUS_CMD_ENDPOINT_MAKE succeeded, the new + endpoint will appear in the filesystem + ( + kdbus.bus + 7 + ), and the used file descriptor will manage the + newly created endpoint resource. It cannot be used to manage further + resources and must be kept open as long as the endpoint is needed. The + endpoint will be terminated as soon as the file descriptor is closed. + + + Endpoint names may be chosen freely except for one restriction: the name + must be prefixed with the numeric effective UID of the creator and a dash. + This is required to avoid namespace clashes between different users. When + creating an endpoint, the name that is passed in must be properly + formatted or the kernel will refuse creation of the endpoint. Example: + 1047-my-endpoint is an acceptable name for an + endpoint registered by a user with UID 1047. However, + 1024-my-endpoint is not, and neither is + my-endpoint. The UID must be provided in the + user-namespace of the bus. + + + To create connections to a bus, use KDBUS_CMD_HELLO + on a file descriptor returned by open() on an + endpoint node. See + + kdbus.connection + 7 + + for further details. + + + + + Creating custom endpoints + + To create a new endpoint, the + KDBUS_CMD_ENDPOINT_MAKE command is used. Along with + the endpoint's name, which will be used to expose the endpoint in the + + kdbus.fs + 7 + , + the command also optionally takes items to set up the endpoint's + + kdbus.policy + 7 + . + KDBUS_CMD_ENDPOINT_MAKE takes a + struct kdbus_cmd argument. + + +struct kdbus_cmd { + __u64 size; + __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. + + + + + flags + The flags for creation. + + + KDBUS_MAKE_ACCESS_GROUP + + Make the endpoint file group-accessible. + + + + + KDBUS_MAKE_ACCESS_WORLD + + Make the endpoint file world-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. + + + + + items + + + The following items are expected for + KDBUS_CMD_ENDPOINT_MAKE. + + + + KDBUS_ITEM_MAKE_NAME + + Contains a string to identify the endpoint name. + + + + + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS + + + These items are used to set the policy attached to the + endpoint. For more details on bus and endpoint policies, see + + kdbus.policy + 7 + . + + + + + + Unrecognized items are rejected, and the ioctl will fail with + errno set to EINVAL. + + + + + + + + Updating endpoints + + To update an existing endpoint, the + KDBUS_CMD_ENDPOINT_UPDATE command is used on the file + descriptor that was used to create the update, using + KDBUS_CMD_ENDPOINT_MAKE. The only relevant detail of + the endpoint that can be updated is the policy. When the command is + employed, the policy of the endpoint is replaced + atomically with the new set of rules. + The command takes a struct kdbus_cmd argument. + + +struct kdbus_cmd { + __u64 size; + __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. + + + + + flags + + Unused for this command. + KDBUS_FLAG_NEGOTIATE is accepted to probe for + valid flags. If set, the ioctl will return 0, + 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 + + + The following items are expected for + KDBUS_CMD_ENDPOINT_UPDATE. + + + + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS + + + These items are used to set the policy attached to the + endpoint. For more details on bus and endpoint policies, see + + kdbus.policy + 7 + . + Existing policy is atomically replaced with the new rules + provided. + + + + + + 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. + + + + + + + + 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_ENDPOINT_MAKE</constant> may fail with the + following errors + + + + + EINVAL + + The flags supplied in the struct kdbus_cmd + are invalid. + + + + + EINVAL + + Illegal combination of KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS was provided. + + + + + EEXIST + + An endpoint of that name already exists. + + + + + EPERM + + The calling user is not privileged. See + + kdbus + 7 + + for information about privileged users. + + + + + + + + <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the + following errors + + + + + EINVAL + + The flags supplied in struct kdbus_cmd + are invalid. + + + + + EINVAL + + Illegal combination of KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS was provided. + + + + + EEXIST + + An endpoint of that name already exists. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + diff --git a/Documentation/kdbus/kdbus.fs.xml b/Documentation/kdbus/kdbus.fs.xml new file mode 100644 index 000000000000..8c2a90e10b66 --- /dev/null +++ b/Documentation/kdbus/kdbus.fs.xml @@ -0,0 +1,124 @@ + + + + + + + kdbus.fs + kdbus.fs + + + + kdbus.fs + 7 + + + + kdbus.fs + kdbus file system + + + + File-system Layout + + + The kdbusfs pseudo filesystem provides access to + kdbus entities, such as buses and + endpoints. Each time the filesystem is mounted, + a new, isolated kdbus instance is created, which is independent from the + other instances. + + + The system-wide standard mount point for kdbusfs is + /sys/fs/kdbus. + + + + Buses are represented as directories in the file system layout, whereas + endpoints are exposed as files inside these directories. At the top-level, + a control node is present, which can be opened to + create new buses via the KDBUS_CMD_BUS_MAKE ioctl. + Each bus shows a default endpoint called + bus, which can be opened to either create a connection + with the KDBUS_CMD_HELLO ioctl, or to create new + custom endpoints for the bus with + KDBUS_CMD_ENDPOINT_MAKE. See + + kdbus.bus + 7 + , + + kdbus.connection + 7 + and + + kdbus.endpoint + 7 + + for more details. + + + Following, you can see an example layout of the + kdbusfs filesystem: + + + /sys/fs/kdbus/ ; mount-point + |-- 0-system ; bus directory + | |-- bus ; default endpoint + | `-- 1017-custom ; custom endpoint + |-- 1000-user ; bus directory + | |-- bus ; default endpoint + | |-- 1000-service-A ; custom endpoint + | `-- 1000-service-B ; custom endpoint + `-- control ; control file + + + + + Mounting instances + + In order to get a new and separate kdbus environment, a new instance + of kdbusfs can be mounted like this: + + + # mount -t kdbusfs kdbusfs /tmp/new_kdbus/ + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + mount + 8 + + + + + diff --git a/Documentation/kdbus/kdbus.item.xml b/Documentation/kdbus/kdbus.item.xml new file mode 100644 index 000000000000..bfe47362097f --- /dev/null +++ b/Documentation/kdbus/kdbus.item.xml @@ -0,0 +1,840 @@ + + + + + + + kdbus.item + kdbus item + + + + kdbus.item + 7 + + + + kdbus.item + kdbus item structure, layout and usage + + + + Description + + + To flexibly augment transport structures, data blobs of type + struct kdbus_item can be attached to the structs passed + into the ioctls. Some ioctls make items of certain types mandatory, + others are optional. Items that are unsupported by ioctls they are + attached to will cause the ioctl to fail with errno + set to EINVAL. + Items are also used for information stored in a connection's + pool, such as received messages, name lists or + requested connection or bus owner information. Depending on the type of + an item, its total size is either fixed or variable. + + + + Chaining items + + Whenever items are used as part of the kdbus kernel API, they are + embedded in structs that are embedded inside structs that themselves + include a size field containing the overall size of the structure. + This allows multiple items to be chained up, and an item iterator + (see below) is capable of detecting the end of an item chain. + + + + + Alignment + + The kernel expects all items to be aligned to 8-byte boundaries. + Unaligned items will cause the ioctl they are used with to fail + with errno set to EINVAL. + An item that has an unaligned size itself hence needs to be padded + if it is followed by another item. + + + + + Iterating items + + A simple iterator would iterate over the items until the items have + reached the embedding structure's overall size. An example + implementation is shown below. + + + size)) + +#define KDBUS_ITEM_FOREACH(item, head, first) \ + for (item = (head)->first; \ + ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \ + ((uint8_t *)(item) >= (uint8_t *)(head)); \ + item = KDBUS_ITEM_NEXT(item)) + ]]> + + + + + Item layout + + A struct kdbus_item consists of a + size field, describing its overall size, and a + type field, both 64 bit wide. They are followed by + a union to store information that is specific to the item's type. + The struct layout is shown below. + + + +struct kdbus_item { + __u64 size; + __u64 type; + /* item payload - see below */ + union { + __u8 data[0]; + __u32 data32[0]; + __u64 data64[0]; + char str[0]; + + __u64 id; + struct kdbus_vec vec; + struct kdbus_creds creds; + struct kdbus_pids pids; + struct kdbus_audit audit; + struct kdbus_caps caps; + struct kdbus_timestamp timestamp; + struct kdbus_name name; + struct kdbus_bloom_parameter bloom_parameter; + struct kdbus_bloom_filter bloom_filter; + struct kdbus_memfd memfd; + int fds[0]; + struct kdbus_notify_name_change name_change; + struct kdbus_notify_id_change id_change; + struct kdbus_policy_access policy_access; + }; +}; + + + + struct kdbus_item should never be used to allocate + an item instance, as its size may grow in future releases of the API. + Instead, it should be manually assembled by storing the + size, type and payload to a + struct of its own. + + + + + Item types + + + Negotiation item + + + KDBUS_ITEM_NEGOTIATE + + With this item is attached to any ioctl, programs can + probe the kernel for known item items. + The item carries an array of uint64_t values in + item.data64, each set to an item type to + probe. The kernel will reset each member of this array that is + not recognized as valid item type to 0. + This way, users can negotiate kernel features at start-up to + keep newer userspace compatible with older kernels. This item + is never attached by the kernel in response to any command. + + + + + + + Command specific items + + + KDBUS_ITEM_PAYLOAD_VEC + KDBUS_ITEM_PAYLOAD_OFF + + Messages are directly copied by the sending process into the + receiver's + + kdbus.pool + 7 + . + This way, two peers can exchange data by effectively doing a + single-copy from one process to another; the kernel will not buffer + the data anywhere else. KDBUS_ITEM_PAYLOAD_VEC + is used when sending message. The item + references a memory address when the payload data can be found. + KDBUS_ITEM_PAYLOAD_OFF is used when messages + are received, and the + offset value describes the offset inside the + receiving connection's + + kdbus.pool + 7 + + where the message payload can be found. See + + kdbus.message + 7 + + for more information on passing of payload data along with a + message. + +struct kdbus_vec { + __u64 size; + union { + __u64 address; + __u64 offset; + }; +}; + + + + + + KDBUS_ITEM_PAYLOAD_MEMFD + + Transports a file descriptor of a memfd in + struct kdbus_memfd in item.memfd. + The size field has to match the actual size of + the memfd that was specified when it was created. The + start parameter denotes the offset inside the + memfd at which the referenced payload starts. See + + kdbus.message + 7 + + for more information on passing of payload data along with a + message. + +struct kdbus_memfd { + __u64 start; + __u64 size; + int fd; + __u32 __pad; +}; + + + + + + KDBUS_ITEM_FDS + + Contains an array of file descriptors. + When used with KDBUS_CMD_SEND, the values of + this array must be filled with valid file descriptor numbers. + When received as item attached to a message, the array will + contain the numbers of the installed file descriptors, or + -1 in case an error occurred. + file descriptor. + In either case, the number of entries in the array is derived from + the item's total size. See + + kdbus.message + 7 + + for more information. + + + + + + + Items specific to some commands + + + KDBUS_ITEM_CANCEL_FD + + Transports a file descriptor that can be used to cancel a + synchronous KDBUS_CMD_SEND operation by + writing to it. The file descriptor is stored in + item.fd[0]. The item may only contain one + file descriptor. See + + kdbus.message + 7 + + for more information on this item and how to use it. + + + + + KDBUS_ITEM_BLOOM_PARAMETER + + Contains a set of bloom parameters as + struct kdbus_bloom_parameter in + item.bloom_parameter. + The item is passed from userspace to kernel during the + KDBUS_CMD_BUS_MAKE ioctl, and returned + verbatim when KDBUS_CMD_HELLO is called. + The kernel does not use the bloom parameters, but they need to + be known by each connection on the bus in order to define the + bloom filter hash details. See + + kdbus.match + 7 + + for more information on matching and bloom filters. + +struct kdbus_bloom_parameter { + __u64 size; + __u64 n_hash; +}; + + + + + + KDBUS_ITEM_BLOOM_FILTER + + Carries a bloom filter as + struct kdbus_bloom_filter in + item.bloom_filter. It is mandatory to send this + item attached to a struct kdbus_msg, in case the + message is a signal. This item is never transported from kernel to + userspace. See + + kdbus.match + 7 + + for more information on matching and bloom filters. + +struct kdbus_bloom_filter { + __u64 generation; + __u64 data[0]; +}; + + + + + + KDBUS_ITEM_BLOOM_MASK + + Transports a bloom mask as binary data blob + stored in item.data. This item is used to + describe a match into a connection's match database. See + + kdbus.match + 7 + + for more information on matching and bloom filters. + + + + + KDBUS_ITEM_DST_NAME + + Contains a well-known name to send a + message to, as null-terminated string in + item.str. This item is used with + KDBUS_CMD_SEND. See + + kdbus.message + 7 + + for more information on how to send a message. + + + + + KDBUS_ITEM_MAKE_NAME + + Contains a bus name or + endpoint name, stored as null-terminated + string in item.str. This item is sent from + userspace to kernel when buses or endpoints are created, and + returned back to userspace when the bus creator information is + queried. See + + kdbus.bus + 7 + + and + + kdbus.endpoint + 7 + . + + + + + KDBUS_ITEM_ATTACH_FLAGS_SEND + KDBUS_ITEM_ATTACH_FLAGS_RECV + + Contains a set of attach flags at + send or receive time. See + + kdbus + 7 + , + + kdbus.bus + 7 + and + + kdbus.connection + 7 + + for more information on attach flags. + + + + + KDBUS_ITEM_ID + + Transports a connection's numerical ID of + a connection as uint64_t value in + item.id. + + + + + KDBUS_ITEM_NAME + + Transports a name associated with the + name registry as null-terminated string as + struct kdbus_name in + item.name. The flags + contains the flags of the name. See + + kdbus.name + 7 + + for more information on how to access the name registry of a bus. + +struct kdbus_name { + __u64 flags; + char name[0]; +}; + + + + + + + + Items attached by the kernel as metadata + + + + KDBUS_ITEM_TIMESTAMP + + Contains both the monotonic and the + realtime timestamp, taken when the message + was processed on the kernel side. + Stored as struct kdbus_timestamp in + item.timestamp. + +struct kdbus_timestamp { + __u64 seqnum; + __u64 monotonic_ns; + __u64 realtime_ns; +}; + + + + + + KDBUS_ITEM_CREDS + + Contains a set of user and + group information as 32-bit values, in the + usual four flavors: real, effective, saved and filesystem related. + Stored as struct kdbus_creds in + item.creds. + +struct kdbus_creds { + __u32 uid; + __u32 euid; + __u32 suid; + __u32 fsuid; + __u32 gid; + __u32 egid; + __u32 sgid; + __u32 fsgid; +}; + + + + + + KDBUS_ITEM_PIDS + + Contains the PID, TID + and parent PID (PPID) of a remote peer. + Stored as struct kdbus_pids in + item.pids. + +struct kdbus_pids { + __u64 pid; + __u64 tid; + __u64 ppid; +}; + + + + + + KDBUS_ITEM_AUXGROUPS + + Contains the auxiliary (supplementary) groups + a remote peer is a member of, stored as array of + uint32_t values in item.data32. + The array length can be determined by looking at the item's total + size, subtracting the size of the header and and dividing the + remainder by sizeof(uint32_t). + + + + + KDBUS_ITEM_OWNED_NAME + + Contains a well-known name currently owned + by a connection. The name is stored as null-terminated string in + item.str. Its length can also be derived from + the item's total size. + + + + + KDBUS_ITEM_TID_COMM [*] + + 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 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. + + + + + KDBUS_ITEM_CMDLINE [*] + + Contains the command line arguments of a + task, stored as an array of null-terminated + strings in item.str. The total length of all + strings in the array can 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_CGROUP + + Contains the cgroup path of a task, stored + as null-terminated string in item.str. Its + length can also be derived from the item's total size. + + + + + KDBUS_ITEM_CAPS + + Contains sets of capabilities, stored as + struct kdbus_caps in item.caps. + As the item size may increase in the future, programs should be + written in a way that it takes + item.caps.last_cap into account, and derive + the number of sets and rows from the item size and the reported + number of valid capability bits. + +struct kdbus_caps { + __u32 last_cap; + __u32 caps[0]; +}; + + + + + + KDBUS_ITEM_SECLABEL + + Contains the LSM label of a task, stored as + null-terminated string in item.str. Its length + can also be derived from the item's total size. + + + + + KDBUS_ITEM_AUDIT + + Contains the audit sessionid and + loginuid of a task, stored as + struct kdbus_audit in + item.audit. + +struct kdbus_audit { + __u32 sessionid; + __u32 loginuid; +}; + + + + + + KDBUS_ITEM_CONN_DESCRIPTION + + Contains the connection description, as set + by KDBUS_CMD_HELLO or + KDBUS_CMD_CONN_UPDATE, stored as + null-terminated string in item.str. Its length + can also be derived from the item's total size. + + + + + + All metadata is automatically translated into the + namespaces of the task that receives them. See + + kdbus.message + 7 + + for more information. + + + + [*] Note that the content stored in metadata items of type + KDBUS_ITEM_TID_COMM, + KDBUS_ITEM_PID_COMM, + KDBUS_ITEM_EXE and + KDBUS_ITEM_CMDLINE + can easily be tampered by the sending tasks. Therefore, they should + not be used for any sort of security relevant + assumptions. The only reason they are transmitted is to let + receivers know about details that were set when metadata was + collected, even though the task they were collected from is not + active any longer when the items are received. + + + + + Items used for policy entries, matches and notifications + + + + KDBUS_ITEM_POLICY_ACCESS + + This item describes a policy access entry to + access the policy database of a + + kdbus.bus + 7 + or + + kdbus.endpoint + 7 + . + Please refer to + + kdbus.policy + 7 + + for more information on the policy database and how to access it. + +struct kdbus_policy_access { + __u64 type; + __u64 access; + __u64 id; +}; + + + + + + KDBUS_ITEM_ID_ADD + KDBUS_ITEM_ID_REMOVE + + This item is sent as attachment to a + kernel notification and indicates that a + new connection was created on the bus, or that a connection was + disconnected, respectively. It stores a + struct kdbus_notify_id_change in + item.id_change. + The id field contains the numeric ID of the + connection that was added or removed, and flags + is set to the connection flags, as passed by + KDBUS_CMD_HELLO. See + + kdbus.match + 7 + + and + + kdbus.message + 7 + + for more information on matches and notification messages. + +struct kdbus_notify_id_change { + __u64 id; + __u64 flags; +}; + + + + + + KDBUS_ITEM_NAME_ADD + KDBUS_ITEM_NAME_REMOVE + KDBUS_ITEM_NAME_CHANGE + + This item is sent as attachment to a + kernel notification and indicates that a + well-known name appeared, disappeared or + transferred to another owner on the bus. It stores a + struct kdbus_notify_name_change in + item.name_change. + old_id describes the former owner of the name + and is set to 0 values in case of + KDBUS_ITEM_NAME_ADD. + 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 + 7 + + and + + kdbus.message + 7 + + for more information on matches and notification messages. + +struct kdbus_notify_name_change { + struct kdbus_notify_id_change old_id; + struct kdbus_notify_id_change new_id; + char name[0]; +}; + + + + + + KDBUS_ITEM_REPLY_TIMEOUT + + This item is sent as attachment to a + kernel notification. It informs the receiver + that an expected reply to a message was not received in time. + The remote peer ID and the message cookie is stored in the message + header. See + + kdbus.message + 7 + + for more information about messages, timeouts and notifications. + + + + + KDBUS_ITEM_REPLY_DEAD + + This item is sent as attachment to a + kernel notification. It informs the receiver + that a remote connection a reply is expected from was disconnected + before that reply was sent. The remote peer ID and the message + cookie is stored in the message header. See + + kdbus.message + 7 + + for more information about messages, timeouts and notifications. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + memfd_create + 2 + + + + + + diff --git a/Documentation/kdbus/kdbus.match.xml b/Documentation/kdbus/kdbus.match.xml new file mode 100644 index 000000000000..ef77b64e5890 --- /dev/null +++ b/Documentation/kdbus/kdbus.match.xml @@ -0,0 +1,553 @@ + + + + + + + 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 + connections 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 are as large as + the bloom 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 of the struct 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 section below 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 + + + + + diff --git a/Documentation/kdbus/kdbus.message.xml b/Documentation/kdbus/kdbus.message.xml new file mode 100644 index 000000000000..c25000dcfbc7 --- /dev/null +++ b/Documentation/kdbus/kdbus.message.xml @@ -0,0 +1,1277 @@ + + + + + + + kdbus.message + kdbus.message + + + + kdbus.message + 7 + + + + kdbus.message + kdbus message + + + + Description + + + A kdbus message is used to exchange information between two connections + on a bus, or to transport notifications from the kernel to one or many + connections. This document describes the layout of messages, how payload + is added to them and how they are sent and received. + + + + + Message layout + + The layout of a message is shown below. + + + +-------------------------------------------------------------------------+ + | Message | + | +---------------------------------------------------------------------+ | + | | Header | | + | | size: overall message size, including the data records | | + | | destination: connection ID of the receiver | | + | | source: connection ID of the sender (set by kernel) | | + | | payload_type: "DBusDBus" textual identifier stored as uint64_t | | + | +---------------------------------------------------------------------+ | + | +---------------------------------------------------------------------+ | + | | Data Record | | + | | size: overall record size (without padding) | | + | | type: type of data | | + | | data: reference to data (address or file descriptor) | | + | +---------------------------------------------------------------------+ | + | +---------------------------------------------------------------------+ | + | | padding bytes to the next 8 byte alignment | | + | +---------------------------------------------------------------------+ | + | +---------------------------------------------------------------------+ | + | | Data Record | | + | | size: overall record size (without padding) | | + | | ... | | + | +---------------------------------------------------------------------+ | + | +---------------------------------------------------------------------+ | + | | padding bytes to the next 8 byte alignment | | + | +---------------------------------------------------------------------+ | + | +---------------------------------------------------------------------+ | + | | Data Record | | + | | size: overall record size | | + | | ... | | + | +---------------------------------------------------------------------+ | + | ... further data records ... | + +-------------------------------------------------------------------------+ + + + + + Message payload + + + When connecting to the bus, receivers request a memory pool of a given + size, large enough to carry all backlog of data enqueued for the + connection. The pool is internally backed by a shared memory file which + can be mmap()ed by the receiver. See + + kdbus.pool + 7 + + for more information. + + + + Message payload must be described in items attached to a message when + it is sent. A receiver can access the payload by looking at the items + that are attached to a message in its pool. The following items are used. + + + + + KDBUS_ITEM_PAYLOAD_VEC + + + This item references a piece of memory on the sender side which is + directly copied into the receiver's pool. This way, two peers can + exchange data by effectively doing a single-copy from one process + to another; the kernel will not buffer the data anywhere else. + This item is never found in a message received by a connection. + + + + + + KDBUS_ITEM_PAYLOAD_OFF + + + This item is attached to messages on the receiving side and points + to a memory area inside the receiver's pool. The + offset variable in the item denotes the memory + location relative to the message itself. + + + + + + KDBUS_ITEM_PAYLOAD_MEMFD + + + Messages can reference memfd files which + contain the data. memfd files are tmpfs-backed files that allow + sealing of the content of the file, which prevents all writable + access to the file content. + + + Only memfds that have + (F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL) + + set are accepted as payload data, which enforces reliable passing of + data. The receiver can assume that neither the sender nor anyone + else can alter the content after the message is sent. If those + seals are not set on the memfd, the ioctl will fail with + -1, and errno will be + set to ETXTBUSY. + + + + + + KDBUS_ITEM_FDS + + + Messages can transport regular file descriptors via + KDBUS_ITEM_FDS. This item carries an array + of int values in item.fd. The + maximum number of file descriptors in the item is + 253, and only one item of this type is + accepted per message. All passed values must be valid file + descriptors; the open count of each file descriptors is increased + by installing it to the receiver's task. This item can only be + used for directed messages, not for broadcasts, and only to + remote peers that have opted-in for receiving file descriptors + at connection time (KDBUS_HELLO_ACCEPT_FD). + + + + + + + The sender must not make any assumptions on the type in which data is + received by the remote peer. The kernel is free to re-pack multiple + KDBUS_ITEM_PAYLOAD_VEC and + KDBUS_ITEM_PAYLOAD_MEMFD payloads. For instance, the + kernel may decide to merge multiple VECs into a + single VEC, inline MEMFD + payloads into memory, or merge all passed VECs into a + single MEMFD. However, the kernel preserves the order + of passed data. This means that the order of all VEC + and MEMFD items is not changed in respect to each + other. In other words: All passed VEC and + MEMFD data payloads are treated as a single stream + of data that may be received by the remote peer in a different set of + chunks than it was sent as. + + + + + Sending messages + + + Messages are passed to the kernel with the + KDBUS_CMD_SEND ioctl. Depending on the destination + address of the message, the kernel delivers the message to the specific + destination connection, or to some subset of all connections on the same + bus. Sending messages across buses is not possible. Messages are always + queued in the memory pool of the destination connection (see above). + + + + The KDBUS_CMD_SEND ioctl uses a + struct kdbus_cmd_send to describe the message + transfer. + + +struct kdbus_cmd_send { + __u64 size; + __u64 flags; + __u64 return_flags; + __u64 msg_address; + struct kdbus_msg_info reply; + 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 for message delivery + + + KDBUS_SEND_SYNC_REPLY + + + 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. + + + + + + KDBUS_FLAG_NEGOTIATE + + + Request a set of valid flags for this ioctl. When this bit is + set, no action is taken; the ioctl will fail with + -1, errno + is set to EPROTO. + Once the ioctl returned, the flags + field will have all bits set that the kernel recognizes as + 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. + + + + + msg_address + + In this field, users have to provide a pointer to a message + (struct kdbus_msg) to send. See below for a + detailed description. + + + + + reply + + Only used for synchronous replies. See description of + struct kdbus_cmd_recv for more details. + + + + + items + + + The following items are currently recognized. + + + + KDBUS_ITEM_CANCEL_FD + + + When this optional item is passed in, and the call is + executed as SYNC call, the passed in file descriptor can be + used as alternative cancellation point. The kernel will call + + poll + 2 + + on this file descriptor, and once it reports any incoming + bytes, the blocking send operation will be canceled; the + blocking, synchronous ioctl call will return + -1, and errno will + be set to ECANCELED. + Any type of file descriptor on which + + poll + 2 + + can be called on can be used as payload to this item; for + example, an eventfd can be used for this purpose, see + + eventfd + 2 + . + For asynchronous message sending, this item is allowed but + ignored. + + + + + + Unrecognized items are rejected, and the ioctl will fail with + errno set to EINVAL. + + + + + + + The fields in this struct are described below. + The message referenced the msg_address above has + the following layout. + + + +struct kdbus_msg { + __u64 size; + __u64 flags; + __s64 priority; + __u64 dst_id; + __u64 src_id; + __u64 payload_type; + __u64 cookie; + __u64 timeout_ns; + __u64 cookie_reply; + 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 describe message details. + + + KDBUS_MSG_EXPECT_REPLY + + + Expect a reply to this message from the remote peer. With + this bit set, the timeout_ns field must be set to a non-zero + number of nanoseconds in which the receiving peer is expected + to reply. If such a reply is not received in time, the sender + will be notified with a timeout message (see below). The + value must be an absolute value, in nanoseconds and based on + CLOCK_MONOTONIC. + + For a message to be accepted as reply, it must be a direct + message to the original sender (not a broadcast and not a + signal message), and its + kdbus_msg.reply_cookie must match the + previous message's kdbus_msg.cookie. + + Expected replies also temporarily open the policy of the + sending connection, so the other peer is allowed to respond + within the given time window. + + + + + + KDBUS_MSG_NO_AUTO_START + + + By default, when a message is sent to an activator + connection, the activator is notified and will start an + implementer. This flag inhibits that behavior. With this bit + set, and the remote being an activator, the ioctl will fail + with errno set to + EADDRNOTAVAIL. + + + + + + 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. + + + + + + + + + priority + + 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. If unused, the priority field + should be set to 0. + + + + + dst_id + + The numeric ID of the destination connection, or + KDBUS_DST_ID_BROADCAST + (~0ULL) to address every peer on the bus, or + KDBUS_DST_ID_NAME (0) to look + it up dynamically from the bus' name registry. + In the latter case, an item of type + KDBUS_ITEM_DST_NAME is mandatory. + Also see + + kdbus.name + 7 + + . + + + + + src_id + + Upon return of the ioctl, this member will contain the sending + connection's numerical ID. Should be 0 at send time. + + + + + payload_type + + Type of the payload in the actual data records. Currently, only + KDBUS_PAYLOAD_DBUS is accepted as input value + of this field. When receiving messages that are generated by the + kernel (notifications), this field will contain + KDBUS_PAYLOAD_KERNEL. + + + + + cookie + + Cookie of this message, for later recognition. Also, when replying + to a message (see above), the cookie_reply + field must match this value. + + + + + timeout_ns + + If the message sent requires a reply from the remote peer (see above), + this field contains the timeout in absolute nanoseconds based on + CLOCK_MONOTONIC. Also see + + clock_gettime + 2 + . + + + + + cookie_reply + + If the message sent is a reply to another message, this field must + match the cookie of the formerly received message. + + + + + items + + + A dynamically sized list of items to contain additional information. + The following items are expected/valid: + + + + KDBUS_ITEM_PAYLOAD_VEC + KDBUS_ITEM_PAYLOAD_MEMFD + KDBUS_ITEM_FDS + + + Actual data records containing the payload. See section + "Passing of Payload Data". + + + + + + KDBUS_ITEM_BLOOM_FILTER + + + Bloom filter for matches (see below). + + + + + + KDBUS_ITEM_DST_NAME + + + Well-known name to send this message to. Required if + dst_id is set to + KDBUS_DST_ID_NAME. + If a connection holding the given name can't be found, + the ioctl will fail with errno set to + ESRCH is returned. + + + For messages to a unique name (ID), this item is optional. If + present, the kernel will make sure the name owner matches the + given unique name. This allows programs to tie the message + sending to the condition that a name is currently owned by a + certain unique name. + + + + + + + + + + The message will be augmented by the requested metadata items when + queued into the receiver's pool. See + + kdbus.connection + 7 + + and + + kdbus.item + 7 + + for more information on metadata. + + + + + Receiving messages + + + Messages are received by the client with the + KDBUS_CMD_RECV ioctl. The endpoint file of the bus + supports poll()/epoll()/select(); when new messages + are available on the connection's file descriptor, + POLLIN is reported. For compatibility reasons, + POLLOUT is always reported as well. Note, however, + that the latter does not guarantee that a message can in fact be sent, as + this depends on how many pending messages the receiver has in its pool. + + + + With the KDBUS_CMD_RECV ioctl, a + struct kdbus_cmd_recv is used. + + + +struct kdbus_cmd_recv { + __u64 size; + __u64 flags; + __u64 return_flags; + __s64 priority; + __u64 dropped_msgs; + struct kdbus_msg_info msg; + 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 receive command. + + + KDBUS_RECV_PEEK + + + Just return the location of the next message. Do not install + file descriptors or anything else. This is usually used to + determine the sender of the next queued message. + + + + + + KDBUS_RECV_DROP + + + Drop the next message without doing anything else with it, + and free the pool slice. This a short-cut for + KDBUS_RECV_PEEK and + KDBUS_CMD_FREE. + + + + + + KDBUS_RECV_USE_PRIORITY + + + Dequeue the messages ordered by their priority, and filtering + them with the priority field (see below). + + + + + + KDBUS_FLAG_NEGOTIATE + + + Request a set of valid flags for this ioctl. When this bit is + set, no action is taken; the ioctl will fail with + -1, errno + is set to EPROTO. + Once the ioctl returned, the flags + field will have all bits set that the kernel recognizes as + valid for this command. + + + + + + + + + return_flags + + Flags returned by the kernel. If the dropped_msgs + field is non-zero, KDBUS_RECV_RETURN_DROPPED_MSGS + is set. If a file descriptor could not be installed, the + KDBUS_RECV_RETURN_INCOMPLETE_FDS flag is set. + + + + + priority + + With KDBUS_RECV_USE_PRIORITY set in + flags, messages will be dequeued ordered by their + priority, starting with the highest value. Also, messages will be + filtered by the value given in this field, so the returned message + will at least have the requested priority. If no such message is + waiting in the queue, the ioctl will fail, and + errno will be set to EAGAIN. + + + + + dropped_msgs + + Whenever a message with KDBUS_MSG_SIGNAL is sent + but cannot be queued on a peer (e.g., as it contains FDs but the peer + does not support FDs, or there is no space left in the peer's pool..) + the 'dropped_msgs' counter of the peer is incremented. On the next + RECV ioctl, the 'dropped_msgs' field is copied into the ioctl struct + and cleared on the peer. If it was non-zero, the + KDBUS_RECV_RETURN_DROPPED_MSGS flag will be set + in return_flags. Note that this will only happen + if the ioctl succeeded or failed with EAGAIN. In + other error cases, the 'dropped_msgs' field of the peer is left + untouched. + + + + + msg + + Embedded struct containing information on the received message when + this command succeeded (see below). + + + + + items + + Items to specify further details for the receive command. + Currently unused, and all items will be rejected with + errno set to EINVAL. + + + + + + Both struct kdbus_cmd_recv and + struct kdbus_cmd_send embed + struct kdbus_msg_info. + For the KDBUS_CMD_SEND ioctl, it is used to catch + synchronous replies, if one was requested, and is unused otherwise. + + + +struct kdbus_msg_info { + __u64 offset; + __u64 msg_size; + __u64 return_flags; +}; + + + The fields in this struct are described below. + + + + offset + + Upon return of the ioctl, this field contains the offset in the + receiver's memory pool. The memory must be freed with + KDBUS_CMD_FREE. See + + kdbus.pool + 7 + + for further details. + + + + + msg_size + + Upon successful return of the ioctl, this field contains the size of + the allocated slice at offset offset. + It is the combination of the size of the stored + struct kdbus_msg object plus all appended VECs. + You can use it in combination with offset to map + a single message, instead of mapping the entire pool. See + + kdbus.pool + 7 + + for further details. + + + + + return_flags + + + Kernel-provided return flags. Currently, the following flags are + defined. + + + + KDBUS_RECV_RETURN_INCOMPLETE_FDS + + + The message contained memfds or file descriptors, and the + kernel failed to install one or more of them at receive time. + Most probably that happened because the maximum number of + file descriptors for the receiver's task were exceeded. + In such cases, the message is still delivered, so this is not + a fatal condition. File descriptors numbers inside the + KDBUS_ITEM_FDS item or memfd files + referenced by KDBUS_ITEM_PAYLOAD_MEMFD + items which could not be installed will be set to + -1. + + + + + + + + + + Unless KDBUS_RECV_DROP was passed, the + offset field contains the location of the new message + inside the receiver's pool after the KDBUS_CMD_RECV + ioctl was employed. The message is stored as struct kdbus_msg + at this offset, and can be interpreted with the semantics described above. + + + Also, if the connection allowed for file descriptor to be passed + (KDBUS_HELLO_ACCEPT_FD), and if the message contained + any, they will be installed into the receiving process when the + KDBUS_CMD_RECV ioctl is called. + memfds may always be part of the message payload. + The receiving task is obliged to close all file descriptors appropriately + once no longer needed. If KDBUS_RECV_PEEK is set, no + file descriptors are installed. This allows for peeking at a message, + looking at its metadata only and dropping it via + KDBUS_RECV_DROP, without installing any of the file + descriptors into the receiving process. + + + The caller is obliged to call the KDBUS_CMD_FREE + ioctl with the returned offset when the memory is no longer needed. + + + + + Notifications + + A kernel notification is a regular kdbus message with the following + details. + + + + + 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 items attached that are described below. + + + Always has a timestamp item (KDBUS_ITEM_TIMESTAMP) + attached. + + + + + The kernel will notify its users of the following events. + + + + + When connection A is terminated while connection + B is waiting for a reply from it, connection + B is notified with a message with an item of + type KDBUS_ITEM_REPLY_DEAD. + + + + When connection A does not receive a reply from + connection B within the specified timeout window, + connection A will receive a message with an + item of type KDBUS_ITEM_REPLY_TIMEOUT. + + + + When an ordinary connection (not a monitor) is created on or removed + from a bus, messages with an item of type + KDBUS_ITEM_ID_ADD or + KDBUS_ITEM_ID_REMOVE, respectively, are delivered + to all bus members that match these messages through their match + database. Eavesdroppers (monitor connections) do not cause such + notifications to be sent. They are invisible on the bus. + + + + When a connection gains or loses ownership of a name, messages with an + item of type KDBUS_ITEM_NAME_ADD, + KDBUS_ITEM_NAME_REMOVE or + KDBUS_ITEM_NAME_CHANGE are delivered to all bus + members that match these messages through their match database. + + + + + + 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_SEND</constant> may fail with the following + errors + + + + + EOPNOTSUPP + + The connection is not an ordinary connection, or the passed + file descriptors in KDBUS_ITEM_FDS item are + either kdbus handles or unix domain sockets. Both are currently + unsupported. + + + + + EINVAL + + The submitted payload type is + KDBUS_PAYLOAD_KERNEL, + KDBUS_MSG_EXPECT_REPLY was set without timeout + or cookie values, KDBUS_SEND_SYNC_REPLY was + set without KDBUS_MSG_EXPECT_REPLY, an invalid + item was supplied, src_id was non-zero and was + different from the current connection's ID, a supplied memfd had a + size of 0, or a string was not properly null-terminated. + + + + + ENOTUNIQ + + The supplied destination is + KDBUS_DST_ID_BROADCAST and either + file descriptors were passed, or + KDBUS_MSG_EXPECT_REPLY was set, + or a timeout was given. + + + + + E2BIG + + Too many items + + + + + EMSGSIZE + + The size of the message header and items or the payload vector + is excessive. + + + + + EEXIST + + Multiple KDBUS_ITEM_FDS, + KDBUS_ITEM_BLOOM_FILTER or + KDBUS_ITEM_DST_NAME items were supplied. + + + + + EBADF + + The supplied KDBUS_ITEM_FDS or + KDBUS_ITEM_PAYLOAD_MEMFD items + contained an illegal file descriptor. + + + + + EMEDIUMTYPE + + The supplied memfd is not a sealed kdbus memfd. + + + + + EMFILE + + Too many file descriptors inside a + KDBUS_ITEM_FDS. + + + + + EBADMSG + + An item had illegal size, both a dst_id and a + KDBUS_ITEM_DST_NAME was given, or both a name + and a bloom filter was given. + + + + + ETXTBSY + + The supplied kdbus memfd file cannot be sealed or the seal + was removed, because it is shared with other processes or + still mapped with + + mmap + 2 + . + + + + + ECOMM + + A peer does not accept the file descriptors addressed to it. + + + + + EFAULT + + The supplied bloom filter size was not 64-bit aligned, or supplied + memory could not be accessed by the kernel. + + + + + EDOM + + The supplied bloom filter size did not match the bloom filter + size of the bus. + + + + + EDESTADDRREQ + + dst_id was set to + KDBUS_DST_ID_NAME, but no + KDBUS_ITEM_DST_NAME was attached. + + + + + ESRCH + + The name to look up was not found in the name registry. + + + + + EADDRNOTAVAIL + + KDBUS_MSG_NO_AUTO_START was given but the + destination connection is an activator. + + + + + ENXIO + + The passed numeric destination connection ID couldn't be found, + or is not connected. + + + + + ECONNRESET + + The destination connection is no longer active. + + + + + ETIMEDOUT + + Timeout while synchronously waiting for a reply. + + + + + EINTR + + Interrupted system call while synchronously waiting for a reply. + + + + + EPIPE + + When sending a message, a synchronous reply from the receiving + connection was expected but the connection died before answering. + + + + + ENOBUFS + + Too many pending messages on the receiver side. + + + + + EREMCHG + + Both a well-known name and a unique name (ID) was given, but + the name is not currently owned by that connection. + + + + + EXFULL + + The memory pool of the receiver is full. + + + + + EREMOTEIO + + While synchronously waiting for a reply, the remote peer + failed with an I/O error. + + + + + + + + <constant>KDBUS_CMD_RECV</constant> may fail with the following + errors + + + + + EOPNOTSUPP + + The connection is not an ordinary connection, or the passed + file descriptors are either kdbus handles or unix domain + sockets. Both are currently unsupported. + + + + + EINVAL + + Invalid flags or offset. + + + + + EAGAIN + + No message found in the queue + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + clock_gettime + 2 + + + + + ioctl + 2 + + + + + poll + 2 + + + + + select + 2 + + + + + epoll + 7 + + + + + eventfd + 2 + + + + + memfd_create + 2 + + + + + diff --git a/Documentation/kdbus/kdbus.name.xml b/Documentation/kdbus/kdbus.name.xml new file mode 100644 index 000000000000..3f5f6a6c5ed6 --- /dev/null +++ b/Documentation/kdbus/kdbus.name.xml @@ -0,0 +1,711 @@ + + + + + + + kdbus.name + kdbus.name + + + + kdbus.name + 7 + + + + kdbus.name + kdbus.name + + + + Description + + Each + + kdbus.bus + 7 + + instantiates a name registry to resolve well-known names into unique + connection IDs for message delivery. The registry will be queried when a + message is sent with kdbus_msg.dst_id set to + KDBUS_DST_ID_NAME, or when a registry dump is + requested with KDBUS_CMD_NAME_LIST. + + + + All of the below is subject to policy rules for SEE + and OWN permissions. See + + kdbus.policy + 7 + + for more information. + + + + + Name validity + + A name has to comply with the following rules in order to be considered + valid. + + + + + + The name has two or more elements separated by a + '.' (period) character. + + + + + All elements must contain at least one character. + + + + + Each element must only contain the ASCII characters + [A-Z][a-z][0-9]_ and must not begin with a + digit. + + + + + The name must contain at least one '.' (period) + character (and thus at least two elements). + + + + + The name must not begin with a '.' (period) + character. + + + + + The name must not exceed 255 characters in + length. + + + + + + + Acquiring a name + + To acquire a name, a client uses the + KDBUS_CMD_NAME_ACQUIRE ioctl with + struct kdbus_cmd as argument. + + + +struct kdbus_cmd { + __u64 size; + __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. + + + + + flags + Flags to control details in the name acquisition. + + + KDBUS_NAME_REPLACE_EXISTING + + + Acquiring a name that is already present usually fails, + unless this flag is set in the call, and + KDBUS_NAME_ALLOW_REPLACEMENT (see below) + was set when the current owner of the name acquired it, or + if the current owner is an activator connection (see + + kdbus.connection + 7 + ). + + + + + + KDBUS_NAME_ALLOW_REPLACEMENT + + + Allow other connections to take over this name. When this + happens, the former owner of the connection will be notified + of the name loss. + + + + + + KDBUS_NAME_QUEUE + + + A name that is already acquired by a connection can not be + acquired again (unless the + KDBUS_NAME_ALLOW_REPLACEMENT flag was + set during acquisition; see above). + However, a connection can put itself in a queue of + connections waiting for the name to be released. Once that + happens, the first connection in that queue becomes the new + owner and is notified accordingly. + + + + + + KDBUS_FLAG_NEGOTIATE + + + Request a set of valid flags for this ioctl. When this bit is + set, no action is taken; the ioctl will fail with + -1, and errno + is set to EPROTO. + Once the ioctl returned, the flags + field will have all bits set that the kernel recognizes as + valid for this command. + The KDBUS_FLAG_NEGOTIATE bit will be + cleared by the operation. + + + + + + + + + return_flags + + + Flags returned by the kernel. Currently, the following may be + returned by the kernel. + + + + KDBUS_NAME_IN_QUEUE + + + The name was not acquired yet, but the connection was + placed in the queue of peers waiting for the name. + This can only happen if KDBUS_NAME_QUEUE + was set in the flags member (see above). + The connection will receive a name owner change notification + once the current owner has given up the name and its + ownership was transferred. + + + + + + + + + items + + + 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. + KDBUS_ITEM_NEGOTIATE may be used to probe for + valid item types. See + + kdbus.item + 7 + + for a detailed description of how this item is used. + + + Unrecognized items are rejected, and the ioctl will fail with + errno set to >EINVAL. + + + + + + + + Releasing a name + + A connection may release a name explicitly with the + KDBUS_CMD_NAME_RELEASE ioctl. If the connection was + an implementer of an activatable name, its pending messages are moved + back to the activator. If there are any connections queued up as waiters + for the name, the first one in the queue (the oldest entry) will become + the new owner. The same happens implicitly for all names once a + connection terminates. See + + kdbus.connection + 7 + + for more information on connections. + + + The KDBUS_CMD_NAME_RELEASE ioctl uses the same data + structure as the acquisition call + (KDBUS_CMD_NAME_ACQUIRE), + but with slightly different field usage. + + + +struct kdbus_cmd { + __u64 size; + __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. + + + + + flags + + Flags to the command. Currently unused. + KDBUS_FLAG_NEGOTIATE is accepted to probe for + valid flags. If set, the ioctl will return 0, + 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 + + + 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. + KDBUS_ITEM_NEGOTIATE may be used to probe for + valid item types. See + + kdbus.item + 7 + + for a detailed description of how this item is used. + + + Unrecognized items are rejected, and the ioctl will fail with + errno set to EINVAL. + + + + + + + + Dumping the name registry + + A connection may request a complete or filtered dump of currently active + bus names with the KDBUS_CMD_LIST ioctl, which + takes a struct kdbus_cmd_list as argument. + + + +struct kdbus_cmd_list { + __u64 flags; + __u64 return_flags; + __u64 offset; +}; + + + The fields in this struct are described below. + + + + flags + + + Any combination of flags to specify which names should be dumped. + + + + KDBUS_LIST_UNIQUE + + + List the unique (numeric) IDs of the connection, whether it + owns a name or not. + + + + + + KDBUS_LIST_NAMES + + + List well-known names stored in the database which are + actively owned by a real connection (not an activator). + + + + + + KDBUS_LIST_ACTIVATORS + + + List names that are owned by an activator. + + + + + + KDBUS_LIST_QUEUED + + + List connections that are not yet owning a name but are + waiting for it to become available. + + + + + + KDBUS_FLAG_NEGOTIATE + + + Request a set of valid flags for this ioctl. When this bit is + set, no action is taken; the ioctl will fail with + -1, and errno + is set to EPROTO. + Once the ioctl returned, the flags + field will have all bits set that the kernel recognizes as + 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. + + + + + offset + + When the ioctl returns successfully, the offset to the name registry + dump inside the connection's pool will be stored in this field. + + + + + + The returned list of names is stored in a struct kdbus_list + that in turn contains an array of type struct kdbus_info, + The array-size in bytes is given as list_size. + The fields inside struct kdbus_info is described next. + + + +struct kdbus_info { + __u64 size; + __u64 id; + __u64 flags; + struct kdbus_item items[0]; +}; + + + The fields in this struct are described below. + + + + size + + The overall size of the struct, including its items. + + + + + id + + The owning connection's unique ID. + + + + + flags + + The flags of the owning connection. + + + + + items + + + Items containing the actual name. Currently, one item of type + KDBUS_ITEM_OWNED_NAME will be attached, + including the name's flags. In that item, the flags field of the + name may carry the following bits: + + + + KDBUS_NAME_ALLOW_REPLACEMENT + + + Other connections are allowed to take over this name from the + connection that owns it. + + + + + + KDBUS_NAME_IN_QUEUE + + + When retrieving a list of currently acquired names in the + registry, this flag indicates whether the connection + actually owns the name or is currently waiting for it to + become available. + + + + + + KDBUS_NAME_ACTIVATOR + + + An activator connection owns a name as a placeholder for an + implementer, which is started on demand by programs as soon + as the first message arrives. There's some more information + on this topic in + + kdbus.connection + 7 + + . + + + In contrast to + KDBUS_NAME_REPLACE_EXISTING, + when a name is taken over from an activator connection, all + the messages that have been queued in the activator + connection will be moved over to the new owner. The activator + connection will still be tracked for the name and will take + control again if the implementer connection terminates. + + + This flag can not be used when acquiring a name, but is + implicitly set through KDBUS_CMD_HELLO + with KDBUS_HELLO_ACTIVATOR set in + kdbus_cmd_hello.conn_flags. + + + + + + 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. + + + + + + + + + + The returned buffer must be freed with the + KDBUS_CMD_FREE ioctl when the user is finished with + it. See + + kdbus.pool + 7 + + for more information. + + + + + 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_NAME_ACQUIRE</constant> may fail with the following + errors + + + + + EINVAL + + Illegal command flags, illegal name provided, or an activator + tried to acquire a second name. + + + + + EPERM + + Policy prohibited name ownership. + + + + + EALREADY + + Connection already owns that name. + + + + + EEXIST + + The name already exists and can not be taken over. + + + + + E2BIG + + The maximum number of well-known names per connection is exhausted. + + + + + + + + <constant>KDBUS_CMD_NAME_RELEASE</constant> + may fail with the following errors + + + + + EINVAL + + Invalid command flags, or invalid name provided. + + + + + ESRCH + + Name is not found in the registry. + + + + + EADDRINUSE + + Name is owned by a different connection and can't be released. + + + + + + + + <constant>KDBUS_CMD_LIST</constant> may fail with the following + errors + + + + + EINVAL + + Invalid command flags + + + + + ENOBUFS + + No available memory in the connection's pool. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.item + 7 + + + + + kdbus.policy + 7 + + + + + kdbus.pool + 7 + + + + + diff --git a/Documentation/kdbus/kdbus.policy.xml b/Documentation/kdbus/kdbus.policy.xml new file mode 100644 index 000000000000..67324163880a --- /dev/null +++ b/Documentation/kdbus/kdbus.policy.xml @@ -0,0 +1,406 @@ + + + + + + + kdbus.policy + kdbus.policy + + + + kdbus.policy + 7 + + + + kdbus.policy + kdbus policy + + + + Description + + + A kdbus policy restricts the possibilities of connections to own, see and + talk to well-known names. A policy can be associated with a bus (through a + policy holder connection) or a custom endpoint. kdbus stores its policy + information in a database that can be accessed through the following + ioctl commands: + + + + + KDBUS_CMD_HELLO + + When creating, or updating, a policy holder connection. See + + kdbus.connection + 7 + . + + + + + KDBUS_CMD_ENDPOINT_MAKE + KDBUS_CMD_ENDPOINT_UPDATE + + When creating, or updating, a bus custom endpoint. See + + kdbus.endpoint + 7 + . + + + + + + In all cases, the name and policy access information is stored in items + of type KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS. For this transport, the + following rules apply. + + + + + + An item of type KDBUS_ITEM_NAME must be followed + by at least one KDBUS_ITEM_POLICY_ACCESS item. + + + + + + An item of type KDBUS_ITEM_NAME can be followed + by an arbitrary number of + KDBUS_ITEM_POLICY_ACCESS items. + + + + + + An arbitrary number of groups of names and access levels can be given. + + + + + + Names passed in items of type KDBUS_ITEM_NAME must + comply to the rules of valid kdbus.name. See + + kdbus.name + 7 + + for more information. + + The payload of an item of type + KDBUS_ITEM_POLICY_ACCESS is defined by the following + struct. For more information on the layout of items, please refer to + + kdbus.item + 7 + . + + + +struct kdbus_policy_access { + __u64 type; + __u64 access; + __u64 id; +}; + + + The fields in this struct are described below. + + + + type + + + One of the following. + + + + + KDBUS_POLICY_ACCESS_USER + + Grant access to a user with the UID stored in the + id field. + + + + + KDBUS_POLICY_ACCESS_GROUP + + Grant access to a user with the GID stored in the + id field. + + + + + KDBUS_POLICY_ACCESS_WORLD + + Grant access to everyone. The id field + is ignored. + + + + + + + + access + + + The access to grant. One of the following. + + + + + KDBUS_POLICY_SEE + + Allow the name to be seen. + + + + + KDBUS_POLICY_TALK + + Allow the name to be talked to. + + + + + KDBUS_POLICY_OWN + + Allow the name to be owned. + + + + + + + + id + + For KDBUS_POLICY_ACCESS_USER, stores the UID. + For KDBUS_POLICY_ACCESS_GROUP, stores the GID. + + + + + + + All endpoints of buses have an empty policy database by default. + Therefore, unless policy rules are added, all operations will also be + denied by default. Also see + + kdbus.endpoint + 7 + . + + + + + Wildcard names + + Policy holder connections may upload names that contain the wildcard + suffix (".*"). Such a policy entry is effective for + every well-known name that extends the provided name by exactly one more + level. + + For example, the name foo.bar.* matches both + "foo.bar.baz" and + "foo.bar.bazbaz" are, but not + "foo.bar.baz.baz". + + This allows connections to take control over multiple names that the + policy holder doesn't need to know about when uploading the policy. + + Such wildcard entries are not allowed for custom endpoints. + + + + + Privileged connections + + The policy database is overruled when action is taken by a privileged + connection. Please refer to + + kdbus.connection + 7 + + for more information on what makes a connection privileged. + + + + + Examples + + For instance, a set of policy rules may look like this: + + + +KDBUS_ITEM_NAME: str='org.foo.bar' +KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=1000 +KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, ID=1001 +KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=SEE + +KDBUS_ITEM_NAME: str='org.blah.baz' +KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=0 +KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK + + + + That means that 'org.foo.bar' may only be owned by UID 1000, but every + user on the bus is allowed to see the name. However, only UID 1001 may + actually send a message to the connection and receive a reply from it. + + The second rule allows 'org.blah.baz' to be owned by UID 0 only, but + every user may talk to it. + + + + + TALK access and multiple well-known names per connection + + Note that TALK access is checked against all names of a connection. For + example, if a connection owns both 'org.foo.bar' and + 'org.blah.baz', and the policy database allows + 'org.blah.baz' to be talked to by WORLD, then this + permission is also granted to 'org.foo.bar'. That + might sound illogical, but after all, we allow messages to be directed to + either the ID or a well-known name, and policy is applied to the + connection, not the name. In other words, the effective TALK policy for a + connection is the most permissive of all names the connection owns. + + For broadcast messages, the receiver needs TALK permissions to the sender + to receive the broadcast. + + + Both the endpoint and the bus policy databases are consulted to allow + name registry listing, owning a well-known name and message delivery. + If either one fails, the operation is failed with + errno set to EPERM. + + For best practices, connections that own names with a restricted TALK + access should not install matches. This avoids cases where the sent + message may pass the bloom filter due to false-positives and may also + satisfy the policy rules. + + Also see + + kdbus.match + 7 + . + + + + + Implicit policies + + Depending on the type of the endpoint, a set of implicit rules that + override installed policies might be enforced. + + On default endpoints, the following set is enforced and checked before + any user-supplied policy is checked. + + + + + + Privileged connections always override any installed policy. Those + connections could easily install their own policies, so there is no + reason to enforce installed policies. + + + + + Connections can always talk to connections of the same user. This + includes broadcast messages. + + + + + + Custom endpoints have stricter policies. The following rules apply: + + + + + + Policy rules are always enforced, even if the connection is a + privileged connection. + + + + + Policy rules are always enforced for TALK access, + even if both ends are running under the same user. This includes + broadcast messages. + + + + + To restrict the set of names that can be seen, endpoint policies can + install SEE policies. + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + diff --git a/Documentation/kdbus/kdbus.pool.xml b/Documentation/kdbus/kdbus.pool.xml new file mode 100644 index 000000000000..05fd01902ad4 --- /dev/null +++ b/Documentation/kdbus/kdbus.pool.xml @@ -0,0 +1,320 @@ + + + + + + + kdbus.pool + kdbus.pool + + + + kdbus.pool + 7 + + + + kdbus.pool + kdbus pool + + + + Description + + A pool for data received from the kernel is installed for every + connection of the bus, and + is sized according to the information stored in the + pool_size member of struct kdbus_cmd_hello + when KDBUS_CMD_HELLO is employed. Internally, the + pool is segmented into slices, each referenced by its + offset in the pool, expressed in bytes. + See + + kdbus.connection + 7 + + for more information about KDBUS_CMD_HELLO. + + + + The pool is written to by the kernel when one of the following + ioctls is issued: + + + + KDBUS_CMD_HELLO + + ... to receive details about the bus the connection was made to + + + + KDBUS_CMD_RECV + + ... to receive a message + + + + KDBUS_CMD_LIST + + ... to dump the name registry + + + + KDBUS_CMD_CONN_INFO + + ... to retrieve information on a connection + + + + + + + The offset fields returned by either one of the + aforementioned ioctls describe offsets inside the pool. In order to make + the slice available for subsequent calls, + KDBUS_CMD_FREE has to be called on that offset + (see below). Otherwise, the pool will fill up, and the connection won't + be able to receive any more information through its pool. + + + + + Pool slice allocation + + Pool slices are allocated by the kernel in order to report information + back to a task, such as messages, returned name list etc. + Allocation of pool slices cannot be initiated by userspace. See + + kdbus.connection + 7 + + and + + kdbus.name + 7 + + for examples of commands that use the pool to + return data. + + + + + Accessing the pool memory + + Memory in the pool is read-only for userspace and may only be written + to by the kernel. To read from the pool memory, the caller is expected to + + mmap + 2 + + the buffer into its task, like this: + + +uint8_t *buf = mmap(NULL, size, PROT_READ, MAP_SHARED, conn_fd, 0); + + + + In order to map the entire pool, the size parameter in + the example above should be set to the value of the + pool_size member of + struct kdbus_cmd_hello when + KDBUS_CMD_HELLO was employed to create the + connection (see above). + + + + The file descriptor used to map the memory must be + the one that was used to create the connection. + In other words, the one that was used to call + KDBUS_CMD_HELLO. See + + kdbus.connection + 7 + + for more details. + + + + 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 + size along with it, so programs can be written + in a way that it only maps portions of the pool to access a specific + slice. + + + + When access to the pool memory is no longer needed, programs should + call munmap() on the pointer returned by + mmap(). + + + + + Freeing pool slices + + The KDBUS_CMD_FREE ioctl is used to free a slice + inside the pool, describing an offset that was returned in an + offset field of another ioctl struct. + The KDBUS_CMD_FREE command takes a + struct kdbus_cmd_free as argument. + + + +struct kdbus_cmd_free { + __u64 size; + __u64 flags; + __u64 return_flags; + __u64 offset; + struct kdbus_item items[0]; +}; + + + The fields in this struct are described below. + + + + size + + The overall size of the struct, including its items. + + + + + flags + + Currently unused. + KDBUS_FLAG_NEGOTIATE is accepted to probe for + valid flags. If set, the ioctl will return 0, + 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. + + + + + offset + + The offset to free, as returned by other ioctls that allocated + memory for returned information. + + + + + items + + Items to specify further details for the receive command. + Currently unused. + Unrecognized items are rejected, and the ioctl will fail with + errno set to EINVAL. + All items except for + KDBUS_ITEM_NEGOTIATE (see + + kdbus.item + 7 + + ) will be rejected. + + + + + + + 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_FREE</constant> may fail with the following + errors + + + + + ENXIO + + No pool slice found at given offset. + + + + + EINVAL + + Invalid flags provided. + + + + + EINVAL + + The offset is valid, but the user is not allowed to free the slice. + This happens, for example, if the offset was retrieved with + KDBUS_RECV_PEEK. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.name + 7 + + + + + mmap + 2 + + + + + munmap + 2 + + + + + diff --git a/Documentation/kdbus/kdbus.xml b/Documentation/kdbus/kdbus.xml new file mode 100644 index 000000000000..194abd2e76cc --- /dev/null +++ b/Documentation/kdbus/kdbus.xml @@ -0,0 +1,1012 @@ + + + + + + + kdbus + kdbus + + + + kdbus + 7 + + + + kdbus + Kernel Message Bus + + + + Synopsis + + kdbus is an inter-process communication bus system controlled by the + kernel. It provides user-space with an API to create buses and send + unicast and multicast messages to one, or many, peers connected to the + same bus. It does not enforce any layout on the transmitted data, but + only provides the transport layer used for message interchange between + peers. + + + This set of man-pages gives a comprehensive overview of the kernel-level + API, with all ioctl commands, associated structs and bit masks. However, + most people will not use this API level directly, but rather let one of + the high-level abstraction libraries help them integrate D-Bus + functionality into their applications. + + + + + Description + + kdbus provides a pseudo filesystem called kdbusfs, + which is usually mounted on /sys/fs/kdbus. Bus + primitives can be accessed as files and sub-directories underneath this + mount-point. Any advanced operations are done via + ioctl() on files created by + kdbusfs. Multiple mount-points of + kdbusfs are independent of each other. This allows + namespacing of kdbus by mounting a new instance of + kdbusfs in a new mount-namespace. kdbus calls these + mount instances domains and each bus belongs to exactly one domain. + + + + kdbus was designed as a transport layer for D-Bus, but is in no way + limited, nor controlled by the D-Bus protocol specification. The D-Bus + protocol is one possible application layer on top of kdbus. + + + + For the general D-Bus protocol specification, its payload format, its + marshaling, and its communication semantics, please refer to the + + D-Bus specification. + + + + + + Terminology + + + Domain + + A domain is a kdbusfs mount-point containing all + the bus primitives. Each domain is independent, and separate domains + do not affect each other. + + + + + Bus + + A bus is a named object inside a domain. Clients exchange messages + over a bus. Multiple buses themselves have no connection to each other; + messages can only be exchanged on the same bus. The default endpoint of + a bus, to which clients establish connections, is the "bus" file + /sys/fs/kdbus/<bus name>/bus. + Common operating system setups create one "system bus" per system, + and one "user bus" for every logged-in user. Applications or services + may create their own private buses. The kernel driver does not + distinguish between different bus types, they are all handled the same + way. See + + kdbus.bus + 7 + + for more details. + + + + + Endpoint + + An endpoint provides a file to talk to a bus. Opening an endpoint + creates a new connection to the bus to which the endpoint belongs. All + endpoints have unique names and are accessible as files underneath the + directory of a bus, e.g., /sys/fs/kdbus/<bus>/<endpoint> + Every bus has a default endpoint called "bus". + A bus can optionally offer additional endpoints with custom names + to provide restricted access to the bus. Custom endpoints carry + additional policy which can be used to create sandboxes with + locked-down, limited, filtered access to a bus. See + + kdbus.endpoint + 7 + + for more details. + + + + + Connection + + A connection to a bus is created by opening an endpoint file of a + bus. Every ordinary client connection has a unique identifier on the + bus and can address messages to every other connection on the same + bus by using the peer's connection ID as the destination. See + + kdbus.connection + 7 + + for more details. + + + + + Pool + + Each connection allocates a piece of shmem-backed memory that is + used to receive messages and answers to ioctl commands from the kernel. + It is never used to send anything to the kernel. In order to access that + memory, an application must mmap() it into its address space. See + + kdbus.pool + 7 + + for more details. + + + + + Well-known Name + + A connection can, in addition to its implicit unique connection ID, + request the ownership of a textual well-known name. Well-known names are + noted in reverse-domain notation, such as com.example.service1. A + connection that offers a service on a bus is usually reached by its + well-known name. An analogy of connection ID and well-known name is an + IP address and a DNS name associated with that address. See + + kdbus.name + 7 + + for more details. + + + + + Message + + Connections can exchange messages with other connections by addressing + the peers with their connection ID or well-known name. A message + consists of a message header with information on how to route the + message, and the message payload, which is a logical byte stream of + arbitrary size. Messages can carry additional file descriptors to be + passed from one connection to another, just like passing file + descriptors over UNIX domain sockets. Every connection can specify which + set of metadata the kernel should attach to the message when it is + delivered to the receiving connection. Metadata contains information + like: system time stamps, UID, GID, TID, proc-starttime, well-known + names, process comm, process exe, process argv, cgroup, capabilities, + seclabel, audit session, loginuid and the connection's human-readable + name. See + + kdbus.message + 7 + + for more details. + + + + + Item + + The API of kdbus implements the notion of items, submitted through and + returned by most ioctls, and stored inside data structures in the + connection's pool. See + + kdbus.item + 7 + + for more details. + + + + + Broadcast, signal, filter, match + + Signals are messages that a receiver opts in for by installing a blob of + bytes, called a 'match'. Signal messages must always carry a + counter-part blob, called a 'filter', and signals are only delivered to + peers which have a match that white-lists the message's filter. Senders + of signal messages can use either a single connection ID as receiver, + or the special connection ID + KDBUS_DST_ID_BROADCAST to potentially send it to + all connections of a bus, following the logic described above. See + + kdbus.match + 7 + + and + + kdbus.message + 7 + + for more details. + + + + + Policy + + A policy is a set of rules that define which connections can see, talk + to, or register a well-known name on the bus. A policy is attached to + buses and custom endpoints, and modified by policy holder connections or + owners of custom endpoints. See + + kdbus.policy + 7 + + for more details. + + + + + Privileged bus users + + A user connecting to the bus is considered privileged if it is either + the creator of the bus, or if it has the CAP_IPC_OWNER capability flag + set. See + + kdbus.connection + 7 + + for more details. + + + + + + Bus Layout + + + A bus provides and defines an environment that peers + can connect to for message interchange. A bus is created via the kdbus + control interface and can be modified by the bus creator. It applies the + policy that control all bus operations. The bus creator itself does not + participate as a peer. To establish a peer + connection, you have to open one of the + endpoints of a bus. Each bus provides a default + endpoint, but further endpoints can be created on-demand. Endpoints are + used to apply additional policies for all connections on this endpoint. + Thus, they provide additional filters to further restrict access of + specific connections to the bus. + + + + Following, you can see an example bus layout: + + + + + + + + Data structures and interconnections + + + + + Metadata + + + When metadata is collected + + kdbus records data about the system in certain situations. Such metadata + can refer to the currently active process (creds, PIDs, current user + groups, process names and its executable path, cgroup membership, + capabilities, security label and audit information), connection + information (description string, currently owned names) and time stamps. + + + Metadata is collected at the following times. + + + + + When a bus is created (KDBUS_CMD_MAKE), + information about the calling task is collected. This data is returned + by the kernel via the KDBUS_CMD_BUS_CREATOR_INFO + call. + + + + + When a connection is created (KDBUS_CMD_HELLO), + information about the calling task is collected. Alternatively, a + privileged connection may provide 'faked' information about + credentials, PIDs and security labels which will be stored instead. + This data is returned by the kernel as information on a connection + (KDBUS_CMD_CONN_INFO). Only metadata that a + connection allowed to be sent (by setting its bit in + attach_flags_send) will be exported in this way. + + + + + + When a message is sent (KDBUS_CMD_SEND), + information about the sending task and the sending connection are + collected. This metadata will be attached to the message when it + arrives in the receiver's pool. If the connection sending the + message installed faked credentials (see + + kdbus.connection + 7 + ), + the message will not be augmented by any information about the + currently sending task. Note that only metadata that was requested + by the receiving connection will be collected and attached to + messages. + + + + + + Which metadata items are actually delivered depends on the following + sets and masks: + + + + + (a) the system-wide kmod creds mask + (module parameter attach_flags_mask) + + + + (b) the per-connection send creds mask, set by the connecting client + + + + (c) the per-connection receive creds mask, set by the connecting + client + + + + (d) the per-bus minimal creds mask, set by the bus creator + + + + (e) the per-bus owner creds mask, set by the bus creator + + + + (f) the mask specified when querying creds of a bus peer + + + + (g) the mask specified when querying creds of a bus owner + + + + + With the following rules: + + + + + + [1] The creds attached to messages are determined as + a & b & c. + + + + + + [2] When connecting to a bus (KDBUS_CMD_HELLO), + and ~b & d != 0, the call will fail with, + -1, and errno is set to + ECONNREFUSED. + + + + + + [3] When querying creds of a bus peer, the creds returned are + a & b & f. + + + + + + [4] When querying creds of a bus owner, the creds returned are + a & e & g. + + + + + + Hence, programs might not always get all requested metadata items that + it requested. Code must be written so that it can cope with this fact. + + + + + Benefits and heads-up + + Attaching metadata to messages has two major benefits. + + + + + Metadata attached to messages is gathered at the moment when the + other side calls KDBUS_CMD_SEND, or, + respectively, then the kernel notification is generated. There is + no need for the receiving peer to retrieve information about the + task in a second step. This closes a race gap that would otherwise + be inherent. + + + + + As metadata is delivered along with messages in the same data + blob, no extra calls to kernel functions etc. are needed to gather + them. + + + + + Note, however, that collecting metadata does come at a price for + performance, so developers should carefully assess which metadata to + really opt-in for. For best practice, data that is not needed as part + of a message should not be requested by the connection in the first + place (see attach_flags_recv in + KDBUS_CMD_HELLO). + + + + + Attach flags for metadata items + + To let the kernel know which metadata information to attach as items + to the aforementioned commands, it uses a bitmask. In those, the + following attach flags are currently supported. + Both the the attach_flags_recv and + attach_flags_send fields of + struct kdbus_cmd_hello, as well as the payload of the + KDBUS_ITEM_ATTACH_FLAGS_SEND and + KDBUS_ITEM_ATTACH_FLAGS_RECV items follow this + scheme. + + + + + KDBUS_ATTACH_TIMESTAMP + + Requests the attachment of an item of type + KDBUS_ITEM_TIMESTAMP. + + + + + KDBUS_ATTACH_CREDS + + Requests the attachment of an item of type + KDBUS_ITEM_CREDS. + + + + + KDBUS_ATTACH_PIDS + + Requests the attachment of an item of type + KDBUS_ITEM_PIDS. + + + + + KDBUS_ATTACH_AUXGROUPS + + Requests the attachment of an item of type + KDBUS_ITEM_AUXGROUPS. + + + + + KDBUS_ATTACH_NAMES + + Requests the attachment of an item of type + KDBUS_ITEM_OWNED_NAME. + + + + + KDBUS_ATTACH_TID_COMM + + Requests the attachment of an item of type + KDBUS_ITEM_TID_COMM. + + + + + KDBUS_ATTACH_PID_COMM + + Requests the attachment of an item of type + KDBUS_ITEM_PID_COMM. + + + + + KDBUS_ATTACH_EXE + + Requests the attachment of an item of type + KDBUS_ITEM_EXE. + + + + + KDBUS_ATTACH_CMDLINE + + Requests the attachment of an item of type + KDBUS_ITEM_CMDLINE. + + + + + KDBUS_ATTACH_CGROUP + + Requests the attachment of an item of type + KDBUS_ITEM_CGROUP. + + + + + KDBUS_ATTACH_CAPS + + Requests the attachment of an item of type + KDBUS_ITEM_CAPS. + + + + + KDBUS_ATTACH_SECLABEL + + Requests the attachment of an item of type + KDBUS_ITEM_SECLABEL. + + + + + KDBUS_ATTACH_AUDIT + + Requests the attachment of an item of type + KDBUS_ITEM_AUDIT. + + + + + KDBUS_ATTACH_CONN_DESCRIPTION + + Requests the attachment of an item of type + KDBUS_ITEM_CONN_DESCRIPTION. + + + + + + Please refer to + + kdbus.item + 7 + + for detailed information about the layout and payload of items and + what metadata should be used to. + + + + + + The ioctl interface + + + As stated in the 'synopsis' section above, application developers are + strongly encouraged to use kdbus through one of the high-level D-Bus + abstraction libraries, rather than using the low-level API directly. + + + + kdbus on the kernel level exposes its functions exclusively through + + ioctl + 2 + , + employed on file descriptors returned by + + open + 2 + + on pseudo files exposed by + + kdbus.fs + 7 + . + + + Following is a list of all the ioctls, along with the command structs + they must be used with. + + + + + + + ioctl signature + command + transported struct + + + + + 0x40189500 + KDBUS_CMD_BUS_MAKE + struct kdbus_cmd * + + 0x40189510 + KDBUS_CMD_ENDPOINT_MAKE + struct kdbus_cmd * + + 0xc0609580 + KDBUS_CMD_HELLO + struct kdbus_cmd_hello * + + 0x40189582 + KDBUS_CMD_BYEBYE + struct kdbus_cmd * + + 0x40389590 + KDBUS_CMD_SEND + struct kdbus_cmd_send * + + 0x80409591 + KDBUS_CMD_RECV + struct kdbus_cmd_recv * + + 0x40209583 + KDBUS_CMD_FREE + struct kdbus_cmd_free * + + 0x401895a0 + KDBUS_CMD_NAME_ACQUIRE + struct kdbus_cmd * + + 0x401895a1 + KDBUS_CMD_NAME_RELEASE + struct kdbus_cmd * + + 0x80289586 + KDBUS_CMD_LIST + struct kdbus_cmd_list * + + 0x80309584 + KDBUS_CMD_CONN_INFO + struct kdbus_cmd_info * + + 0x40209551 + KDBUS_CMD_UPDATE + struct kdbus_cmd * + + 0x80309585 + KDBUS_CMD_BUS_CREATOR_INFO + struct kdbus_cmd_info * + + 0x40189511 + KDBUS_CMD_ENDPOINT_UPDATE + struct kdbus_cmd * + + 0x402095b0 + KDBUS_CMD_MATCH_ADD + struct kdbus_cmd_match * + + 0x402095b1 + KDBUS_CMD_MATCH_REMOVE + struct kdbus_cmd_match * + + + + + + + Depending on the type of kdbusfs node that was + opened and what ioctls have been executed on a file descriptor before, + a different sub-set of ioctl commands is allowed. + + + + + + On a file descriptor resulting from opening a + control node, only the + KDBUS_CMD_BUS_MAKE ioctl may be executed. + + + + + On a file descriptor resulting from opening a + bus endpoint node, only the + KDBUS_CMD_ENDPOINT_MAKE and + KDBUS_CMD_HELLO ioctls may be executed. + + + + + A file descriptor that was used to create a bus + (via KDBUS_CMD_BUS_MAKE) is called a + bus owner file descriptor. The bus will be + active as long as the file descriptor is kept open. + A bus owner file descriptor can not be used to + employ any further ioctls. As soon as + + close + 2 + + is called on it, the bus will be shut down, along will all associated + endpoints and connections. See + + kdbus.bus + 7 + + for more details. + + + + + A file descriptor that was used to create an endpoint + (via KDBUS_CMD_ENDPOINT_MAKE) is called an + endpoint owner file descriptor. The endpoint + will be active as long as the file descriptor is kept open. + An endpoint owner file descriptor can only be used + to update details of an endpoint through the + KDBUS_CMD_ENDPOINT_UPDATE ioctl. As soon as + + close + 2 + + is called on it, the endpoint will be removed from the bus, and all + connections that are connected to the bus through it are shut down. + See + + kdbus.endpoint + 7 + + for more details. + + + + + A file descriptor that was used to create a connection + (via KDBUS_CMD_HELLO) is called a + connection owner file descriptor. The connection + will be active as long as the file descriptor is kept open. + A connection owner file descriptor may be used to + issue any of the following ioctls. + + + + + KDBUS_CMD_UPDATE to tweak details of the + connection. See + + kdbus.connection + 7 + . + + + + KDBUS_CMD_BYEBYE to shut down a connection + without losing messages. See + + kdbus.connection + 7 + . + + + + KDBUS_CMD_FREE to free a slice of memory in + the pool. See + + kdbus.pool + 7 + . + + + + KDBUS_CMD_CONN_INFO to retrieve information + on other connections on the bus. See + + kdbus.connection + 7 + . + + + + KDBUS_CMD_BUS_CREATOR_INFO to retrieve + information on the bus creator. See + + kdbus.connection + 7 + . + + + + KDBUS_CMD_LIST to retrieve a list of + currently active well-known names and unique IDs on the bus. See + + kdbus.name + 7 + . + + + + KDBUS_CMD_SEND and + KDBUS_CMD_RECV to send or receive a message. + See + + kdbus.message + 7 + . + + + + KDBUS_CMD_NAME_ACQUIRE and + KDBUS_CMD_NAME_RELEASE to acquire or release + a well-known name on the bus. See + + kdbus.name + 7 + . + + + + KDBUS_CMD_MATCH_ADD and + KDBUS_CMD_MATCH_REMOVE to add or remove + a match for signal messages. See + + kdbus.match + 7 + . + + + + + + + These ioctls, along with the structs they transport, are explained in + detail in the other documents linked to in the 'see also' section below. + + + + + See Also + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + ioctl + 2 + + + + + mmap + 2 + + + + + open + 2 + + + + + close + 2 + + + + D-Bus + + + + + diff --git a/Documentation/kdbus/stylesheet.xsl b/Documentation/kdbus/stylesheet.xsl new file mode 100644 index 000000000000..52565eac7d0d --- /dev/null +++ b/Documentation/kdbus/stylesheet.xsl @@ -0,0 +1,16 @@ + + + 1 + ansi + 80 + 0 + A4 + 2 + 1 + 1 + + + diff --git a/Makefile b/Makefile index 3cc6f4477e78..e030a4385a5d 100644 --- a/Makefile +++ b/Makefile @@ -1344,6 +1344,7 @@ $(help-board-dirs): help-%: %docs: scripts_basic FORCE $(Q)$(MAKE) $(build)=scripts build_docproc $(Q)$(MAKE) $(build)=Documentation/DocBook $@ + $(Q)$(MAKE) $(build)=Documentation/kdbus $@ else # KBUILD_EXTMOD