diff options
Diffstat (limited to 'Documentation/kdbus/kdbus.pool.xml')
| -rw-r--r-- | Documentation/kdbus/kdbus.pool.xml | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/Documentation/kdbus/kdbus.pool.xml b/Documentation/kdbus/kdbus.pool.xml new file mode 100644 index 000000000..a9e16f196 --- /dev/null +++ b/Documentation/kdbus/kdbus.pool.xml @@ -0,0 +1,326 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<refentry id="kdbus.pool"> + + <refentryinfo> + <title>kdbus.pool</title> + <productname>kdbus.pool</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>kdbus.pool</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>kdbus.pool</refname> + <refpurpose>kdbus pool</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + <para> + A pool for data received from the kernel is installed for every + <emphasis>connection</emphasis> of the <emphasis>bus</emphasis>, and + is sized according to the information stored in the + <varname>pool_size</varname> member of <type>struct kdbus_cmd_hello</type> + when <constant>KDBUS_CMD_HELLO</constant> is employed. Internally, the + pool is segmented into <emphasis>slices</emphasis>, each referenced by its + <emphasis>offset</emphasis> in the pool, expressed in <type>bytes</type>. + See + <citerefentry> + <refentrytitle>kdbus.connection</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + for more information about <constant>KDBUS_CMD_HELLO</constant>. + </para> + + <para> + The pool is written to by the kernel when one of the following + <emphasis>ioctls</emphasis> is issued: + + <variablelist> + <varlistentry> + <term><constant>KDBUS_CMD_HELLO</constant></term> + <listitem><para> + ... to receive details about the bus the connection was made to + </para></listitem> + </varlistentry> + <varlistentry> + <term><constant>KDBUS_CMD_RECV</constant></term> + <listitem><para> + ... to receive a message + </para></listitem> + </varlistentry> + <varlistentry> + <term><constant>KDBUS_CMD_LIST</constant></term> + <listitem><para> + ... to dump the name registry + </para></listitem> + </varlistentry> + <varlistentry> + <term><constant>KDBUS_CMD_CONN_INFO</constant></term> + <listitem><para> + ... to retrieve information on a connection + </para></listitem> + </varlistentry> + <varlistentry> + <term><constant>KDBUS_CMD_BUS_CREATOR_INFO</constant></term> + <listitem><para> + ... to retrieve information about a connection's bus creator + </para></listitem> + </varlistentry> + </variablelist> + + </para> + <para> + The <varname>offset</varname> fields returned by either one of the + aforementioned ioctls describe offsets inside the pool. In order to make + the slice available for subsequent calls, + <constant>KDBUS_CMD_FREE</constant> 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. + </para> + </refsect1> + + <refsect1> + <title>Pool slice allocation</title> + <para> + 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 + <citerefentry> + <refentrytitle>kdbus.connection</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + and + <citerefentry> + <refentrytitle>kdbus.name</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + for examples of commands that use the <emphasis>pool</emphasis> to + return data. + </para> + </refsect1> + + <refsect1> + <title>Accessing the pool memory</title> + <para> + 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 + <citerefentry> + <refentrytitle>mmap</refentrytitle> + <manvolnum>2</manvolnum> + </citerefentry> + the buffer into its task, like this: + </para> + <programlisting> +uint8_t *buf = mmap(NULL, size, PROT_READ, MAP_SHARED, conn_fd, 0); + </programlisting> + + <para> + In order to map the entire pool, the <varname>size</varname> parameter in + the example above should be set to the value of the + <varname>pool_size</varname> member of + <type>struct kdbus_cmd_hello</type> when + <constant>KDBUS_CMD_HELLO</constant> was employed to create the + connection (see above). + </para> + + <para> + The <emphasis>file descriptor</emphasis> used to map the memory must be + the one that was used to create the <emphasis>connection</emphasis>. + In other words, the one that was used to call + <constant>KDBUS_CMD_HELLO</constant>. See + <citerefentry> + <refentrytitle>kdbus.connection</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + for more details. + </para> + + <para> + Alternatively, instead of mapping the entire pool buffer, only parts + of it can be mapped. Every kdbus command that returns an + <emphasis>offset</emphasis> (see above) also reports a + <emphasis>size</emphasis> along with it, so programs can be written + in a way that it only maps portions of the pool to access a specific + <emphasis>slice</emphasis>. + </para> + + <para> + When access to the pool memory is no longer needed, programs should + call <function>munmap()</function> on the pointer returned by + <function>mmap()</function>. + </para> + </refsect1> + + <refsect1> + <title>Freeing pool slices</title> + <para> + The <constant>KDBUS_CMD_FREE</constant> ioctl is used to free a slice + inside the pool, describing an offset that was returned in an + <varname>offset</varname> field of another ioctl struct. + The <constant>KDBUS_CMD_FREE</constant> command takes a + <type>struct kdbus_cmd_free</type> as argument. + </para> + +<programlisting> +struct kdbus_cmd_free { + __u64 size; + __u64 flags; + __u64 return_flags; + __u64 offset; + struct kdbus_item items[0]; +}; +</programlisting> + + <para>The fields in this struct are described below.</para> + + <variablelist> + <varlistentry> + <term><varname>size</varname></term> + <listitem><para> + The overall size of the struct, including its items. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>flags</varname></term> + <listitem><para> + Currently unused. + <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for + valid flags. If set, the ioctl will return <errorcode>0</errorcode>, + and the <varname>flags</varname> field is set to + <constant>0</constant>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>return_flags</varname></term> + <listitem><para> + Flags returned by the kernel. Currently unused and always set to + <constant>0</constant> by the kernel. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>offset</varname></term> + <listitem><para> + The offset to free, as returned by other ioctls that allocated + memory for returned information. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>items</varname></term> + <listitem><para> + Items to specify further details for the receive command. + Currently unused. + Unrecognized items are rejected, and the ioctl will fail with + <varname>errno</varname> set to <constant>EINVAL</constant>. + All items except for + <constant>KDBUS_ITEM_NEGOTIATE</constant> (see + <citerefentry> + <refentrytitle>kdbus.item</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + ) will be rejected. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Return value</title> + <para> + On success, all mentioned ioctl commands return <errorcode>0</errorcode>; + on error, <errorcode>-1</errorcode> is returned, and + <varname>errno</varname> is set to indicate the error. + If the issued ioctl is illegal for the file descriptor used, + <varname>errno</varname> will be set to <constant>ENOTTY</constant>. + </para> + + <refsect2> + <title> + <constant>KDBUS_CMD_FREE</constant> may fail with the following + errors + </title> + + <variablelist> + <varlistentry> + <term><constant>ENXIO</constant></term> + <listitem><para> + No pool slice found at given offset. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>EINVAL</constant></term> + <listitem><para> + Invalid flags provided. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>EINVAL</constant></term> + <listitem><para> + The offset is valid, but the user is not allowed to free the slice. + This happens, for example, if the offset was retrieved with + <constant>KDBUS_RECV_PEEK</constant>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>See Also</title> + <simplelist type="inline"> + <member> + <citerefentry> + <refentrytitle>kdbus</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + </member> + <member> + <citerefentry> + <refentrytitle>kdbus.bus</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + </member> + <member> + <citerefentry> + <refentrytitle>kdbus.connection</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + </member> + <member> + <citerefentry> + <refentrytitle>kdbus.endpoint</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + </member> + <member> + <citerefentry> + <refentrytitle>kdbus.name</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + </member> + <member> + <citerefentry> + <refentrytitle>mmap</refentrytitle> + <manvolnum>2</manvolnum> + </citerefentry> + </member> + <member> + <citerefentry> + <refentrytitle>munmap</refentrytitle> + <manvolnum>2</manvolnum> + </citerefentry> + </member> + </simplelist> + </refsect1> +</refentry> |