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