summaryrefslogtreecommitdiff
path: root/Documentation/kdbus/kdbus.pool.xml
diff options
context:
space:
mode:
authorAndré Fabian Silva Delgado <emulatorman@parabola.nu>2016-02-22 01:12:47 -0300
committerAndré Fabian Silva Delgado <emulatorman@parabola.nu>2016-02-22 01:12:47 -0300
commit6d461a4fe7896faa1aec5a5417888cf179e46b9f (patch)
tree2e0f1a0b7a5418189c8d53592d33a44d0b356fc9 /Documentation/kdbus/kdbus.pool.xml
parent5c545e1fb127a4b11ddc5f1a5ed066b853dd1a1a (diff)
Linux-libre 4.4.2-gnupck-4.4.2-gnu
Diffstat (limited to 'Documentation/kdbus/kdbus.pool.xml')
-rw-r--r--Documentation/kdbus/kdbus.pool.xml326
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>