ipc/kdbus/Documentation/kdbus.pool.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <refentry id="kdbus.pool">
   6
   7   <refentryinfo>
   8     <title>kdbus.pool</title>
   9     <productname>kdbus.pool</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus.pool</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus.pool</refname>
  19     <refpurpose>kdbus pool</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24     <para>
  25       A pool for data received from the kernel is installed for every
  26       <emphasis>connection</emphasis> of the <emphasis>bus</emphasis>, and
  27       is sized according to the information stored in the
  28       <varname>pool_size</varname> member of <type>struct kdbus_cmd_hello</type>
  29       when <constant>KDBUS_CMD_HELLO</constant> is employed. Internally, the
  30       pool is segmented into <emphasis>slices</emphasis>, each referenced by its
  31       <emphasis>offset</emphasis> in the pool, expressed in <type>bytes</type>.
  32       See
  33       <citerefentry>
  34         <refentrytitle>kdbus.connection</refentrytitle>
  35         <manvolnum>7</manvolnum>
  36       </citerefentry>
  37       for more information about <constant>KDBUS_CMD_HELLO</constant>.
  38     </para>
  39
  40     <para>
  41       The pool is written to by the kernel when one of the following
  42       <emphasis>ioctls</emphasis> is issued:
  43
  44       <variablelist>
  45         <varlistentry>
  46           <term><constant>KDBUS_CMD_HELLO</constant></term>
  47           <listitem><para>
  48             ... to receive details about the bus the connection was made to
  49           </para></listitem>
  50         </varlistentry>
  51         <varlistentry>
  52           <term><constant>KDBUS_CMD_RECV</constant></term>
  53           <listitem><para>
  54             ... to receive a message
  55           </para></listitem>
  56         </varlistentry>
  57         <varlistentry>
  58           <term><constant>KDBUS_CMD_LIST</constant></term>
  59           <listitem><para>
  60             ... to dump the name registry
  61           </para></listitem>
  62         </varlistentry>
  63         <varlistentry>
  64           <term><constant>KDBUS_CMD_CONN_INFO</constant></term>
  65           <listitem><para>
  66             ... to retrieve information on a connection
  67           </para></listitem>
  68         </varlistentry>
  69         <varlistentry>
  70           <term><constant>KDBUS_CMD_BUS_CREATOR_INFO</constant></term>
  71           <listitem><para>
  72             ... to retrieve information about a connection's bus creator
  73           </para></listitem>
  74         </varlistentry>
  75       </variablelist>
  76
  77     </para>
  78     <para>
  79       The <varname>offset</varname> fields returned by either one of the
  80       aforementioned ioctls describe offsets inside the pool. In order to make
  81       the slice available for subsequent calls,
  82       <constant>KDBUS_CMD_FREE</constant> has to be called on that offset
  83       (see below). Otherwise, the pool will fill up, and the connection won't
  84       be able to receive any more information through its pool.
  85     </para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Pool slice allocation</title>
  90     <para>
  91       Pool slices are allocated by the kernel in order to report information
  92       back to a task, such as messages, returned name list etc.
  93       Allocation of pool slices cannot be initiated by userspace. See
  94       <citerefentry>
  95         <refentrytitle>kdbus.connection</refentrytitle>
  96         <manvolnum>7</manvolnum>
  97       </citerefentry>
  98       and
  99       <citerefentry>
 100         <refentrytitle>kdbus.name</refentrytitle>
 101         <manvolnum>7</manvolnum>
 102       </citerefentry>
 103       for examples of commands that use the <emphasis>pool</emphasis> to
 104       return data.
 105     </para>
 106   </refsect1>
 107
 108   <refsect1>
 109     <title>Accessing the pool memory</title>
 110     <para>
 111       Memory in the pool is read-only for userspace and may only be written
 112       to by the kernel. To read from the pool memory, the caller is expected to
 113       <citerefentry>
 114         <refentrytitle>mmap</refentrytitle>
 115         <manvolnum>2</manvolnum>
 116       </citerefentry>
 117       the buffer into its task, like this:
 118     </para>
 119     <programlisting>
 120 uint8_t *buf = mmap(NULL, size, PROT_READ, MAP_SHARED, conn_fd, 0);
 121     </programlisting>
 122
 123     <para>
 124       In order to map the entire pool, the <varname>size</varname> parameter in
 125       the example above should be set to the value of the
 126       <varname>pool_size</varname> member of
 127       <type>struct kdbus_cmd_hello</type> when
 128       <constant>KDBUS_CMD_HELLO</constant> was employed to create the
 129       connection (see above).
 130     </para>
 131
 132     <para>
 133       The <emphasis>file descriptor</emphasis> used to map the memory must be
 134       the one that was used to create the <emphasis>connection</emphasis>.
 135       In other words, the one that was used to call
 136       <constant>KDBUS_CMD_HELLO</constant>. See
 137       <citerefentry>
 138         <refentrytitle>kdbus.connection</refentrytitle>
 139         <manvolnum>7</manvolnum>
 140       </citerefentry>
 141       for more details.
 142     </para>
 143
 144     <para>
 145       Alternatively, instead of mapping the entire pool buffer, only parts
 146       of it can be mapped. Every kdbus command that returns an
 147       <emphasis>offset</emphasis> (see above) also reports a
 148       <emphasis>size</emphasis> along with it, so programs can be written
 149       in a way that it only maps portions of the pool to access a specific
 150       <emphasis>slice</emphasis>.
 151     </para>
 152
 153     <para>
 154       When access to the pool memory is no longer needed, programs should
 155       call <function>munmap()</function> on the pointer returned by
 156       <function>mmap()</function>.
 157     </para>
 158   </refsect1>
 159
 160   <refsect1>
 161     <title>Freeing pool slices</title>
 162     <para>
 163       The <constant>KDBUS_CMD_FREE</constant> ioctl is used to free a slice
 164       inside the pool, describing an offset that was returned in an
 165       <varname>offset</varname> field of another ioctl struct.
 166       The <constant>KDBUS_CMD_FREE</constant> command takes a
 167       <type>struct kdbus_cmd_free</type> as argument.
 168     </para>
 169
 170 <programlisting>
 171 struct kdbus_cmd_free {
 172   __u64 size;
 173   __u64 flags;
 174   __u64 return_flags;
 175   __u64 offset;
 176   struct kdbus_item items[0];
 177 };
 178 </programlisting>
 179
 180     <para>The fields in this struct are described below.</para>
 181
 182     <variablelist>
 183       <varlistentry>
 184         <term><varname>size</varname></term>
 185         <listitem><para>
 186           The overall size of the struct, including its items.
 187         </para></listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><varname>flags</varname></term>
 192         <listitem><para>
 193           Currently unused.
 194           <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
 195           valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
 196           and the <varname>flags</varname> field is set to
 197           <constant>0</constant>.
 198         </para></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><varname>return_flags</varname></term>
 203         <listitem><para>
 204           Flags returned by the kernel. Currently unused and always set to
 205           <constant>0</constant> by the kernel.
 206         </para></listitem>
 207       </varlistentry>
 208
 209       <varlistentry>
 210         <term><varname>offset</varname></term>
 211         <listitem><para>
 212           The offset to free, as returned by other ioctls that allocated
 213           memory for returned information.
 214         </para></listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><varname>items</varname></term>
 219         <listitem><para>
 220           Items to specify further details for the receive command.
 221           Currently unused.
 222           Unrecognized items are rejected, and the ioctl will fail with
 223           <varname>errno</varname> set to <constant>EINVAL</constant>.
 224           All items except for
 225           <constant>KDBUS_ITEM_NEGOTIATE</constant> (see
 226             <citerefentry>
 227               <refentrytitle>kdbus.item</refentrytitle>
 228               <manvolnum>7</manvolnum>
 229             </citerefentry>
 230           ) will be rejected.
 231         </para></listitem>
 232       </varlistentry>
 233     </variablelist>
 234   </refsect1>
 235
 236   <refsect1>
 237     <title>Return value</title>
 238     <para>
 239       On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
 240       on error, <errorcode>-1</errorcode> is returned, and
 241       <varname>errno</varname> is set to indicate the error.
 242       If the issued ioctl is illegal for the file descriptor used,
 243       <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
 244     </para>
 245
 246     <refsect2>
 247       <title>
 248         <constant>KDBUS_CMD_FREE</constant> may fail with the following
 249         errors
 250       </title>
 251
 252       <variablelist>
 253         <varlistentry>
 254           <term><constant>ENXIO</constant></term>
 255           <listitem><para>
 256             No pool slice found at given offset.
 257           </para></listitem>
 258         </varlistentry>
 259
 260         <varlistentry>
 261           <term><constant>EINVAL</constant></term>
 262           <listitem><para>
 263             Invalid flags provided.
 264           </para></listitem>
 265         </varlistentry>
 266
 267         <varlistentry>
 268           <term><constant>EINVAL</constant></term>
 269           <listitem><para>
 270             The offset is valid, but the user is not allowed to free the slice.
 271             This happens, for example, if the offset was retrieved with
 272             <constant>KDBUS_RECV_PEEK</constant>.
 273           </para></listitem>
 274         </varlistentry>
 275       </variablelist>
 276     </refsect2>
 277   </refsect1>
 278
 279   <refsect1>
 280     <title>See Also</title>
 281     <simplelist type="inline">
 282       <member>
 283         <citerefentry>
 284           <refentrytitle>kdbus</refentrytitle>
 285           <manvolnum>7</manvolnum>
 286         </citerefentry>
 287       </member>
 288       <member>
 289         <citerefentry>
 290           <refentrytitle>kdbus.bus</refentrytitle>
 291           <manvolnum>7</manvolnum>
 292         </citerefentry>
 293       </member>
 294       <member>
 295         <citerefentry>
 296           <refentrytitle>kdbus.connection</refentrytitle>
 297           <manvolnum>7</manvolnum>
 298         </citerefentry>
 299       </member>
 300       <member>
 301         <citerefentry>
 302           <refentrytitle>kdbus.endpoint</refentrytitle>
 303           <manvolnum>7</manvolnum>
 304         </citerefentry>
 305       </member>
 306       <member>
 307         <citerefentry>
 308           <refentrytitle>kdbus.name</refentrytitle>
 309           <manvolnum>7</manvolnum>
 310         </citerefentry>
 311       </member>
 312       <member>
 313         <citerefentry>
 314           <refentrytitle>mmap</refentrytitle>
 315             <manvolnum>2</manvolnum>
 316           </citerefentry>
 317         </member>
 318       <member>
 319         <citerefentry>
 320           <refentrytitle>munmap</refentrytitle>
 321           <manvolnum>2</manvolnum>
 322         </citerefentry>
 323       </member>
 324     </simplelist>
 325   </refsect1>
 326 </refentry>