From: Konrad Lipinski Date: Fri, 9 Sep 2016 10:43:33 +0000 (+0200) Subject: Revert "kdbus: add documentation" X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=092936436a6c4c21bf69ac3dcc4e7cc37a3e6f3e;p=platform%2Fkernel%2Flinux-exynos.git Revert "kdbus: add documentation" This reverts commit 36c18a4057fcaa150c129c29a842567e83f93a8b. --- diff --git a/Documentation/Makefile b/Documentation/Makefile index e2127a76b5d6..bc0548201755 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,4 +1,4 @@ subdir-y := accounting auxdisplay blackfin connector \ - filesystems filesystems ia64 kdbus laptops mic misc-devices \ + filesystems filesystems ia64 laptops mic misc-devices \ networking pcmcia prctl ptp spi timers vDSO video4linux \ watchdog diff --git a/Documentation/kdbus/Makefile b/Documentation/kdbus/Makefile deleted file mode 100644 index cd6b48ee41bf..000000000000 --- a/Documentation/kdbus/Makefile +++ /dev/null @@ -1,30 +0,0 @@ -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 deleted file mode 100644 index 4d875e59ac02..000000000000 --- a/Documentation/kdbus/kdbus.bus.xml +++ /dev/null @@ -1,360 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 09852125b2d4..000000000000 --- a/Documentation/kdbus/kdbus.connection.xml +++ /dev/null @@ -1,1252 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 76e325d4e931..000000000000 --- a/Documentation/kdbus/kdbus.endpoint.xml +++ /dev/null @@ -1,436 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 8c2a90e10b66..000000000000 --- a/Documentation/kdbus/kdbus.fs.xml +++ /dev/null @@ -1,124 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index bfe47362097f..000000000000 --- a/Documentation/kdbus/kdbus.item.xml +++ /dev/null @@ -1,840 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index ef77b64e5890..000000000000 --- a/Documentation/kdbus/kdbus.match.xml +++ /dev/null @@ -1,553 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index c25000dcfbc7..000000000000 --- a/Documentation/kdbus/kdbus.message.xml +++ /dev/null @@ -1,1277 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 3f5f6a6c5ed6..000000000000 --- a/Documentation/kdbus/kdbus.name.xml +++ /dev/null @@ -1,711 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 67324163880a..000000000000 --- a/Documentation/kdbus/kdbus.policy.xml +++ /dev/null @@ -1,406 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 05fd01902ad4..000000000000 --- a/Documentation/kdbus/kdbus.pool.xml +++ /dev/null @@ -1,320 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 194abd2e76cc..000000000000 --- a/Documentation/kdbus/kdbus.xml +++ /dev/null @@ -1,1012 +0,0 @@ - - - - - - - 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 deleted file mode 100644 index 52565eac7d0d..000000000000 --- a/Documentation/kdbus/stylesheet.xsl +++ /dev/null @@ -1,16 +0,0 @@ - - - 1 - ansi - 80 - 0 - A4 - 2 - 1 - 1 - - - diff --git a/Makefile b/Makefile index 4b29608675f1..7a6b00d46f1c 100644 --- a/Makefile +++ b/Makefile @@ -1344,7 +1344,6 @@ $(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