path: root/doc/kdbus.pool.xml

<?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
      <constant>KDBUS_ITEM_BLOOM_PARAMETER</constant> item that is returned by
      <constant>KDBUS_CMD_HELLO</constant>. Internally, the pool is segmented
      into <emphasis>slices</emphasis>, each referenced by its
      <emphasis>offset</emphasis> in the pool.
    </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_NAME_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>
      </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>Accessing the pool memory</title>
    <para>
      Memory is 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>
/*
 * POOL_SIZE has to be a multiple of PAGE_SIZE, and it must match the
 * value that was previously returned through the KDBUS_ITEM_BLOOM_PARAMETER
 * item field when the KDBUS_CMD_HELLO ioctl returned.
 */

uint8_t *buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0);
    </programlisting>

    <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 userspace can be written
      in a way that it only maps portions of the part to access a specific
      <emphasis>slice</emphasis>.
    </para>

    <para>
      When access to the pool memory is no longer needed, userspace should
      call <function>munmap</function> on the pointer returned by
      <function>mmap</function>.
    </para>
  </refsect1>

  <refsect1>
    <title>Pool slice allocation</title>
    <para>
      Pool slices are allocated by the kernel in order to report information
      back to a userspace 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.names</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>
      for examples of commands that use the <emphasis>pool</emphasis> to
      return data.
    </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 offset;
  __u64 flags;
  __u64 kernel_flags;
  __u64 return_flags;
  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>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>kernel_flags</varname></term>
        <listitem><para>
          Valid flags for this command, returned by the kernel upon each call.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>return_flags</varname></term>
        <listitem><para>
          Flags returned by the kernel. Currently unused and always set to
          zero by the kernel.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>items</varname></term>
        <listitem><para>
          Items to specify further details for the receive command.
          Currently unused. All items will be rejected with
          <constant>-EINVAL</constant>.
        </para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Return value</title>
    <para>
      On success, all metioned ioctl commands return <errorcode>0</errorcode>;
      on error, <errorcode>-1</errorcode> is returned, and
      <varname>errno</varname> is set to indicate the error.
    </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.names</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>