path: root/Documentation/kdbus/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
      <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>