From 6d461a4fe7896faa1aec5a5417888cf179e46b9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fabian=20Silva=20Delgado?= Date: Mon, 22 Feb 2016 01:12:47 -0300 Subject: Linux-libre 4.4.2-gnu --- Documentation/kdbus/kdbus.pool.xml | 326 ------------------------------------- 1 file changed, 326 deletions(-) delete mode 100644 Documentation/kdbus/kdbus.pool.xml (limited to 'Documentation/kdbus/kdbus.pool.xml') diff --git a/Documentation/kdbus/kdbus.pool.xml b/Documentation/kdbus/kdbus.pool.xml deleted file mode 100644 index a9e16f196..000000000 --- a/Documentation/kdbus/kdbus.pool.xml +++ /dev/null @@ -1,326 +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 - - - - KDBUS_CMD_BUS_CREATOR_INFO - - ... to retrieve information about a connection's bus creator - - - - - - - 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 - - - - - -- cgit v1.2.3