Linux-libre 4.4.2-gnupck-4.4.2-gnu

1 files changed, 0 insertions, 326 deletions

diff --git a/Documentation/kdbus/kdbus.pool.xml b/Documentation/kdbus/kdbus.pool.xml
deleted file mode 100644
index a9e16f196..000000000
--- a/Documentation/kdbus/kdbus.pool.xml
+++ /dev/null
@@ -1,326 +0,0 @@
-<?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>