| <?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> |
