diff options
Diffstat (limited to 'Documentation/kdbus/kdbus.pool.xml')
| -rw-r--r-- | Documentation/kdbus/kdbus.pool.xml | 326 |
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> |